COPY Statement

The COPY statement copies text or a resource (static data such as a bitmap) into the source program from the specified file immediately prior to compilation. The text or resource is inserted for compilation only and does not permanently replace the COPY statement in the program source. Resources and COPY files that are inserted in this way into the object code are loaded from the object file at runtime. If you change the resource (such as a bitmap) or the COPY file, you must recompile for the change to be reflected in the object code.

The REPLACING phrase allows word and substring substitutions to be made in the inserted text prior to compilation.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

Format 1

COPY INDEXED library-name [ {IN} path-name ] [ SUPPRESS ]
                            {OF}
[ REPLACING { { old-text BY new-text              } } ... ] .
            { { {LEADING } literal-1 BY {literal-2} } }
            { { {TRAILING}              {SPACE    } } }
            { {                         {SPACES   } } }

Format 2

COPY RESOURCE resource-name [ {IN} path-name ] .
                              {COPY RESOURCE resource-name [ {IN} path-name ] .
{OF}}

Syntax Rules

The COPY statement must be terminated by a period. The period is part of the COPY statement and does not otherwise affect the program.
library-name must be a nonnumeric literal or user-defined word. path-name must be a nonnumeric literal or a user-defined word. Note that a nonnumeric literal may reference an environment variable by placing a $ in the name, as described in General Rule 2. To preserve the case of library-name and path-name, you must place them within quotation marks, otherwise they will be treated as uppercase by case sensitive operating systems. See COPY Libraries for more information.
The COPY statement may be used anywhere a separator may occur. It may be placed in Area A or Area B.
old-text and new-text may be any of the following:
1. A series of text words placed between == delimiters. For example ==WORD-1 WORD-2== specifies a two-word sequence. In old-text, at least one word must be specified. In new-text, zero words may be used.
2. A numeric or nonnumeric literal.
3. A data name, including qualifiers, subscripts, and reference
  
  modification.
4. Any single text word.
For purposes of the COPY statement, a text word is a contiguous sequence of characters in Area A or Area B that form one of the following:
1. A separator, except for: space, a pseudo-text delimiter (“==”), and the opening and closing delimiters for nonnumeric literals.
2. A numeric or nonnumeric literal.
3. Any of a sequence of characters except comment lines and the word COPY, bounded by separators, which is neither a separator nor a literal.
literal-1 and literal-2 are nonnumeric literals.
The phrases SPACE and SPACES are equivalent. When one of these is used instead of literal-2, literal-1 is deleted and no spaces are actually substituted.
The format of the COPY file must conform to one of the allowed ACUCOBOL-GT source formats (either terminal or ANSI). This format need not be the same as that used in the rest of the program.
resource-name must be an alphanumeric literal or a user-defined word. A resource name with a hyphen is equivalent to the same name with an underscore in place of the hyphen. For example, MY-FILE is treated as being identical to MY_FILE. To preserve the case of resource-name, you must place it within quotation marks; otherwise, it will be treated as uppercase by case-sensitive operating systems.
COPY statements may be nested in other COPY libraries. Any one of the COPY statements in this structure can include the REPLACING phrase.
Depending on the scope of each statement, the REPLACING phrases might affect subsidiary COPY statements. For example, if program-a.cbl contains a copy/replace as follows:
```
COPY "program-b.cpy"
   REPLACING ==genericitems== BY ==myitems==.
```
and program-b.cpy contains a nested copy/replace statement:
```
COPY "program-c.cpy"
   REPLACING ==variabledata== BY == specificdata==.
```
The replace performed in program-b.cpy by the copy/replace statement in program-a.cbl will affect program-c.cpy. If you do not want the copy/replace statement in program-a.cbl to cascade to program-c.cpy, you must add the following statement to program-b.cpy, so that the copy/replace performed in program-b.cpy will not be performed in program-c.cpy.
```
COPY "program-c.cpy"
   REPLACING ==genericitems== BY ==genericitems==.
```

General Rules

library-name and path-name identify a source file to be included at the location of the COPY statement. The text of the source file logically replaces the COPY statement, including the terminating period. The rules for interpreting these names are described in COPY Libraries. The -Ce compile option can be used to specify an alternate default filename extension. See Compatibility Options for more information.
You may use operating system environment variables in the OF phrase of a COPY statement. To reference an environment variable, place a $ in front of it. For example, if you assign MYLIB to C:\MYFILES\MYLIB, then the statement:
```
COPY "FILE1" OF "$MYLIB"
```
would use the file C:\MYFILES\MYLIB\FILE1.

