SUBSTR Function

Purpose

Returns a string that is a copy of a specified part of the specified string.

Syntax

SUBSTR(s,i,j)

or

SUBSTR(s,i)

Parameters

s is a bit string, character string, or picture value. If s is not a string, it is converted to a bit string if it is binary or to a character string if it is decimal. i is an integer value indicating the first bit (if s is a bit string) or character of a substring within s; and j is an integer value indicating the length of the substring within s.

Description

The SUBSTR function returns a string that is a copy of a part of the string s starting at the character specified by i for a length specified by j. If j is not given, j = LENGTH(s)-i+1, that is, the remainder of the string s.

If an error occurs with the bif substring and -prefix stringrange is set, then the STRINGRANGE condition occurs.

Note: For more information, see STRINGRANGE Condition.

When the following condition is met, no error condition occurs:

i = Length(s) + 1 and j = 0

For example, no error condition occurs when length = 10, i = 11, and j = 0. This is the same behavior as with mainframe PL/I.

The program is in error if i < 1 or (i + j -1) > LENGTH(s) or j < 0. If the program is compiled with subscript checking enabled, these errors result in the STRINGRANGE condition; otherwise, these errors produce unpredictable results.

Note: If the STRINGRANGE condition is not handled, it is raised to ERROR.

For a description of the SUBSTR function's use as a pseudo-variable, and for the description of the ASSIGNMENT statement, see the section Assignment in the chapter Statements.

Examples

SUBSTR('ABCDE',2,2)   /* returns 'BC' */ 
SUBSTR('ABCDE',2)         /* returns 'BCDE' */

Restrictions

None.