OA64667: NEW FUNCTION - ARCHRCOV and ARCHSEND API UNIX File Enhancements

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• NEW FUNCTION which enables existing UNIX File Enhancements on
  the ARCHRCOV and ARCHSEND DFSMShsm User Macros. ARCHRCOV is
  enhanced with new parameters RECURSE, NEWDIR, EXCLUDE, and
  EXCLUDEF which enable the same support as the equivalent TSO
  HRECOVER keywords. ARCHSEND is enhanced with new parameter
  FILEMODE which allows directing commands to DFSMShsm Filemode
  hosts.
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * NEW FUNCTION - All DFSMShsm Application                      *
  * Programmers using the ARCHRCOV and/or                        *
  * ARCHSEND User Macros in z/OS 2.5 and later.                  *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * NEW FUNCTION - The DFSMShsm ARCHRCOV                         *
  * User Macro is enhanced to enable                             *
  * recently introduced UNIX file support.                       *
  * New parameters NEWDIR, RECURSE, EXCLUDE                      *
  * and EXCLUDEF are added to ARCHRCOV.                          *
  * These new parameters enable the same                         *
  * support available through the TSO                            *
  * HRECOVER and UNIX hrecover commands.                         *
  * The DFSMShsm ARCHSEND User Macro is                          *
  * enhanced to enable directing                                 *
  * commands to filemode hosts through                           *
  * the new parameter FILEMODE.                                  *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  

Problem conclusion

Temporary fix

Comments

