Special behavior of BUF_TO_STRING/BUF_TO_WSTRING
For the STRING/WSTRING data type the handling is different. If a string is applied at the BUFFER input, it is assumed that this string is a runtime system formatted string having a 4 byte header and a terminating zero character (see the following note). In case of a format change (Little-/Big-Endian) this header is converted; whereas variables, having other data types like an array of BYTE or WORD connected to the parameter BUFFER indicate that the string applied is a single byte string without a header (for a STRING value) and a UTF16 string without a header (for a WSTRING value). This string must also be terminated with a zero.
| Note
In a STRING, each character is represented by one byte and in a WSTRING each character is represented by two bytes and, for some language characters, by 4 bytes.. |
For the STRING/WSTRING data type the size to be copied assigned in BUF_CNT is limited to 32767 bytes (maximum allowed STRING length). In case of a larger size ERROR is set to TRUE and STATUS gets the value 10.
If the destination data type is not a STRING/WSTRING, ERROR is set to TRUE and the STATUS gets the value 8.
The necessary free memory in the destination string only consists of the bytes to be copied. If the destination string is less than necessary, the parameter
ERROR is set to TRUE and the parameter
STATUS gets the value 7.
If the source is not a STRING/WSTRING, the requested data are copied and a terminating zero character is set at the end of the copied characters.
If the source is a STRING/WSTRING and an offset is declared at the BUF_OFFS input, ERROR is set to TRUE and STATUS gets the value 9. If no offset is declared it is checked whether the requested data are available in the source string. Only the available data or the requested data if lower than the available size are copied, and a terminating zero character is set at the end of the copied characters.