Built-in Functions › SUBSTRING

SUBSTRING

Purpose

Returns the substring of a string value, starting from a specified position and continuing for a specified length.

Syntax

►►─┬─ SUBSTRING ─┬─ ( string, starting-position ─┬───────────┬─ ) ────────────►◄
   └─ SUBStr ────┘                               └─ ,length ─┘

Parameters

string

Specifies the string value from which the substring is taken.

String can be:

• A string literal, enclosed in single quotation marks
• The name of a user-defined variable data field containing the string

starting-position

Specifies the numeric starting position of the substring within the string value.

Starting-position can be:

• An arithmetic expression
• The name of a user-defined variable data field
• A user-supplied numeric literal

Starting-position must be positive and not greater than the length of string.

length

Specifies the numeric length of the substring within the string value.

Length can be:

• An arithmetic expression
• The name of a user-defined variable data field
• A user-supplied numeric literal

The sum of starting-position and length, minus 1, cannot be greater than the length of string.

If length is not specified, the substring is taken from the specified starting position to the end of the string value.

Example 1: Extracting a substring

In the following example, the substring function is used to extract a substring of EMP-LNAME (PIC X(20)), starting at position 4 and continuing for a length of 3:

Initial value:
    EMP-LNAME:  'SMITH               '
Statement:
    MOVE SUBSTR(EMP-LNAME,4,3) TO WK-NAME.
Returned string:
    'TH '

Example 2: Replacing a leading zero

In the next example, the substring function is used in conjunction with the verify and concatenate functions to replace each leading zero in a number stored in WK-AMT (PIC X(10)) with an asterisk (*):

Initial value:
    WK-AMT: '000500.43 '
Statements:
    MOVE VERIFY(WK-AMT,'0') TO WK-START-POSITION.
    IF WK-START-POSITION GT 1
      THEN
        MOVE CON(REP(SUBS(WK-AMT,1,WK-START-POSITION - 1),'0','*'),
                 SUBS(WK-AMT,WK-START-POSITION)) TO WK-EDITED.


Returned value from verify function:                      4
Returned string from first substring function:         '000'
Returned string from replace function:                 '***'
Returned string from second substring function:    '500.43 '
Returned string from concatenate function:      '***500.43 '

The string '***500.43 ', with a length of ten characters, is moved to the field WK-EDITED. Note that the MOVE VERIFY command in the above example locates the position of the first nonzero character in WK-AMT.

Another example of the substring function is provided in INSERT.