NDMX: Non-Discardable Messages user exit (DFSNDMX0 and other NDMX exits)

Use the Non-Discardable Messages exit routine to tell IMS what to do with the input message associated with an abended application program.

If IMS does not call the Non-Discardable Messages exit routine, IMS arbitrarily discards messages from the system and issues message DFS555I.

Subsections:

About this routine
Processing options
Restrictions
Communicating with IMS

About this routine

The Non-Discardable Messages exit routine receives control when an IMS application abends with an input message in process.

Note: Non-message-driven BMP regions do not receive input messages, but you can use this routine to specify what IMS does when a program abends in these regions. Details are available throughout this topic.

Attributes of the Non-Discardable Messages exit routine are as follows:

Table 1. Non-discardable messages exit routine attributes
Attribute	Description
IMS environments	DB/DC, DCCTL.
Naming convention	You can name this exit routine DFSNDMX0 and link it into a library that is included in the STEPLIB concatenation. If DFSNDMX0 is linked into a library in the STEPLIB concatenation and the USER_EXITS section of the DFSDFxxx member defines exit routines, the exit routines in the DFSDFxxx member are loaded. DFSNDMX0 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 DFSDF`xxx` member of the IMS.PROCLIB data set. The routines are called in the order that they are listed in the parameter.
Binding	This exit routine must be reentrant. It runs in non-cross-memory mode.
Including the routine	If you write your own exit routine and plan to use IMS callable services, you must manually link edit the routine withDFSCSI00, and you must link the routine with IMS.SDFSRESL. The following example shows the required bind JCL statements. `INCLUDE LOAD(DFSNDMX0) INCLUDE LOAD(DFSCSI00) ENTRY DFSNDMX0 NAME DFSNDMX0(R)` The module or modules must be included in an authorized library in the JOBLIB, STEPLIB, or LINKLIST concatenation. To use a single exit routine that is named DFSNDMX0, no additional steps are needed. By default, the exit is activated for MPR, JMP, and message-driven BMP region types; IFP and non-message-driven BMP regions are not activated. To use multiple exit routines, specify EXITDEF=(TYPE=NDMX,EXIT=(exit_names)) in the EXITDEF parameter of the USER_EXITS section of the DFSDFxxx member of the IMS.PROCLIB data set. To activate support for message-driven IFP regions or non-message-driven BMP regions, specify the additional parameter NDMX_CALLED_FOR() in the USER_EXITS section of the DFSDFxx member and include the following options: To activate support for IFP regions, specify NDMX_CALLED_FOR(IFP(Y)). To activate support for only non-message-driven BMP regions, specify NDMX_CALLED_FOR(BMP(NMD_ONLY)). This activates support for non-message-driven BMP regions and deactivates default activation for message-driven BMP regions. To activate support for both message-driven and non-message-driven BMP regions, specify NDMX_CALLED_FOR(BMP(ALL)). As a shorter alternative, you can use NDMX_CALLED_FOR(BMP(A)). To learn more, see USER_EXITS section of the DFSDFxxx member.
IMS callable services	To use callable services with this routine, examine the value of the SXPLATOK field in the IMS standard user exit parameter list to see whether a callable services token is passed to the routine. If SXPLATOK is zero, you cannot use callable services with this routine. If SXPLATOK is nonzero, the callable services token is included, and you can use callable services. You can use the 256-byte work area that is addressed by SXPLAWRK in the standard user exit parameter list to call DFSCSIF0.
Sample routine location	IMS.ADFSSMPL (member name DFSNDMX0). The mapping of the NDM interface block is available from the IMS library IMS.ADFSMAC (member name DFSNDM).

Processing options

The following processing options are valid for DFSNDMX0. If you request an option that is not valid, IMS ignores your request and continues normal processing (the default option).

Continue normal processing

Continue normal processing is the default option. Request this option by setting register 15 to zero before returning to IMS. IMS proceeds as if this exit routine had not been called.

Depending on the type of application abend that initiated the exit routine, IMS might delete the message, issue a DFS555I message to the originating terminal and master terminal, and issue a DFS554A message to the master terminal.

Delete the input message from the system

