# LGF_FileReadWriteDelete (FB / 1.0.0)

Overview

Author: Simatic Systems Support

## Short description

The function `LGF_FileReadWriteDelete` can be used to read, write or delete a file to/from the SIMATIC Memory Card (SMC).

To read or write the data, it is necessary to deserialize/serialize it, which the function already does for the user. For this purpose, an external buffer in the form of a byte array must be connected, which can hold the amount of data; if the buffer is too small, an error is output.

The file name must always be specified in full together with the folder name and the file extension in the following format: `UserFiles/Test.dat`.

### Block Interface

| LGF_FileReadWriteDelete (FB) |
--- | --- | ---
Bool |  |  | executeRead |  | done |  |  | Bool
Bool |  |  | executeWrite |  | busy |  |  | Bool
Bool |  |  | executeDelete |  | error |  |  | Bool
String |  |  | fileName |  | status |  |  | Word
LGF_typeFileReadWriteDeleteParameter |  |  | parameter |  | dataLength |  |  | DInt
|  |  |  |  | fileDoesNotExist |  |  | Bool
|  |  |  |  | timestamps |  |  | LGF_typeFileReadWriteDeleteTimestamps
|  |  |  |  | diagnostics |  |  | LGF_typeDiagnostics
Array[*] of Byte |  |  | bufferByteArray |  |  | Array[*] of Byte
Variant |  |  | data |  |  | Variant

### Input parameter

Identifier | Data type | Default value | Description
--- | --- | --- | ---
executeRead | Bool | FALSE | Rising edge starts file read once
executeWrite | Bool | FALSE | Rising edge starts file write once
executeDelete | Bool | FALSE | Rising edge starts file delete once
fileName | String | '' | Name of file including path: `UserFiles/test.dat`
parameter | LGF_typeFileReadWriteDeleteParameter | --- | This UDT belongs to the Module `LGF_FileReadWriteDelete` and lists all possible parameters to configure its behavior.

### Output parameter

Identifier | Data type | Description
--- | --- | ---
done | Bool | TRUE: Commanded functionality has been completed successfully
busy | Bool | TRUE: FB is not finished; new output values can be expected
error | Bool | TRUE: An error occurred during the execution of the functionality
status | Word | 16#0000 - 16#7FFF: Status of the FB, 16#8000 - 16#FFFF: Error identification
dataLength | DInt | Data length read from file (serialized length of `data`)
fileDoesNotExist | Bool | True: The file or the path present at `fileName` does not exist
timestamps | LGF_typeFileReadWriteDeleteTimestamps | Timestamps for commands and file
diagnostics | LGF_typeDiagnostics | Diagnostic structure to store and transfer diagnostic information from blocks through the interface.

### In/Out parameter

Identifier | Data type | Description
--- | --- | ---
bufferByteArray | Array[*] of Byte | Byte array buffer for read / write from / to file
data | Variant | Data set read from file / to write to file

### Status & Error codes

Code / Value | Identifier / Description
--- | ---
16#0000 | STATUS_EXECUTION_FINISHED Execution finished without errors
16#7000 | STATUS_NO_CALL No job being currently processed
16#7001 | STATUS_FIRST_CALL First call after incoming new job (rising edge 'execute')
16#7002 | STATUS_SUBSEQUENT_CALL Subsequent call during active processing without further details
16#8201 | ERR_BUFFER_LOWERBOUND Error: Buffer array lower bound Lower bound must be 0
16#8202 | ERR_BUFFER_ARRAY_TO_SMALL_TO_COPY Error: Buffer size less than needed size for data
16#8400 | ERR_MULTIPLE_COMMANDS Error: Multiple commands add the same time not allowed.
16#8401 | ERR_FILE_PATH Error: File path error: File path must start with 'UserFiles/'.
16#8402 | ERR_READ_TIME_LOCAL Error: Read local time `RD_LOC_T`- see `diagnostics.subFunctionStatus`
16#8403 | ERR_READ_TIME_SYSTEM Error: Read system time (UTC) `RD_SYS_T` - see `diagnostics.subFunctionStatus`
16#8411 | ERR_FILE_SIZE_GRATER_THEN_DATA_SIZE Error: File length and Data length dose not match!
16#8412 | ERR_FILE_SIZE_LESS_THEN_DATA_SIZE Error: File length and Data length dose not match!
16#8600 | ERR_UNDEFINED_STATE Error due to an undefined state in state machine
16#8601 | ERR_MOVE_BLK_VARIANT Error: Move block variant (buffer to data) - see `diagnostics.subFunctionStatus`
16#8602 | ERR_SERIALIZE_DATA Error: Serialize data - see `diagnostics.subFunctionStatus`
16#8603 | ERR_DESERIALIZE_DATA Error: Deserialize data - see `diagnostics.subFunctionStatus`
16#8604 | ERR_SERIALIZE_DATE_TIMESTAMP Error: Serialize date and time stamp - see `diagnostics.subFunctionStatus`
16#8605 | ERR_DESERIALIZE_DATE_TIMESTAMP Error: Deserialize date and time stamp - see `diagnostics.subFunctionStatus`
16#8610 | ERR_FILE_READ_INIT Error: Read file Initialization from SMC - see `diagnostics.subFunctionStatus`
16#8611 | ERR_FILE_READ Error: Read file from SMC - see `diagnostics.subFunctionStatus`
16#8620 | ERR_FILE_WRITE_INIT Error: Write file Initialization to SMC - see `diagnostics.subFunctionStatus`
16#8621 | ERR_FILE_WRITE Error: Write file to SMC - see `diagnostics.subFunctionStatus`
16#8630 | ERR_FILE_DELETE_INIT Error: Delete file Initialization from SMC - see `diagnostics.subFunctionStatus`
16#8631 | ERR_FILE_DELETE Error: Delete file from SMC - see `diagnostics.subFunctionStatus`

