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, and hyphen
- The first or last character must not be a hyphen
- Cannot contain an 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.
When the compiler searches for COPY members in PDS or PDSE datasets, including those specified in the COPYLOC option with the DSN argument, only the first eight characters of text-name are used as the identifying name. When the compiler searches for COPY text in z/OS® Unix directories, such as those directories specified via the -I option of the cob2 command or those directories specified via the SYSLIB environment variable (when the compiler is invoked from cob2) or those directories specified via the COPYLOC option with the PATH argument, all characters are significant.
If you have specified only z/OS UNIX search locations for COPY members, the restrictions mentioned above on the legal characters in text-name do not apply and any valid COBOL character can be used in the name.
For details, see Copy member search order.
- literal-1 , literal-2
- Must be alphanumeric literals.
literal-1 identifies the copy text. literal-2 identifies where
the copy text exists.
When compiling from JCL or TSO:
- Literals can be from 1-30 characters in length.
- Literals can contain characters: A-Z, a-z, 0-9, hyphen, @, #, or $.
- The first or last character must not be a hyphen.
- Literals cannot contain an underscore.
- Only the first eight characters are used as the identifying name.
When compiling with the cob2 command and processing COPY text residing in the z/OS UNIX file system, the literal can be from 1 to 160 characters in length and the restrictions on characters in the literal mentioned above do not apply and any character that is legal in a z/OS UNIX file name can appear in the literal.
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 Enterprise COBOL 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.
- 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.
For details, see Comparison and replacement rules.
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. Library text can consist of or include any words, identifiers, or literals that can be written in the source text. This includes DBCS user-defined words, DBCS literals, and national literals.
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
- pseudo-text
A sequence of text words that are bounded by, but not including, pseudo-text delimiters (==). Both characters of each pseudo-text delimiter must appear on one line.
Individual text words within pseudo-text can be up to 322 characters long. They can be continued subject to the normal continuation rules for source code format.
A text word 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 be one or more text words. It can consist solely of the separator comma or separator semicolon. pseudo-text-2 can be zero or more text words. It can consist solely of space characters, comment lines, or inline comments.
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 DBCS user-defined words, DBCS literals, and national literals.
DBCS user-defined words must be wholly formed; that is, there is no partial-word replacement for DBCS words.
Words or literals containing DBCS 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 DBCS user-defined words. DBCS user-defined words must
be wholly formed. You cannot replace part of a DBCS 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 DBCS 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.