Built-in Functions › INSERT

INSERT

Purpose

Returns the string that results from a specified string being inserted into a string value starting at a specified position.

Syntax

►►─── INSert ( string, insertion-string, starting-position ) ─────────────────►◄

Parameters

string

Specifies the string into which insertion-string is inserted.

String can be:

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

insertion-string

Specifies the string that is inserted into string.

Insertion-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 position at which insertion will begin.

Starting-position can be:

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

Starting-position is in a range from 1 to the length of string plus 1.

Usage

Considerations

• If starting-position is 1 or less, insertion starts at the beginning of the string value.
• If starting-position is greater than the length of string, insertion starts at the end of the string value.

Example

In the following example, the INSERT function is used with the SUBSTRING function to insert the first six letters of the string contained in EMP-LNAME (PIC X(20)) into the string '**', starting at position 2:

Initial value:
    EMP-LNAME: 'PARKINSON          '
Statement:
    MOVE INSERT('**',SUBS(EMP-LNAME,1,6),2) TO WK-STRING.
Returned string:
    '*PARKIN*'