FB_FileOpen

The function block FB_FileOpen creates a new file or opens an existing file for editing.

	This function block is only suitable for logging in real-time to a limited extent. For good performance, we recommend using the TF3500 TwinCAT Analytics Logger product, which is subject to a charge.

Inputs

VAR_INPUT
    sNetId     : T_AmsNetId;
    sPathName  : T_MaxString;
    nMode      : DWORD;
    ePath      : E_OpenPath := PATH_GENERIC;
    bExecute   : BOOL;
    tTimeout   : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

Name	Type	Description
sNetId	T_AmsNetId	String containing the AMS network ID of the target device to which the ADS command is addressed (type: T_AmsNetId).
sPathName	T_MaxString	Storage path and file name of the file to be opened. The path can only point to the local file system of the computer. Network paths cannot be specified here (type: T_MaxString).
nMode	DWORD	Mode for opening the file.
ePath	E_OpenPath	This input can be used to select a TwinCAT system path on the target device for opening the file (type: E_OpenPath).
bExecute	BOOL	The function block is activated by a rising edge at this input.
tTimeout	TIME	States the length of the timeout that may not be exceeded by execution of the ADS command.

Predefined opening modes for nMode

Mode for opening the file. The codes listed below are the various opening modes which are already pre-defined as constants in the library and which can accordingly be passed symbolically to the function block. The opening modes can be ORed. The opening modes can be combined, similar to the opening modes of the fopen function in C or C++.

Modes	Description
FOPEN_MODEREAD	r: Opens a file for reading. An error is returned if the file cannot be found or does not exist.
FOPEN_MODEWRITE	w: Opens an empty file for writing. If the file already exists, it is overwritten.
FOPEN_MODEAPPEND	a: Opens a file for writing at the end of the file (append). If the file does not exist, a new file is created.
FOPEN_MODEREAD OR FOPEN_MODEPLUS	r+: Opens a file for reading and writing. The file must exist.
FOPEN_MODEWRITE OR FOPEN_MODEPLUS	w+: Opens an empty file for reading and writing. If the file already exists, it is overwritten.
FOPEN_MODEAPPEND OR FOPEN_MODEPLUS	a+: opens a file for reading and writing at the end of the file (append). If the file does not exist, a new file is created. For this, the memory path must be known, otherwise error 1804 appears. All write operations are always performed at end of a file, if the file was opened in the modes a or a+. The file pointer can be moved with FB_FileSeek, although for writing it is moved to the end of the file by default, i.e. existing data cannot be overwritten.
FOPEN_MODEBINARY	b: Opens the file in binary mode
FOPEN_MODETEXT	t: Opens the file in text mode

Outputs

VAR_OUTPUT
    bBusy  : BOOL;
    bError : BOOL;
    nErrId : UDINT;
    hFile  : UINT;(* file handle *)
END_VAR

Name	Type	Description
bBusy	BOOL	When the function block is activated, this output is set to TRUE and remains set until feedback is received. As long as bBusy is TRUE, no new command can be executed.
bError	BOOL	If an error occurs during command execution, this output is set, once the bBusy output has been reset.
nErrId	UDINT	Returns the ADS error code or the command-specific error code when the bError output is set.
hFile	UINT	Contains the file handle created for the file when opening has been successful. This handle is then transferred to the other file function blocks as ID for the file to be edited.

Error codes for hFile

Command-specific error code	Possible cause
0x703	Unknown or invalid nMode or ePath parameter.
0x70C	File not found. Invalid file name or path.
0x716	No further free file handles.

Information:

In the opening mode, a maximum of 3 parameters may be ORed:

Mode = [ Parameter1 ] OR [ Parameter2 ] OR [ Paramerter3 ]
Parameter1 may have only a subordinate value:

FOPEN_MODEREAD
FOPEN_MODEWRITE
FOPEN_MODEAPPEND

Parameter2 may have only one subordinate value:

FOPEN_MODEPLUS

Parameter3 may have only one subordinate value:

FOPEN_MODEBINARY
FOPEN_MODETEXT

If no binary or text mode is specified, the file opens in a mode defined by an operating system variable. In most cases, the file will then open in text mode. However, it is not possible to make a clear statement. It is useful to always specify the text or binary mode. This system variable cannot be changed in the PLC!
This results in the following permissible combinations:

Text file opening modes	Binary file opening modes
FOPEN_MODEREAD OR FOPEN_MODETEXT	FOPEN_MODEREAD OR FOPEN_MODEBINARY
FOPEN_MODEWRITE OR FOPEN_MODETEXT	FOPEN_MODEWRITE OR FOPEN_MODEBINARY
FOPEN_MODEAPPEND OR FOPEN_MODETEXT	FOPEN_MODEAPPEND OR FOPEN_MODEBINARY
FOPEN_MODEREAD OR FOPEN_MODEPLUS OR FOPEN_MODETEXT	FOPEN_MODEREAD OR FOPEN_MODEPLUS OR FOPEN_MODEBINARY
FOPEN_MODEWRITE OR FOPEN_MODEPLUS OR FOPEN_MODETEXT	FOPEN_MODEWRITE OR FOPEN_MODEPLUS OR FOPEN_MODEBINARY
FOPEN_MODEAPPEND OR FOPEN_MODEPLUS OR FOPEN_MODETEXT	FOPEN_MODEAPPEND OR FOPEN_MODEPLUS OR FOPEN_MODEBINARY

All other combinations are wrong. Examples of invalid opening modes:
FOPEN_MODEBINARY OR FOPEN_MODETEXT
FOPEN_MODEWRITE OR FOPEN_MODEAPPEND

Example of calling the block in ST:

File access from the PLC

Example of calling the block in FBD:

PROGRAM Test
VAR
    fbFileOpen      : FB_FileOpen;
    bFileOpen       : BOOL;
    bFileOpenBusy   : BOOL;
    bFileOpenError  : BOOL;
    nFileOpenErrId  : UDINT;
    hFile           : UINT;
END_VAR

This should create (or overwrite) the file TestFile2.txt in the root directory of drive C: in the text mode.

Prerequisites

Development Environment	Target platform	PLC libraries to be integrated (category group)
TwinCAT v3.1.0	PC or CX (x86, x64, Arm^®)	Tc2_System (system)