Built-in Functions › REPLACE

REPLACE

Purpose

Returns a string that results from replacing, in a string value, each occurrence of a specified search string with a specified replacement string.

Syntax

►►─── REPlace ───── ( string, search-string ──┬───────────────────────┬─ ) ───►◄
                                              └─ ,replacement-string ─┘

Parameters

string

Specifies the string value on which the replace function is performed.

String can be:

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

search-string

Specifies the string that the replace function searches for within the string value.

Search-string can be:

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

replacement-string

Specifies the string that replaces each occurrence of search-string in the string value.

Replacement-string can be:

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

If replacement-string is not specified, each occurrence of search-string in the string value is deleted.

Usage

The replacement string can be a different length than the search string; if this is the case, the target string value is adjusted appropriately for each replacement.

The resulting string value cannot be greater than 1,024 characters. Excess characters are truncated.

Example

In the following example, the replace function is used to replace all occurrences of BB with XXX in the string 'AABBCCBBBDD':

Statement:
    MOVE REPLACE('AABBCCBBBDD','BB','XXX') TO WK-STRING.
Returned string:
    'AAXXXCCXXXBDD'

A further example of the replace function is provided in SUBSTRING.