FB_FileOpen
The function block creates a new file or opens an existing file for editing.
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 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.
Requirements
|
Development environment |
Target system type |
PLC libraries to include (Category group) |
|---|---|---|
|
TwinCAT v3.1.0 |
PC or CX (x86, x64, ARM) |
Tc2_System (System) |