TSTool / Command / FormatStringProperty

Overview
Command Editor
Command Syntax
- Endianness
Examples
Troubleshooting
See Also

Overview

The FormatStringProperty command uses zero or more processor properties as input and formats an output processor property. Although the command was originally implemented to create a string property as output, it can also set a property that is another type by converting the formatted string to a property of a different type.

Examples of use include:

concatenate values from several properties to create a string that can be used in a command
assign a literal string to a property, although SetProperty is more suitable
manipulate strings to create a number and set as a number or DateTime property
format an integer's bytes as hex codes, for example for data representations that use hex format

Formatting occurs as follows:

The data types for input properties control the type of formatting that can be done. For example, properties that are floating-point numbers must use the format specifiers for floating-point numbers.
Format specifiers are consistent with the C programming language that have similarly been implemented by Java
A newline character can be inserted using \n, although properties with newlines may cause issues if output to a file.
Null input properties will result in blanks in output.

Command Editor

The following dialog is used to edit the command and illustrates the command syntax for general parameters.

FormatStringProperty Command Editor for General Parameters (see also the full-size image)

The following is used to edit the command and illustrates the command syntax for integer parameters.

FormatStringProperty Command Editor for Integer Parameters (see also the full-size image)

Command Syntax

The command syntax is as follows:

FormatStringProperty(Parameter="Value",...)

Command Parameters

Tab	Parameter	Description	Default
*All*	`InputProperties`	The name(s) of one or more input processor properties. Values corresponding to the properties will be formatted according to the `Format` or `IntegerFormat` parameters. Input properties can be omitted if the format string is a literal value. The property names should not be surrounded by `${ }` because this results in an immediate expansion of the property values. If detected, the surrounding `${ }` characters will automatically be removed.	Required if the `Format` parameter provides formatting specifiers or the `IntegerFormat` parameter is specified.
*General*	`Format`	The format specifier string used to format the property values. See the editor dialog for examples and refer to `sprintf` documentation for further explanation. Specify as many format specifiers as there are input properties. All other characters will be transferred literally to the output string.	Required if `IntegerFormat` is not specified.
*Integer*	`IntegerFormat`	Used if input properties are all integers and are output in byte representation: `HexBytes` - each byte is encoded as a 2-character hex code using lower case letters `HexBytesUpperCase` - same as `HexBytes` but use upper case letters
*Integer*	`Endianness`	The endianness for the order of bytes in an integer (see the Endianness section below): `Big` - big endian `Little` - little endian	`Big`, which results in an output order similar to normal numbers.
*Integer*	`Delimiter`	The delimiter used with `IntegerFormat`, to separate byte values. Use `\s` for space.	None, values are packed together.
*Integer*	`NumBytes`	Number of bytes to output, for example specify `2` to output only two bytes from a 4-byte integer (the size in Java). The most significant 0-bytes in an integer can be discarded without changing the value of the integer.	Determine automatically based on the input properties.
*All*	`OutputProperty` required	The name of the processor property to be set.	None – must be specified.
*All*	`PropertyType`	Indicate the output property type, which allows the command to create properties other than strings. The formatted string must have an appropriate value to allow the conversion: `Boolean` – string must be true or false (case-insensitive) `DateTime` – string must be a standard date/time format such as supported by `SetProperty` `Double` – floating point number `Integer` – integer number `String` – any text	`String`

Endianness

Endianness is important when formatting integers in byte representations, such as hexadecimal (IntegerFormat=HexBytes). Endianness indicates the order of bytes. See Endianness on Wikipedia.

Big endian format numbers are shown with the most significant bytes at the lowest (leftmost) address when written as text.
Little endian format numbers are shown with the least significant bytes at the lowest (leftmost) address when written as text.
The 8 bits within a byte are always represented with the most significant bit on the left, regardless of whether big or little endian
Normal numbers are written with most significant digits on the left, similar to big-endian format.

An unsigned one byte integer is able to store a maximum value of 255, as shown below. A four byte signed integer can be treated as 3 unsigned byte and 1 signed byte.

1 1 1 1 1 1 1 1
| | | | | | | |
| | | | | | | +- =   1
| | | | | | +--- =   2
| | | | | +----- =   4
| | | | +------- =   8
| | | +--------- =  16
| | +----------- =  32
| +------------- =  64
+--------------- = 128
           Total = 255

The next significant byte will continue a similar pattern with larger numbers 256, 512, etc. Rather than representing a byte in binary representation, a two-character hexadecimal value can be used. For example ff is equivalent to 8-bits set to 1 or decimal 255.

A four byte unsigned integer has a value range of 0 to 4,294,967,295, whereas a signed integer has a value range of -2,147,483,648 to 2,147,483,647.

A decimal value of 25000 has a big-endian hexidecimal value of 000061a8, meaning that the byte values from left to right are (00, 00, 61, a8).

The same number in little-endian format is the reverse order (a8, 61, 00, 00).

The target computer system must ensure that the byte is consistent with the endian-ness of the in-memory integer.

Examples

See the automated tests.