Format specification
This format specification is used by the function block FB_FormatString and the function F_FormatArgToStr. With the function block, the format specification is transferred via a string input variable. With the function, the individual function parameters are used.
The format specification containing the required and optional parameter fields has the following form:
%[ ] [ ] [ . ] Flags Width Precision Type
The simplest format specification only contains the percent sign and the type field (e.g. %s). All characters after the percent sign and up to the type field are interpreted as parameter fields. Characters to the left of the percent sign and after the type field are copied into the output string. Formatting is aborted with an error in the event of unidentifiable or illegal characters. Two consecutive percent signs (%%) can be used if the output string is to contain the percent sign.
Type
Required parameter field. This is an ASCII character that determines whether the associated argument is interpreted as a string, integer, or floating-point number. Please note that some type field parameters are case-sensitive.
Type | Argument | Output |
|---|---|---|
b, B | BYTE, WORD, DWORD, *REAL, **SINT, **INT, **DINT, USINT, UINT, UDINT | Binary string ( e.g.: '101010111000' ). |
o, O | BYTE, WORD, DWORD, *REAL, **SINT, **INT, **DINT, USINT, UINT, UDINT | Octal string. |
u, U | BYTE, WORD, DWORD, **SINT, **INT, **DINT, USINT, UINT, UDINT | Decimal string without sign. |
c, C | BYTE, USINT | Single (ASCII) byte character. |
f, F | ***REAL, LREAL | Floating-point number. The string has the following form: [ - ]dddd.dddd, (dddd are decimal numbers). The number of digits before the decimal point depends on the value of the floating-point number. The number of digits after the decimal point depends on the required precision. The sign only appears for negative values. '#INF' is returned for infinite positive values, '-#INF' for infinite negative values. If the variable transferred has an illegal value (NaN, Not-a-Number), '#QNAN' or '-#QNAN' is returned. If the length of the formatted string exceeds the maximum permissible length of the resulting string, '#OVF' or '-#OVF' is returned. |
d, D | BYTE, WORD, DWORD, SINT, INT, DINT, USINT, UINT, UDINT | Decimal string. The sign only appears for negative values. |
s, S | STRING | Single byte character string. Characters are output up to the last zero or until the precision parameter is reached. |
X | BYTE, WORD, DWORD, *REAL, **SINT, **INT, **DINT, USINT, UINT, UDINT | Hexadecimal string. Upper case letters ('ABCDEF') are used for formatting. |
x | BYTE, WORD, DWORD, *REAL, **SINT, **INT, **DINT, USINT, UINT, UDINT | Hexadecimal string. Lower case letters ('abcdef') are used for formatting. |
E | Not implemented. Reserved for future use!. | Floating-point numbers in scientific notation. |
e | Not implemented. Reserved for future use!. | Floating-point numbers in scientific notation. |
* The content of the REAL variable is returned as a binary, octal, hexadecimal or decimal string.
** The content of the signed types is returned as a binary, octal, hexadecimal or decimal string.
*** The REAL variable is converted to type LREAL and then formatted.
Flags
Optional parameter field. One or several flags can be specified in any order. These parameters determine the alignment of the formatted value and output of sign, blanks and the binary/octal/hex prefixes.
Flag | Meaning | Type | Standard |
|---|---|---|---|
- | Left alignment flag. The formatted value is left aligned within the width aligned in parameter Width. Width. | Can be used in conjunction with all types. | Right alignment. |
+ | Sign flag. Forces output of the positive sign for signed positive numbers. | Only in conjunction with e, E, f, F, d, D. Otherwise the flag is ignored. | The negative sign only appears for negative values. |
0 | Zero flag. If this flag precedes the Width parameter, the resulting string is filled with zeros from the left until the required width is reached. | Only in conjunction with e, E, f, F, s, S. Otherwise the flag is ignored. The zero flag is also ignored if the left alignment flag (-) was set at the same time. | No filling with zeros. |
Blank (' ') | Blank flag. A positive value is preceded by a blank | Only in conjunction with e, E, f, F, d, D. Otherwise the flag is ignored. The blank flag is also ignored if the left sign flag (+) was set at the same time | No blank. |
# | Prefix flag. The formatted value is preceded by an "IEC" or a "standard C" prefix. "IEC" prefixes: 2#, 8#, 16# (default) "Standard C" prefixes: 0, 0x, 0X | Only in conjunction with b, B, o, O, x, X. Otherwise the flag is ignored. The "standard C" prefix type can be activated by setting the global variable GLOBAL_FORMAT_HASH_PREFIX_TYPE in the program: GLOBAL_FORMAT_HASH_PREFIX_TYPE := HASHPREFIX_STDC; | No prefix. |
Width
Optional parameter field. This parameter must have a positive decimal value. It determines the minimum number of characters in the output string. Blanks (left or right, depending on the alignment flag) are added to the output string until the required width is reached. If the zero flag precedes the Width parameter, the resulting string is filled with zeros from the left until the required width is reached. However, the Width parameter never causes the output string to be cut to the desired length!
An asterisk (*) may also be used for the Width parameter. The required value is then provided by an argument (permissible types: BYTE, WORD, DWORD, USINT, UINT, UDINT). The argument for the Width parameter is then followed by the argument for the value to be formatted.
Precision
Optional parameter field. This parameter follows after the dot (.) and must have a positive decimal value. If the dot is not followed by a value, the default precision value is used (see table).
Type | Meaning | Standard |
|---|---|---|
b, B, o, O, u, U, x, X, d, D | The precision parameter determines the number of digits in the output string. If there are not enough digits, the string is filled with zeros from the left. The output string is never cut. | Standard: 1 |
c, C | Has no meaning and is ignored. | Output: 1 character |
f, F | The precision parameter determines the number of decimal places. The argument value is always rounded to the respective number of decimal places. | Standard: 6 decimal places |
s, S | The precision parameter determines how many characters from the argument string are output. Characters exceeding the precision value are not output. | All characters up to the last zero are output. |
An asterisk (*) may also be used for the Precision parameter. The required value is then provided by an argument (permissible types: BYTE, WORD, DWORD, USINT, UINT, UDINT). The argument for the Precision parameter is then followed by the argument for the value to be formatted.
Requirements
Development environment | Target system type | PLC libraries to be linked |
|---|---|---|
TwinCAT v2.9.0 Build >1021 | PC or CX (x86) | TcUtilities.Lib ( Standard.Lib; TcBase.Lib; TcSystem.Lib are included automatically ) |
TwinCAT v2.10.0 Build >= 1301 | CX (ARM) |