## User defined datatype(s)

### LGF_typeFileReadWriteDeleteParameter (UDT / V0.0.1)

This UDT belongs to the Module `LGF_FileReadWriteDelete` and lists all possible parameters to configure its behavior.

Identifier | Data type | Default value | Description
--- | --- | --- | ---
dataLengthMustMatch | Bool | TRUE | TRUE: The length of the file data set and the dataset in the PLC must match (File read)
clearBufferBefore | Bool | TRUE | TRUE: Buffer would be cleared with 16#00 Byte before writing the data (File write)
includeTimestamp | Bool | FALSE | TRUE: A Timestamp (DTL) is included in front of the Data. `executeWrite` adds the actual time (system- or local time) `executeRead` reads back the timestamp
timeStampIsLocal | Bool | FALSE | TRUE: The timestamp is used in local time. FALSE: The timestamp is used in system time / UTC. Only used if `includeTimestamp` is set.

### LGF_typeFileReadWriteDeleteTimestamps (UDT / V0.0.1)

This UDT belongs to the module `LGF_FileReadWriteDelete` and lists all timestamps of the commands and the file, if known.
If the timestamp is unknown, the default timestamp is displayed: `DTL#1970-01-01-00:00:00`.

Identifier | Data type | Default value | Description
--- | --- | --- | ---
file | LGF_typeFileReadWriteDeleteTimestamp | --- | Time stamp of file
lastCommand | LGF_typeFileReadWriteDeleteTimestamp | --- | Time stamp of last command
executeRead | LGF_typeFileReadWriteDeleteTimestamp | --- | Time stamp of command `executeRead`
executeWrite | LGF_typeFileReadWriteDeleteTimestamp | --- | Time stamp of command `executeWrite`
executeDelete | LGF_typeFileReadWriteDeleteTimestamp | --- | Time stamp of command `executeDelete`
lastError | LGF_typeFileReadWriteDeleteTimestamp | --- | Time stamp of the last error that occurred

### LGF_typeFileReadWriteDeleteTimestamp (UDT / V0.0.1)

This UDT belongs to the module `LGF_FileReadWriteDelete` and keeps a timestamp of a command or a file.
If the timestamp is unknown, the default timestamp is displayed: `DTL#1970-01-01-00:00:00`.

Identifier | Data type | Default value | Description
--- | --- | --- | ---
dateAndTime | DTL | --- | Time stamp
timestampIsLocal | Bool | FALSE | TRUE: The timestamp is used in local time. FALSE: The timestamp is used in system time / UTC. Only used if `includeTimestamp` is set.

### LGF_typeDiagnostics (UDT / V1.0.1)

Diagnostic structure to store and transfer diagnostic information from blocks through the interface.

Identifier | Data type | Default value | Description
--- | --- | --- | ---
status | Word | 16#0000 | Status of the Block or error identification when error occurred
subfunctionStatus | Word | 16#0000 | Status or return value of called FB's, FC's and system blocks
stateNumber | DInt | 0 | State in the state machine of the block where the error occurred

## Functional description

### All commands

The file name must always be specified in full together with the folder name and the file extension in the following format: `UserFiles/test.dat`.

### Time stamps

Time stamps are written for commands, an error and the file, they are stored in the variable `timestamps`. In the event of an error, the timestamps of the individual commands are not written, the timestamp of the file is reset to the default value `DTL#1970-01-01-00:00:00`.

### File Read - Command `executeRead`

With the command `executeRead` a file can be read into the data budget of a variable at `data`. To read the data it is necessary to deserialize it, which the function already takes from the user.
For deserialization an external buffer in the form of a byte array must be connected which can take up the amount of data, if the buffer is too small an error is output.

### File Delete - Command `executeDelete`

With the command `executeDelete` a file can be deleted from the SIMATIC Memory Card (SMC). The file name must always be specified in full together with the folder name and the file extension in the following format: `UserFiles/test.dat`.

### File Write - Command `executeWrite`

With the command `executeWrite` the data budget of a variable can be written to `data` in a file. For writing the data it is necessary to serialize it, which the function already takes from the user.
For serialization an external buffer in the form of a byte array must be connected which can take up the data quantity, if the buffer is too small an error is output.

Note
  The file extension (here e.g. `dat`) can be freely selected or omitted, it is useful for external processing to indicate the format of the file to the user.
  A file extension in the file name has no influence on the content of the file as well as its formatting, providing the data in an appropriate file format is up to the user.

Warning
  The SMC (SIMATIC Memory Card) is a flash memory with finite writing cycles.
  A high frequent write access therefore also affects the lifetime of the SMC!

## Change log

Version & Date | Change description
--- | ---
| 1.0.0 | Simatic Systems Support
| 10.07.2025 | First released version