COPY Libraries

The COPY verb accepts the following forms:

COPY library-name [ OF path-name ] [ SUPPRESS ].
COPY RESOURCE resource-name [ OF path-name ].

where library-name and path-name are either user-defined words or alphanumeric literals. resource-name is an alphanumeric literal.

Environment variables may be used in path-name -- this is indicated by a $ sign before the name of the variable. For example:

COPY library-name OF "$COPYLIB".

You may also use multiple environment variables to define a path:

COPY library-name OF "$LIB/$COPYLIB/$SUBDIR".

library-name is the file name of the copy file to include in the object library. resource-name is a file (other than a COBOL object) that is to be included in a COBOL object library. If path-name is specified, then it is treated as a directory specification for library-name or resource-name.

The file name is derived by concatenating path-name with library-name or resource-name, using the appropriate syntax for the host operating system. For example, on a UNIX system,

COPY MYCOPY OF "/usr2/acctdir"

is translated to

COPY "/usr2/acctdir/MYCOPY".

Note: Note the use of quotation marks on path-name and on library-name and resource-name when they include lower case letters. This is a requirement on systems that are case sensitive, because the runtime would otherwise convert lower case to upper case.

The -Ce compatibility option can be used to specify an alternate default file extension. See Compatibility Options for more information.

A library name can be specified by a user-defined word which may include a period. This is a special extension to the meaning of user-defined word. This allows you to specify a file extension without putting the name in quotes. For example, the two statements:

COPY "MYFILE.CPY"

and

COPY MYFILE.CPY

are both allowed and mean exactly the same thing.

When a period is placed in a library name which is a user-defined word used without quotes, it must be preceded and followed by a (non-period) character normally allowed in an identifier (thus .MYFILE, MYFILE. and MYFILE..CPY are all disallowed).

In addition, the COPY RESOURCE statement allows the resource name to be a user-defined word just like in a Format 1 COPY statement (the resource name does not have to be an alphanumeric literal).

Note: User-defined words are always treated as uppercase on machines where file names are case-sensitive.

If the derived file name is a full path name or contains a drive designation, then that name is used unmodified. Otherwise, a series of directories is searched to find the COPY file. The default search path is just the current directory.

You can modify the search path by setting an operating system variable. On UNIX, Linux, and Windows systems, you do this by setting the environment variable COPYPATH to be the list of directories to search. For VMS systems, the symbol COPYPATH is set instead.

The COPYPATH variable consists of a series of prefixes to apply to the file name. Each prefix is terminated by a special character that depends on the host operating system.

System	Separator
Windows	Semicolon
UNIX/Linux	Colon
MPE/iX	Colon
VMS	Comma

For example, to search the current directory, the directory /u/pr and the directory /u/ap on a UNIX system, the appropriate COPYPATH setting would be:

:/u/pr:/u/ap:

The initial colon indicates an empty prefix (i.e., the current directory). Note that the -Sp compiler option can also be used to specify the search path for COPY libraries. If used, it takes precedence over the COPYPATH setting.

You may use the word SUPPRESS to exclude the contents of a COPY file or any COPY files nested within from the program listing. For example:

COPY MYFILE OF "$MYLIB" SUPPRESS.

COPY statements may contain other COPY statements. This nesting is limited by the total number of files that the operating system will allow a program to open at once.