EGL Reference Guide for iSeries
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
String expressions
System words
System words in alphabetical order
try
The system function strLib.compareStr compares two substrings
in accordance with their ASCII or EBCDIC order at run time.

- result
- Numeric item that receives one of the following values (defined as type
INT or the equivalent: type BIN with length 9 and no decimal places)
returned by the function:
- -1
- The substring based on target is less than the substring based
on source
- 0
- The substring based on target is equal to the substring based
on source
- 1
- The substring based on target is greater than the substring
based on source
- target
- String from which a target substring is derived. Can be an item or
a literal.
- targetSubStringIndex
- Identifies the starting byte of the substring in target, given
that the first byte in target has the index value 1. This
index can be an integer literal. Alternatively, this index can be an
item defined as type INT or the following equivalent: type BIN with
length 9 and no decimal places.
- targetSubStringLength
- Identifies the number of bytes in the substring that is derived from
target. The length can be an integer literal.
Alternatively, this index can be an item defined as type INT or the following
equivalent: type BIN with length 9 and no decimal places.
- source
- String from which a source substring is derived. Can be an item or
a literal.
- sourceSubStringIndex
- Identifies the starting byte of the substring in source, given
that the first byte in source has the index value of 1. This
index can be an integer literal. Alternatively, this index can be an
item defined as type INT or the following equivalent: type BIN with
length 9 and no decimal places.
- sourceSubStringLength
- Identifies the number of bytes in the substring that is derived from
source. The length can be an integer literal.
Alternatively, this index can be an item defined as type INT or the following
equivalent: type BIN with length 9 and no decimal places.
A byte-to-byte binary comparison of the substring values is
performed. If the substrings are not the same length, the shorter
substring is padded with spaces before the comparison.
The following values are returned in
sysVar.errorCode:
- 8
- Index less than 1 or greater than string length.
- 12
- Length less than 1.
- 20
- Invalid double-byte index. Index for a DBCHAR or UNICODE string
points to middle of double-byte character
- 24
- Invalid double-byte length. Length in bytes for a DBCHAR or UNICODE
string is odd (double-byte lengths must always be even).
target = "123456";
source = "34";
result =
strLib.compareStr(target,3,2,source,1,2);
// result = 0
Related reference
String handling (system words)
The system function strLib.concatenate concatenates two
strings.

- result
- Numeric item that receives one of the following values (defined as type
INT or the equivalent: type BIN with length 9 and no decimal places)
returned by the function:
- -1
- Concatenated string is too long to fit in the target item and the string
was truncated, as described later
- 0
- Concatenated string fits in the target item
- target
- Target item
- source
- Source item or literal
When two strings are concatenated, the following occurs:
- Any trailing spaces or nulls are deleted from the target
string.
- The source string is appended to the string produced by
step 1.
- If the string produced by step 2 is longer than the target string item, it is
truncated. If it is shorter than the target item, it is padded with
blanks.
phrase = "and/ "; // CHAR(7)
or = "or";
result =
strLib.concatenate(phrase,or);
if (result = 0)
print phrase; // phrase = "and/or "
end
Related reference
String handling (system words)
The system function strLib.concatenateWithSeparator
concatenates two strings, inserting a separator string between them. If
the initial length of the target string is zero (not counting trailing blanks
and nulls), the separator is omitted and the source string is copied to the
target string.

- result
- Numeric item that receives one of the following values (defined as type
INT or the equivalent: type BIN with length 9 and no decimal places)
returned by the function: :
- 0
- Concatenated string fits in target item.
- -1
- Concatenated string is too long to fit in the target item and the string
was truncated, as described later
- target
- Target item.
- source
- Source item or literal.
- separator
- Separator item or literal.
Trailing spaces and nulls are truncated from target; then,
the separator string and source are appended to the
truncated value. If the concatenation is longer than the target allows,
truncation occurs. If the concatenation is shorter than the target
allows, the concatenated value is padded with spaces.
phrase = "and"; // CHAR(7)
or = "or";
result =
strLib.concatenateWithSeparator(phrase,or,"/");
if (result = 0)
print phrase; // phrase = "and/or "
end
Related reference
String handling (system words)
The system function strLib.copyStr copies one substring to
another.

