Replacement rules

This topic introduces detailed rules for replacement.

  • The sequence of text words in the source text, pseudo-text-1, and partial-word-1 is determined by the rules for reference format. For more information, see Reference format.
  • Text words that are 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. When inserting text words of pseudo-text-2 or partial-word-2 into the source text, additional spaces are introduced only between text words where there already exists a space, including the assumed space between source lines.
  • If more 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 or partial-word-2 is of a length too great to be accommodated on a single line without continuation to another line in the resultant program, and the literal is not being placed on a debugging line, more continuation lines are introduced that contain the remainder of the literal. If replacement requires the continued literal to be continued on a debugging line, the program is in error.
  • Each word in pseudo-text-2 or partial-word-2 that is to be placed into the resultant program begins in the same area of the resultant program as it appears in pseudo-text-2 or partial-word-2.
  • The following rules apply to comment lines, inline comments, and blank lines:
    • Comment lines, inline comments, or blank lines in the source text, pseudo-text-1, or partial-word-1 are ignored for purposes of matching.
    • Comment lines, inline comments, or blank lines in the source text are copied into the resultant source text unchanged with the following exception: a comment line, an inline comment, or a blank line in the source text is not copied if that comment line, inline comment, or blank line appears in the sequence of text words that match pseudo-text-1 or partial-word-1.
    • Comment lines, inline comments, or blank lines in pseudo-text-2 or partial-word-2 are copied into the resultant program unchanged whenever pseudo-text-2 or partial-word-2 is placed into the source text as a result of text replacement.
  • Lines that contain *CONTROL (*CBL), EJECT, SKIP1, SKIP2, SKIP3, or TITLE statements can appear in the source text. Such lines are copied into the resultant source text unchanged.
  • The following rules apply to debugging lines:
    • Debugging lines are permitted in pseudo-text or partial-words. Text words within a debugging line participate in the matching rules as if the letter "D" did not appear in the indicator area.
    • When a REPLACE statement is specified on a debugging line, the statement is treated as if the letter "D" did not appear in the indicator area.
    • After all COPY and REPLACE statements are processed, a debugging line is considered to have all the characteristics of a comment line if the WITH DEBUGGING MODE clause is not specified in the SOURCE-COMPUTER paragraph.
  • Except for COPY and REPLACE statements, the syntactic correctness of the source text cannot be determined until all COPY and REPLACE statements are completely processed.
  • (This rule only applies to pseudo-text.) If the source text has occurrences of a dummy operand :TAG: that is delimited by colons in the program text, the compiler replaces the dummy operand with the required text. The colons serve as separators and make TAG a stand-alone operand.
    For example, you can use the REPLACE statement in the DATA DIVISION of a program as follows:
    REPLACE ==:TAG:== BY ==Payroll==.
    
    01  :TAG:.
      02  :TAG:-WEEK          PIC S99.
      02  :TAG:-GROSS-PAY     PIC S9(5)V99.
      02  :TAG:-HOURS         PIC S999  OCCURS 1 TO 52 TIMES
          DEPENDING ON :TAG:-WEEK OF :TAG:.
    
  • The REPLACE statement can be used to replace parts of words, either by using the LEADING|TRAILING partial-word-1 BY partial-word-2 phrase, or by using the pseudo-text :TAG: method.