Operator Reference

HALCON Operator Reference / File / Access

• HDevelop
• .NET
• Python
• C++
• C

ClassesClasses | | Operators

open_fileT_open_fileOpenFileOpenFileopen_file (Operator)

open_fileT_open_fileOpenFileOpenFileopen_file — Open a file in text or binary format.

Signature

open_file( : : FileName, FileType : FileHandle)

Herror T_open_file(const Htuple FileName, const Htuple FileType, Htuple* FileHandle)

void OpenFile(const HTuple& FileName, const HTuple& FileType, HTuple* FileHandle)

void HFile::HFile(const HString& FileName, const HTuple& FileType)

void HFile::HFile(const HString& FileName, const HString& FileType)

void HFile::HFile(const char* FileName, const char* FileType)

void HFile::HFile(const wchar_t* FileName, const wchar_t* FileType)   ( Windows only)

void HFile::OpenFile(const HString& FileName, const HTuple& FileType)

void HFile::OpenFile(const HString& FileName, const HString& FileType)

void HFile::OpenFile(const char* FileName, const char* FileType)

void HFile::OpenFile(const wchar_t* FileName, const wchar_t* FileType)   ( Windows only)

static void HOperatorSet.OpenFile(HTuple fileName, HTuple fileType, out HTuple fileHandle)

public HFile(string fileName, HTuple fileType)

public HFile(string fileName, string fileType)

void HFile.OpenFile(string fileName, HTuple fileType)

void HFile.OpenFile(string fileName, string fileType)

def open_file(file_name: str, file_type: MaybeSequence[str]) -> HHandle

Description

open_fileopen_fileOpenFileOpenFileopen_file opens a file in text format or in binary format. The name of the file is defined by the parameter FileNameFileNameFileNamefileNamefile_name. The operator open_fileopen_fileOpenFileOpenFileopen_file returns a handle to the file in the output parameter FileHandleFileHandleFileHandlefileHandlefile_handle. The parameter FileTypeFileTypeFileTypefileTypefile_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 FileTypeFileTypeFileTypefileTypefile_type are supported:

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

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

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

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

'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":

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

'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":

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

'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":

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":

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_charFreadCharFreadCharfread_char returns always one byte, and separator characters that depend on a specific locale are not handled in fread_linefread_lineFreadLineFreadLinefread_line and fread_stringfread_stringFreadStringFreadStringfread_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" ('input'"input""input""input""input" and 'output'"output""output""output""output") and 'error'"error""error""error""error" (only '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

FileNameFileNameFileNamefileNamefile_name (input_control)  filename → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Name of file to be opened.

Default: 'standard' "standard" "standard" "standard" "standard"

Suggested values: 'standard'"standard""standard""standard""standard", 'error'"error""error""error""error", '/tmp/dat.dat'"/tmp/dat.dat""/tmp/dat.dat""/tmp/dat.dat""/tmp/dat.dat"

FileTypeFileTypeFileTypefileTypefile_type (input_control)  string(-array) → HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)

Type of file access and optional the string encoding.

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

List of values: 'append'"append""append""append""append", 'append_binary'"append_binary""append_binary""append_binary""append_binary", 'ignore_encoding'"ignore_encoding""ignore_encoding""ignore_encoding""ignore_encoding", 'input'"input""input""input""input", 'input_binary'"input_binary""input_binary""input_binary""input_binary", 'locale_encoding'"locale_encoding""locale_encoding""locale_encoding""locale_encoding", 'output'"output""output""output""output", 'output_binary'"output_binary""output_binary""output_binary""output_binary", 'utf8_encoding'"utf8_encoding""utf8_encoding""utf8_encoding""utf8_encoding"

FileHandleFileHandleFileHandlefileHandlefile_handle (output_control)  file → HFile, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

File handle.

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_fileOpenFileOpenFileopen_file returns the value 2 ( H_MSG_TRUE) . If necessary, an exception is raised.

Possible Successors

fwrite_stringfwrite_stringFwriteStringFwriteStringfwrite_string, fread_charfread_charFreadCharFreadCharfread_char, fread_stringfread_stringFreadStringFreadStringfread_string, fread_linefread_lineFreadLineFreadLinefread_line, fread_serialized_itemfread_serialized_itemFreadSerializedItemFreadSerializedItemfread_serialized_item, fwrite_serialized_itemfwrite_serialized_itemFwriteSerializedItemFwriteSerializedItemfwrite_serialized_item, fread_bytesfread_bytesFreadBytesFreadBytesfread_bytes, fwrite_bytesfwrite_bytesFwriteBytesFwriteBytesfwrite_bytes, close_fileclose_fileCloseFileCloseFileclose_file

See also

close_fileclose_fileCloseFileCloseFileclose_file

Module

Foundation

---

ClassesClasses | | Operators