String handling (system words)

String-handling system functions provide operations such as comparing or concatenating strings, each of which is a fixed-length sequence of bytes. For EGL, a string is an item with a type of CHAR, DBCHAR, HEX, MBCHAR, or UNICODE.

The meaning of a blank in a string varies by primitive type, as described in Data initialization.

A substring is a subset of a string and is identified by an index and a length. The index value identifies the starting byte of the substring within the item. The index value for the first byte in the item is 1. The length is the number of bytes in the substring.

To prevent substring definition from extending outside an item, the index must be a value between 1 and the number of bytes in the item, and the substring length must not extend beyond the end of the item that contains the substring. Lengths that are too long are adjusted so that the substring ends at the last byte of the item.

Functions can raise exception conditions, which your program can detected in these cases:

• The function is in a try block; or

• The function word sysVar.handleSysLibErrors is set to 1 when the program runs in VisualAge Generator compatibility mode.

The next table lists the string-handling system words.

System function and invocation	Description
strLib.compareStr result = strLib.compareStr (target, targetSubstringIndex, targetSubstringLength, source, sourceSubstringIndex, sourceSubstringLength)	Compares two substrings in accordance with their ASCII or EBCDIC order at run time and returns a value (-1, 0, or 1) to indicate which is greater.
strLib.concatenate result = strLib.concatenate (target, source)	Concatenates target and source; places the new string in target; and returns an integer that indicates whether target was long enough to contain the new string
strLib.concatenateWithSeparator result = strLib.concatenateWithSeparator (target, source, separator)	Concatenates target and source, inserting separator between them; places the new string in target; and returns an integer that indicates whether target was long enough to contain the new string
strLib.copyStr strLib.copyStr (target, targetSubstringIndex, targetSubstringLength, source, sourceSubstringIndex, sourceSubstringLength)	Copies one substring to another
strLib.findStr result = strLib.findStr (source, sourceSubstringIndex, sourceSubstringLength, searchString)	Searches for the first occurrence of a substring within a string
strLib.getNextToken result = strLib.getNextToken (target, source, sourceSubstringIndex, sourceStringLength, characterDelimiter)	Searches a string for the next token and copies the token to target
strLib.setBlankTerminator strLib.setBlankTerminator (target)	Replaces a null terminator and any subsequent characters in a string with spaces, so that a string value returned from a C or C++ program can operate correctly in an EGL-generated program
strLib.setNullTerminator strLib.setNullTerminator (target)	Changes all trailing spaces in a string to nulls
strLib.setSubStr strLib.setSubStr (target, targetSubstringIndex, targetSubstringLength, source)	Replaces each character in a substring with a specified character
strLib.strLen result = strLib.strLen (source)	Returns the number of bytes in an item, excluding any trailing spaces or nulls

Related concepts
Compatibility with VisualAge Generator

Related reference
Assignments
Data initialization
EGL statements
Exception handling
Function invocations
Text expressions
System words
System words in alphabetical order
try