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 copybooks 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 library, you must recompile in order 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.
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 ] .
{OF}
Syntax Rules
1. The COPY statement must be terminated by a period. The period is part of the COPY statement and does not otherwise affect the program.
2. 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. For more information, see the ACUCOBOL-GT User's Guide, section 2.5, "Copy Libraries."
3. The COPY statement may be used anywhere a separator may occur. It may be placed in Area A or Area B.
4. Old-text and new-text may be any of the following:
a) 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.
b) A numeric or nonnumeric literal.
c) A data name, including qualifiers, subscripts and reference modification.
d) Any single text word.
5. 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:
a) A separator, except for: space, a pseudo-text delimiter ("=="), and the opening and closing delimiters for nonnumeric literals.
b) A numeric or nonnumeric literal.
c) Any of a sequence of characters except comment lines and the word "COPY", bounded by separators, which is neither a separator nor a literal.
6. Literal-1 and literal-2 are nonnumeric literals.
7. 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.
8. The format of the library text 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. Section 2.4 of the ACUCOBOL-GT User's Guide contains details about which source format is used for COPY libraries.
9. 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".
10. COPY statements may be nested in other COPY libraries. Any one of the COPY statements in this structure can include the REPLACING phrase.
Note that, depending on the scope of each statement, these 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 statment 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
1. Library-name and path-name identify a source file to be included at the location of the COPY statement. The rules for interpreting these names are described in the ACUCOBOL-GT User's Guide (section 2.5). The text of the source file logically replaces the COPY statement, including the terminating period.
2. 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, then 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.
3. 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.
4. If the word SUPPRESS appears after library-name and path-name, then the program listing file will not include the contents of the library file or any other library 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.
5. The text of the library file is copied unchanged into the source program unless the REPLACING option is used. If the REPLACING option is used, then elements of the library 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:
a) 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.
b) 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.
c) 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.
d) 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.
e) 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.
f) 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 "MY-COPY.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)
g) 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.
6. 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.
7. 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.
8. 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.
9. 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==.
Then 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.
This parallels the behavior of VAX/COBOL.
10. 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 the ACUCOBOL-GT User's Guide (section 2.5). Note that the compiler's "COPY path" applies to resources (Format 2) as well as to source files (Format 1).
11. 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.
12. If resource-name 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 Acucorp recommends 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 "cblutil" also checks for duplicated program names; COPY RESOURCE does not.
More: