Overview

The data type “Dynamic Text” allows the memory efficient processing of texts with a length of up to 4095 characters. Only the needed memory is allocated for every single text. In difference to the string data types with a fixed size a combination of short and long texts does not lead to a large amount of wasted memory. At present the “Dynamic Texts” are only stored in the RAM, i.e. they are only available during runtime. With the functions blocks of this library the “Dynamic Texts” are created by the conversion of standard texts and numeric values or the loading of HMI resource texts. Furthermore the function blocks support the processing and the display of the texts.

The memory blocks DYNTEXTDATA and DYNTEXTRAM form the base of the data type “Dynamic Text”. The elements of the first memory block are assigned to the outputs and the internal memories of the function blocks. They contain references to sections of the second memory block. The texts are stored in these sections. The offset and the size in bytes serve as reference information. They are displayed during the online observation in the signal line window.

Some distinctive features in comparison to the standard data types result from the described reference structure. So multiple elements of DYNTEXTDATA can refer to the same section of DYNTEXTRAM. And for the assignment of a longer text a new memory allocation is necessary, i.e. a new section must be found that fits for the size of the new text. In that case the values of offset and size are adapted in the belonging DYNTEXTDATA element.

If the used section could not be enlarged anymore and a new section was assigned, then DYNTEXTRAM gets fragmented, i.e. a gap occurs between two used sections. The gap is of course checked if it can be used for one of the following memory allocations. However it is not probable, that the needed memory amount exactly corresponds with the gaps size. Therefore the additional memory consumption for the fragmentation must be taken into account when the size of DYNTEXTRAM is defined in the resource request file.

The function block "Memory Diagnosis" is used to supervise the fragmentation. It provides on its outputs LONG values with the size of DYNTEXTRAM in bytes as well as the amount of the used memory and of the gaps. If a HIGH signal is connected with the BIT input then the defragmentation (garbage collection) is started. And the used sections will be moved one after another so that no gaps will remain anymore. The references in DYNTEXTDATA will be adapted accordingly. The runtime cost of the defragmentation depends on the number of the DYNTEXTDATA elements and the size of the sections that have to be moved. This should be kept in mind when implementing an automatic defragmentation strategy.

When a memory allocation fails, i.e. no free section with the needed size could be found, the offset and the size of the DYNTEXTDATA element are initialized with 0. The following operations and function block interpret this reference as an empty text and process it accordingly.


Append

Symbol: |
Description: | The output “result” provides a "Dynamic Text“, which was created by first copying the contents of “dtxt1” and then copying the contents of “dtxt2”. The length of the new text is limited on 4095 characters.
Signals: | Name | I/O | Type(s) | Function
 | dtxt1 | I | DYNTEXT | Leading text
 | dtxt2 | I | DYNTEXT | Trailing text
 | result | O | DYNTEXT | Result


Comparator

Symbol:

Description:

This function block compares the "Dynamic Texts" connected to its inputs. The compare relations ==, <>, >, >=, < and <= are possible. It is possible to distinguish the cases.

The comparison result is written to the output “result”. If the selected relation is fulfilled by the texts then a HIGH signal is set to the output.

Parameter:

The parameter dialog can be used to select the desired compare relation. Furthermore the case sensitivity of the comparison can be configured.

When using a target system with Unicode support the “Dynamic Texts” are coded in the UTF8 format. In that case the dialog option “ignore the case” includes only the normal Latin letters (a-z or A-Z).

Signals:

Name

I/O

Type(s)

Function

dtxt1

I

DYNTEXT

Text 1

dtxt2

I

DYNTEXT

Text 2

result

O

BIT

Comparison result

Visualization:

The selected relation and the case sensitivity will be display in the symbol.

Comment:

The parameter dialog can be opened only in the edit mode.


Converter

Symbol:

Description:

The function block converts a binary, numeric or text value to a "Dynamic Text” or vice versa. Furthermore it supports the copying of “Dynamic Texts”.

For the conversion of numeric values (beside BIT) a format string can be connected with the "format" input to get a special representation (such as a hexadecimal value or limited number of fractional digits). The standard conversion is performed when no format string is linked to the function block.

The conversion of single values is provided for all data types. An additional vector conversion can be performed only for the data type TEXT. The single texts of the vector are written one after another into the allocated memory without the terminating 0 for the conversion into a “Dynamic Text”. However the maximum length of 4095 characters can't be exceeded at this. The other way round the “Dynamic Text” is divided in partial texts with a terminating 0, which are written into the vector elements.

When using a target system with Unicode support the “Dynamic Texts” are coded in the UTF8 format. Therefore standard texts can be only loss-free assigned when they are conform to the UTF8 format. Otherwise characters with a value above 127 are replaced by question marks. The reverse conversion of “Dynamic Texts” into standard texts is also limited. Question marks will be written instead of Unicode characters with a value above 127.

Format string:

The format string, optionally used by converting numerical values, has to meet the target system specific conventions of the sprintf function. An overview of the most relevant features will be given here.