• NEW FUNCTION - The DFSMShsm ARCHRCOV User Macro is enhanced to
  accept new parameters NEWDIR, RECURSE, EXCLUDE, and EXCLUDEF for
  UNIX file processing. These new parameters enable the same
  support available through the TSO HRECOVER and UNIX hrecover
  commands. The DFSMShsm ARCHSEND User Macro is enhanced to enable
  directing commands to Filemode hosts through the new parameter
  FILEMODE.
  
  Documentation updates are made to the following publications:
  
  z/OS DFSMShsm Managing Your Own Data
  SC23-6870
  Chapter 29. Using DFSMShsm User Macros
  ARCHRCOV: Recovering a data set
  
  The following parameters and their explanations are added.
  
  >------------------------------------------------------------->
     |---,RECURSE=------------------------------|
                  |----CROSSMOUNTS---|
                  |--NOCROSSMOUNTS--|
  
  >---------------------------->
     |---,NEWDIR=dnameaddr---|
  
  >------------------------------------------------------------->
     |---,EXCLUDE=elistaddr---| |---,EXCLUDEF=efnameaddr---|
  
  
  RECURSE
  specifies that backups of all files in the directory tree will
  be recovered. The RECURSE parameter accepts sub-parameters
  CROSSMOUNTS and NOCROSSMOUNTS.
  
  When CROSSMOUNTS is specified, the recover starts at the
  specified directory, including files within subdirectories. If
  backups of files from different file systems are encountered, it
  is acceptable to recover them as well.
  
  When NOCROSSMOUNTS is specified, the recover starts at the
  specified directory, including files within subdirectories, but
  will not cross mount points into different file systems. If
  backups from a different file system are encountered, they will
  not be recovered when this option is specified.
  
  If neither CROSSMOUNT or NOCROSSMOUNTS is specified, the file
  backups will be recovered as if RECURSE was not specified.
  
  The RECURSE parameter is mutually exclusive with the DSN
  parameter.
  
  
  NEWDIR
  specifies the address of a field containing the UNIX file path
  of a target directory that the recovered files should be placed
  into. For dnameaddr, use the address of a structure where the
  first two bytes contain the length of the file path and bytes
  3-1025 contain the EBCDIC file path. The specified file path
  must be an absolute path to an existing directory and must end
  in a forward slash '/'. Write and search permission to the
  directory is required.
  
  The NEWDIR parameter is mutually exclusive with the DSN
  parameter.
  
  
  EXCLUDE
  specifies the address of a field containing a comma separated
  list of exclude criteria to apply to the recovered files. Files
  in the backup matching the filename patterns in the exclude
  criteria will be excluded from the request and not recovered.
  For elistaddr, use the address of a structure where the first
  two bytes contain the length of the comma separated list of
  exclude criteria and bytes 3-1025 contain the comma separated
  list. For a detailed explanation of the option, exclude criteria
  syntax, and examples please refer to "EXCLUDE and EXCLUDEF:
  Specifying files or directories to be excluded from
  processing" in Chapter 27. HRECOVER: Recovering data sets or
  UNIX files.
  
  The EXCLUDE parameter is mutually exclusive with the DSN and the
  EXCLUDEF parameters.
  
  EXCLUDEF
  specifies the address of a field containing the UNIX file path
  to a file containing exclude criteria to apply to the recovered
  files. Files in the backup matching the filename patterns in the
  exclude criteria will be excluded from the request and not
  recovered. For efnameaddr, use the address of a structure where
  the first two bytes contain the length of the file path and
  bytes 3-1025 contain the EBCDIC file path. The file path must be
  an absolute path. For a detailed explanation of the option,
  exclude criteria syntax, and examples please refer to "EXCLUDE
  and EXCLUDEF: Specifying files or directories to be excluded
  from processing" in Chapter 27. HRECOVER: Recovering data sets
  or UNIX files.
  
  
  The EXCLUDEF parameter is mutually exclusive with the DSN and
  the EXCLUDE parameters.
  
  z/OS DFSMShsm Managing Your Own Data
  SC23-6870
  Chapter 29. Using DFSMShsm User Macros
  ARCHSEND: Sending a command to DFSMShsm
  
  The following parameter and its explanation is added.
  
  >-------------------------->
     |---,FILEMODE=-----------|
                    |--YES-|
                    |--NO--|
  
  
  FILEMODE
  specifies whether to direct the command to a DFSMShsm Filemode
  host.
  
  
  When YES is specified:
  - If a DFSMShsm Filemode/Classic host environment is configured
    and a Filemode host is active, then the command will be
    directed to the Filemode host.
  - If a DFSMShsm Filemode/Classic host environment is configured
    and a Filemode host is not active, then the command will be
    rejected.
  - If a DFSMShsm Full host environment is configured and a Full
    host is active, then the command will be directed to the Full
    host.
  - If a DFSMShsm Full host environment is configured and a Full
    host is not active, then the command will be rejected.
  
  When NO is specified:
  - If a DFSMShsm Filemode/Classic host environment is configured
    and a Classic host is active, then the command will be
    directed to the Classic host.
  - If a DFSMShsm Filemode/Classic host environment is configured
    and a Classic host is not active, then the command will be
    rejected.
  - If a DFSMShsm Full host environment is configured and a Full
    host is active, then the command will be directed to the Full
    host.
  - If a DFSMShsm Full host environment is configured and a Full
    host is not active, then the command will be rejected.
  
  The default value for FILEMODE is NO.
  
  z/OS DFSMShsm Managing Your Own Data
  SC23-6870
  Chapter 29. Using DFSMShsm User Macros
  Register usage for return codes
  
  The following return codes are added to the list of return
  codes.
  
  418
  The NEWDIR parameter specified a UNIX file path with an invalid
  length. The length of the UNIX file path of the new directory
  which UNIX files will be recovered must be 1-1023 bytes.
  
  419
  The EXCLUDE parameter specified an exclude criteria list with an
  invalid length. The length of the exclude criteria list must be
  1-1023 bytes.
  
  420
  The EXCLUDEF parameter specified a UNIX file path with an
  invalid length. The length of the UNIX file path of the UNIX
  file containing exclude criteria must be 1-1023 bytes.
  
  807
  The requested function is unavailable.
  
  z/OS DFSMShsm Data Areas
  GC14-7504
  Chapter 51. QCT - Queue Control Table
  
  MQCTF_API_UNIXENH is added at byte 6 bit 3 of the QCT. When set
  to 1 indicates this DFSMShsm host has the OA64667 API
  Enhancements.
  
  Table 146. QCT - Queue Control Table
  Offset  Type      Length  Name              Description
  Decimal
  (Hex)
  6(6)    ..1. ....         MQCTF_UNIX_ENH    When 1, indicates
                                              this DFSMShsm host
                                              has the OA64667 API
                                              Enhancements.
  
  
  MQCTF_API_UNIXENH is also added to the QCT Cross-Reference.
  
  Table 151. QCT Control Block Cross-Reference Table
  Name                Hex Offset  Hex Value   Struct Level
  MQCTF_API_UNIXENH   6           2000        3
  
   KEYWORDS: UNIXFILEBACKUP/K
  

APAR Information

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

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

  UJ95400 UJ95404

Modules/Macros

• ARCHRCOV ARCHSEND ARCGIVER ARCPMWE  ARCINIT  ARCGDSN
  

Fix information

• Fixed component name

  DFSMSHSM, ISMF

• Fixed component ID

  5695DF170

Applicable component levels

• R310 PSY UJ95400

     UP24/06/25 P F406  

• R250 PSY UJ95404

     UP24/06/25 P F406  

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.