8.1.4 "COBOL Language Reference" IBM Library Server

8.1.4 COPY Statement

The COPY statement is a library statement that places prewritten text in a COBOL program.

Prewritten source program entries can be included in a source program 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 the source program by means of the COPY statement.

Compilation of the source program containing COPY statements is logically equivalent to processing all COPY statements before processing the resulting source program.

The effect of processing a COPY statement is that the library text associated with text-name is copied into the source program, 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 _|  |            <__________________________  |         |
   |                    |_REPLACING____operand-1__BY__operand-2_|_|         |
   |                                                                        |
   |________________________________________________________________________|

text-name, library-name

Text-name identifies the name of the copy text. Library-name identifies where the copy text exists.

Must follow the normal rules of formation for a user-defined word:

The word can be from 1-30 characters in length.
The word can contain characters: A-Z, a-z, 0-9, hyphen.
At least one character must be alphabetic.
The hyphen can't be the first or last character.

>_Host_> For OS/390 and VM, only the first eight characters are used as the identifying name. <_Host_<

X literal-1, literal-2

X Literal-1 identifies the name of the copy text. Literal-2 identifies
X where the copy text exists.

X >_Host_> On OS/390 and VM:

X The first eight characters are used as the identifying name.
X The literal can contain characters: A-Z, a-z, 0-9, hyphen, @, #,
X $.
X The leading character must be alphabetic. <_Host_<

X >_Workstation_> On AIX, OS/2, and Windows:

X The literal can be from 1-160 characters in length.
X <_Workstation_<

The uniqueness of text-name and library-name is determined after the formation and conversion rules for a system-dependent name have been applied.

X As an IBM extension, a user-defined word can be the same as a text-name or
X a library-name.

X As an IBM extension, if more than one COBOL library is available during
X compilation, text-name need not be qualified. If text-name is not
X qualified, a library-name of SYSLIB is assumed.

For information on processing rules, see the IBM COBOL Programming Guide for your platform.

operand-1, operand-2

Can be either pseudo-text, an identifier, a function-identifier, a literal, or a COBOL word (except COPY).

Each COPY statement must be preceded by a space and ended with a separator period.

A COPY statement can appear in the source program anywhere a character
X string or a separator can appear. As an IBM extension, COPY statements
X can be nested. However, nested COPY statements cannot contain the
X REPLACING phrase, and a COPY statement with the REPLACING phrase cannot
X contain nested COPY statements.

X A COPY statement cannot cause recursion. That is, a COPY member can be
X named only once in a set of nested COPY statements until the end-of-file
X for that COPY member is reached. For example, assume that the source
X program contains the statement: COPY X. and library-text X contains the
X statement: COPY Y..

X In this case, the library-text Y must not have a COPY X or a COPY Y
X 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 program after the opening pseudo-text delimiter but before the matching closing pseudo-text delimiter.

If additional lines are introduced into the source program 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 program.

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 program 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 (refer to "Replacement and Comparison Rules" on topic 8.1.4.3).

X Lines containing *CONTROL (*CBL), EJECT, SKIP1/2/3, or TITLE statements
X can occur in library text. Such lines are treated as comment lines during
X COPY statement processing.

The syntactic correctness of the entire COBOL source program 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 format.

Note: Characters outside the standard COBOL character set must not appear in library text or pseudo-text, other than as part of nonnumeric literals, comment lines, or comment-entries.

X DBCS words, DBCS literals, and EUC words are allowed in library text and
X pseudo-text.

Subtopics:

Adobe, the Adobe logo, Acrobat, the Acrobat logo, and Acrobat Reader are registered trademarks of Adobe Systems incorporated.

8.1.4 COPY Statement

IBM Library Server Copyright 1989, 2005 IBM Corporation. All rights reserved.