PPUE: Partner Product exit routine (DFSPPUE0 and other PPUE exits)

The Partner Product exit routine (DFSPPUE0 or another PPUE type exit routine) is provided to allow the initialization of products that run with IMS. The exit routine can load or link one or more partner product routines.

This topic contains Product-sensitive Programming Interface information.


About this routine

The Partner Product exit routine is entered immediately before IMS is ready for startup (before the DFS994I start complete message is issued). The exit routine is deleted after control returns to IMS.

Be aware that the interface to this exit routine might change in future releases of IMS.

The exit routine must reside on the library pointed to by the STEPLIB DD statement. If the exit routine exists, it is called.

The following table shows the attributes of the Partner Product exit routine.

Table 1. Partner product exit routine attributes
Attribute Description
IMS environments DB/DC, DBCTL, DCCTL.
Naming convention You can name this exit routine DFSPPUE0 and link it into a library that is included in the STEPLIB concatenation.

If DFSPPUE0 is linked into a library in the STEPLIB concatenation and the USER_EXITS section of the DFSDFxxx member defines exit routines, the exit routines defined in the DFSDFxxx member will be loaded. DFSPPUE0 is only loaded if it is listed as one of the exit routines in the DFSDFxxx member.

Alternatively, you can define one or more exit routine modules with the EXITDEF parameter of the USER_EXITS section of the DFSDFxxx member of the IMS.PROCLIB data set. The routines are called in the order that they are listed in the parameter.

Including the routine The module or modules must be included in an authorized library in the JOBLIB, STEPLIB, or LINKLIST concatenation. No additional steps are necessary to use a single exit routine that is named DFSPPUE0. If you use multiple exit routines, specify EXITDEF=(TYPE= PPUE,EXIT=(exit_names)) in the EXITDEF parameter of the USER_EXITS section of the DFSDFxxx member of the IMS.PROCLIB data set.
IMS callable services This exit routine can use IMS Callable Storage Services. This exit routine is defined to IMS as an IMS standard user exit. Exit routines that are defined to IMS receive the callable services token in the standard exit parameter list. This exit routine does not need to issue an initialization call (DFSCSII0) to use IMS callable services. You must manually bind this exit routine with DFSCSI00.
Sample routine location A sample exit named DFSPPEX0 is provided in the IMS.ADFSML data set.

Communicating with IMS

IMS uses the entry registers, a parameter list, and the exit registers to communicate with the exit routine.

Content of registers on entry

On entry, the exit routine must save all registers using the provided save area. The registers contain the following:
Register Contents
1 Address of the IMS standard user exit parameter list
13 Address of the save area. Your exit routine must not change the first three words of this save area. This save area is not chained to any other IMS save area.
14 Return address to IMS.
15 Entry point of this exit routine.

Standard IMS user exit parameter list

This exit routine uses the Version 6 standard exit parameter list. The address of the work area passed to this exit routine in SXPLAWRK will be the same each time that this exit routine is called.

Function-specific parameter list on entry

The following table shows the content of the function-specific parameter list. The address of this parameter list is in the standard IMS user exit parameter list field SXPLFSPL.

Table 2. Function-specific parameter list for partner product exit (mapped by DFSPPUE)
Field Offset Length Content
PPUEIMSD 0 4 IMS identifier
PPUEREL 4 1 IMS level
PPUETYP 5 1 IMS subsystem type
PPUEOSL 6 1 z/OS® level
Reserved 7 1  

Content of registers on exit

Before returning to IMS, the exit routine must restore all registers except register 15, which must contain one of the following return codes:
Return codes Meaning
0 Processing continues.
non-0 IMS abends with U0740. The exit routine should return this code if critical tasks do not complete successfully.

If multiple DFSPPUE0 exit routines are called, the highest return code is returned to the calling program.