You may use multiple environment variables by preceding each one with a $ symbol. Symbol names may contain alphanumeric characters, hyphens, underscores, and dollar signs. If the symbol name is not found in the environment, it is left unchanged (including the initial $ symbol). Symbols are not processed recursively — if the value of a symbol contains a $, the dollars sign is used literally in the final file name.
When INDEXED appears after the word COPY, it is ignored by the compiler. It may be included to provide compatibility with some older COBOL dialects.
If the word SUPPRESS appears after library-name and path-name, the program listing file will not include the contents of the COPY file or any other COPY files that may be nested within. This word provides compatibility with one feature of IBM DOS/VS COBOL. It is not a reserved word in ACUCOBOL-GT and may be used in other contexts as a user-defined name.
The text of the COPY file is copied unchanged into the source program unless the REPLACING option is used. If the REPLACING option is used, elements of the COPY file that match old-text or literal-1 are replaced by new-text or literal-2. The comparison operation that determines text replacement is done as follows:
1. The leftmost library text word that is not a separator comma or semicolon is the first text word used for comparison. Starting with this word, and the first old-text specified, the entire old-text sequence is compared with an equivalent number of contiguous library text words.
2. old-text matches the library text only if the ordered sequence of text words of old-text is identical to the ordered sequence of library text words. For purposes of matching, a separator semicolon, comma, or space is considered a space, and a sequence of one or more spaces is considered a single space. Also, lower-case characters are considered the same as upper-case characters in all text words except for nonnumeric literals.
3. If no match occurs, the comparison is repeated for each old-text specified until a match is found or each old-text has been tried.
4. After all old-text comparisons have been tried and no match has occurred, the leftmost library text word is copied into the source program. The next text word is then considered as the leftmost word and the cycle is repeated.
5. Whenever a match occurs between the library text and old-text, the corresponding new-text is placed in the source program. The library text word that follows the rightmost word that participated in the match then becomes the new leftmost word for subsequent cycles.
6. When you are using the LEADING/TRAILING option, the replacement process differs slightly. When a match occurs between library text and literal-1, the only characters replaced by literal-2 are the specific LEADING or TRAILING characters indicated in the COPY statement. These characters can be a substring or a whole word. If a SPACE or SPACES phrase is used, the LEADING or TRAILING characters are deleted. For example, if you have the following COPY library named MYCOPY.CPY:
```
    01 dummy-rec.
        03 dummy-number-null    PIC X(10)
```
  and you used this COPY statement:
```
COPY "MY-COPY.CPY" REPLACING 
        LEADING "dummy" by "employee"
        TRAILING "null" by SPACES.
```
  Then the replacement will result in:
```
01 employee-rec.
        03 employee-number    PIC X(10)
```
7. The comparison cycle continues until the rightmost text word in the library has either participated in a match or has been the leftmost word of a comparison cycle.
Comment lines and blank lines occurring in the library or in old-text are ignored for purposes of matching. Comment lines and blank lines occurring in library text that is matched by a REPLACING operand are not copied into the source program.
Debugging lines may appear within the library text and in old-text. Text words appearing in a debugging line participate in the matching rules as if the line were a normal text line.
When new-text is copied into the source program, the first word of new-text is copied into the same Area as the leftmost word of the replaced text. Subsequent words of new-text are copied into Area B.
It is possible to use the REPLACING phrase to replace substrings. This allows you to construct COPY libraries in which several strings have a uniform substring that you plan to modify.
For example, the substring individual might occur in the COPY library in individual-name, individual-address, individual-state, individual-city, individual-zip, and individual-title. The REPLACING phrase could be used to replace individual with specific substrings such as employee, owner, student, teacher, professor, or advisor.

To make use of this, delimit the substring that will be replaced in the COPY library with quotes. Then use the standard COPY syntax to replace the quoted substring by another substring. The resulting sequence of characters is re-evaluated by the compiler to make a new string.

