PI91584: SUPPORT FOR MIXING COPYBOOKS FROM PDS DATASETS AND Z/OS UNIX DIRECTORIES IN A SINGLE COMPILE

Obtain the fix for this APAR.

APAR status

• Closed as unreproducible in next release.

Error description

• Support has been added to the compiler to allow a single compile
  job to access copybooks from both PDS datasets as well as z/OS
  UNIX directories. A new option COPYLOC is provided for this
  support.
  

Local fix

• N/A
  

Problem summary

• ****************************************************************
  * USERS AFFECTED: Users of Enterprise COBOL 6.2 who want to    *
  *                 invoke the compiler from z/OS UNIX using     *
  *                 the cob2 command and access copybooks        *
  *                 located in PDS or PDSE datasets, or invoke   *
  *                 the compiler from JCL or TSO and access      *
  *                 copybooks located in z/OS UNIX directories.  *
  ****************************************************************
  * PROBLEM DESCRIPTION: New function: Users need a way to       *
  *                      access copybooks in PDS or PDSE         *
  *                      datasets when the compiler is invoked   *
  *                      from cob2, and they also need a way to  *
  *                      access copybooks from z/OS UNIX         *
  *                      directories when the compiler is        *
  *                      invoked from JCL or TSO.  This APAR     *
  *                      provides a new compiler option COPYLOC  *
  *                      that allows users to specify copybook   *
  *                      search locations that are either PDS    *
  *                      (or PDSE) datasets or z/OS UNIX         *
  *                      directories and these search locations  *
  *                      can be specified regardless of how the  *
  *                      compiler is invoked (cob2, JCL, etc.).  *
  ****************************************************************
  * RECOMMENDATION: Apply the provided PTF.                      *
  ****************************************************************
  When the COBOL compiler was invoked from z/OS UNIX using the
  cob2 command, it was only possible to access copybooks located
  in z/OS UNIX directories.  Similarly, when the COBOL compiler
  was invoked from JCL or TSO, it was only possible to access
  copybooks located in PDS or PDSE datasets.
  

Problem conclusion

Temporary fix

Comments

