SUBSTRING( ) Output substring

Domain: String functions

The SUBSTRING( ) function extracts a substring from the specified string. The start position of the substring and its length are determined by means of the input parameters.

Format

SUBSTRING( )

SUBSTR( )

STRING = string_expression

,START = 1 / arithm_expressionr₁

,LENGTH = *REST-LENGTH / arithm_expression₂

Result type

STRING

Input parameters

STRING = string_expression
Designates the input string from which a substring is to be extracted.

START = 1 /arithm_expression₁
Designates the start position of the substring, i.e. first character in the substring; “arithm_expression₁” is a positive INTEGER and must not be greater than the length of the input string. The default for “arithm_expression₁” is 1. If “arithm_expression₁” does not designate a valid start position in the input string, the null string is returned.

LENGTH =
Length of the substring.

LENGTH = *REST-LENGTH
Implicitly designates the length of the substring as the rest length, starting at the character position specified by START (string length - “arithm_expression₁” + 1 = rest length).

LENGTH = arithm_expression₂
Explicitly designates the length of the substring; if the length entry is too large, LENGTH = *REST-LENGTH applies implicitly.

Result

Substring of the input string with the length specified by LENGTH.

Null string (’’) means:
START = “arithm_expression₁” was not a valid start position, or LENGTH = 0 applied implicitly or explicitly.

Error messages

SDP0412     START POSITION OUT OF RANGE
SDP0414     WARNING: *REST-LENGTH VALUE USED FOR LENGTH OPERAND

Example

/A = 'ABCDEFGH'
/B = SUBSTRING(STRING = A, START = 2, LENGTH = 4)
/SHOW-VARIABLE B
B = BCDE
/C = 2
/B = SUBSTRING(STRING = A, START = C)
/SHOW-VARIABLE B
B = BCDEFGH
/D = 4
/B = SUBSTRING(STRING = A, LENGTH = D)
/SHOW-VARIABLE B
B = ABCD
/B = SUBSTRING(STRING = A, START = 9)
SDP0412  START POSITION OUT OF RANGE
/SHOW-VARIABLE B
B =

See  "VERIFY( ) Verify strings" for another example.