open_file — Open a file in text or binary format.
open_file( : : FileName, FileType : FileHandle)
open_file opens a file in text format or in binary format.
The name of the file is defined by the parameter
open_file returns a handle to the file in the output
FileType determines the type of the file.
For text files this parameter can also be used to specify the encoding
used for strings in that file, where besides UTF-8 only the local-8-bit
encoding is supported.
The following settings for
FileType are supported:
An already existing input file is opened for reading in text format.
A new output file is opened for writing in text format.
An already existing output file is opened for writing at the end of the file in text format.
An already existing input file is opened for reading in binary format.
A new output file is opened for writing in binary format.
An already existing output file is opened for writing at the end of the file in binary format.
For text files the tuple passed to
FileType can be extended by
one of the following encoding settings:
Strings in the file are encoded in UTF-8. This is the default, so for UTF-8 encoded files and all files which use only pure 7-bit US-ASCII characters this value can be omitted.
Strings in the file are encoded in the local-8-bit encoding which depends on the system's current locale setting. Valid encodings are defined, e.g., under Windows by the code pages 1252 (a Microsoft dialect of Latin-1) or 932 (Shift-JIS) or on Linux by the locales en_US.utf8, de_DE.iso885915, or ja_JP.sjis.
The encoding of the strings that are read from the file or written into
it is not handled. In that mode multi-byte characters are neither
processed nor interpreted, the operator
always one byte, and separator characters that depend on a specific
locale are not handled in
Furthermore, the strings are not transcoded into or from the current
encoding of the HALCON library.
Note: Strings are still transcoded in the HALCON C/C++ interface, when the encoding of the HALCON C/C++ interface differs from the encoding of the HALCON library. For HDevelop scripts, the encoding is always set to UTF-8. To avoid transcoding of strings to HDevelop, the encoding of the HALCON library should be set to UTF-8.
For the standard terminal input and output streams, the file names 'standard' ('input' and 'output') and 'error' (only 'output') are reserved.
This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.
Name of file to be opened.
Default value: 'standard'
Suggested values: 'standard', 'error', '/tmp/dat.dat'
Type of file access and optional the string encoding.
Default value: 'output'
List of values: 'append', 'append_binary', 'ignore_encoding', 'input', 'input_binary', 'locale_encoding', 'output', 'output_binary', 'utf8_encoding'
* Creating an output text file with the name '/tmp/log.txt' and writing * of a string: open_file('/tmp/log.txt','output',FileHandle) fwrite_string(FileHandle,'these are the first and last lines') fnew_line(FileHandle) close_file(FileHandle)
If the parameters are valid, the operator
open_file returns the value 2 (H_MSG_TRUE).
If necessary, an exception is raised.