Strings are limited to 255 characters. Here is a set of functions and function blocks for working with not limited text buffers. Text buffers are dynamically allocated or re-allocated.
Important notes:
|
The application is responsible for freeing all allocated text buffers. However, all allocated buffers are automatically released when the application stops.
Below are the functions and function blocks for managing variable length text buffers:
Memory management / Miscellaneous:
TxbManager: main gatherer of text buffer data in memory
TxbLastError: get detailed error report about last call
Allocation / exchange with files:
TxbNew: Allocate a new empty buffer
TxbNewString: Allocate a new buffer initialized with string
TxbFree: Release a text buffer
TxbReadFile: Allocate a new buffer from file
TxbWriteFile: Store a text buffer to file
Data exchange:
TxbGetLength: Get length of a text buffer
TxbGetData: Store text contents to an array of characters
TxbGetString: Store text contents to a string
TxbSetData: Store an array of characters to a text buffer
TxbSetString: Store string to text buffer
TxbClear: Empty a text buffer
TxbCopy: Copy a text buffer
Sequential reading:
TxbRewind: Rewind sequential reading
TxbGetLine: Sequential read line by line
Sequential writing:
TxbAppend: Append variable value
TxbAppendLine: Append a text line
TxbAppendEol: Append end of line characters
TxpAppendTxb: Append contents of another buffer
UNICODE conversions:
TxbAnsiToUtf8: Convert a text buffer to UNICODE
TxbUtf8ToAnsi: Convert a text buffer to ANSI
|
|
InstanceName |
|
|
|
|
TxbManager |
|
|
|
|
|
bOK |
- BOOL |
|
|
|
nBuffers |
- DINT |
|
|
|
|
|
Description:
This function block is used for managing the memory allocated for text buffers. It takes care of releasing the corresponding memory when the application stops, and can be used for tracking memory leaks.
Important: There must be one and only one instance of this block declared in the IEC application in order to use any other Txb... function.
Outputs:
|
bOK : BOOL |
TRUE if the text buffers memory system is correctly initialized.
|
|
nBuffers : DINT |
Number of text buffers currently allocated in memory. |
|
|
TxbLastError |
|
|
|
|
|
iErr |
- DINT |
|
|
|
|
|
Description:
All TXB functions and blocks simply return a boolean information as a return value. This function can be called after any other function giving a FALSE return. It gives a detailed error code about the last detected error.
Outputs:
|
iErr : DINT |
Error code reported by the last call: 0 = OK other = error (see below) |
Below are possible error codes:
1
invalid instance of TXBManager - should be only one
2 manager already open - should be only one instance of
TxbManager
3 manager not open - no instance of TxbManager
declared
4 invalid handle
5 string has been truncated during copy
6 cannot read file
7 cannot write file
8 unsupported data type
9 too many text buffers allocated
|
|
TxbNew |
|
|
|
|
|
hTxb |
- DINT |
|
|
|
|
|
Description:
This function allocates a new text buffer initially empty. The application will be responsible for releasing the buffer by calling the TxbFree() function.
Outputs:
|
hTxb : DINT |
Handle of the new buffer |
|
|
TxbNewString |
|
|
|
STRING - |
szText |
hTxb |
- DINT |
|
|
|
|
|
Description:
This function allocates a new text buffer initially filled with teh specified string. The application will be responsible for releasing the buffer by calling the TxbFree() function.
Inputs:
|
szText : STRING |
Initial value of the text buffer |
Outputs:
|
hTxb : DINT |
Handle of the new buffer |
|
|
TxbFree |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
|
|
|
|
Description:
This function releases a text buffer from memory.
Inputs:
|
hTxb : DINT |
Handle of a valid text buffer |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbReadFile |
|
|
|
STRING - |
szPath |
hTxb |
- DINT |
|
|
|
|
|
Description:
This function allocates a new text buffer and fills it with the contents of the specified file. The application will be responsible for releasing the buffer by calling the TxbFree() function.
Inputs:
|
szPath : STRING |
Full qualified pathname of the file to be read |
Outputs:
|
hTxb : DINT |
Handle of the new buffer |
|
|
TxbWriteFile |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
STRING - |
szPath |
|
|
|
|
|
|
|
Description:
This function stores the contents of a text buffer to a file. The text buffer remains allocated in memory.
Inputs:
|
hTxb : DINT |
Handle of the text buffer
|
|
szPath : STRING |
Full qualified pathname of the file to be created. |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbGetLength |
|
|
|
DINT - |
hTxb |
len |
- DINT |
|
|
|
|
|
Description:
This function returns the current length of a text buffer.
Inputs:
|
hTxb : DINT |
Handle of the text buffer |
Outputs:
|
len : DINT |
Number of characters in the text buffer |
|
|
TxbGetData |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
SINT[] - |
arData |
|
|
|
|
|
|
|
Description:
This function copies the contents of a text buffer to an array of characters.
Inputs:
|
hTxb : DINT |
Handle of the text buffer
|
|
arData : SINT[] |
Array of characters to be filled with text |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbGetString |
|
|
|
DINT - |
hTxb |
szText |
- STRING |
|
|
|
|
|
Description:
This function copies the contents of a text buffer to a string. The text is truncated if the string is not large enough.
Inputs:
|
hTxb : DINT |
Handle of the text buffer |
Outputs:
|
szText : STRING |
String to be filled with text |
|
|
TxbSetData |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
SINT[] - |
arData |
|
|
|
|
|
|
|
Description:
This function copies an array of characters to a text buffer. All characters of the input array are copied.
Inputs:
|
hTxb : DINT |
Handle of the text buffer
|
|
arData : SINT[] |
Array of characters to copy |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbSetString |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
STRING - |
szText |
|
|
|
|
|
|
|
Description:
This function copies the contents of a string to a text buffer.
Inputs:
|
hTxb : DINT |
Handle of the text buffer
|
|
szText : STRING |
String to be copied |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbClear |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
|
|
|
|
Description:
This function empties a text buffer.
Inputs:
|
hTxb : DINT |
Handle of the text buffer |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbCopy |
|
|
|
DINT - |
hTxbDst |
bOK |
- BOOL |
|
DINT - |
hTxb |
|
|
|
|
|
|
|
Description:
This function copies the contents of the hTxb buffer the to hTxbDst buffer.
Inputs:
|
hTxbDst : DINT |
Handle of the destination text buffer
|
|
hTxb : DINT |
Handle of the source text buffer |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbRewind |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
|
|
|
|
Description:
This function resets the sequential reading of a text buffer (rewind to the beginning of the text).
Inputs:
|
hTxb : DINT |
Handle of the text buffer |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbGetLine |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
STRING - |
szText |
|
|
|
|
|
|
|
Description:
This function sequentially reads a line of text from a text buffer. End of line characters are not copied to the output string.
Inputs:
|
hTxb : DINT |
Handle of the text buffer
|
|
szText : STRING |
String to be filled with read line |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbAppend |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
ANY - |
data |
|
|
|
|
|
|
|
Description:
This function adds the contents of a variable, formatted as text, to a text buffer. The specified variable can have any data type.
Inputs:
|
hTxb : DINT |
Handle of the text buffer
|
|
data : ANY |
Any variable |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbAppendLine |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
STRING - |
szText |
|
|
|
|
|
|
|
Description:
This function adds the contents of the specified string variable to a text buffer, plus end of line characters.
Inputs:
|
hTxb : DINT |
Handle of the text buffer
|
|
szText : STRING |
String to be added to the text |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbAppendEol |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
|
|
|
|
Description:
This function adds end of line characters to a text buffer.
Inputs:
|
hTxb : DINT |
Handle of the text buffer |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbAppendTxb |
|
|
|
DINT - |
hTxbDst |
bOK |
- BOOL |
|
DINT - |
hTxb |
|
|
|
|
|
|
|
Description:
This function adds the contents of the hTxb text buffer to the hTxbDst text buffer.
Inputs:
|
hTxbDst : DINT |
Handle of the text buffer to be completed
|
|
hTxb : DINT |
Handle of the text buffer to be added |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbAnsiToUtf8 |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
|
|
|
|
Description:
This function converts the whole contents of a text buffer from ANSI to UNICODE UTF8 encoding. Warning: this function may be time and memory consuming for large buffers.
Warning: UNICODE conversion may be not available on some operating systems
Inputs:
|
hTxb : DINT |
Handle of the text buffer |
Outputs:
|
bOK : BOOL |
TRUE if successful |
|
|
TxbUtf8ToAnsi |
|
|
|
DINT - |
hTxb |
bOK |
- BOOL |
|
|
|
|
|
Description:
This function converts the whole contents of a text buffer from UNICODE UTF8 to ANSI encoding. Warning: this function may be time and memory consuming for large buffers.
Warning: UNICODE conversion may be not available on some operating systems
Inputs:
|
hTxb : DINT |
Handle of the text buffer |
Outputs:
|
bOK : BOOL |
TRUE if successful |