I would like to share some information about the new COPYLOC compiler option that is available in Enterprise COBOL 6.2 with the PTF for PI91584 installed (i.e., the January 2018 PTF), and should be available very soon in the 6.1 release.
The COPYLOC compiler option allows the COBOL compiler to access a mix of copybooks located in partitioned datasets and z/OS UNIX directories within a single compile job, regardless of how the compiler is invoked. This feature may be of particular interest to users wanting to explore the popular Git source code control system for use with their build and development systems and who thus want to invoke the compiler via the cob2 command while still accessing copybooks located in existing partitioned datasets.
Background
Prior to the introduction of the COPYLOC compiler option, compile jobs launched from z/OS UNIX via the cob2 command could only access copybooks located in z/OS UNIX directories. Conversely, compile jobs launched from JCL (or TSO, etc.) could only access copybooks located in partitioned datasets.
With COPYLOC, however, it is now possible within a single compile job to specify a mix of z/OS UNIX directories and partitioned datasets to search for COBOL copybooks. Moreover, since COPYLOC is provided as a true compiler option and not an option that is tied to a specific type of invocation (i.e., it's not a cob2 option), this facility is available no matter how the compiler is invoked (e.g., from cob2, from JCL, from TSO, from an assembler program, from a 'C' program, etc.).
The basic syntax of the the COPYLOC compiler option is as follows:
COPYLOC([library-name,] DSN(dataset-name) | PATH('unix-dir-name'))
Note that if library-name is omitted, it is assumed to be SYSLIB. Multiple instances of the option are allowed in order to specify as many locations as needed. Locations are searched in the order they are specified.
The best way to learn how the option works is to probably work through some examples.
Examples
Example 1:
A user launches the compiler from z/OS UNIX via the cob2 command to compile a program, prog.cbl, located on the z/OS UNIX file system, and copybooks for prog.cbl reside in four different PDSE datasets divided between two different library names, SYSLIB and MYLIB1.
SYSLIB: CBLSRC.COBOL.COPYLIB1
CBLSRC.COBOL.COPYLIB2
MYLIB1: CBLSRC.COBOL.COPYLIB3
CBLSRC.COBOL.COPYLIB4
Here is a cob2 command that can be used to compile prog.cbl:
cob2 prog.cbl -o prog "-qlist,opt(2)"
"-qcopyloc(dsn(cblsrc.cobol.copylib1))"
"-qcopyloc(dsn(cblsrc.cobol.copylib2))"
"-qcopyloc(mylib1,dsn(cblsrc.cobol.copylib3))"
"-qcopyloc(mylib1,dsn(cblsrc.cobol.copylib4))"
Notes:
1. Assuming this program was previously compiled from JCL, no change to the user source is required in this scenario. All COPY statements in the current source will work as-is.
2. It is still possible to specify z/OS UNIX directory search locations via the -I option of cob2 and also by associating colon-separated lists of z/OS UNIX paths to environment variables with names that match their corresponding library name. If you choose to use either (or both) of these existing methods, the locations they specify will be searched prior to any locations specified via COPYLOC.
For simplicity, it may be convenient to handle the specification of all search locations via COPYLOC. However, if you are using -I today in your build scripts and just want to add in a list of partitioned datasets to search when the copybook is not found on the z/OS UNIX file system, simply adding one or more COPYLOC options to your existing scripts can be a very straight-forward solution.
Example 2:
A user launches the compiler from z/OS UNIX via the cob2 command to compile a program, prog.cbl, located on the z/OS UNIX file system, and all copybooks needed by prog.cbl are associated with library name SYSLIB and reside in a mix of PDSE datasets and z/OS UNIX directories because some of the copybooks in each dataset have been migrated to z/OS UNIX directories (but not all of them). Previously the search order of the datasets when the compiler was invoked from JCL was as follows:
CBLSRC.COBOL.COPYLIB1
CBLSRC.COBOL.COPYLIB2
CBLSRC.COBOL.COPYLIB3
During migration, some copybooks from CBLSRC.COBOL.COPYLIB1 were moved to /home/cblsrc/lib/copylib1, and similarly for the other two datasets.
To achieve the same search order used prior to this partial migration of copybooks to z/OS UNIX directories, the new set of copybook locations need to be searched in the following order:
CBLSRC.COBOL.COPYLIB1
/home/cblsrc/lib/copylib1
CBLSRC.COBOL.COPYLIB2
/home/cblsrc/lib/copylib2
CBLSRC.COBOL.COPYLIB3
/home/cblsrc/lib/copylib3
A cob2 command that will achieve this search order for copybooks is as follows:
cob2 prog.cbl -o prog "-qlist,opt(2)"
"-qcopyloc(dsn(cblsrc.cobol.copylib1)),copyloc(path('/home/cblsrc/lib/copylib1'))"
"-qcopyloc(dsn(cblsrc.cobol.copylib2)),copyloc(path('/home/cblsrc/lib/copylib2'))",
"-qcopyloc(dsn(cblsrc.cobol.copylib3)),copyloc(path('/home/cblsrc/lib/copylib3'))"
Notes:
1. Assuming the copybook names appear in COPY statements without being surrounded by alphanumeric character delimiters (e.g., ' or "), to avoid changing the source code in this scenario, the copybooks need to be copied to the z/OS UNIX directory with their name in upper case, although a file extension, even a lower-case one, can be added and the file will still be located by the compiler.
e.g., Copybook CBLSRC.COBOL.COPYLIB1(ACCTINFO) could be moved to:
/home/cblsrc/lib/copylib1/ACCTINFO.cpy
Note that when the copybook name in the COPY statement is NOT delimited by alphanumeric character delimiters, the compiler will try to search for the copybook on the z/OS UNIX file system trying each of the following extensions (including no extension) until the item is found: .cpy, .CPY, .cbl, .CBL, .cob and .COB. This behavior has always existed for locating copybooks in z/OS UNIX directories.
2. If you want the copybook member to have a lowercase name in the z/OS UNIX file system, e.g.
/home/cblsrc/lib/copylib1/acctinfo.cpy
the COPY statement in your code will need to have the copybook name delimited by alphanumeric character delimiters, e.g.
COPY 'acctinfo.cpy'.
Note that when the copybook name is delimited by alphanumeric character delimiters in the source, the compiler does NOT search automatically for different variations of the copybook name with different extensions as shown in point (1) above. Instead, a single search is done for the exact name provided in the COPY statement. Again, this behavior has always existed for locating copybooks in z/OS UNIX directories.
3. I think in the future it may be useful for users to have the ability (through a compiler option, probably) to tell the compiler to search for a lowercase version of copybook names that appear in COPY statements, whether the name is delimited or not, and to also try searching for different filename extensions as well. This would allow copybooks migrated to z/OS UNIX directories to have lowercase names and a filename extension, which is more natural in UNIX, and might help avoid the need to change source code. Some feedback on this point would be welcome.
Example 3:
A user launches the compiler from JCL to compile COBOL program PROG. Copybooks associated with library name SYSLIB are located in PDSE datasets CBLSRC.COBOL.COPYLIB1 and CBLSRC.COBOL.COPYLIB2. All copybooks associated with library name MYLIB1 are located in z/OS UNIX directory /home/cblsrc/lib/copylib3.
It is assumed that the JCL for the compile job already contains the following SYSLIB concatenation.
SYSLIB DD DSN=CBLSRC.COBOL.COPYLIB1,DISP=SHR
DD DSN=CBLSRC.COBOL.COPYLIB1,DISP=SHR
This should be maintained in the JCL, but the following should be added to the options file (via SYSOPTF) or directly to the PARM string, if there is enough space:
SYSOPTF DD DATA,DLM='/>'
COPYLOC(MYLIB1,PATH('/home/cblsrc/lib/copylib3'))
/>
For these types of JCL compiles, the library concatenations specified in the JCL will always be searched before any locations specified by the COPYLOC option are searched.
Support for COPYLOC in ID/z
ID/z recognizes and understands the COPYLOC option. Here is a short YouTube video showing how to use COPYLOC from within ID/z:
https://www.youtube.com/watch?v=IEVY9D3dsWc
Further reading
https://www.ibm.com/support/knowledgecenter/SS6SG3_6.2.0/pg/ui/up1010.html?sc=SS6SG3_latest