• When the COBOL compiler was invoked from z/OS UNIX using the
  cob2 command, it was only possible to access copybooks located
  in z/OS UNIX directories.  Similarly, when the COBOL compiler
  was invoked from JCL or TSO, it was only possible to access
  copybooks located in PDS or PDSE datasets.
  
  
  = PROBLEM CONCLUSION =                          (max col 64 )<-|
  Support for the COPYLOC option was added to the compiler.  This
  option allows users to specify PDS or PDSE copybook locations
  when compiling from the cob2 command and to specify z/OS UNIX
  directory copybook locations when invoking the compiler from
  JCL or TSO.
  
  
  +-------------------------------------------------------------+
  | Start of changes for:                                       |
  | Enterprise COBOL for z/OS Programming Guide, SC27-8714-01   |
  
  Chapter 17: Compiler options
  
  Add new compiler option COPYLOC.
  
  COPYLOC
  
  Use the COPYLOC compiler option to add either a PDS or PDSE
  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
  
     .-NOCOPYLOC-------------------------------------------.
  >>-+-----------------------------------------------------+---->
     '-copyloc-option-clause-------------------------------'
  
  
  copyloc-option-clause:
  
                 .-SYSLIB--,-------.
  >--COPYLOC--(--+-----------------+---------------------------->
                 '-library-name--,-'
  
  >--+-DSN--(--dataset-name--)---------+--)--------------------><
     '-PATH--(--unix-directory-name--)-'
  
  Default is: NOCOPYLOC
  
  Abbreviations are: CPLC | NOCPLC
  
  library-name
      The library name with which the copy location is to be
      associated. 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 PDS and PDSE locations with
  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 by using the
  COPYLOC option, you should avoid using any of the existing
  methods for indicating copybook locations, for example,
  allocating datasets to a ddname in JCL, or using 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 prior to the COPYLOC locations being searched.
  
  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 above 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 firstly in the USERID.COBOL.COPYLIB1
  dataset, secondly in the z/OS UNIX directory
  /home/userid/copylib1, and finally in the
  USERID.COBOL.COPYLIB2 dataset.
  
  Chapter 15: Compiling under z/OS UNIX
  
  Setting environment variables under z/OS UNIX
  ...
  SYSLIB
  ...
           4.  In the locations specified in instances of the
           COPYLOC option that use the default library name or
           specify an explicit library name of SYSLIB.
  
  | End of changes for:                                         |
  | Enterprise COBOL for z/OS Programming Guide, SC27-8714-01   |
  +-------------------------------------------------------------+
  
  +-------------------------------------------------------------+
  | Start of changes for:                                       |
  | Enterprise COBOL for z/OS Language Reference, SC27-8713-01  |
  
  Chapter 22: Compiler-directing statements
  
  COPY statement
  ...
  text-name, library-name
  ...
  When searching for COPY members in PDS or PDSE datasets,
  including those specified in the COPYLOC option with the DSN
  argument, only the first eight characters of text-name are used
  as the identifying name. When searching for COPY text in
  z/OS UNIX directories, such as those directories specified
  via the -I option of the cob2 command or those directories
  specified via the SYSLIB environment variable (when the
  compiler is invoked from cob2) or those directories specified
  via the COPYDIR option, all characters are significant.
  
  Add new sub-section to COPY statement documentation:
  
  Copy member search order
  
  This topic discusses the search order of copy members when a
  COPY statement is processed.
  
  When the compiler is invoked from JCL or any method
  other than from z/OS UNIX, the search for a copy member is
  performed according to the following rules:
  
      o If an explicit library name is specified in the COPY
      statement, the name is assumed to correspond to a ddname
      that has been allocated to a concatenation of datasets
      in which the compiler will search for the copy
      member. If no library name is specified in the COPY
      statement, the concatenation of datasets allocated to the
      SYSLIB ddname is searched.
      o If the copy member was not found during the above search,
      then all locations specified via the COPYLOC option will be
      searched in the order that they were specified. These
      locations can include a mix of z/OS UNIX directories and
      PDS or PDSE datasets.
  
  When the compiler is invoked in z/OS UNIX using the cob2
  command, the search for a copy member is performed according
  to the following rules:
  
      o If an explicit library name is specified in the COPY
      statement and the name is a literal, the name will be
      interpreted as a z/OS UNIX directory and that directory
      will be searched.
      o If an explicit library name is specified in the COPY
      statement and it is not a literal, the name is interpreted
      to be an environment variable specifying a colon-separated
      list of z/OS UNIX directories. If the environment variable
      exists, those z/OS UNIX directories will be searched in the
      order they appear in the list. If the environment variable
      does not exist, the current directory will be searched.
      o If an explicit library name was not specified in the COPY
      statement, the compiler searches for copy members in this
      order:
          - The current z/OS UNIX directory is searched for the
          copy member.
          - Any z/OS UNIX directories specified via the -I option
          of cob2 are searched.
          - Any z/OS UNIX directories specified via the SYSLIB
          environment variable are searched.
  
      o If the copy member was not found during the above search,
      then all locations specified via the COPYLOC option are
      searched in the order that they were specified. These
      locations can include a mix of z/OS UNIX directories and
      PDS or PDSE datasets.
  
  | End of changes for:                                         |
  | Enterprise COBOL for z/OS Language Reference, SC27-8713-01  |
  +-------------------------------------------------------------+
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  PI96231

Modules/Macros

• IGY8RWRD IGY8RWTU IGYCASMB IGYCCBE  IGYCCCRT IGYCCICS IGYCCSRV
  IGYCDGEN IGYCDIAG IGYCDMAP IGYCDOPT IGYCEN$0 IGYCEN$1 IGYCEN$2
  IGYCEN$3 IGYCEN$4 IGYCEN$5 IGYCEN$8 IGYCEN$D IGYCEN$R IGYCFGEN
  IGYCFREE IGYCINIT IGYCJA$0 IGYCJA$1 IGYCJA$2 IGYCJA$3 IGYCJA$4
  IGYCJA$5 IGYCJA$8 IGYCJA$D IGYCJA$R IGYCLIBH IGYCLIBO IGYCLIBR
  IGYCLSTR IGYCLVL0 IGYCLVL1 IGYCLVL2 IGYCLVL3 IGYCLVL8 IGYCMALL
  IGYCOB2E IGYCOPI  IGYCOSCN IGYCPGEN IGYCRCTL IGYCRDPR IGYCRDSC
  IGYCREAL IGYCRWT  IGYCSCAN IGYCSIMD IGYCUE$0 IGYCUE$1 IGYCUE$2
  IGYCUE$3 IGYCUE$4 IGYCUE$5 IGYCUE$8 IGYCUE$D IGYCUE$R IGYCXREF
  IGYDRV   IGYEQCWI IGYMSGE  IGYMSGK  IGYMSGT  IGYMSGXT IGYQCBE
  IGYZQDRV IGYZQENU IGYZQJPN
  

Fix information

• Fixed component name

  ENT COBOL FOR Z

• Fixed component ID

  5655EC600

Applicable component levels

• R620 PSY UI53355

     UP18/01/27 P F801

• R621 PSY UI53356

     UP18/01/27 P F801

• R622 PSY UI53357

     UP18/01/27 P F801

• R62H PSY UI53358

     UP18/01/27 P F801

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.