open_fileT_open_fileOpenFileOpenFileopen_file (Operator)

Name

open_fileT_open_fileOpenFileOpenFileopen_file — Open a file in text or binary format.

Signature

Description

open_fileopen_fileOpenFileOpenFileOpenFileopen_file opens a file in text format or in binary format. The name of the file is defined by the parameter FileNameFileNameFileNameFileNamefileNamefile_name. The operator open_fileopen_fileOpenFileOpenFileOpenFileopen_file returns a handle to the file in the output parameter FileHandleFileHandleFileHandleFileHandlefileHandlefile_handle. The parameter FileTypeFileTypeFileTypeFileTypefileTypefile_type 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 FileTypeFileTypeFileTypeFileTypefileTypefile_type are supported:

'input'"input""input""input""input""input":

An already existing input file is opened for reading in text format.

'output'"output""output""output""output""output":

A new output file is opened for writing in text format.

'append'"append""append""append""append""append":

An already existing output file is opened for writing at the end of the file in text format.

'input_binary'"input_binary""input_binary""input_binary""input_binary""input_binary":

An already existing input file is opened for reading in binary format.

'output_binary'"output_binary""output_binary""output_binary""output_binary""output_binary":

A new output file is opened for writing in binary format.

'append_binary'"append_binary""append_binary""append_binary""append_binary""append_binary":

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 FileTypeFileTypeFileTypeFileTypefileTypefile_type can be extended by one of the following encoding settings:

'utf8_encoding'"utf8_encoding""utf8_encoding""utf8_encoding""utf8_encoding""utf8_encoding":

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.

'locale_encoding'"locale_encoding""locale_encoding""locale_encoding""locale_encoding""locale_encoding":

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.

'ignore_encoding'"ignore_encoding""ignore_encoding""ignore_encoding""ignore_encoding""ignore_encoding":

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 fread_charfread_charFreadCharFreadCharFreadCharfread_char returns always one byte, and separator characters that depend on a specific locale are not handled in fread_linefread_lineFreadLineFreadLineFreadLinefread_line and fread_stringfread_stringFreadStringFreadStringFreadStringfread_string. 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'"standard""standard""standard""standard""standard" ('input'"input""input""input""input""input" and 'output'"output""output""output""output""output") and 'error'"error""error""error""error""error" (only 'output'"output""output""output""output""output") are reserved.

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Processed without parallelization.

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.

Parameters

Example (HDevelop)

* 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)
   

Result

If the parameters are valid, the operator open_fileopen_fileOpenFileOpenFileOpenFileopen_file returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.

Possible Successors

fwrite_stringfwrite_stringFwriteStringFwriteStringFwriteStringfwrite_string, fread_charfread_charFreadCharFreadCharFreadCharfread_char, fread_stringfread_stringFreadStringFreadStringFreadStringfread_string, fread_linefread_lineFreadLineFreadLineFreadLinefread_line, fread_serialized_itemfread_serialized_itemFreadSerializedItemFreadSerializedItemFreadSerializedItemfread_serialized_item, fwrite_serialized_itemfwrite_serialized_itemFwriteSerializedItemFwriteSerializedItemFwriteSerializedItemfwrite_serialized_item, fread_bytesfread_bytesFreadBytesFreadBytesFreadBytesfread_bytes, fwrite_bytesfwrite_bytesFwriteBytesFwriteBytesFwriteBytesfwrite_bytes, close_fileclose_fileCloseFileCloseFileCloseFileclose_file

See also

close_fileclose_fileCloseFileCloseFileCloseFileclose_file

Module

Foundation