The format instruction always starts with the percentage symbol (%). It is followed by a number of optional parameters and ends with the specifier of the type of the input value. The parameters have to be given in the correct order and without a blank space between them, or they can't be interpreted correctly. The formal description is the following:

%[flags][width][.precision][length]type specifier

A valid example is: %.2f

It is possible to add any text before and/or after the format instruction. This has no influence on the conversion, but the text will be part of the output. It has to keep in mind, that the input "format" allows only a limited number of characters. It is recommended to use the Append function block to add more text.

Type specifier:

The type specifier is a necessary parameter and specifies the expected data type and the basic display of the input value.

- d or i – decimal integer values

- x – hexadecimal integer values

- f – floating point values

- e – scientific notation of floating point values using the e character

- g – using the most compact style for floating point values (f or e)

Flags:

The flags are the first parameter(s) and are used to control the justification of the output. These parameters are not so commonly used.

- Minus (-): Left align the result within the given field (default is right align)

- Plus (+): Enforce the display of a sign (even with positive values)

- Space: If no sign is going to be written, a blank space is inserted before the value.

Width:

The second optional parameter defines the minimum number of characters written. If the value to be printed is shorter than this number, the result is padded with blank spaces.

Precision:

This parameter starts always with a dot and is a number, which is interpreted according the specified type.

- Using d, i or x: defines the minimum number of characters to be written – if the value is shorter than this number, the result is padded with leading zeros.

- Using e or f: defines the number of digits after the decimal point – if necessary, it will be filled with trailing zeros

- Using g: Number of significant digits

Length:

The last optional parameter modifies the size of the data type and so the range of acceptable values. For our system there is no need for this parameter, except one.

- I64 (used with i or d:): 64 Bit integer value – is needed to cover the whole range of the LONGLONG data type

Parameter:

The parameter dialog can be used to select the data types of the input and the output. Furthermore the size of an output vector can be determined, when converting to TEXT.

Signals:

Name

I/O

Type(s)

Function

in

I

BIT, UCHAR, WORD, LONG, LONGLONG, FLOAT, DOUBLE, TEXT, DYNTEXT

Input signal

format

I

TEXT

Format (optional)

out

O

BIT, UCHAR, WORD, LONG, LONGLONG, FLOAT, DOUBLE, TEXT, DYNTEXT

Output signal

Visualization:

The selected data types are represented by the colors in the symbol.

Comment:

The parameter dialog can be opened only in the edit mode.


Create

Symbol:

Description:

The function block allocates a memory block for a "Dynamic Text". The value of the input signal “size” specifies the number of allocated bytes. The function block supports only sizes between 1 and 4096 bytes. In other cases a memory block with the size 0 is provided at the output “dtxt”.

After the allocation the text of the input “init” is copied into the memory block. The remaining bytes in the memory block are initialized with 0. When the initialization text plus the terminating 0 is too long for the memory block, only a part of the text is copied.

Signals:

Name

I/O

Type(s)

Function

init

I

DYNTEXT

Initialization text

size

I

WORD

Size

dtxt

O

DYNTEXT

Result


Find

Symbol:

Description:

The "Dynamic Text" connected with the input “dtxt” is searched for the string that is assigned to the input “substr”. The starting point for the search is defined by the input “start”. After the search the position of the first character of the found sub string is written to the output “index”. The return value -1 indicates that the sub string could not be found. The indexing of the “Dynamic Text” starts with 0 and is independent of the encoding always byte-by-byte.

The search can be case sensitive or insensitive.

Parameter:

The parameter dialog can be used to select, whether the function block distinguishes or ignores the case.

When a text in UTF8 format is searched, the dialog option “ignore the case” includes only the normal Latin letters (a-z or A-Z).

Signals:

Name

I/O

Type(s)

Function

dtxt

I

DYNTEXT

Text

sSubstr

I

DYNTEXT

Substring to find

start

I

WORD

Start index

index

O

Word

Position of the found string

Visualization:

The case sensitivity is indicated by the superior C in the function block symbol.

Comment:

The dialog can be opened only in the edit mode.


Get[i]

Symbol:

Description:

A character of the "Dynamic Text" assigned to the input “dtxt” is selected with the input “index” and written to the output “char”. The index 0 references the first character in the text. The output is set to 0 when the index exceeds the memory block of the “Dynamic Text”.

When using a target system with Unicode support the “Dynamic Texts” are coded in the UTF8 format. Then a Unicode character can consist of up to 3 consecutive bytes, which can be read only one by one with this function block.

Signals:

Name

I/O

Type(s)

Function

dtxt

I

DYNTEXT

Text

index

I

WORD

Position

char

O

UCHAR

Character


Load Text Resource

Symbol:

Description:

A HMI resource text is selected with the input values. It is copied into a newly created "Dynamic Text" that is provided at the output “dtxt”. If no text resource could be found for the connected identifier, then the function block outputs an empty text.