Request this option by setting register 15 to 4 before returning to IMS. If you request this option, IMS performs the following actions:

Issues a DFS555I message to the originating terminal (if possible) and to the master terminal
Deletes the input message from the system
Issues a DFS554A message to the master terminal

Queue the message to the suspend queue

Request this option by setting register 15 to 8 before returning to IMS. If you request this option, IMS queues the input message to the suspend queue of the transaction that was being processed when the application abended. IMS suspends the transaction, and might issue a DFS554A message to the master terminal based on the abend type that occurred.

This option is not applicable to IFP and non-message-driven BMP regions.

Requeue the input message to the original transaction

Request this option by setting register 15 to 12 before returning to IMS. If you request this option, IMS queues the input message to the normal processing queue of the transaction that was being processed when the application abended. IMS USTOPs the transaction unless directed to do otherwise by the contents of NDMTRNST, and might issue a DFS554A message to the master terminal depending on the abend type that occurred.

This option is not applicable to IFP and non-message-driven BMP regions.

Queue the message to an alternate destination

Request this option by setting register 15 to 16 before returning to IMS and placing a valid destination name in the NDMDEST field of the NDM interface block. The following table shows the valid destination types and how to specify them in NDMDEST.

This option is not applicable to IFP and non-message-driven BMP regions.

Table 2. Valid alternative destinations
Alternative destination	NDMDEST value
LTERM	Specify a local, remote, or ETO LTERM, using the LTERM name or ETO user descriptor name.
OTMA	Specify the OTMA TPIPE name, or a name that is meaningful to the OTMA exit routines.
LU 6.2	Specify a local LU 6.2 device descriptor. The LU 6.2 device must be on the local IMS subsystem.
Transaction	Specify a local or remote transaction code. The following transaction types are not valid destinations: Fast Path exclusive transaction. Conversational transaction. SAA communications-driven transaction (that is, a CPI-C driven transaction). If you specify an invalid transaction type, IMS ignores the request and continues normal processing.

If NDMDEST contains an invalid destination, such as zeros or blanks, IMS ignores the request to change the destination and continues normal processing.

If NDMDEST contains a destination that is unknown to IMS, processing depends on whether OTMA, and ETO or shared queues are active.

With OTMA, and ETO or shared queues active: IMS starts the OTMA exit routines before it starts the Destination Creation exit routine (DFSINSX0).
Without OTMA, ETO, or shared queues: IMS ignores the request and continues normal processing.

When IMS requeues the input message to a valid destination, IMS completes the message processing as follows:

Issues a DFS550I message (succeeded version) to the master terminal
Issues a DFS555I message to the originating terminal (if possible) and to the master terminal
Deletes the input message from the abended transaction
Issues a DFS554A message to the master terminal

Restrictions

Not all destinations are valid alternatives for input messages. You can use this exit routine to requeue messages to alternative destinations.

The following processing options are not supported for a message-driven Fast Path region:

Queue the message to the suspend queue.
Requeue the input message to the original transaction.
Queue the message to an alternative destination that is named in the NDMDEST field in the NDM interface block.

Communicating with IMS

This exit routine uses a parameter list, entry and exit registers, and the Non-Discardable Messages interface block (NDM) to communicate with IMS.

Contents of registers on entry

At entry, the exit routine must save all registers that use the provided save area. The registers contain the following items:

Register	Content
1	Address of the IMS standard user exit parameter list.
13	Address of a single standard z/OS® save area.
14	Return address to IMS.
15	Entry point of this exit routine.

Standard 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 can be different each time that this exit routine is called.

If your NDMX user exit can be called in an enhanced user exit environment, more user exit routines might be called after your routine. When your user exit routine finds a transaction to act upon, it can set SXPL_CALLNXTN in the byte that SXPLCNXT points to, which tells IMS to not call more exit routines.

NDM interface block

The following table shows the contents of the NDM interface block. The address of this parameter list is in the standard user exit parameter list (field name SXPLFSPL). The mapping of the NDM interface block is available from the IMS library IMS.ADFSMAC (member name DFSNDM).

