z/OS V1R6.0 DFSMS Access Method Services for Catalogs

Appendix E. DCOLLECT User ExitUser Exit DescriptionThis appendix is intended to help you understand the DCOLLECT user exit.DCOLLECT enables you to intercept records after they are created, but before theyare written to the output data set. This ability is provided by either IDCDCX1, thedefault DCOLLECT user exit, or any load module named with the EXITNAMEparameter. In this chapter, the term DCOLLECT user exit is used to denote eitherthe default exit or a named exit.The DCOLLECT user exit allows the programmer to enhance, modify, or deleterecords created by DCOLLECT. If IDCDCX1 is modified, it must be link-editedinto the IDCDC01 load module, or applied to the system by the SystemModification Program Extended (SMP/E). A separate user exit must be loaded intoan APF authorized load library if the EXITNAME parameter is used. All recordsproduced by DCOLLECT, including records created for DFSMShsm are passed tothe DCOLLECT user exit before they are written to the output data set.Use the default exit, IDCDCX1, to provide some standard customization toDCOLLECT. You can use and the EXITNAME parameter for special situations, ortesting a new exit for DCOLLECT.The DCOLLECT user exit should use standard save area conventions, and itshould be reentrant. The user exit must return to the caller in the caller’saddressing mode.Each record is passed to the DCOLLECT user exit by placing the length of therecord in register 0, and its address in register 1. If the record is modified, thecontents of register 0 and register 1 must be updated to reflect the new length andaddress of the record. The record can be modified in any way by the exit, exceptthat it cannot exceed 32760 bytes. If the user exit extends the record, the suppliedrecord buffer must not be used.When a record is passed to the DCOLLECT user exit, the user exit has the optionof leaving the record unmodified, changing one or more existing fields, addingnew fields to the end of the record, or specifying that the record not be written tothe output data set.vvvTo leave the record unmodified, the user exit should set register 15 to 0, andreturn control to the caller.To change any existing fields but not change the length of the record itself, theuser exit can overwrite the appropriate field in the record passed to it. Register15 should be set to 4 to indicate that the record has been modified.To add new fields to the end of the record, the user exit should get sufficientstorage for a new record buffer that is large enough to hold the original recordplus the fields that are to be added. This buffer must reside in storage below 16MB.The new fields can be written into the new buffer. Register 0 should be loadedwith the length of the new record. Register 1 should contain the address of thenew buffer. Register 15 should be set to 4 to indicate that the record has beenmodified.© Copyright IBM Corp. 1973, 2004 431