This statement is used to manipulate data items stored in containers. Typically these items exist in plist files.
Note that both of the Add Item to Container Array and Set Item in Container statements can create empty data items.
All text fields in the statement can contain any of the escape sequences defined in Escape Sequences.
The statement is only executed once when the execution mode is stepwise.
The action test state returns true on success and false on failure. If an error has occurred descriptive text is placed into the Container Error named variable.
Many of the functions support four data types as the source or destination. The data types are:
- Data
The source or destination is a directed path reference to a Data item in a container.
-
The source or destination is a string with a specified encoding.
- Integer
The source or destination is an integer. Each integer can specify, signed or unsigned, a width (8, 16, 32 or 64) and possibly an LE (little endian) or BE (big endian) designation. The endianness describes the order that the bytes comprising the integer are stored. Additional information on endianness can be found here. A field which specifies an integer is fully scanned. ie. the typical method of reading a leading integer is not used.
- Decimal
The source or destination is a decimal number. The number can be 32 or 64 bits in width and possibly an LE (little endian) or BE (big endian) designation.
The functions fall into two categories: Manipulation and Input/Output.
Manipulation Functions
Input/Output Functions
Manipulation Functions
All the manipulation functions functions work on a subrange of a Data item. Note that you can specify that the subrange is the entire data item. The directed path to the data item is supplied in the Data item field. Data items can only be in Arrays or Objects in containers. With the Extract function being the only exception, the referenced item must exist.
The following functions are available:
Extract
This function is used to extract all or part of a data item using a specified encoding and store it in a named variable or a different data item. After executing this function the named variable Binary Data Next Offset, is set to the first byte following the extracted item. The following fields are available:
- Data item
A directed path which must resolve to be a directed path to an existing Data item.
- Offset
An integer which describes the index of the first byte to be extracted. 0 represents the first byte. If you are doing successive extracts, you can reference the Binary Data Next Offset named variable.
- Count
The number of bytes to be extracted. -1 is a special value which means to the end of the data. This field is not displayed for Integer and Decimal data type extraction as the count is set by the width of the item.
- Extract type
The type of data being extracted: Data, String, Integer or Binary. Depending on the specified type, various other qualifying fields will be displayed.
- Directed path or Named variable
String, Integer and Decimal data types are saved to a named variable. Extracted Data items are saved to a directed path formatted in one of two ways:
- dpath.item
- dpath must be a directed path to an existing Object in a container. An Object named iten is set to the extracted data as a Data item.
- array[]
- array must be a directed path to an existing Array in a container. The extracted data is added to the array as a Data item.
Set
This function is used to set or create a data item to the encoded specified source data. The following fields are available:
- Data item
The Data Item is a directed path to the item being set. The directed path is formatted in one of two ways:
- dpath.item
- dpath must be a directed path to an existing Object in a container. An Object element named item is set to the extracted data as a Data item.
- array[]
- array must be a directed path to an existing Array in a container. The extracted data is added to the array as a Data item.
- Source type
The type of data being set: Data, String, Integer or Binary. Depending on the specified type, various other qualifying fields will be displayed.
- String, Integer, Decimal or Data
For String, Integer and Decimal data types, the field contains the source. eg this is a string, 123 or 123.4. For Data the field must contain a directed path to an existing data item or a hex string formatted as follows:
0xhh hh...
where hh are hex digits. Note that spaces are completely ignored. There must be an even number of hex digits.
Remove
This function is used to remove bytes from a data item. The following fields are available:
- Data item
The Data Item must be a directed path to an existing Data item.
- Offset
An integer which describes the index of the first byte to be removed. 0 represents the first byte.
- Count
The number of bytes to be removed. -1 is a special value which means to the end of the data.
Replace
This function is used to remove a specified number of bytes and replace them with the source data. The following fields are available:
- Data item
The Data Item must be a directed path to an existing Data item.
- Offset
An integer which describes the index of the first byte to be removed. 0 represents the first byte.
- Count
The number of bytes to be removed. -1 is a special value which means to the end of the data.
- Source type
The type of data replacing the removed bytes: Data, String, Integer or Binary. Depending on the specified type, various other qualifying fields will be displayed.
- String, Integer, Decimal or Data
For String, Integer and Decimal data types, the field contains the source. eg this is a string, 123 or 123.4. For Data the field must contain a directed path to an existing data item or a hex string formatted as follows:
0xhh hh...
where hh are hex digits. Note that spaces are completely ignored. There must be an even number of hex digits.
Insert
This inserts the source at a specified offset. The following fields are available:
- Data item
The Data Item must be a directed path to an existing Data item.
- Offset
An integer which describes the index where the source is to be inserted. 0 represents the first byte.
- Source type
The type of data to be inserted: Data, String, Integer or Binary. Depending on the specified type, various other qualifying fields will be displayed.
- String, Integer, Decimal or Data
For String, Integer and Decimal data types, the field contains the source. eg this is a string, 123 or 123.4. For Data the field must contain a directed path to an existing data item or a hex string formatted as follows:
0xhh hh...
where hh are hex digits. Note that spaces are completely ignored. There must be an even number of hex digits.
Append
This function appends the source data to the end of the data item. The following fields are available:
- Data item
The Data Item must be a directed path to an existing Data item.
- Source type
The type of data to be appended: Data, String, Integer or Binary. Depending on the specified type, various other qualifying fields will be displayed.
- String, Integer, Decimal or Data
For String, Integer and Decimal data types, the field contains the source. eg this is a string, 123 or 123.4. For Data the field must contain a directed path to an existing data item or a hex string formatted as follows:
0xhh hh...
where hh are hex digits. Note that spaces are completely ignored. There must be an even number of hex digits.
Reset
This function resets a number of bytes in the data by setting them to zero. The following fields are available:
- Data item
The Data Item must be a directed path to an existing Data item.
- Offset
An integer which describes the index of the first byte to be zeroed. 0 represents the first byte.
- Count
The number of bytes to be zeroed. -1 is a special value which means to the end of the data.
Increase
This function increases the length of the data item by adding a number of zero bytes to the end of the item. The following fields are available:
- Data item
The Data Item must be a directed path to an existing Data item.
- Count
The number of zero bytes to append.
Search
This function is used to search a portion of the data item for the specified source. On a failed search, the action test state is set to false. Two named variables are set which allow you to differentiate between a failed search and an error:
- Binary Data Index
On a successful match the named variable is set to the index where the first byte of the source is found. On an unsuccessful search, the named variable is set to -1.
- Binary Data Length
The named variable is set to the length of the matched source.
The following fields are available:
- Data item
The Data Item must be a directed path to an existing Data item.
- Offset
An integer which describes the index of the first byte to be searched. 0 represents the first byte.
- Count
The number of bytes to be searched. -1 is a special value which means to the end of the data.
- Source type
The type of data that you are searching for: Data, String, Integer or Binary. Depending on the specified type, various other qualifying fields will be displayed.
- String, Integer, Decimal or Data
For String, Integer and Decimal data types, the field contains the source. eg this is a string, 123 or 123.4. For Data the field must contain a directed path to an existing data item or a hex string formatted as follows:
0xhh hh...
where hh are hex digits. Note that spaces are completely ignored. There must be an even number of hex digits.
Compare
This function compares all or part of a data item with another data item. An action test state of true implies that the effective data items are equal. An action test state of false either implies inequality (named variable Container Error is empty) or an error occurred (named variable Container Error is not empty). The following fields are available:
- Data item
The Data Item must be a directed path to an existing Data item.
- Offset
An integer which describes the index of the first byte to be tested. 0 represents the first byte.
- Count
The number of bytes to be used in the supplied Data Item. -1 is a special value which means to the end of the data.
- Data
The field must contain a directed path to an existing data item or a hex string formatted as follows:
0xhh hh...
where hh are hex digits. Note that spaces are completely ignored. There must be an even number of hex digits.
Overview
Input/Output Functions
Input/Output Functions
The Input/Output functions operate on binary files. ie. individual bytes are processed. The functions all refer to a file using a full path. This path must be consistent across the function usage. It is a good idea to place the path in a named variable and to specify the named variable in its escaped form with these functions as the path. These functions all have a File path field where you specify the path.
Binary files can be opened for reading, for reading and writing or for creation (read and write). A binary file stays open until it is explicitly closed or the action terminates. When batch processing, the files say open until batch processing terminates. It is a good idea to explicitly close binary files as that way you can test for errors. When an automatic close fails and you are running in the UI, a popup error will be displayed. When running via the Batch Processor, an item will be placed in the log file.
The following functions are supported:
Open File (RO)
The specified file is opened only for reading.
Open File (RW)
The specified file is opened only for reading and writing.
Create File (RW)
The specified file is created as an empty file If the file already exists, the function fails. All intermediate paths will be created if necessary. The file can be read and written.
Close File
The specified file is closed.
Truncate File
When a file has read and write access it can be truncated at a supplied offset. All data, if any after the specified offset is removed.
Read File
A String, Integer, Decimal or Data item can be read from the specified file. The following fields may be displayed:
- Offset
The offset of the first byte in the file to be read. -1 can be used to imply the current position.
- Count
The number of bytes in the file to be read. -1 can be used to imply to the end of the file. Note that this field is not displayed for Integer and Decimal data types as their width is count is extracted from their width.
- Source type
One of String, Integer, Decimal or Data.
- Directed Path or Named Variable
String, Integer and Decimal data types are saved to a named variable. Read Data items are saved to a directed path formatted in one of two ways:
- dpath.item
- dpath must be a directed path to an existing Object in a container. An Object named iten is set to the extracted data as a Data item.
- array[]
- array must be a directed path to an existing Array in a container. The extracted data is added to the array as a Data item.
Write File
A String, Integer, Decimal or Data item can be written to the the specified file ... if it has write access. The amount of data to be written is determined by the data type. The following fields may be displayed:
- Offset
The offset of the first byte in the file to be written. -1 can be used to imply the current position.
- Source type
One of String, Integer, Decimal or Data.
- String, Integer, Decimal or Data
For String, Integer and Decimal data types, the field contains the source. eg this is a string, 123 or 123.4. For Data the field must contain a directed path to an existing data item or a hex string formatted as follows:
0xhh hh...
where hh are hex digits. Note that spaces are completely ignored. There must be an even number of hex digits.
Append to File
A String, Integer, Decimal or Data item can be appended to the the specified file ... if it has write access. The amount of data to be written is determined by the data type. The following fields may be displayed:
- Source type
One of String, Integer, Decimal or Data.
- String, Integer, Decimal or Data
For String, Integer and Decimal data types, the field contains the source. eg this is a string, 123 or 123.4. For Data the field must contain a directed path to an existing data item or a hex string formatted as follows:
0xhh hh...
where hh are hex digits. Note that spaces are completely ignored. There must be an even number of hex digits.
Filesize
The current filesize is saved to the specified named variable.
Current Offset
The current offset in the file is saved to the specified named variable.
Overview
Manipulation Functions
