IMS 15 - Exit routines - IMS standard user exit parameter list

This interface creates a clearly differentiated programming interface (CDPI) between IMS and the exit routine. Part of the interface consists of a standard user exit parameter list. The list contains information such as a pointer to a version number and a pointer to a function-specific parameter list. All standard user exit parameter lists that have the same version number will contain the same parameters. If a new parameter is added, it is added to the end of the parameter list and the version number is increased by one.

There are currently two active versions of the IMS standard user exit parameter list: version 1 and the current version. The Version 6 standard exit parameter list is the current version. In general, IMS exit routines that do not use the Version 1 standard exit parameter list use the Version 6 standard exit parameter list. Refer to the information for each individual exit routine.

Version 1 standard exit parameter list

The version 1 parameter list contains only pointers to the version number and the function-specific parameter list. The following table shows the content of the Version 1 standard exit parameter list. When the user exit routine is called, IMS passes it the address of this list in register 1.

Table 1. Version 1 standard exit parameter list (mapped by DFSSXPL)
Field	Offset	Length	Description
SXPL	X'00'	N/A	DSECT label for the IMS standard user exit parameter list
SXPLVER	X'00'	X'04'	Address of fullword containing version number of standard exit parameter list
SXPLATOK	X'04'	X'04'	Reserved
SXPLAWRK	X'08'	X'04'	Reserved
SXPLFSPL	X'0C'	X'04'	Address of function-specific parameter list
SXPLINTX	X'10'	X'04'	Reserved
SXPLASCD	X'14'	X'04'	Reserved

The following user exit routines use the Version 1 parameter list:

Version 6 standard exit parameter list

This version is the current version of the parameter list. The Version 6 standard exit parameter list contains additional fields beyond those in version 1 of the parameter list. The following table shows the layout of the parameter list. When a user exit routine is called, IMS passes the address of this parameter list to the exit routine module in register 1.

Table 2. Version 6 standard exit parameter list (mapped by DFSSXPL)
Field	Offset	Length	Description
SXPL	X'00'	N/A	DSECT label for the IMS standard user exit parameter list
SXPLVER	X'00'	X'04'	Address of fullword containing version number of standard exit parameter list
SXPLATOK	X'04'	X'04'	0 or the address of a fullword containing the callable services token for this instance of the routine
SXPLAWRK	X'08'	X'04'	Pointer to a 512-byte work area. This area is intended as working storage for a user exit routine. The storage is not initialized, and may contain residual data. The contents of the storage are not guaranteed to be preserved between user exit calls. If a work area that is preserved between calls is required, use the storage pointed to by SXPLASWA.
SXPLFSPL	X'0C'	X'04'	Address of the function-specific parameter list
SXPLINTX	X'10'	X'04'	Address of the user data table loaded by DFSINTX0 at IMS initialization time. This field is valid only in IMS environments where DFSINTX0 is called. It will be X'80000000' in any other environment.
SXPLASCD	X'14'	X'04'	Address of the IMS SCD
SXPLASWA	X'18'	X'04'	Address of a 256–byte static work area. Each exit routine is assigned its own static work area and is available for the exit routine to store data that is preserved from call to call. The static work area is cleared before the first time the exit routine is called. Each exit routine is assigned a separate static work area that is preserved between calls to that exit routine. This work area is available for all user exits that use this version of the standard exit parameter list, regardless of whether the exit is defined with the EXITDEF parameter in the USER_EXITS section of the DFSDFxxx member of the IMS.PROCLIB data set. If your exit routine can be called concurrently under different ITASKs, you must consider the results of sharing a single static work area in the design of your exit routine. If an exit routine is replaced with the REFRESH USEREXIT command, the same static work area is passed to the new version of the exit routine. If an exit routine is deleted with the command, the static work area is also deleted. If a new exit routine is added with the command, a new static work area is allocated. The same static work area is shared by the old and new versions of an exit routine until the old exit is deleted. This must be handled by your exit routine in the same way as the multiple concurrent executions under different ITASKs. SXPL_F1SWASHR is set when your exit is called while the static work area is shared. When the old exit routine is deleted, SXPL_F1WASHR is no longer set.
SXPLIMSR	X'1C'	X'04'	Address of the version of IMS that is calling the exit. The 4-byte version data is stored in the following format: `0000vvmm` `vv` IMS version (SSCDIMSR) `mm` IMS mod (SSCDIMSM)
SXPLIMID	X'20'	X'04'	Address of the IMS ID. Standalone invocation of the Image Copy Utility and Change Accumulation Utility set address of the job name.
SXPLRSEN	X'24'	X'04'	Address of the 8 character Recoverability Service Name (RSENAME). This name is set using the RSENAME startup parameter in the DFSHSBxx member. If the control region is not XRF capable or DBCTL warm standby capable, this field is blank.
SXPLCNXT	X’28’	X’04’	Address of a flag byte in storage. The flag indicates if the next exit routine in the definition list will be called after this exit routine releases control. When an exit type is defined as refreshable, multiple exit routines of the same type can be called in sequence. By setting this flag to SXPL_CALLNXTN, an exit routine in the sequence can return control to the IMS system without calling any subsequently defined exit routine. SXPL_CALLNXTN The next exit routine will not be called. SXPL_CALLNXTY The next exit routine will be called.
SXPLFLGA	X’2C’	X’04’	Address of a full word in storage that contains flags for the user exit. SXPL_F1ENHSRV The exit is called with the enhanced callable services, including the ability to call multiple exit routines of the same user exit type. SXPL_F1SWARFR Do not use this flag. Instead, use either SXPL_F1RFRSHD, SXPL_F1SWASHR, or both. SXPL_F1RFRSHD If this flag is set, the exit is refreshed. This flag is set based on a flag in a control block that represents the exit routine, and this flag is not reset until the exit returns to IMS. If the user exit runs in parallel, multiple calls to the user exit can be made with this flag set before the control block flag is reset. SXPL_F1SWASHR If this flag is set, the static work area whose address is contained in SXPLASWA is shared and can be accessed by the old and new versions of the exit because the old version might still be active. You should consider this behavior when you use your user exit if the two versions use different layouts for the area. When the old exit routine is deleted, this flag will no longer be set.

If an exit routine is written to use a parameter that was added in a later version, and the exit routine can execute in an environment in which earlier versions of the parameter list could be received, the exit routine should check the version of the parameter list it receives to ensure that the data is available to the exit routine.