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.
Format >>-COPY--+-text-name-+--+--------------------------+------------> '-literal-1-' '-+-OF-+--+-library-name-+-' '-IN-' '-literal-2----' >--+----------+--+-----------------------------------------+----> '-SUPPRESS-' | .--------------------------. | | V | | '-REPLACING----operand-1--BY--operand-2-+-' >--.-----------------------------------------------------------><
text-name and library-name can be the same as a user-defined word.
text-name need not be qualified. If text-name is not qualified, a library-name of SYSLIB is assumed.
When compiling from JCL or TSO, only the first eight characters are used as the identifying name. When compiling with the cob2 command and processing COPY text residing in the Hierarchical File System (HFS), all characters are significant.
When compiling from JCL or TSO:
When compiling with the cob2 command and processing COPY text residing in the HFS, the literal can be from 1 to 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 processing rules, see the Enterprise COBOL Programming Guide.
Library text and 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 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.
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. However, nested COPY statements cannot contain the REPLACING phrase, and a COPY statement with the REPLACING phrase cannot contain nested COPY statements.
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 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 or blank lines can occur in library text. Comment lines or blank lines appearing in library text are copied into the resultant source text unchanged with the following exception: a comment line or blank line in library text is not copied if that comment line or blank line appears within the sequence of text words that match operand-1 (see Replacement and comparison 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 Standard COBOL 85 format.
Note: Characters outside those defined for COBOL words and separators must not appear in library text or pseudo-text except in comment lines, comment-entries, alphanumeric literals, DBCS literals, or national literals.
The SUPPRESS phrase specifies that the library text is not to be printed on the source listing.
In the discussion that follows, each operand can consist of one of the following:
When the REPLACING phrase is specified, the library text is copied, and each properly matched occurrence of operand-1 within the library text is replaced by the associated operand-2.
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 or comment lines.
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 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.
You can include the nonseparator COBOL characters (for example, +, *, /, $, <, >, and =) as part of a COBOL word when used as REPLACING operands. In addition, the hyphen character can be at the beginning or end of the word.
For purposes of matching, each identifier-1, literal-1, or word-1 is treated as pseudo-text containing only identifier-1, literal-1, or word-1, respectively.
When the library text contains a closing quotation mark that is not immediately followed by a separator space, comma, semicolon, or period, the closing quotation mark is considered a separator quotation mark.
The colons serve as separators and make TAG a stand-alone operand.
Sequences of code (such as file and data descriptions, error and exception routines) that are common to a number of programs can be saved in a library, and then used in conjunction with the COPY statement. If naming conventions are established for such common code, then the REPLACING phrase need not be specified. If the names will change from one program to another, then the REPLACING phrase can be used to supply meaningful names for this program.
Example 1
In this example, the library text PAYLIB consists of the following data division entries:
01 A.
02 B PIC S99.
02 C PIC S9(5)V99.
02 D PIC S9999 OCCURS 1 TO 52 TIMES
DEPENDING ON B OF A.
The programmer can use the COPY statement in the data division of a program as follows:
COPY PAYLIB.
In this program, the library text is copied; the resulting text is treated as if it had been written as follows:
01 A.
02 B PIC S99.
02 C PIC S9(5)V99.
02 D PIC S9999 OCCURS 1 TO 52 TIMES
DEPENDING ON B OF A.
Example 2
To change some (or all) of the names within the library text, the programmer can use the REPLACING phrase:
COPY PAYLIB REPLACING A BY PAYROLL
B BY PAY-CODE
C BY GROSS-PAY
D BY HOURS.
In this program, the library text is copied; the resulting text is treated as if it had been written as follows:
01 PAYROLL.
02 PAY-CODE PIC S99.
02 GROSS-PAY PIC S9(5)V99.
02 HOURS PIC S9999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAY-CODE OF PAYROLL.
The changes shown are made only for this program. The text, as it appears in the library, remains unchanged.
Example 3
If the following conventions are followed in library text, then parts of names (for example the prefix portion of data names) can be changed with the REPLACING phrase.
In this example, the library text PAYLIB consists of the following data division entries:
01 :TAG:.
02 :TAG:-WEEK PIC S99.
02 :TAG:-GROSS-PAY PIC S9(5)V99.
02 :TAG:-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON :TAG:-WEEK OF :TAG:.
The programmer can use the COPY statement in the data division of a program as follows:
COPY PAYLIB REPLACING ==:TAG:== BY ==Payroll==.
Usage Note: It is important to notice in this example the required use of colons or parentheses as delimiters in the library text. Colons are recommended for clarity because parentheses can be used for a subscript, for instance in referencing a table element.
In this program, the library text is copied; the resulting text is treated as if it had been written as follows:
01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 PAYROLL-GROSS-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.
The changes shown are made only for this program. The text, as it appears in the library, remains unchanged.
Example 4
This example shows how to selectively replace level numbers without replacing the numbers in the PICTURE clause:
COPY xxx REPLACING ==(01)== BY ==(01)==
== 01 == BY == 05 ==.