COPYLOC

Use the COPYLOC compiler option to add either a PDSE (or PDS) dataset or z/OS® UNIX directory as an additional location to be searched for copy members during the library phase. The location specified by the COPYLOC option is added to the end of the order of locations to search for copy members. For details, see COPY member search order.

COPYLOC is introduced in Enterprise COBOL V6.2 with the PTF for APAR PI91584 installed.

COPYLOC option syntax

Default is: NOCOPYLOC

Abbreviations are: CPLC | NOCPLC

library-name: The library name that the copy location is to be associated with. When library-name is not specified, the default is SYSLIB, which is the library name assumed in COPY statements that do not include an explicit library name.
dataset-name: The name of a PDS or PDSE dataset in which the compiler should search for copy members when processing COPY statements that refer to library library-name.

unix-directory-name: The name of a z/OS UNIX directory in which the compiler should search for copy members when processing COPY statements that refer to library library-name. The specified path must not exceed 64 characters. To specify a lowercase path, which is standard for z/OS UNIX, the path should be surrounded in quotes. Otherwise, the path name will be converted to uppercase.

Multiple instances of the COPYLOC option are supported. There is no limit on the number of z/OS UNIX directories that can be specified, but there is a limit of 256 datasets that can be specified for searching. Copy locations will be searched in the order that they are specified via the COPYLOC option. This provides users the ability to mix PDSE (or PDS) locations and z/OS UNIX directories in the search.

If the NOCOPYLOC option is specified, any previous instances of the COPYLOC option are ignored.

To control the searching of copy member locations exclusively using the COPYLOC option, you should avoid using any of the existing methods for indicating copybook locations, such as, allocating datasets to a ddname in JCL, or specifying the -I option of the cob2 command. If the compiler is invoked from cob2, you should also avoid keeping copy members in the current directory, because the current directory will always be searched before the COPYLOC locations are being searched.

Tip: You might find it convenient to control searching of copy members exclusively using the COPYLOC option, especially when the compiler is invoked from the cob2 command.

When COPYLOC options are specified in CBL statements, they can be used only on the first program of a batch program. Therefore, if a file has multiple COBOL programs in it, there can be CBL statements with COPYLOC options preceding the first program, but not the other programs. The COPYLOC options specified for the first program (and COPYLOC options specified in PARM of JCL or COPYLOC options specified as cob2 command options under z/OS UNIX) apply to all programs in a file. The copy locations specified in COPYLOC options found in CBL cards will be searched after copy locations found in COPYLOC options specified as invocation parameters.

Example

COPYLOC(MYLIB,DSN(USERID.COBOL.COPYLIB1))
COPYLOC(MYLIB,PATH('/home/userid/copylib1'))
COPYLOC(MYLIB,DSN(USERID.COBOL.COPYLIB2))

For COPY statements that reference library name MYLIB explicitly, if the preceding options were specified in a single invocation of the compiler and a copy member could not be found in the locations specified in JCL (or in locations indicated for a cob2 compile), additional searching for the copy member will be done in the following places sequentially:

USERID.COBOL.COPYLIB1 dataset
z/OS UNIX directory /home/userid/copylib1
USERID.COBOL.COPYLIB2 dataset

related references
COPY statement (Enterprise COBOL for z/OS Language Reference)
COPY member search order (Enterprise COBOL for z/OS Language Reference)
ALOWCOPYLOC (Enterprise COBOL Customization Guide)