For example, suppose you have a COPY library (called MYLIB) that contains the following:
```
77  MY-'DUMMY'-DATA-ITEM  PIC X(10).
```
and you used this COPY statement:
```
COPY "MYLIB" REPLACING =='DUMMY'== BY ==REAL==.
```
The text of MYLIB is effectively treated as:
```
77  MY-REAL-DATA-ITEM  PIC X(10).
```
You should use hyphens rather than underscores in this instance. In addition to the use of single and double quotes to delimit the substring, the following delimiters are also allowed:
```
==(XYZ)==
==|XYZ|==  (in HP COBOL compatibility mode)
==*XYZ*==
==:XYZ:==
==XYZ*==
==XYZ&==
==XYZ#==
```
resource-name and path-name identify a resource file to be included in the resulting object file. The rules for interpreting these names are described in COPY Libraries. Note that the compiler's COPY path applies to resources (Format 2) as well as to source files (Format 1).
The effect of a COPY RESOURCE statement is to add resource-name to a list of resources that the compiler embeds into the resulting COBOL object file. The resources are added to the end of the COBOL object in the same order as the corresponding COPY statements. Because the resources are added to the end of the object, the location of the corresponding COPY RESOURCE statement in the COBOL program is irrelevant. Conventionally, COPY RESOURCE statements are placed either in Working-Storage or at the end of the program, but any location is acceptable.
If individual resolves to a COBOL object or library file, the compiler includes this object or library in the resulting object in a manner similar to cblutil -lib. These are not considered resources, but are embedded COBOL objects. Note that we recommend using cblutil -lib to create libraries containing multiple COBOL objects instead of using COPY RESOURCE. There are two advantages to using cblutil. The first is that you do not need to worry about the order in which COBOL objects are compiled (if you use COPY RESOURCE, you must ensure that the copied object is compiled first), and the second is that cblutil also checks for duplicated program names; COPY RESOURCE does not.

Code Examples

Assume the existence of disk directory CODELIB. In directory CODELIB is file ENROLLREC. The contents of ENROLLREC are:

01 ENROLLMENT-RECORD.
   05 STUDENT-NAME PIC X(30).
   05 STUDENT-ADDR PIC X(50).
   05 STUDENT-GPA PIC 99V9.
   05 SID PIC 9(7).

Code Example 1:

IDENTIFICATION DIVISION.
PROGRAM-ID. COPY-EXAMPLE-1.
...
DATA DIVISION.
FILE SECTION.
FD SCIENCE-DEPT-ENROLLMENT-FILE.
COPY ENROLLREC IN "LIBRARY/CODELIB".
...

Code compiled after COPY substitutions:

...
DATA DIVISION.
FILE SECTION.
FD SCIENCE-DEPT-ENROLLMENT-FILE.
01 ENROLLMENT-RECORD.
   05 STUDENT-NAME PIC X(30).
   05 STUDENT-ADDR PIC X(30).
   05 STUDENT-GPA PIC 99V9.
   05 SID PIC 9(7).
...

Code Example 2:

IDENTIFICATION DIVISION.
PROGRAM-ID. COPY-EXAMPLE-2.
...
DATA DIVISION.
  FILE SECTION.
  FD SCIENCE-DEPT-ENROLLMENT-FILE.
  COPY ENROLLREC
     IN "LIBRARY/CODELIB"
        REPLACING ==SID== BY ==STUDENT-ID==,
                  ==9(7)== BY ==9(9)==.
...

Compiled code after COPY/REPLACING substitutions:

...
DATA DIVISION.
FILE SECTION.
FD SCIENCE-DEPT-ENROLLMENT-FILE.
01 ENROLLMENT-RECORD.
   05 STUDENT-NAME PIC X(30).
   05 STUDENT-ADDR PIC X(30).
   05 STUDENT-GPA PIC 99V9.
   05 STUDENT-ID PIC 9(9).
...

Highlights for first-time users

COPY will always import the entire contents of the named COPY file.
The REPLACING text does not appear in the listing produced by the ACUCOBOL-GT compiler (-Lo filename compiler argument). This is a common source of confusion for users who check the compilation listing file for verification that the replacing action occurred. You can, however, use the -Lp compiler option to create an output file that includes the REPLACING text. See Listing Options in the ACUCOBOL-GT User's Guide for more information.