- target
- String from which a target substring is derived. Can be an item or
a literal.
- targetSubstringIndex
- Identifies the starting byte in target, given that the first
byte in target has the value 1. This index can be an integer
literal. Alternatively, this index can be an item defined as type INT
or the following equivalent: type BIN with length 9 and no decimal
places.
- targetSubstringLength
- Identifies the number of bytes in the substring that is derived from
target. The length can be an integer literal.
Alternatively, the length can be an item defined as type INT or the following
equivalent: type BIN with length 9 and no decimal places.
- source
- String from which a source substring is derived. Can be an item or
a literal.
- sourceSubstringIndex
- Identifies the starting byte of the substring in source, given
that the first byte in source has the value 1. This index
can be an integer literal. Alternatively, this index can be an item
defined as type INT or the following equivalent: type BIN with length 9
and no decimal places.
- sourceSubstringLength
- Identifies the number of bytes in the substring that is derived from
source. The length can be an integer literal.
Alternatively, the length can be an item defined as type INT or the following
equivalent: type BIN with length 9 and no decimal places.
If the source is longer than the target, the source is truncated. If
the source is shorter than the target, the source value is padded on the right
with spaces.
The following values are returned in
sysVar.errorCode:
- 8
- Index less than 1 or greater than string length.
- 12
- Length less than 1.
- 20
- Invalid double-byte index. Index for a DBCHAR or UNICODE string
points to middle of double-byte character.
- 24
- Invalid double-byte length. Length in bytes for a DBCS or UNICODE
string is odd (double-byte lengths must always be even).
target = "120056";
source = "34";
strLib.copyStr(target,3,2,source,1,2);
// target = "123456"
Related reference
String handling (system words)
The system function strLib.findStr searches for the first
occurrence of a substring in a string.

- result
- Numeric item that receives one of the following values (defined as type
INT or the equivalent: type BIN with length 9 and no decimal places)
returned by the function:
- -1
- Search string was not found
- 0
- Search string was found
- source
- String from which a source substring is derived. Can be an item or
a literal.
- sourceSubstringIndex
- Identifies the starting byte for the substring in source, given
that the first byte in source has the index value of 1. This
index can be an item defined as type INT or the following equivalent:
type BIN with length 9 and no decimal places.
- sourceStringLength
- Identifies the number of bytes in the substring that is derived from
source. This index can be an item defined as type INT or the
following equivalent: type BIN with length 9 and no decimal
places.
- searchString
- String item or literal to be searched for in the source substring.
Trailing blanks or nulls are truncated from the search string before searching
begins.
If searchString is found in the source substring,
sourceSubstringIndex is set to indicate its location (the byte of
the source where the matching substring begins). Otherwise,
sourceSubstringIndex is not changed.
The following values are returned in sysVar.errorCode:
- 8
- Index less than 1 or greater than string length.
- 12
- Length less than 1.
- 20
- Invalid double-byte index. Index for a DBCHAR or UNICODE string
points to middle of double-byte character.
- 24
- Invalid double-byte length. Length in bytes for a DBCHAR or UNICODE
string is odd (double-byte lengths must always be even).
source = "123456";
sourceIndex = 1
sourceLength = 6
search = "34";
result =
strLib.findStr(source,sourceIndex,sourceLength,"34");
// result = 0, sourceIndex = 3
Related reference
String handling (system words)
The system function strLib.getNextToken searches a substring
for a token and copies that token to a target item.
Tokens are strings separated by delimiter characters. For example,
if the characters space (" ") and comma (",") are defined as delimiters, the
string "CALL PROGRAM ARG1,ARG2,ARG3" can be broken down into the
five tokens "CALL", "PROGRAM", "ARG1",
"ARG2", and "ARG3".

