getNextToken()

The strLib.getNextToken() system function searches a substring for a token and copies that token to a target item.

Tokens are strings that are 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". The function fetches one token at a time, based on an index value that refers to the position of the token within the string.

Syntax

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 character that follows the token. If no token is found, index is set to one plus the length of the source string.
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.

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 character that follows the token. If no token is found, index is set to one plus the length of the source string.
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.

Example

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 readParms()
      max = strLib.byteLen(commandLine);
      while( i < max) // i is updated below
	       token = StrLib.getNextToken(commandLine, i, delimiters);
	       if (token != null)
		        tokens.appendElement(token);
        end // if
      end // while
   end // main

Error conditions

The preferred (three parameter) form of the function throws the egl.core.IndexOutOfBoundsException if any of the following are true:
  • index is less than 1.
  • index is greater than the length of the source string.
  • index is even and source is a UNICODE or DBCHAR type.
The compatibility (five parameter) form of the function throws a RuntimeException in the event of an error, unless you are running in V6 exception mode. You are running in V6 exception mode if all of the following conditions are true:
  • You set the v60ExceptionCompatibility program property to YES.
  • One of the following is true:
    • You have set the vgvar.handleSysLibErrors system variable to 1, or
    • You called the function from a try block.
In V6 exception mode, the following values are returned in sysVar.errorCode:
8
index is less than 1 or is greater than number of bytes in the substring under review.
12
substringLength is less than 0.
20
The value in index for a DBCHAR or UNICODE string refers to the middle of a double-byte character.
24
The value in substringLength for a DBCHAR or UNICODE string is odd (double-byte lengths must always be even).

Compatibility considerations

Table 1. Compatibility considerations
Platform Issue
JavaScript generation The function strLib.getNextToken() is not supported.

Feedback