Table 3. NDM interface block
Field	Offset	Length	Content
NDMEYE	X'00'	4	NDM eye catcher.
NDMTRAN	X'04'	8	Transaction that the application was processing when it abended. This transaction is associated with the input message pointed to by NDMMSGA. For non-message-driven BMP regions, the NDMTRAN code is always 0 (zero).
NDMPSBN	X'0C'	8	PSB associated with the application that abended.
NDMUSID	X'14'	8	User ID.
NDMGRPNM	X'1C'	8	Group name.
NDMUSIDI	X'24'	1	Character flag for contents of user ID field NDMUSID: Character Meaning U User ID L LTERM P PSB name O Other name
NDMSRCFL	X'25'	1	A flag that indicates the origin of the input message. This flag is set with one of the following values: Value Meaning 0 NDMLTERM The source of the input message is an LTERM. Subsequent fields contain information about the LTERM. 1 NDMOTMA The source of the input message is OTMA. Subsequent fields contain information about the OTMA source. 2 NDMLU62 The source of the input message is an LU 6.2 device. Subsequent fields contain information about the LU 6.2 device. 3 NDMNMSG Indicates that this is a non-message region and that there is no input message.
NDMSRCIN	X'26'	1	Start of source description.
NDMLTERM	X'26'	8	Name of the originating LTERM if NDMSRCFL is set to NDMLTERM (value 0).
NDMNOMSG	X'26'	8	Non-message-driven regions set the value NDMNOMSG, which signifies a non-message-driven region with no source input message available, and is indicated by 8 bytes of blanks.
NDMTPIPE	X'26'	8	OTMA TPIPE name if NDMSRCFL is set to NDMOTMA (value 1).
NDMMEM	X'2E'	16	OTMA member name.
NDMTPSYN	X'3E'	1	OTMA TPIPE synchronization level.
NDMMGSYN	X'3F'	1	OTMA message synchronization level.
NDMLUNM	X'26'	8	LU name if NDMSRCFL is set to NDMLU62 (value 2).
NDMNWID	X'2E'	8	Network identifier.
NDMSIDE	X'36'	8	APPC side information name.
NDMMODE	X'3E'	8	VTAM® mode table name.
NDMTPNML	X'46'	2	Length of TP name contained in NDMTPNM.
NDMTPNM	X'48'	64	TP name.
NDMCONV	X'88'	1	APPC conversation type.
NDMSYNC	X'89'	1	APPC synchronization level.
	X'8A'	17	Reserved.
NDMRGTYP	X'9B'	1	IMS Dependent Region type: Value Description x'88' Java Message Processing Region (JMP). x'80' Message Processing Region (MPR). x'50' Message-driven Fast Path Region (IFP). x'40' Message-driven Batch Message Processing Region (BMP).
NDMABEND	X'9C'	4	Abend code in system format `00sssuuu`, where: sss z/OS system abend code. uuu IMS user abend code.
NDMTSLCL	X'A0'	8	The local timestamp of the arrival of the input message in the system. NDMTSLCL contains the two fields NDMDLCL and NDMTLCL.
NDMDLCL	X'A0'	4	The local date that the message arrived in the system. The date format is `YYYYDDDf`, where: YYYY Year. DDD Julian day. f X'F'.
NDMTLCL	X'A4'	4	The local time that the message arrived in the system. The time format is `HHMMSSTf`, where: HH Hour. MM Minutes. SS Seconds. T Tenths of the second. f X'F'.
NDMTSUTC	X'A8'	12	The Coordinated Universal Time (UTC) timestamp of the arrival of the input message in the system. The timestamp format is as follows: Year/day `YYYYDDDf` Time `HHMMSSTHmiju` Offset `Aqq$` The timestamp fields include the following items: YYYY Year. DDD Julian day. f X'F'. HH Hour. MM Minutes. SS Seconds. T Tenths of the second. H Hundredths of the second. m Milliseconds. i Tenths of a millisecond. j Hundredths of a millisecond. u Microseconds. A Attribute of the time value. qq Quarter-hours of offset from Coordinated Universal Time (UTC). $ Decimal sign for the offset, either positive (X'C') or negative (X'D').
NDMSPAA	X'B4'	4	Address of the SPA if the transaction in NDMTRAN is a conversational transaction. Otherwise, this field contains zeros. If the SPA is present, the format is as follows: `LL ZZZZ transaction_code data` LL Two-byte length field that includes the length of LLZZZZ. ZZZZ Four-byte field that always contains zeros. transaction_code Eight-byte field that contains the transaction code for the conversation or blanks. data SPA user data.
NDMMSGA	X'B8'	4	Contains the address of the input message if this field is nonzero. If this field is zero, there is no message segment, and can be an SPA segment only. The message format is as follows: `LL ZZ message-segment` LL Two-byte length field that includes the length of LLZZ. ZZ Two-byte field that always contains zeros, except for the last message segment, which contains X'FFFF'. message-segment input message segment For a single-segment message, the pattern is: LL=NDMMSGL and ZZ=X'FFFF'. For a multi-segment message, the pattern is: NDMMSGA=address of first segment. NDMMSGA+LL=address of second segment. NDMMSGA+LL+LL= address of third segment.
NDMMSGL	X'BC'	4	Total length of input message
	X'C0'	20	Reserved
