The COPY Statement

To include pre-written Jazz code in a program.

Synonyms USE, INCLUDE, IMPORT

FORMAT

COPY code-name

[TYPE (type-definition)]

[NAME new-name]

[JAZZ]

;

The COPY statement causes the named code to be copied into the Jazz program from the Jazz Copy Library (refer to the Workbench’s Configuration Window). The code must be one or more complete Jazz statements.

COPY may include further COPY statements. For example: -

COPY AllTables;

might retrieve this code: -

COPY Table1;

COPY Table2;

COPY Table3;

COPY is of course very similar to COBOL’s COPY statement, but it has a few differences that make it more flexible.

Firstly, COPY will not copy code that’s already been copied. For example

COPY Table1;

…

COPY Table1;

The second COPY Table1; statement will be ignored. The advantage of this is that it is possible to include one COPY within another without the risk of this causing errors. For example, here a COMMAREA (CICS Communication Area) includes a copy of the CUSTF record that was read by the enquiry program. The COMMAREA definition is written: -

COPY Custf;

DEFINE COMMAREA TYPE (COMMAREA) DATA(

Function CHAR(1) VALUE ‘E’ VALIDVALUES (‘E’, ‘U’, ‘A’, ‘D’),

SaveCustf LIKE Custf.*);

Now it doesn’t matter whether or not there is already a definition of CustF within the program: the first will be used, and the second harmlessly discarded.

Another difference is that copy code can include both definition and imperative statements. Jazz definitions don’t have to be separated into a Data Division, the only rule is that they must precede any reference to their data. So you could write in one copy book: -

DEFINE Record …;

IF Record.Code = “first” THEN

statements to initialize Record

END IF;

A third difference is that you can change the name of the record, and the definition type, by adding TYPE and NAME options to the statement.

Show COPY Code

Normally you don’t see the code that is retrieved with COPY, although Jazz processes it (for example, creating data definitions that your program can use) as if it were normal code. In Configuration you can click the option “Show Copy Code”: -

The Copy Code is now displayed in your program, with a grey background: -

(NB: in this example “Copy2Tables;” causes “Copy Table” and “Copy Table2” to be included), which results in the actual definitions of Table and Table2 being included).

Changing Copy Code

You should not change the copy code from within this program. While you can change any of the grey lines, any changes you make will be lost as soon as the program is re-processed as COPY will retrieve another copy of the copy book, restoring the original text. You can easily change the copy book with another workbench session: just right-click on the COPY statement and another session will open. If you make changes and return to the parent session then the new record layout will be used when you next [Check] or [Process] the program.

OPTIONS

JAZZ

A Jazz program (extension .jzz) starts with some standard definitions of COBOL figurative constants and functions, and some Jazz standard definitions. These are inserted from Jazz, not from the normal COPY library (Cpylib).

When you are editing a copy book (extension .jzc) these standard definitions are not included again, and [Show all] won’t show any hidden lines unless COPY statements are present. If the copy book includes references to the standard definitions then you can include

COPY COBOL JAZZ;

to include them. JAZZ causes the copy book COBOL to be read from Jazz instead of Cpylib.

NAME and TYPE

This allows you to use a definition with another name. For example,

COPY record1 NAME(Save)

renames the next DEFINE statement to “Save”, so that it is as if COPY Record1 caused code

DEFINE Save TYPE(VSAM) DATA(

Field1 …,

Field2 …);

to be included in your program. You can thus create several record areas with the same layout.

NAME is often used with the TYPE option, which substitutes the TYPE option. For example, suppose that you need to save a previous version of RECORD1. You write

COPY record1;

COPY Record1 NAME(SaveRecord) TYPE(WorkingStorage);

The NAME and TYPE option apply only to the first DEFINE statement encountered within the COPY statement. They do not apply to DEFINE statements following the COPY statement, or in lower-level COPY statements (e.g. if the COPY includes COPY).

NAME and TYPE options only apply when the first statement of the code retrieved from the library is a DEFINE statement. The options will not apply to following DEFINE statements, nor to DEFINE statements that follow another COPY statement (as when COPY brings in COPY statements).