COPY statement
The COPY statement is a library statement that places prewritten text in a COBOL compilation unit.
Prewritten source code entries can be included in a compilation unit at compile time. Thus, an installation can use standard file descriptions, record descriptions, or procedures without recoding them. These entries and procedures can then be saved in user-created libraries; they can then be included in programs and class definitions by means of the COPY statement.
Compilation of the source code containing COPY statements is logically equivalent to processing all COPY statements before processing the resulting source text.
The effect of processing a COPY statement is that the library text associated with text-name is copied into the compilation unit, logically replacing the entire COPY statement, beginning with the word COPY and ending with the period, inclusive. When the REPLACING phrase is not specified, the library text is copied unchanged.
- text-name, library-name
- text-name identifies the copy text. library-name identifies
where the copy text exists.
- Can be from 1-30 characters in length
- Can contain the following characters: Latin uppercase letters A-Z, Latin lowercase letters a-z, digits 0-9, hyphen, and underscore
Neither text-name nor library-name need to be unique within a program. They can be identical to other user-defined words in the program.
text-name need not be qualified. If text-name is not qualified, a library-name of SYSLIB is assumed.
- literal-1 , literal-2
- Must
be alphanumeric literals. literal-1 identifies
the copy text. literal-2 identifies where the copy
text exists.
The literal can be from 1-160 characters in length.
The uniqueness of text-name and library-name is determined after the formation and conversion rules for a system-dependent name have been applied.
For information about the mapping of characters in the text-name, library-name, and literals, see Compiler-directing statements in the COBOL for Linux® on x86 Programming Guide.
- operand-1, operand-2
- Can be pseudo-text, an identifier, a function-identifier, a literal, or a COBOL word (except the
word COPY).
For details, see REPLACING phrase.
Library text can consist of or include any words, identifiers, or literals that can be written in the source text. This includes multibyte user-defined words, multibyte literals, and national literals.
- partial-word-1, partial-word-2
- Can be a partial-word. For details, see REPLACING phrase.
Each COPY statement must be preceded by a space and ended with a separator period.
A COPY statement can appear in the source text anywhere a character string or a separator can appear.
COPY statements can be nested, and any COPY statement in a chain of nested COPY statements can have the REPLACING phrase, provided there is only one such COPY statement in the chain. When the REPLACING phrase is specified for a COPY statement that appears in a chain of nested COPY statements, the REPLACING phrase applies to all library text that is included by COPY statements nested under the COPY statement that has the REPLACING phrase.
A nested COPY statement cannot cause recursion. That
is, a COPY member can be named only once in a set of nested COPY statements
until the end-of-file for that COPY member is reached. For example,
assume that the source text contains the statement: COPY X.
and
library text X contains the statement: COPY Y.
.
In this case, library text contained in Y must not
have a COPY X
or a COPY Y
statement.
Debugging lines are permitted within library text and pseudo-text. Text words within a debugging line participate in the matching rules as if the "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 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.
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.
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.
After all COPY and REPLACE statements have been 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.
Comment lines, inline comments, or blank lines can occur in library text. Comment lines, inline comments, or blank lines appearing in 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 library text is not copied if that comment line, inline comment, or blank line appears within the sequence of text words that match operand-1 (see Comparison and replacement rules).
Lines containing *CONTROL (*CBL), EJECT, SKIP1, SKIP2, SKIP3, or TITLE statements can occur in library text. Such lines are treated as comment lines during COPY statement processing.
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.
Library text copied from the library is placed into the same area of the resultant program as it is in the library. Library text must conform to the rules for the 85 COBOL Standard format.
Note: Characters outside those defined for COBOL words and separators must not appear in library text or pseudo-text except in comment lines, inline comments, comment-entries, alphanumeric literals, DBCS literals, or national literals.
SUPPRESS phrase
The SUPPRESS phrase specifies that the library text is not to be printed on the source listing.
REPLACING phrase
When the REPLACING phrase is specified, the library text is copied, and each properly matched occurrence of operand-1 or partial-word-1 within the library text is replaced by the associated operand-2 or partial-word-2.
In the discussion that follows, when the LEADING or TRAILING keyword of the REPLACING phrase is specified, each operand of the REPLACING phrase must be a partial-word. Otherwise, each operand can consist of one of the following items:
- Pseudo-text
- An identifier
- A literal
- A COBOL word (except the word COPY)
- A function-identifier
- partial-word
- pseudo-text
-
A sequence of character-strings or separators, or both, bounded by, but not including, pseudo-text delimiters (==). Both characters of each pseudo-text delimiter must appear on one line; however, character-strings within pseudo-text can be continued.
Individual character-strings within pseudo-text can be up to 322 characters long; they can be continued subject to the normal continuation rules for source code format.
Keep in mind that a character-string must be delimited by separators. For more information, see Characters
pseudo-text-1 refers to pseudo-text when used for operand-1, and pseudo-text-2 refers to pseudo-text when used for operand-2.
pseudo-text-1 can consist solely of the separator comma or separator semicolon. pseudo-text-2 can be null; it can consist solely of space characters, comment lines, or inline comments.
Pseudo-text must not contain the word COPY.
Each text word in pseudo-text-2 that is to be copied into the program is placed in the same area of the resultant program as the area in which it appears in pseudo-text-2.
Pseudo-text can consist of or include any words (except COPY), identifiers, or literals that can be written in the source text. This includes multibyte user-defined words, DBCS literals, and national literals.
Multibyte user-defined words must be wholly formed; that is, there is no partial-word replacement for multibyte words.
Words or literals containing multibyte characters cannot be continued across lines.
Use pseudo-text when you replace a PICTURE character-string. To avoid ambiguities, the entire PICTURE clause, including the keyword PICTURE or PIC, should be specified in pseudo-text-1.
- identifier
- Can be defined in any section of the DATA DIVISION.
- literal
- Can be numeric, alphanumeric, DBCS, or national.
- word
- Can be any single COBOL word (except COPY), including multibyte user-defined words. Multibyte user-defined words must be wholly formed. You cannot
replace part of a multibyte word.
You can include the nonseparator COBOL characters (for example, + * / $ < > =) as part of a COBOL word when used as REPLACING operands. In addition, a hyphen or underscore can be at the beginning of the word or a hyphen can be at the end of the word.
- function-identifier
- A sequence of character strings and separators that uniquely references the data item that results from the evaluation of a function. For more information, see Function-identifier.
- partial-word
- A single text word that is bounded by, but not
including, pseudo-text delimiters
(==)
. Both characters of each pseudo-text delimiter must appear on one line. However, the text word within a partial-word can be continued.The following rules apply to partial-word-1 and partial-word-2:- partial-word-1 consists of one text word.
- partial-word-2 consists of zero or one text word.
- partial-word-1 and partial-word-2 cannot be an alphanumeric literal, national literal, DBCS literal, or multibyte word.
For purposes of matching, each identifier, literal, word, or function-identifier is treated as pseudo-text that contains only that identifier, literal, word, or function-identifier, respectively.