Comparison and replacement rules

This topic introduces detailed rules for comparison and replacement.

  • Only one COPY REPLACING statement is allowed in a nested COPY chain. The addition of a second COPY REPLACING statement in the same nested COPY chain will result in a severe-level compiler error (RC=12), and the issuing of the following error message:
    IGYLI0078-S   A second "COPY" statement with "REPLACING" phrase was found within a nested "COPY".
                         The second "COPY" statement was discarded.
  • Arithmetic and logical operators are considered text words and can be replaced only through a pseudo-text operand.
  • Beginning and ending blanks are not included in the text comparison process. Embedded blanks are used in the text comparison process to separate multiple text words.
  • When operand-1 is a figurative constant, operand-1 matches only the same exact figurative constant. For example, if ALL "AB" is specified in operand-1, "ABAB" in the library text is not considered a match; only ALL "AB" is considered a match.
  • Any separator comma, semicolon, or space that precedes the leftmost word in the library text is copied into the source text. Beginning with the leftmost library text word and the first operand-1 or partial-word-1 specified in the REPLACING phrase, the entire REPLACING operand that precedes the keyword BY is compared to an equivalent number of contiguous library text words.
  • operand-1 matches the library text only if the ordered sequence of text words that forms operand-1 is equal, character for character, to the ordered sequence of library words. For national characters, the sequence of national characters must be equal, national character for national character, to the ordered sequence of library words.
  • When the LEADING phrase is specified, partial-word-1 matches the library text only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters that start with the leftmost character position of a library text word.

    When the TRAILING phrase is specified, partial-word-1 matches the library text only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters that end with the rightmost character position of a library text word.

  • For matching purposes, each occurrence of a separator comma, a separator semicolon, or a sequence of one or more separator spaces is considered to be a single space.

    However, when operand-1 or partial-word-1 consists solely of a separator comma or separator semicolon, the operand-1 or partial-word-1 participates in the match as a text word. In this case, the space that follows the comma or semicolon separator can be omitted.

    When the library text contains a closing quotation mark that is not immediately followed by a separator space, a separator comma, a separator semicolon, or a separator period, the closing quotation mark is considered a separator quotation mark.

  • If no match occurs, the comparison is repeated with each successive operand-1 or partial-word-1 if specified, until either a match is found or no further REPLACING operands exist.
  • Whenever a match occurs between operand-1 and the library text, the corresponding operand-2 is copied into the source text. Whenever a match occurs between partial-word-1 and the library text word, the matched characters of that library text word are either replaced by partial-word-2 or deleted when partial-word-2 consists of zero text words.
  • When all operands are compared and no match occurs, the leftmost library text word is copied into the source text.
  • Once a library text word is finished being processed and is either copied into the source text unchanged or replaced because of a match, the next successive uncopied library text word is then considered to be the leftmost text word, and the comparison cycle starts again, beginning with the first occurrence of operand-1 or partial-word-1. The process continues until the rightmost library text word is compared.
  • The sequence of text words in the library text, pseudo-text-1, and partial-word-1 is determined by the rules for reference format. For more information, see Reference format.
  • When text words are placed in the source text, additional spaces are introduced only between text words where there already exists a space, including the assumed space between source lines.
  • The following rules apply to comment lines, inline comments, and blank lines:
    • Comment lines, inline comments, or blank lines in the library text, pseudo-text-1, or partial-word-1 are ignored for purposes of matching.
    • Comment lines, inline comments, or blank lines in the library 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 library 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.
    • If the word COPY appears in a comment-entry, or in the place where a comment-entry can appear, it is considered part of the comment-entry.
  • COPY REPLACING does not affect the EJECT, SKIP1, SKIP2, SKIP3, or TITLE compiler-directing statements.
  • Lines that contain *CONTROL (*CBL), EJECT, SKIP1, SKIP2, SKIP3, or TITLE statements can appear in the library text. Such lines are copied into the resultant source text unchanged.
  • The following rules apply to debugging lines:
    • Debugging lines are permitted in library text and pseudo-text. Text words within a debugging line participate in the matching rules as if the letter "D" did not appear in the indicator area. A debugging line is specified within pseudo-text if the debugging line begins in the source text after the opening pseudo-text delimiter but before the matching closing pseudo-text delimiter.
    • If more lines are introduced into the source text as a result of a COPY statement, each text word that is introduced appears on a debugging line if the COPY statement begins on a debugging line or if the text word that is introduced appears on a debugging line in library text. When a text word specified in the BY phrase is introduced, it appears on a debugging line if the first library text word that is being replaced is specified on a debugging line.
    • When a COPY statement is specified on a debugging line, the copied text is treated as though it appeared on a debugging line, except that comment lines in the text appear as comment lines in the resulting source text.
    • After all COPY and REPLACE statements are processed, a debugging line will be considered to have all the characteristics of a comment line, if the WITH DEBUGGING MODE clause is not specified in the SOURCE-COMPUTER paragraph.
  • The syntactic correctness of the entire COBOL source text cannot be determined until all COPY and REPLACE statements have been completely processed, because the syntactic correctness of the library text cannot be independently determined.
  • (This rule applies to pseudo-text only.) 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. Example 3 shows how it is used with the dummy operand :TAG:. The colons serve as separators and make TAG a stand-alone operand. Note that parenthesis can also be used as delimiters, as in (TAG).
  • The COPY statement with REPLACING phrase 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: or (TAG) method.
  • After replacement, text words are placed in the source text according to the 85 COBOL Standard format rules.