Sample Allocation Exits

IBM® Connect:Direct® provides the following sample allocation exits in the $CD.SDGASAMP library.

Exits Description
DGAXADSN This exit documents the path of the data set name and unit that receives data during a COPY. It runs just prior to data set allocation. It is invoked for every COPY step on the receiving end of a transfer.
DGAXUNIQ This exit creates a unique z/OS PDS member name, if the data set name specified in the COPY TO statement is found in the PDS directory.

Each request can only specify one member name. The COPY TO statement must specify the member name. The COPY TO statement must also specify SYSOPTS=”UNIQUE=YES”.

The exit only supports copying sequential files to a PDS member.

DGAXALOX This exit enables a Data exit to be invoked for any or every copy performed by IBM Connect:Direct.
DGAXA390 This exit converts UNIT=3390 to UNIT=SYSDA.
DGAXALEX This exit shows how to access the VSAMPL and the TCQSH, and both the source and destination description in the TCQSH. It shows how to change a value in the Data Set Description Control Blocks (DGA$DDSR or DGA$SDCR) and set a return code and message ID before return.
DGAXARCL In a COPY Process, this exit checks if a data set is archived or migrated. If the data set is archived, the exit requests retrieval and tells the COPY Process to go to the Timer Retry queue (TI RE), from which it is retried based on the ALLOC.WAIT and ALLOC.RETRIES initialization parameters. To ensure that the serially reusable operating system SYSZTIOT resource is freed up for subsequent users and does not cause the IBM Connect:Direct region to hang in a wait condition, use the DMGALRCL exit and specify ARCH as the value for the ALLOC.CODES initialization parameter. Change the setting of the INVOKE.ALLOC.EXIT global initialization parameter to BOTH if using this exit. If running with the CA-DMS product, you must modify the sample exit code as described in the comments at the beginning of the sample code. If you use this exit, add the following DD Statement to the DTF JCL:
              //READER  DD  SYSOUT=(A,INTRDR)
Note: This exit is not necessary to process migrated or archived data sets. IBM Connect:Direct processes recalled data sets synchronously and the COPY Process remains in the Execution queue instead of being diverted to the Timer Retry queue and potentially to the Hold queue should retry limits be exceeded.

In releases prior to Version 4.7, when the DGAXARCL (alias of DMGALRCL) allocation exit attempted to recall a migrated or archived data set offline, the Process went into fail state and was taken out of the Execution queue and put into the Timer Retry (TI RE) queue. As IBM Connect:Direct waited for the allocation and recall to be performed asynchronously, it would retry the Process based on the ALLOC.WAIT and ALLOC.RETRIES initialization parameters. If the Process exceeded the maximum time limit specified for retrying it (number of retries as specified by the ALLOC.RETRIES initialization parameter multiplied by the amount of time that IBM Connect:Direct waits between retries as specified by the ALLOC.WAIT initialization parameter), the Process was put into the Hold queue requiring manual intervention.

In Version 4.7 and later, when IBM Connect:Direct executes a COPY Process without the DMGALRCL exit being present, it will use the ARCHRCAL macro synchronously, which means that the Process stays in the Execution queue not having to loop between the Execution, Timer, and Hold queues. The Process does not terminate while the recall operation is being performed but if the recall is unsuccessful, the COPY step produces a return code indicating the unsuccessful data set recall and instructs the user to correct the error and resubmit the Process.

Although it is not needed for data recall, the DGAXARCL exit will continue to be supported and invoked prior to any allocation activity if the ALLOCATION.EXIT=DGAXARCL initialization parameter is specified. However, this exit is no longer required to process migrated or archived data sets.

Caution: If the sample exit is not being used and a migration/recall product is not active, installed, or is temporarily down, the following messages are displayed:


To proceed with the allocation, you must reply. Please refer to IBM documentation regarding the ARCxxxxA messages. If you reply CANCEL to the ARC0055A message, the Process completes with MSGID=SDE021CI. If 21C is in the ALLOC.CODES= list, the Process retries; otherwise, the Process terminates.

DGAXPALL This exit provides %PNUM substitution in a Process.