Message domain exit XMEOUT

Start of changeThe XMEOUT exit allows you to suppress or reroute CICS® and CICSPlex SM messages that use the message domain.End of change

Note that your exit program is subject to certain restrictions:

Note:
If a message is being rerouted to a transient data queue and the transient data request fails, the message is lost. The MEME exception trace point ID X'0328' is written. The interpretation string of this trace entry provides an explanation of why the transient data request failed.
Important

Because of the danger of recursion, your XMEOUT exit program should not try to reroute:

The message definition template contains an indicator called "noreroute". This indicator is set on if the message being issued cannot be rerouted to a transient data queue by the XMEOUT exit program. The address of the indicator is passed to XMEOUT in the UEPNRTE exit-specific parameter. Your exit program can check the value of the indicator before deciding whether or not to reroute a particular message.

Note:
If the exit program tries to reroute an ineligible message, the message domain inhibits the rerouting and issues the message to the console instead, along with message DFHME0137.

Each of the messages affected by this restriction is identified by a note in the CICS Messages and Codes manual.

Start of changeIt is possible to pass APPLID as an optional parameter in a message. However, the APPLID that is inserted in a message may not be the APPLID of the current CICS system. For example, when a CICSPlex SM MAS message is routed to a CMAS, the APPLID of the MAS system may be passed, therefore the message will contain the APPLID of the MAS system and not the current system (the CMAS).End of change

Your exit program can suppress or reroute messages by altering the values held in the addresses pointed to by the UEPMROU, UEPMNRC, UEPMTDQ, and UEPMNTD fields of the parameter list. These four sets of values (route codes, number of route codes, transient data queue names, and number of TDQs) are the only ones that your program can change.

Exit XMEOUT

When invoked
Before the message domain sends a CICS message to its destination.
Exit-specific parameters
UEPTRANID
Address of the 4-byte transaction ID.
UEPUSER
Address of the 8-byte user ID.
UEPTERM
Address of the 4-byte ID of the terminal under which the current transaction is running. If the current transaction is not associated with a terminal, the addressed field contains hexadecimal zeroes.
UEPPROG
Address of the 8-byte application program name, or nulls if there is no current application.
UEPMNUM
Address of a 4-byte field containing the message number.Start of changeFor CICSPlex SM messages, this field contains binary zeros.End of change
UEPMDOM
Address of a 2-byte field containing the domain identifier of the CICS message. Start of changeFor CICSPlex SM messages, this field contains binary zeros.End of change
UEPMROU
Address of an array of up to 28 route codes. Route codes must be numbers in the range 1 through 28.
UEPMNRC
Address of a halfword containing the number of route codes in the route code array.
UEPMTDQ
Address of an array of up to 25 transient data queue names to which the message is to be sent. TD queue names must consist of 4 alphanumeric characters.
UEPMNTD
Address of a halfword containing the number of TDQs in the queues array.
UEPINSN
Address of a 2-byte field containing the number of message inserts.
UEPINSA
Address of an array, each element of which contains information about a single message insert. The size of the array depends on the number of inserts. Each array element has the following structure:
INSERT_FORMAT_P  DS  A  Address of the 1-byte insert
                        type-code, which has one of
                        the following hexadecimal values:
                        0    Not present
                        1    Character
                        2    Hexadecimal
                        3    Decimal
                        4    The insert is a number
                             representing one item in
                             a list of options.
                             (See the example below.)
 INSERT_P         DS  A  Address of the message insert
 INSERT_LENGTH_P  DS  A  Address of a fullword contain-
                         ing the length of the insert
 INSERT_TYPE_P    DS  A  Reserved.
 
You can find the order of the inserts in the array from the entry for the particular message in the CICS Messages and Codes manual. For example,
DFHFC0531 date time applid Automatic journal journal
journalname, opened for file filename is not of
type MVS™. Module module.
The XMEOUT inserts are date, time, applid, journal, journalname, filename, and module. The fourth insert (journal) is the number specified for JOURNAL on the file definition.
UEPNRTE
Address of 1-character flag indicating whether or not the message can be rerouted by XMEOUT. The possible values are:
C'0:'
The message can be routed.
C'1:'
The message cannot be routed.
Start of changeUEPCPIDEnd of change
Start of changeAddress of 3-byte product ID. The possible values are:
DFH
CICS messages.
EYU
CICSPlex SM messages.
End of change
Start of changeUEPCPDOMEnd of change
Start of changeAddress of a 2-byte field containing the domain identifier of the message.End of change
Start of changeUEPCPNUMEnd of change
Start of changeAddress of a 4-byte field containing the message number.End of change
Start of changeUEPCPSEVEnd of change
Start of changeAddress of the message severity code.End of change
Return codes
UERCNORM
Continue processing.
UERCBYP
Suppress the message for all destinations.

Start of changeNote that CICSPlex SM messages cannot be suppressed. For these messages, a response of UERCBYP is treated as UERCNORM.End of change

XPI calls
WAIT_MVS can be used. Do not use any other calls.

The sample XMEOUT global user exit programs

CICS supplies the following sample programs, which show you how to use the XMEOUT exit to suppress or reroute messages:

DFH$SXP1
Suppress a message by message number
DFH$SXP2
Suppress a message by destination route code
DFH$SXP3
Suppress a message destined for the CSCS transient data queue (which receives signon and sign-off messages)
DFH$SXP4
Reroute a console message to a TDQ
DFH$SXP5
Reroute a TDQ message to another TDQ
DFH$SXP6
Reroute a TDQ message to a console.

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]