- result
- An item defined as type INT or the following equivalent: type BIN
with length 9 and no decimal places. The value is one of these:
- +n
- Number of characters in the token. The token is copied from the
substring under review to the target item.
- 0
- No token was in the substring under review.
- -1
- The token was truncated when copied to the target item.
- target
- Target item of type CHAR, DBCHAR, HEX, MBCHAR, or UNICODE.
- source
- Source item of type CHAR, DBCHAR, HEX, MBCHAR, or UNICODE. May be a
literal of any of those types other than UNICODE.
- sourceSubstringIndex
- Identifies the starting byte at which to begin searching for a delimiter,
given that the first byte in source has the value 1.
sourceSubstringIndex can be an item defined as type INT or the
following equivalent: type BIN with length 9 and no decimal
places. If a token is found, the value in
sourceSubstringIndex is changed to the index of the first character
that follows the token.
- sourceSubstringLength
- Indicates the number of bytes in the substring under review.
sourceSubstringLength can be an item defined as type INT or the
following equivalent: type BIN with length 9 and no decimal
places. If a token is found, the value in
sourceSubstringLength is changed to the number of bytes in the
substring that begins after the returned token.
- characterDelimiter
- One or more delimiter characters, with no characters separating one from
the next. May be an item of type CHAR, DBCHAR, HEX, MBCHAR, or
UNICODE. May be a literal of any of those types other than
UNICODE.
You can invoke a sequence of calls to retrieve each token in a substring
without resetting the values for sourceSubstringIndex and
sourceSubstringLength, as shown in a later example.
The following values are returned in
sysVar.errorCode:
- 8
- sourceSubstringIndex is less than 1 or is greater than number
of bytes in the substring under review.
- 12
- sourceSubstringLength is less than 1.
- 20
- The value in sourceSubstringIndex for a DBCHAR or UNICODE
string refers to the middle of a double-byte character.
- 24
- The value in sourceSubstringLength for a DBCHAR or UNICODE
string is odd (double-byte lengths must always be even).
Function myFunction()
myVar myStructurePart;
myRecord myRecordPart;
i = 1;
myVar.mySourceSubstringIndex = 1;
myVar.mySourceSubstringLength = 29;
while (myVar.mySourceSubstringLength > 0)
myVar.myResult = strLib.getNextToken( myVar.myTarget[i],
"CALL PROGRAM arg1, arg2, arg3",
myVar.mySourceSubstringIndex,
myVar.mySourceSubstringLength, " ," );
if (myVar.myResult > 0)
myRecord.outToken = myVar.myTarget[i];
add myRecord;
set myRecord empty;
i = i + 1;
end
end
end
Record myStructurePart
01 myTarget CHAR(80)[5];
01 mySource CHAR(80);
01 myResult myBinPart;
01 mySourceSubstringIndex INT;
01 mySourceSubstringLength BIN(9,0);
01 i myBinPart;
end
Record myRecordPart
serialRecord:
fileName="Output"
end
01 outToken CHAR(80);
end
Related reference
String handling (system words)
The system function strLib.setBlankTerminator changes a null
terminator and any subsequent characters to spaces.
strLib.setBlankTerminator changes a string value returned from
a C or C++ program to a character value that can operate correctly in an EGL
program.

- target
- The target string item. If no null is found in target,
the function has no effect.
strLib.setBlankTerminator(target);
Related reference
String handling (system words)
The system function strLib.setNullTerminator changes all
trailing spaces in a string to nulls. You can use
strLib.setNullTerminator to convert an item before passing it
to a C or C++ program that expects a null-terminated string as an
argument.

- target
- String to be converted
The target string is searched for trailing spaces and nulls. Any
spaces found are changed to nulls.
The following value can be returned in
sysVar.errorCode:
- 16
- Last byte of string is not a space or null
strLib.setNullTerminator(myItem01);
Related reference
String handling (system words)
The system function strLib.setSubStr replaces each character
in a substring with a specified character.

- target
- Item that is changed.
- targetSubStringIndex
- Identifies the starting byte of the substring in target, given
that the first byte in target has the index value of 1. This
index can be an integer literal. Alternatively, this index can be an
item defined as type INT or the following equivalent: type BIN with
length 9 and no decimal places.
- targetSubstringLength
- Identifies the number of bytes in the substring that is derived from
target. The length can be an integer literal.
Alternatively, the length can be an item defined as type INT or the following
equivalent: type BIN with length 9 and no decimal places.
- source
- If the target item is CHAR, MBCHAR, or HEX, the source item must be a
one-byte CHAR, MBCHAR, or HEX item or a CHAR literal. If the target is
a DBCHAR or UNICODE item, the source must be a single-character DBCHAR or
UNICODE item.
The following values are returned in sysVar.errorCode:
- 8
- Index less than 1 or greater than string length
- 12
- Length less than 1
- 20
- Invalid double-byte index. Index for a DBCHAR or UNICODE string
points to middle of double-byte character
- 24
- Invalid double-byte length. Length in bytes for a DBCHAR or UNICODE
string is odd (double-byte lengths must always be even)
strLib.setSubStr(target,12,5," ");
Related reference
String handling (system words)
The system function strLib.strLen returns the number of bytes
in an item, excluding any trailing spaces and nulls.

- length
- An item defined as type INT or the following equivalent: type BIN
with length 9 and no decimal places.
- source
- String item or literal to be measured.
length = strLib.strLen(source);
Related reference
String handling (system words)
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.