The COPY statement incorporates text into a COBOL compilation group.
- 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.
- 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.
- 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.
- 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.
- The comparison operation to determine text replacement occurs in the following
manner:
- 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.
- 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.

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.
- The following rules apply for the purpose of matching:
- 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.
- 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.
- Text-words within a debugging line participate in the matching as if the
"D" did not appear in the indicator area.


Each operand and operator of a concatenation expression is a separate text-word.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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.
- 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.
- 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.
- If the unit identifier is not explicitly specified, the default drive is
used. (The default is operating system-dependent.)
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.
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:
- In pairs of left and right parentheses. For example, (ABC)
- 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 the next
COBOL standard, however, they are not included in the ANSI '85 COBOL standard.