When using a target system with Unicode support the resource texts first will be encoded in the UTF8 format and after that they will be copied into the “Dynamic Texts”.

Signals:

Name

I/O

Type(s)

Function

idlang

I

WORD

Language resource (ID)

idtext

I

WORD

Text resource (ID)

dtxt

O

DYNTEXT

Text


Length

Symbol: |
Description: | The length of the connected "Dynamic Text” is determined by counting the contained characters up to the terminating 0. When the “Dynamic Text” is encoded in the UTF8 format also every single byte is counted as a character.
Signals: | Name | I/O | Type(s) | Function
 | dtxt | I | DYNTEXT | Text
 | length | O | WORD | Length


Memory Diagnosis

Symbol:

Description:

The function block “Memory Diagnosis” is used to supervise the memory with the “Dynamic Texts”. Its outputs provide LONG values with the total size of the memory ("memsize") and the number of used bytes ("used"). Gaps arise during the runtime when the length of some “Dynamic Texts” changes. The total size of these unused sections between used ones is written to the output "fragment". This value indicates the degree of the memory fragmentation.

A HIGH signal at the input “garbcol” starts the defragmentation. In that process the memory sections with the texts are moved one after another so that no gaps remain. Problems with the memory allocation for more or longer “Dynamic Texts” can be solved by this operation. However the runtime costs can be high. It depends on the number of texts and the degree of the fragmentation.

More information about the memory architecture of the “Dynamic Texts” and the usage of the diagnosis function block can be found in chapter "Overview".

Signals:

Name

I/O

Type(s)

Function

garbcol

I

BIT

Starts the defragmentation

memsize

O

LONG

Size of DYNTEXTRAM (in bytes)

used

O

LONG

Size of used memory (in bytes)

fragmnt

O

LONG

Sum of the memory gaps (in bytes)


Mid

Symbol:

Description:

The values of the inputs “start” and “count” define the starting position and the length of the text part of the "Dynamic Text" that is connected with the input “dtxti”. The text part is copied into a new “Dynamic Text” that is provided via the output “dtxto”. The index 0 references the first character in the input text.

When dealing with “Dynamic Texts” in the UTF8 format the values for the starting position and the length are nevertheless counted in bytes.

Signals:

Name

I/O

Type(s)

Function

dtxti

I

DYNTEXT

Input text

start

I

WORD

Index

count

I

WORD

Length of the text part

dtxto

O

DYNTEXT

Text part


Set[i]

Symbol:

Description:

At the position, which is set at the input “index”, the character assigned to the input “char” is written into the "Dynamic Text", which is connected with the input “dtxt”. The output “result” provides a HIGH signal after the successful writing. The index 0 references the first character. The character is not written when the index exceeds the memory block of the “Dynamic Text”. Furthermore the last byte that is reserved for the terminating 0 can't be changed with this function block.

When using a target system with Unicode support the “Dynamic Texts” are coded in the UTF8 format. Only single bytes can be set with this function block. Therefore up to three function block calls can be needed to write a Unicode character.

Signals:

Name

I/O

Type(s)

Function

dtxt

I/O

DYNTEXT

Text

char

I

UCHAR

Character

index

I

WORD

Position

result

O

BIT

Write flag


Switch

Symbol:

Description:

Depending on the BIT signal of the input “select” the "Dynamic Text" reference from the input “dtxt1” or “dtxt2” is copied to the output “result”. The function block creates no new “Dynamic Text”.

When a LOW signal is connected then the reference of “dtxt1” is copied. Otherwise the reference of “dtxt2” is written to “result”.

Signals:

Name

I/O

Type(s)

Function

dtxt1i

I

DYNTEXT

Input text 1

dtxt2i

I

DYNTEXT

Input text 2

select

I

BIT

Switch

result

O

DYNTEXT

Result


Visualisation

Symbol:

Description:

The function block “Visualisation” displays during the online observation mode the buffered content of the "Dynamic Text" that is connected to its input.

When processing the user program the “Dynamic Texts” can permanently change their size. Again and again new memory is allocated and old one is freed. The addresses of the texts change all the time and an error-free online visualisation is nearly impossible. Therefore an indirect visualisation is used for the “Dynamic Texts”. The target function of the visualisation block copies a part of the connected “Dynamic Text” into a buffer. This buffer is cyclically read by the programming system and the content is displayed in the function block.

Parameter:

The parameter dialog can be used to change the width and the height of the function block. . If only the width is increased, more characters can be displayed. By changing the height the font size is automatically adapted, i.e. the displayed characters get bigger when the function block height is increased. The buffer size and the starting position of the text part are configured in the parameter dialog. The buffer size is limited to 128 bytes.

When using a target system with Unicode support the “Dynamic Texts” are coded in the UTF8 format. The display of the decoded Unicode texts or of the raw data is selected with the dialog option “Decode UTF8 texts”. Invalid texts are always displayed in the raw format.

Signals:

Name

I/O

Type(s)

Function

dtxt

I

DYNTEXT

Text