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

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)