The REPLACE Statement

General Rules

1. Pseudo-text-1 specifies the source text to be replaced by pseudo-text-2.
2. Partial-word-1 specifies the text to be replaced by partial-word-2.
3. The Format 2 REPLACE statement specifies that any text replacement currently in effect is discontinued.
4. A given occurrence of the REPLACE statement is in effect from the point at which it is specified until the next occurrence of the REPLACE statement or the end of the compilation unit, respectively.
5. Any REPLACE statements contained in a source unit are processed after the processing of any COPY statements contained in that source unit.
6. The text produced as a result of the processing of a REPLACE statement must contain neither a COPY statement nor a REPLACE statement.
7. The comparison operation to determine text replacement begins with the text immediately following the REPLACE statement and occurs in the following manner:
   1. Starting with the leftmost source text-word and the first pseudo-text-1 or partial-word-1, pseudo-text-1 or partial-word-1 is compared to an equivalent number of contiguous source text-words.
   2. Pseudo-text-1 matches the source text if, and only if, the order sequence of text-words that forms pseudo-text-1 is equal, character for character, to the ordered sequence of source text-words.

      When the LEADING phrase is specified, partial-word-1 matches the source text-word only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters starting with the leftmost character position of that source text-word. When the TRAILING phrase is specified, partial-word-1 matches the source text-word only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters, ending with the rightmost character position of that source text-word.

   3. The following rules apply for the purpose of matching:
      1. Each occurrence of a separator comma, semicolon, or space in pseudo-text-1 or in the source text is considered to be a single space. Each sequence of one or more space separators is considered to be a single space.
      2. Except when used in nonnumeric or national literals, each lower-case letter is equivalent to the corresponding upper-case letter as specified for the COBOL character set.
      3. text-words within a debugging line participate in the matching as if the "D" did not appear in the indicator area.
      4. Each operand and operator of a concatenation expression is a separate text-word.
   4. If no match occurs, the comparison is repeated with each next successive occurrence of pseudo-text-1 or partial-word-1, until either a match is found or there is no next successive occurrence of pseudo-text-1 or partial-word-1.
   5. When all occurrences of pseudo-text-1 or partial-word-1 have been compared and no match has occurred, the next successive source text-word is then considered as the leftmost source text-word, and the comparison cycle starts again with the first occurrence of pseudo-text-1 or partial-word-1.
   6. Whenever a match occurs between pseudo-text-1 and the source text, the corresponding pseudo-text-2 replaces the matched text in the source text.

      When a match occurs between partial-word-1 and the source text-word, the matched characters of that source text-word are either replaced by partial-word-2 or deleted when partial-word-2 consists of zero text-words.

      The source text-word immediately following the rightmost text-word that participated in the match is then considered as the leftmost source text-word. The comparison cycle starts again with the first occurrence of pseudo-text-1 or partial-word-1.

   7. The comparison operation continues until the rightmost text-word in the source text which is within the scope of the REPLACE statement has either participated in a match or been considered as a leftmost source text-word and participated in a complete comparison cycle.
8. Comment lines or blank lines occurring in either the source text or pseudo-text-1 are ignored for purposes of matching; and the sequence of text-words in the source text and in pseudo-text-1 is determined by the rules for reference format. See the topic Reference Format Representation in the chapter Language Fundamentals. Comment lines or blank lines in pseudo-text-2 are placed into the resultant source text unchanged whenever pseudo-text-2 is placed into the source text as a result of text replacement. A comment line or blank line in source text is not placed into the resultant source text if that comment line or blank line appears within the sequence of text-words that match pseudo-text-1.
9. Only after all COPY and REPLACE statements have been completely processed, can the syntactical correctness of the rest of the source code be determined.
10. text-words inserted into the source text as a result of processing a REPLACE statement are placed in the source text according to the rules for reference format. See the topic Reference Format in the chapter Language Fundamentals. When inserting text-words of pseudo-text-2 into the source text, additional spaces can be introduced only between text-words where a space (including the assumed space between source lines) already exists.
11. If additional lines are introduced into the source text as a result of the processing of REPLACE statements, the indicator area of the introduced lines contains the same character as the line on which the text being replaced begins, unless that line contains a hyphen, in which case the introduced line contains a space.

    If any literal within pseudo-text-2 is of a length too great to be accommodated on a single line without continuation to another line in the resultant source text and the literal is not being placed on a debugging line, additional continuation lines are introduced to contain the remainder of the literal. If replacement requires the continued literal to be continued on a debugging line, the compilation unit is in error.

12. The source text for which a REPLACE statement is in effect must not contain an EXEC HTML statement. Violation of this rule may result in unexpected behavior and syntax errors.