The declared size of the NCHAR identifies UTF-8 characters. A UTF-8 character encoded character can have a physical size up to four bytes. Therefore, each NCHAR character requires a maximum of four bytes and the NCHAR variable physical size in bytes is four times the number of UTF-8 characters declared.
The Physical Length is set to the declared size and both the Length Pointer and Form Pointer are set to zero indicating a Null String.If the NCHAR is an initialized array, the Form Pointer is set to one and the Length Pointer is set to the last UTF-8 character of the initialized contents (that may be less than the Physical Length) for each appropriate array item.
NCHAR variables are blank filled unless an initialized array.
NCHAR variables can have a declared size up to eight megabytes (8MB). When a NCHAR size larger than 16,383 is specified, the NCHAR data construct is implemented as an auto load NCHAR variable. This helps to keep the object code file size as small as possible. See the compiler option to change the default auto load NCHAR variable size. If a user application requires a NCHAR data variable with a size larger than 8MB, a NCHAR pointer can be used and an DMAKE creates a NCHAR with a size up to 500MB (536,870,911 value). This size is limited by the OS memory allowed for the PLB program space. The runtime 'm' or 'MV' command line options increases the PLB program memory size. Note that:
If WRITE operations are performed using very large NCHAR variables, FILE variables with small buffer sizes should be avoided because it can result in a lengthy IO operation.
If a WRITE operation is performed using a very large NCHAR variable, opening a FILE variable in a SHARENF or EXCLUSIVE mode can give the best performance.
NCHAR variables can only contain valid UTF-8 encoded characters. An F14 format error occurs if invalid UTF-8 characters are being moved/stored in a NCHAR variable.
The processing for the auto load NCHAR pointers only allocates a NCHAR pointer when the variable is first used and not allocated when the PLC program is loaded. Therefore, there is no wasted memory allocations used for auto load NCHAR pointers that are never used in a program.
Example:
In this example, the 'B' pointer is not used. Therefore, there is never any memory allocated for the 1000 character variable. Also, the memory allocation for the 'A' variable only occurs when the variable first used in the program.
The processing for the static auto load NCHAR variables only allocates memory when the variable is first used and not when the PLC program is loaded. Thus, there is no wasted memory allocations used for auto load NCHAR variables that are never used. Also, note that the PLBCMP compiler gives a complication error when a static auto load NCHAR variable is encountered in an instruction that uses a pointer as a destination.
Example:
The memory allocation for the 'B' variable only occurs when the variable first used in the program.
UTF-8 string literals that initialize a NCHAR array must be enclosed in quotes and surrounded by parentheses, while valid control codes need only be surrounded by parentheses. Single byte control codes can only have a value from 0 to 127 to be a valid UTF-8 character.
Multi-dimension arrays (format 4) are supported up to a maximum of fourteen dimensions (three in ANSI mode).
The ^ denotes a Pointer Variable.
If the % form is used, the data item is placed in the Global Data Area. The variable is then available to other programs that also declared it with the percent form. Global Data Items are available with PLBCMP only.
If the %% form is used, the data label is placed in the Global Data Area but no initialization takes place if it has not already been defined in the Global Data Area. If an array datalabel is placed in the Global Data Area, when initialized, it must have the same number of elements in the array. Global Data Items are available with PLBCMP only.
If the * form is used, the data item is in common with other programs and all of the rules of COMMON must be followed.
If an array is defined, each element may have a label.
Formats
(12) through (16) are only valid when the SWDBCmode of the compiler is enabled (-zc=3). Even though NCHAR
is not a SWDBC supported data construct, these syntax formats are not being restricted using the Sunbelt
compiler. Format (12) provides another array initialization syntax.
Format
(13) provides a NCHAR syntax for an array of NCHAR pointers.
Format
(14) provides another NCHAR array pointer construct. The NCHAR array pointer can contain an address of
a NCHAR array.
Format
(15) provides a two-dimensioned NCAHR array pointer construct. The two-dimensioned NCHAR array pointer
can contain an address of a two-dimensioned NCHAR array.
Format
(16) provides a three-dimensioned NCHAR array pointer construct. The three-dimensioned NCHAR array pointer
can contain an address of a three-dimensioned NCHAR array.
