REPLACING Phrase

In the discussion that follows, each operand may consist of one of the following:
  • Pseudo-text
  • An identifier
  • A literal
  • A COBOL word (except COPY)
  • Function-identifier

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

Read syntax diagramSkip visual syntax diagram
REPLACING Phrase - Format

>>-REPLACING---------------------------------------------------->

   .--------------------------------------------------.   
   V                                                  |   
>----+-==pseudo-text-1==-+--BY--+-==pseudo-text-2==-+-+--------><
     +-identifier-1------+      +-identifier-2------+     
     +-literal-1---------+      +-literal-2---------+     
     '-word-1------------'      '-word-2------------'     

Related Information:
pseudo-text-1, pseudo-text-2
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 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

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

End of IBM Extension
identifier-1, identifier-2
Can be defined in any Data Division section.

Can be a function-identifier.

literal-1, literal-2
Can be numeric or nonnumeric.
IBM Extension

IBM Extension Start of changeCan be a floating-point literal, DBCS literal, or national literal.End of change End of IBM Extension

End of IBM Extension
word-1, word-2
May be any single COBOL word (except COPY).

For purposes of matching, each identifier-1, literal-1, or word-1 is treated, respectively, as pseudo-text containing only identifier-1, literal-1, or word-1.