Customizing File Manager batch return codes
File Manager provides the facility for you to control the value of return codes issued by the File Manager 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, FMN0RETC, and the usermod FMNUMODR, to create a load module, FMN0RETC. FMN0RETC in FMN.SFMNSAM1 shows the conditions that can be customized for each utility, with the default return codes for those conditions.
During initialization, File Manager will attempt to load FMN0RETC, and if the module is found its contents will be used to build a table of customized condition return codes. If FMN0RETC is not found, all the customizable conditions will issue their default return codes.
To customize the return codes:
- Copy the FMN0RETC member from FMN.SFMNSAM1 to your own source library.
- Modify the FMN0RETC member in your own library, as required. Change the number against the required conditions in FMN0RETC 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 File Manager. Default FMN0RETC macro statements supplied with File Manager shows the default set of FMN0RETC macro statements.
- Modify the FMNUMODR member in FMN.SFMNSAM1 to meet your site's requirements. Refer to the usermod for information about changes you might need to make.
- Install SMP/E usermod FMNUMODR.
FMN0RETC TITLE 'File Manager for z/OS® : Return Codes (Batch Utilities)'
FMN0RETC CSECT
FMN0RETC AMODE 31
FMN0RETC RMODE ANY
FMN0RETI 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
FMN0RETI FUNC=DSG, DSG conditions X
NORECSOUT=4 Zero records specified
FMN0RETI 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
FMN0RETI 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
FMN0RETI 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
FMN0RETI FUNC=DVT, DVT conditions X
NOENTRY=4 No matching entries
FMN0RETI 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
FMN0RETI END
END FMN0RETC
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 File Manager 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 File Manager User’s Guide and Reference .