The COPY Statement

General Rules

1. The compilation of a compilation group containing COPY statements is logically equivalent to the processing of all COPY statements before the processing of the resultant compilation group.
2. The effect of processing a COPY statement is that the library text associated with text-name is copied into the source text, logically replacing the entire COPY statement, beginning with the reserved word COPY and ending with the punctuation character period, inclusive.
3. If the REPLACING phrase is not specified, the library text is copied unchanged.

   If the REPLACING phrase is specified, the library text is copied and each properly matched occurrence of pseudo-text-1, identifier-1, literal-1, word-1 and partial-word-1 in the library text is replaced by the corresponding pseudo-text-2, identifier-2, literal-2, word-2 or partial-word-2.

4. For purposes of matching, identifier-1, literal-1 and word-1 are treated as pseudo-text containing only identifier-1, literal-1 or word-1, respectively.
5. The comparison operation to determine text replacement occurs in the following manner:
   1. The leftmost library text-word which is not a separator comma or a separator semicolon is the first text-word used for comparison. Any text-word or space preceding this text-word is copied into the source text. Starting with the first text-word for comparison and first pseudo-text-1, identifier-1, word-1, literal-1 or partial-word-1 that was specified in the REPLACING phrase, the entire REPLACING phrase operand that precedes the reserved word BY is compared to an equivalent number of contiguous library text-words.
   2. Pseudo-text-1, identifier-1, word-1, or literal-1 match the library text if, and only if, the ordered sequence of text-words that forms pseudo-text-1, identifier-1, word-1, or literal-1 is equal, character for character, to the ordered sequence of library text-words.
   3.  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 starting 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, ending with the rightmost character position of a library text-word.
   4. 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 library 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.
   5. If no match occurs, the comparison is repeated with each next successive pseudo-text-1, identifier-1, word-1, literal-1, or pseudo-text-1, if any, in the REPLACING phrase until either a match is found or there is no next successive REPLACING operand.
   6. When all the REPLACING phrase operands have been compared and no match has occurred, the leftmost library text-word is copied into the source text. The next successive library text-word is then considered as the leftmost library text-word, and the comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, literal-1, or partial-word-1 specified in the REPLACING phrase.
   7. Whenever a match occurs between pseudo-text-1, identifier-1, word-1, or literal-1 and the library text, the corresponding pseudo-text-2, identifier-2, word-2, or literal-2 is placed into the source text.

       When a match occurs between partial-word-1 and the library text-word, the library text-word is placed into the resultant text with the matched characters either replaced by partial-word-1 or deleted when partial-word-2 consists of zero text-words.

      The library text-word immediately following the rightmost text-word that participated in the match is then considered as the leftmost text-word. The comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, literal-1 or partial-word-1 specified in the REPLACING phrase.

   8. The comparison operation continues until the rightmost text-word in the library text has either participated in a match or been considered as a leftmost library text-word and participated in a complete comparison cycle.
6. A comment line occurring in either the library text or pseudo-text-1 is interpreted, for purposes of matching, as a single space. Comment lines appearing in either pseudo-text-2 or library text are copied into the source text unchanged.
7. The text produced as a result of the complete processing of a COPY statement must not contain a COPY statement.

    This text can contain a COPY statement provided neither this contained COPY nor the already expanded COPY includes the REPLACING phrase. However, recursive COPY statements (where a library-text is referred to by a COPY statement within it) are not allowed.

    COPY statements may be nested in this way to any level. One of the COPY statements in this structure may include the REPLACING phrase, and the replacements specified are in effect for all subsidiary COPY statements.

8. The syntactic correctness of the library text cannot be independently determined.

    Except for COPY statements,

   the syntactic correctness of the entire COBOL compilation group cannot be determined until all COPY statements have been completely processed.

9.  If the REPLACING phrase is specified, the library text must not contain an EXEC HTML statement. Violation of this rule may result in unexpected behavior and syntax errors.
10. Each text-word copied from the library but not replaced, or only partially replaced, is copied so as to start in the same area of the line in the resultant source text as it begins in the line within the library. However, if a text-word copied from the library begins in area A but follows another text-word, which also begins in area A of the same line, and if replacement of a preceding text-word in the line by replacement text of greater length occurs, the following text-word begins in area B if it cannot begin in area A. Each text-word in pseudo-text-2 that is to be placed into the resultant source text begins in the same area of the resultant source text as it appears in pseudo-text-2. Each identifier-2, literal-2, and word-2 that is to be placed into the resultant source text begins in the same area of the resultant source text as the leftmost library text-word that participated in the match would appear if it had not been replaced.

    If additional lines are introduced into the source text as a result of a COPY statement, each text-word introduced appears on a debugging line if the copy statement begins on a debugging line, or if the text-word being 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 being replaced is specified on a debugging line. Except in the preceding cases, only those text-words that are specified on debugging lines where the debugging line is within pseudo-text-2 appear on debugging lines in the resultant source text. If any literal specified as literal-2 or within pseudo-text-2 or library text is of too great a length 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 which contain the remainder of the literal. If replacement requires that the continued literal be continued on a debugging line, the compilation group is in error.

11. For purposes of compilation, text-words after replacement are placed in the source text according to the rules for reference format as described in the section Reference Format in the chapter Language Fundamentals.
12. If the unit identifier is not explicitly specified, the default drive is used. (The default is operating system-dependent.)
13.  The OLDCOPY Compiler directive causes the entire entry to be replaced by the information identified by text-name, except that the data-name preceding the COPY statement replaces the corresponding data-name in the text-name.
14.  If certain conventions are followed in library text, parts of names, for example the prefix portion of data-names, can be changed with the REPLACING phrase. To use this type of "partial word replacement" the portion of the words to be modified must be enclosed in one of the following ways:
    1. In pairs of left and right parentheses. For example, (ABC)
    2. Within colons. For example :XYZ:
    Note: The LEADING and TRAILING phrases can also be used for partial word replacement. The LEADING and TRAILING phrases are supported by the MF dialect and ISO2002, however, they are not included in the ANSI '85 COBOL standard.