NDMABRSN	X'D4'	4	Abend reason code if available.
NDMTRNST	X'D8'	4	Transaction status flag. DFSNDMX0 can set this field to any one of the following values. IMS examines this field on return from DFSNDMX0. Value Description 1 Do not (U)STOP the abended transaction and do not STOP the abended program. 2 Do not send the DFS555I message. 3 Do not (U)STOP the abended transaction, do not STOP the abended program, and do not send the DFS555I message. 4 Allow messages to continue to queue for the transaction, but do not allow the transaction to continue to be scheduled. This is equivalent to the PSTOP TRAN command for this transaction only. The PSB and application program are not affected. PSTOP is not valid for fast-path exclusive transaction and is ignored. 5 Allow the transaction to continue to schedule, but do not allow messages to continue to queue for the transaction. This is equivalent to the PURGE TRAN command for this transaction only. The PSB and application program are not affected. 6 Stop the transaction. This is equivalent to the STOP TRAN command. The PSB and application program are not affected.
NDMTRNST (continued)	X'D8'	4	7 Start the transaction. This is equivalent to the START TRAN command. The PSB and application program are not affected. For non-message-driven BMP regions, only codes 1 and 3 apply. For IFP regions, the allowed values that can be specified for NDMTRNST can be any number 1 through 7. However, if NDMTRNST=4 (PSTOP) is specified and the transaction is defined as Fast-Path, exclusive is ignored and the transaction status is set to STOP. This behavior is consistent with the way IMS handles a PSTOP command that is issued against a Fast-Path exclusive transaction. The recommended value for NDMTRNST is 1, which enables the Do not stop Transaction and Program. For both return codes 0 and 4, the Transaction and Program is not stopped. For non-retriable abend situations in IFP regions, the recommended return code is 4. For retriable abends, you cannot stop the program, and the recommended return code is 0. Any other return code is treated as return code 0. The user selected return code is printed in the '67D0' log record for diagnostics purpose.
NDMDEST	X'DC'	8	Name of the alternative destination to which the input message is to be queued. IMS examines this field only if you pass return code 16 in register 15. Otherwise, IMS ignores this field.

Contents 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 code	Meaning
0	Continue normal processing.
4	Delete the input message from the system. This return code is not applicable for non-message-driven BMP regions.
8	Queue the input message to the suspend queue. This return code is not applicable to IFP or non-message-driven BMP regions.
12	Requeue the input message to the original transaction. This return code is not applicable to IFP or non-message-driven BMP regions.
16	Queue the message to an alternative destination that is named in the NDMDEST field in the NDM interface block. This return code is not applicable to IFP or non-message-driven BMP regions.

For return codes 0 and 4, the Transaction and Program are not stopped. For non-retriable abend situations in IFP regions, the recommended return code is 4. For retriable abends, you cannot stop the program, and the recommended return code is 0. Any other return code is treated as return code 0. The user selected return code is printed in the '67D0' log record for diagnostics purpose.