REPLACING Phrase

When the REPLACING phrase is specified, the library text is copied, and each properly matched occurrence of operand-1 or partial-word-1 within the library text is replaced by the associated operand-2 or partial-word-2.

REPLACING Phrase - Format

operand-1, operand-2: Can be pseudo-text, an identifier, a function-identifier, a literal, or a COBOL word (except the word COPY).
Format
partial-word-1, partial-word-2: Can be a partial-word.

Related Information:

Replacement and Comparison Rules

In the discussion that follows, when the LEADING or TRAILING keyword of the REPLACING phrase is specified, each operand of the REPLACING phrase must be a partial-word. Otherwise, each operand can consist of one of the following items:

Pseudo-text
An identifier
A literal
A COBOL word (except the word COPY)
A Function-identifier

pseudo-text

Pseudo-text is a sequence of text words, comment lines, or separator spaces bounded by, but not including, the pseudo-text delimiter (==).

Pseudo-text-1 refers to pseudo-text when used for operand-1, and pseudo-text-2 refers to pseudo-text when used for operand-2.
Pseudo-text-1 can be one or more text words. It can consist solely of the separator comma or separator semicolon. pseudo-text-2 can be zero or more text words. It can consist solely of space characters, comment lines, or inline comments.

Pseudo-text-1 must contain at least one text word other than a separator comma or separator semicolon. Beginning and ending spaces are not included in the text comparison process, and multiple embedded spaces are considered to be a single space.

Pseudo-text-2 does not need to contain a text word; it may consist solely of space characters and/or comment lines.

For example, if library-member TEXTA consists of the following entries:

01  AA-DATA.
  10  AA-ID      PIC X(9).
  10  AA-TYPE    PIC X(1).

…the programmer can use the COPY statement to replace pseudo-text as follows:

    COPY TEXTA REPLACING ==01 AA-DATA== BY ==05 EE-DATA==.
                         ==AA-ID==      BY ==EE-ID==.
                         ==AA-TYPE==    BY ==EE-TYPE==.

…and the resulting text is treated as if it had been written as follows:

05  EE-DATA.
  10  EE-ID      PIC X(9).
  10  EE-TYPE    PIC X(1).

Pseudo-text-1 must contain, as a minimum, a text word. Since text words, by definition, are bounded by separators, pseudo-text cannot be used to select part of a word for replacement (for example, a prefix in a data name): a complete text word must be used in order to find a match. It is possible, however, to simulate the partial replacement of a text word held in the library text, by dividing it into two or more text words using separators that are used only for matching purposes, and not copied into the source program. For an example of this method, refer to Coding Examples.

IBM Extension

Pseudo-text-1 or pseudo-text-2 can contain DBCS or national character-strings. Such pseudo-text cannot be continued across lines.

End of IBM Extension

identifier

Can be defined in any Data Division section.

Can be a function-identifier.

literal

Can be numeric or nonnumeric.

IBM Extension

Can be a floating-point literal, DBCS literal, or national literal.

End of IBM Extension

word

May be any single COBOL word (except COPY).

For purposes of matching, when operand-1 is an identifier, literal, or word, it is treated, respectively, as pseudo-text containing only the identifier, literal, or word.

partial-word

A single text word that is bounded by, but not including, pseudo-text delimiters (==). Both characters of each pseudo-text delimiter must appear on one line. However, the text word within a partial-word can be continued.

The following rules apply to partial-word-1 and partial-word-2:

partial-word-1 consists of one text word.
partial-word-2 consists of zero or one text word.
partial-word-1 and partial-word-2 cannot be an alphanumeric literal, national literal, DBCS literal, or DBCS word.