COPY instruction

Edit online

Use the COPY instruction to obtain source statements from a source language library and include them in the program being assembled. You can thus avoid writing the same, often-used sequence of code over and over.

sequence_symbol: Is a sequence symbol.
member: Name of the source language library member to be copied from either a system macro library or a user macro library. In open code, member can also be a variable symbol that has been set to the member name.

The source statements that are copied into a source module:

Are inserted immediately after the COPY instruction.
Are inserted and processed according to the standard instruction statement coding format, even if an ICTL instruction has been specified.
Must not contain either an ICTL or ISEQ instruction.
Can contain other COPY statements. There are no restrictions on the number of levels of nested copy instructions. However, the COPY nesting must not be recursive. For example, assume that the source program contains the statement:
```
         COPY  A
```
and library member A contains the statement:
```
         COPY  B
```
In this case, the library member B must not contain a COPY A or COPY B statement.
Can contain macro definitions. Note, however, that if a source macro definition is copied into a source module, both the MACRO and MEND statements that delimit the definition must be contained in the same level of copied code.
The scope of any sequence symbols defined by the statements within the COPY member are the same as that of the COPY statement itself. That is, if the COPY statement appears in open code then any sequence symbols defined by statements within the member also have open code scope. Take care to define symbols only once, because COPYing the same member more than once can cause looping due to backward AGO or AIF branches in the source file.
If a copybook is encountered whilst a macro is being parsed, the copybook will be processed. If you need the copybook to be processed conditionally as the macro is executed, you need to code:
```
        AIF     ('&A' NE 'GODZILLA').A0
        MNOTE   0,'DOING THE COPY'
        AINSERT '  COPY    MYCOPY ',BACK
.A0     ANOP    ,
```
MYCOPY will then be included after the macro has completed execution.

Notes:

The COPY instruction can also be used to copy statements into source macro definitions.
The rules that govern the occurrence of assembler language statements in a source module also govern the statements copied into the source module.
Whenever the assembler processes a COPY statement, whether it is in open code or in a macro definition, the assembler attempts to read the source language library member specified in the COPY statement. This means that all source language library members specified by COPY statements in a source program, including those specified in macro definitions, must be available during the assembly. The HLASM Programmer's Guide describes how to specify the libraries when you run the assembler, in these sections:
- CMS: Specifying macro and copy code libraries: SYSLIB
- z/OS®: Specifying macro and copy code libraries: SYSLIB
- z/VSE®: Specifying macro and copy code libraries: LIBDEF job control statement
If an END instruction is encountered in a member during COPY processing, the assembly is ended. Any remaining statements in the COPY member are discarded.