Return codes from the extended set

When the EXTENDRC parameter is specified on the HBACKDS, HDELETE, HRECALL, HRECOVER or HMIGRATE commands, DFSMShsm assigns both a return code and a reason code in register 15 that provides a more detailed indication of the results from processing the request. In most cases, the return codes correspond to the message number that DFSMShsm issues to provide an explanation when the request fails. If there is a reason code associated with the failure, it is also returned.

Important: The return code is returned in the high-order two bytes of register 15. The reason code is returned in the low-order two bytes of register 15.

To obtain the corresponding message number from the contents of register 15, the following algorithms are used:

For return code: HSMRC = (contents of register 15 / 65536)
For reason code: HSMREAS = (contents of register 15 - (HSMRC × 65536))

The following example shows how to obtain the return code, the corresponding message number, and any associated reason code from the contents of register 15. For this example, when we tried to migrate a data set that was not eligible for migration, we received the following values:

Table 1. Return codes from the extended set example: register 15 values
Decimal Value	HEX Value
1310724	00140004

Return code:
- HSMRC = (1310724 / 65536)
- HSMRC = 20.000061
- HSMRC = 20
The HSMRC variable contains the return code value of 20. The return code (or nn) can be used to locate the corresponding message number; in our migration example, ARC12nn or ARC1220.
Reason code:
- HSMRC = 20 (return code must be obtained before reason code)
- HSMREAS = (1310724 - (20 × 65536))
- HSMREAS = (1310724 - 1310720)
- HSMREAS = 4
The HSMREAS variable contains the reason code value of 4. Look for this reason code under the corresponding message number; in our migration example, message ARC1220 and reason code of 4.

When you are using a TSO CLIST, the return and reason codes are both provided in register 15 for access as the CLIST variables: &LASTCC or &MAXCC; The CLIST example (see below) shows how to separate the return and reason codes set by DFSMShsm from the &LASTCC variable.

When you are using ISPF, the return and reason codes are both provided in register 15 and can be obtained by using the HELP function. Use the given algorithms to obtain the return code, the corresponding message number, and any associated reason code.

The EXTENDRC parameter is best used when single data set requests are issued. When a multiple data set request is issued, multiple failures are reported with a single, generic return code of 112.

Table 2 lists the return codes that belong to the extended set. These return codes are returned in the high-order two bytes of register 15 with the exception of return code 18, which is returned in the low-order two bytes of register 15.

Table 2. Extended set return codes
Retcode	Meaning
0	No errors are detected.
18	A command syntax error is detected. The return code is reported in the low-order two bytes of register 15.
112	For a multiple data set request, more than one type of error was detected, or more than one functional failure has occurred.
114	A data set error has occurred. A data set error occurs when the data set is not cataloged for a command that requires a cataloged data set or if the data set name syntax is incorrect. DFSMShsm did not receive the request.
116	A DFSMShsm SVC path error has occurred. An error has occurred in communicating with DFSMShsm. DFSMShsm did not receive the request.
120	An ABEND occurred.
nn	A DFSMShsm functional failure occurred (the WAIT option was specified) and the MWE return code of the functional failure coincides with ARCxxnn messages as follows: Failing recall/recovery/delete messages ARC1101 to ARC1199 have return codes 1 to 99. Note: It is not considered an error when an HRECALL command finds that the data set is not cataloged to volume MIGRAT. The informational message ARC1102I will be issued and zero will be returned in register 15. Failing migration messages ARC1201 to ARC1299 have return codes 1 to 99. Failing backup messages ARC1301 to ARC1399 have return codes 1 to 99. Failing DFSMShsm command messages ARC1601 to ARC1699 have return codes 1 to 99. Attention message ARC1800 has return code 100. This return code is returned when the request is interrupted with a TSO attention request. Abnormal ending message ARC1900 of the preceding function has a return code of 120.

These reason codes have meaning only with specific return codes. Reason codes are described with the corresponding messages. See or z/OS MVS System Messages, Vol 2 (ARC-ASA).

The following fragment is an example of checking return codes when issuing DFSMShsm commands from a CLIST running in the foreground:

        /*ERROR EXIT TO GET RETURN AND REASON CODES FROM REGISTER 15*/
      ERROR DO
              SET   HSMRC = &EVAL(&LASTCC; / 65536)
              SET   HSMREAS = &EVAL(&LASTCC - &EVAL(&HSMRC * 65536))
              RETURN
            END
         /*RECOVER THE DATA SET */
         HRECOVER DATA.SET.NAME REPLACE WAIT EXTENDRC
         IF &HSMRC = 45 THEN -
           /*IF DATA SET IS MIGRATED, RECALL THE DATA SET */
          DO
            SET HSMRC = 0
            SET HSMREAS = 0
            HRECALL DATA.SET.NAME WAIT EXTENDRC
            IF &HSMRC = 0 THEN -
              /*IF RECALL IS SUCCESSFUL, ATTEMPT DATA SET RECOVER
              HRECOVER DATA.SET.NAME REPLACE WAIT EXTENDRC
            ELSE -
              /*IF RECALL IS NOT SUCCESSFUL, ISSUE MESSAGE */
              DO
               WRITE RECALL NOT SUCCESSFUL
               EXIT
              END
          END
         ELSE -
           /*IF DATA SET IS NOT MIGRATED OR RECOVERY NOT SUCCESSFUL
           /*ISSUE MESSAGE */
           DO
             WRITE RECOVERY NOT SUCCESSFUL
             EXIT
           END
      EXIT