%SUBST (Get Substring)

%SUBST(string:start {:length {: *NATURAL | *STDCHARSIZE }})

%SUBST returns a portion of argument string. It may also be used as the result of an assignment with the EVAL operation code.

The start parameter represents the starting position of the substring.

The length parameter represents the length of the substring. If it is not specified, the length is the length of the string parameter less the start value plus one.

The string must be character, graphic, or UCS-2data. Starting position and length may be any numeric value or numeric expression with zero decimal positions. The starting position must be greater than zero. The length may be greater than or equal to zero.

When the string parameter is varying length, the values of the other parameters are checked against the current length, not the maximum length.

The third or fourth parameter can be *NATURAL or *STDCHARSIZE to override the current CHARCOUNT mode for the statement. If this parameter is specified, it must be the last parameter.
  • Specify *NATURAL to indicate that %SUBST operates in CHARCOUNT NATURAL mode. The start position and length are measured in characters rather than bytes or double bytes. For example, if the base string is a UTF-8 string with the value 'ábç12', a start position of 3 refers to 'ç' because it is the third character.
  • Specify *STDCHARSIZE to indicate that %SUBST operates in CHARCOUNT STDCHARSIZE mode. In the previous example, with CHARCOUNT STDCHARSIZE mode, a start position of 3 refers to 'b' because it is the third byte. Characters 'á' and 'ç' are 2-byte characters.
See Processing string data by the natural size of each character and Character Data Type.
Note: %SUBST can also operate in CHARCOUNT NATURAL mode due to the /CHARCOUNT compiler directive or the CHARCOUNT Control keyword.

When specified as a parameter for a definition specification keyword, the parameters must be literals or named constants representing literals. When specified on a free-form calculation specification, the parameters may be any expression.

For more information, see String Operations or Built-in Functions.