getNextToken()

The strLib.getNextToken() function is overloaded, so you can call the same function name with different configurations of parameters and return values. The following form of the function is preferred:

  strLib.getNextToken(
    source STRING | CHAR | DBCHAR | MBCHAR | UNICODE inOut,
    index INT inOut,
    delimiters STRING | CHAR | DBCHAR | MBCHAR | UNICODE in)
  returns (token STRING? | CHAR? | DBCHAR? | MBCHAR? | UNICODE?)

source

Input can be any value that is assignment compatible with any of the above types.

index

An INT variable that identifies the starting byte at which to begin searching for a token, given that the first byte in source has the value 1. If a token is found, the value in index is changed to the index of the first byte that follows the token. If no token is found, index is unchanged.

delimiters

One or more delimiter characters, with no characters separating one from the next. Make this a variable or literal of the same type as source.

token

If a token is found, it is returned as the same type as the type to which source was assigned. If no token is found, the function returns a null value.

result

An INT containing the number of characters in the token. The following values for result have special meaning:

null

The function did not find a token.

-1

The token was truncated during the copy to target.

The following form is available for compatibility with earlier versions:

  strLib.getNextToken(
    target CHAR | DBCHAR | MBCHAR | UNICODE inOut,
    source CHAR | DBCHAR | MBCHAR | UNICODE in,
    index INT inOut,
    substringLength INT inOut,
    delimiters STRING in)
  returns (result INT)

target

The target variable is where the function places a token (if it finds one). The target must be assignment compatible with at least one of the types shown.

source

Input must be the same type as target.

index

An INT variable that identifies the starting byte in source at which to begin searching for a token, given that the first byte has the value 1. If a token is found, the value in index is changed to the index of the first byte that follows the token. If no token is found, index is unchanged.

substringLength

An INT that indicates the number of bytes in the substring of the source under review. If a token is found, the value in substringLength is changed to the number of bytes in the substring that begins after the returned token.

delimiters

One or more delimiter characters, with no characters separating one from the next. Input can be any variable or expression that is assignment compatible with the STRING type.

result

An INT containing the number of characters in the token. The following values for result have special meaning:

0

The function did not find a token.

-1

The token was truncated during the copy to target.

In this example, the program uses the updated value of i to loop through a string and store the tokens in an array.

   commandLine string = "CALL PROG1 arg1,arg2";
   delimiters string = " ,"; // space and comma delimiters
   i int = 1;
   max int;
   tokens string[0];
   token string? = "";
 
   function main()
      max = strLib.byteLen(commandLine);
      
      // end processing when the getNextToken function returns a null
      while(i < max && token != null)
         token = StrLib.getNextToken(commandLine, i, delimiters);
         if (token != null)        
            tokens.appendElement(token);
         end
      end
    end