Function
The COPY statement inserts texts from a library into a compilation unit. At the same time, it permits parts of the new texts to be replaced.
Format
| ||||
|
|
|
|
|
Syntax rules
text-name is the name of the text which is to be inserted in the compilation unit. The text is stored as a library element ("member") with this name in a library.
text-name is a user-defined word with a length of 1 to 31 characters.If text-name is qualified by library-name, the specified library is searched for the text. If text-name is not qualified by library-name, up to ten libraries are searched for the text. Assignment of libraries at compile time is described in more detail in the "COBOL2000 User Guide" [1].
The COPY statement must be preceded by a space or some other separator symbol.
pseudo-text-1 must contain at least one text word, (see “Text-word” in section "Glossary") while pseudo-text-2 may be empty (
====) or may contain only spaces, comma, semicolon and comment lines.Text words in pseudo-text-1 and pseudo-text-2 and text words which form identifier-1, identifier-2, literal-1, literal-2, word-1, word-2 may be continued on the next line. The pseudo-text separator (
==), on the other hand, must not be continued.word-1 and word-2 may be any single COBOL word except "COPY".
Lowercase letters that are used in text words are equivalent to the corresponding uppercase letters.
A COPY statement is recognized anywhere within a program except:
in comment lines
within non-numeric literals.
The text generated by one COPY statement must not contain another COPY statement. However, the compiler described here permits this in the outermost COPY:If a COPY statement does not contain the REPLACING clause, the related library text may contain COPY statements; these statements may contain the REPLACING clause.
General rules
Execution of a COPY statement causes the library text specified via text-name to be copied to the compilation unit. The library text then replaces the entire COPY statement (including the terminating separator period).
If SUPPRESS is specified, the library text is not included in the compilation unit list.
If REPLACING is not specified, the library text is copied unchanged.
COPY...REPLACING...
If REPLACING is specified, the library text is copied and the text preceding BY (A-operand) is replaced by the text following BY (B-operand).
Text is replaced only if each text word in the text preceding BY matches, character for character, the corresponding library text.
identifier-1, word-1 and literal-1 are treated as pseudo-text containing nothing but identifier-1, word-1 and literal-1.
The comparison of the library text with the text preceding BY (A-operand), the result of which decides whether or not a text is replaced, is carried out as follows:
Everything which precedes the first text word in the library text is copied into the compilation unit. Starting with the first of the A-operands (pseudo-text-1, identifier-1, word-1, literal-1), each A-operand is in turn compared with the corresponding number of library text words, starting each time with the first library word.
Each of the separators comma (,'BLANK'), semicolon (;'BLANK') or space in pseudo-text-1 or in the library text is treated as a single space. Each string of one or more spaces is treated as a single space.
If there is no match, the comparison is repeated with the next A-operand. This process is continued until a match is found or until there are no more A-operands.
When all A-operands of the REPLACING phrase have been compared with the library text without finding a match, the first word of the library text is copied into the compilation unit. The next library text word is then regarded as the first word and the comparison operation is started again with the first A-operand.
Whenever a match occurs between an A-operand and the library text, the corresponding B-operand (pseudo-text-2, identifier-2, word-2 or literal-2) is placed in the compilation unit and replaces the library text corresponding to the A-operand. The library text word following the last text word which was replaced is then regarded as the first text word and the comparison operation is repeated starting with the first A-operand.
The comparison cycle is repeated until the last library text word has been either copied or replaced.
Comment lines or empty lines in the library text or pseudo-text-1 are treated as space characters for the comparison. Any comment lines or empty lines in pseudo-text-2 are moved to the compilation unit unchanged. Comment lines and empty lines in the library text are copied unchanged into the compilation unit unless they are located within a text word sequence which matches pseudo-text-1 and which is therefore replaced.
Debugging lines are permitted within a library text or pseudo-text. Text words in a debugging line are subjected to the comparison rules as if there were no ’D’ in the indicator area (column 7) of the debugging line. A debugging line lies within a pseudo-text if the opening pseudo-text separator appears on a line which precedes the debugging line.
Each word copied from the library, but not replaced, is copied so that it starts in the same area of the line as in the library text.
If replaced by pseudo-text, each text word begins in the same area as specified in pseudo-text-2. Text from a library is copied to the same area of the compilation unit which it occupied in the library. For this reason, it must comply with the rules of the COBOL reference format.If there is a COPY statement in a debugging line, the copied text is treated as if it were also in debugging lines. This also applies to additional lines created by replacements in the compilation unit.
If a COPY statement with the REPLACING phrase causes a line to be lengthened such that additional lines are required, corresponding continuation lines are generated. These lines may contain a continuation character in column 7.
If parts of a text word are to be replaced, the string to be replaced must be enclosed between appropriate separators (e.g. colons or parentheses) in the library text and in the A-operand of the REPLACING phrase, thus identifying it as a separate text word (see "Example 3-4").
The reference format which applies for the COPY statement must be the same as that which also applies for the parts of the library text which may need to be replaced.
Example 3-1
Assume a German library text named ADR, stored in library ADRLIB and consisting of the following lines:
05 STRASSE PIC X(20). 05 PLZ PIC 9(5). 05 ORT PIC X(20). 05 LAND PIC X(20).
In a compilation unit, the COPY statement is written as follows:
01 ADRESSE.
COPY ADR OF ADRLIB.
After execution of the COPY statement, the compilation unit contains:
01 ADRESSE.
COPY ADR OF ADRLIB. ———————————————————————— (1)
05 STRASSE PIC X(20).
05 PLZ PIC 9(5).
05 ORT PIC X(20).
05 LAND PIC X(20).
(1) | Though appearing in the source listing, the COPY statement is treated as comments during compilation. |
Example 3-2
In order to modify library text, the REPLACING phrase is specified in the COPY statement:
COPY ADR OF ADRLIB
REPLACING ADRESSE BY ADDRESS
STRASSE BY STREET
==PLZ PIC 9(5)== BY ==POST CODE PIC X(8)==
ORT BY TOWN
LAND BY COUNTRY.
After execution of this COPY statement, the compilation unit contains:
01 ADRESSE.
COPY ADR OF ADRLIB (1)
REPLACING ADRESSE BY ADDRESS |
STRASSE BY STREET |
==PLZ PIC 9(5)== BY ==POST CODE PIC X(6)== |
ORT BY TOWN |
LAND BY COUNTRY. (1)
05 STREET PIC X(20).
05 POST CODE PIC X(6).
05 TOWN PIC X(20).
05 COUNTRY PIC X(20).
(1) | Though appearing in the source listing, the COPY statement is treated as comments during compilation. |
The changes only affect this compilation unit; the text in the library remains unchanged.
Example 3-3
In order to replace the following string in the library text:
... PIC X(30).
by the string
... PIC X(40).
a space must be inserted after the period in pseudo-text-1 and pseudo-text-2. Otherwise a search will be conducted for a period, but the library text contains a separator period:
...REPLACING ==PIC X(30).
'BLANK' == BY ==PIC X(40).'BLANK'==
Example 3-4
The library text in ELEM
01 FILLER 02 :prefix:-name PIC X(30). 02 :prefix:-address PIC X(30).
is expanded by the COPY statements
... COPY ELEM OF COPYLIB REPLACING ==:prefix:== BY ==in==. COPY ELEM OF COPYLIB REPLACING ==:prefix:== BY ==out==. ...
to
...
01 FILLER
02 in-name PIC X(30).
02 in-address PIC X(30).
01 FILLER
02 out-name PIC X(30).
02 out-address PIC X(30).
...