Customizing Z Data Tools batch return codes
Z Data Tools provides the facility for you to control the value of return codes issued by the Z Data Tools batch utilities. You can set return codes to values more suitable for your site, for example, to suit your job control environment. Return codes cannot be changed on an ad hoc basis. They are established for the whole installation.
- Data set copy (DSC)
- Data set generate (DSG)
- Data set compare (DSM)
- Data set print (DSP)
- Data set update (DSU, and including DSEB)
- Display VTOC (DVT)
- Find/change (FCH)
You customize the batch utility return codes using the macro statements sample member, HFM0RETC, and the usermod HFMUMODR, to create a load module, HFM0RETC. HFM0RETC in HFM.SHFMSAM1 shows the conditions that can be customized for each utility, with the default return codes for those conditions.
During initialization, Z Data Tools will attempt to load HFM0RETC, and if the module is found its contents will be used to build a table of customized condition return codes. If HFM0RETC is not found, all the customizable conditions will issue their default return codes.
To customize the return codes:
- Copy the HFM0RETC member from HFM.SHFMSAM1 to your own source library.
- Modify the HFM0RETC member in your own library, as required. Change the number against the required conditions in HFM0RETC to the return code values you want those conditions to give. Note that you cannot change any condition's value to 16. The value 16 is reserved for use by Z Data Tools. Default HFM0RETC macro statements supplied with Z Data Tools shows the default set of HFM0RETC macro statements.
- Modify the HFMUMODR member in HFM.SHFMSAM1 to meet your site's requirements. Refer to the usermod for information about changes you might need to make.
- Install SMP/E usermod HFMUMODR.
HFM0RETC TITLE 'Z Data Tools : Return Codes (Batch Utilities)'
HFM0RETC CSECT
HFM0RETC AMODE 31
HFM0RETC RMODE ANY
HFM0RETI FUNC=DSC, DSC conditions X
NORECSSOME=1, No records copied for some members X
NORECSANY=2, No records copied for any members X
NONESEL=4, No records selected to copy X
NOMEMBERS=4, No members to process X
EMPTY=4, Empty input data set X
SKIPPED=4, Input packed, so skipped X
NOREPLACE=4, NOREPLACE prevented copy X
NOCPYDUPE=2, No copy - duplicate X
NOCPYREXX=2, No copy - REXX X
RECTRC=0, Records truncated X
FLDTRC=0, Fields truncated X
RECSHORT=8, DSC external form output truncated X
REXXCONFLICT=3 REXX return message conflict
HFM0RETI FUNC=DSG, DSG conditions X
NORECSOUT=4 Zero records specified
HFM0RETI FUNC=DSM, DSM conditions X
NOTMATCH=1, Compare sets not empty & don't match X
ONEEMPTY=2, One compare set empty X
SKIPPED=4, Input packed, so skipped X
BOTHEMPTY=4, Both compare sets empty X
INVMAP=4, Invalid mapping X
INVDATA=8 Invalid data X
SYNCERR=8 Key Synchronization error
HFM0RETI FUNC=DSP, DSP conditions X
MBRERR=1, Some members not printed X
PRTERR=2, Print error encountered X
NONESEL=4, No records selected to print X
NOMEMBERS=4, No members to process X
SKIPPED=4, Input packed, so skipped X
EMPTY=4, Empty input data set X
NOPRTREXX=2, No print - REXX X
REXXCONFLICT=3 REXX return message conflict
HFM0RETI FUNC=DSU, DSU conditions X
MBRNOTUPDT=1, Some members not updated X
NOCHANGE=2, Change failed X
NONEUPDATED=4, No records updated X
NOMEMBERS=4, No members to process X
SKIPPED=4, Input packed, so skipped X
EMPTY=4 Empty input data set
HFM0RETI FUNC=DVT, DVT conditions X
NOENTRY=4 No matching entries
HFM0RETI FUNC=FCH, FCH conditions X
FSOME=1, Some OK, some not OK X
CFAIL=2, Change failed X
NOHIT=4, No strings found to change X
NOMEMBERS=4, No members to process X
SKIPPED=4, Input packed, so skipped X
LOWSTOR=12, Ran low on storage during FCH X
EMPTY=4 Empty input data set
HFM0RETI END
END HFM0RETC
The return code from a batch utility will be the highest return code, (customized or otherwise), for all the conditions that arose during the execution of the utility. For example, suppose you have changed the return code for "No members to process" in the DSC utility from 4 to 9. If a condition arises that in isolation would result in return code 8 (normally an error), and the "No members to process" condition also occurs, the return code for the DSC utility will be 9.
The return code from a batch job executing more than one utility will continue to be the maximum of the codes, (customized or otherwise), returned by each of the utilities. The exception to this is that if any of the utilities encounters a terminating condition then the job step will terminate with a return code 16.
- Several conditions can be present in a function concurrently. For example, using DSP with a template on an empty file may result in both the "empty input data set" condition, and the "no records selected to print" condition. If you customize a return code, be aware that a higher return code for another condition may override it or be over-ridden by it. If you customize one return code for a given function, review that function's other return codes for compatibility.
- In batch, you might want Z Data Tools to abend rather
than end with the original or customized non-zero return code, to
prevent the execution of successive steps or jobs. You do this by
setting the ABENDCC installation option to a value less than or equal
to the return code. This will then be transformed to an abend (Abend
999, Reason Code=888 (hex: 378)). For more information, see ABENDCC, and also the ABENDCC option of
the SET command, described in section
SET (Set Processing Options)
in Z Data Tools User’s Guide and Reference .