EGL Reference Guide for iSeries

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 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

strLib.compareStr

The system function strLib.compareStr compares two substrings in accordance with their ASCII or EBCDIC order at run time.



strLib.compareStr syntax diagram

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.

Definition considerations

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).

Example
  target = "123456";
  source = "34";
  result = 
    strLib.compareStr(target,3,2,source,1,2);
  // result = 0


Related reference
String handling (system words)

strLib.concatenate

The system function strLib.concatenate concatenates two strings.



strLib.concatenate syntax diagram

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:

  1. Any trailing spaces or nulls are deleted from the target string.
  2. The source string is appended to the string produced by step 1.
  3. 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.

Example
  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)

strLib.concatenateWithSeparator

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.



strLib.concatenateWithSeparator syntax diagram

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.

Example
  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)

strLib.copyStr

The system function strLib.copyStr copies one substring to another.



strLib.copyStr syntax diagram

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.

Definition considerations

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).

Example
  target = "120056";
  source = "34";
  strLib.copyStr(target,3,2,source,1,2);
  // target = "123456"


Related reference
String handling (system words)

strLib.findStr

The system function strLib.findStr searches for the first occurrence of a substring in a string.



strLib.findStr syntax diagram

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.

Definition considerations

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).

Example
  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)

strLib.getNextToken

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".



strLib.getNextToken syntax diagram

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.

Error conditions

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).

Example
  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)

strLib.setBlankTerminator

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.



strLib.setBlankTerminator syntax diagram

target
The target string item. If no null is found in target, the function has no effect.

Example
  strLib.setBlankTerminator(target);


Related reference
String handling (system words)

strLib.setNullTerminator

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.



strLib.setNullTerminator syntax diagram

target
String to be converted

The target string is searched for trailing spaces and nulls. Any spaces found are changed to nulls.

Definition considerations

The following value can be returned in sysVar.errorCode:

16
Last byte of string is not a space or null

Example
  strLib.setNullTerminator(myItem01);


Related reference
String handling (system words)

strLib.setSubStr

The system function strLib.setSubStr replaces each character in a substring with a specified character.



strLib.setSubStr syntax diagram

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.

Definition considerations

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)

Example
  strLib.setSubStr(target,12,5," ");


Related reference
String handling (system words)

strLib.strLen

The system function strLib.strLen returns the number of bytes in an item, excluding any trailing spaces and nulls.



strLib.strLen syntax diagram

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.

Example
  length = strLib.strLen(source);


Related reference
String handling (system words)


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]