The XMEOUT exit allows you to suppress or reroute CICS® and CICSPlex
SM messages that use the message domain.
Note that your exit program is subject to certain restrictions:
- It cannot suppress or reroute messages sent to terminal operators, but
only those sent to the system console or to transient data queues. (XMEOUT
is not invoked for the former type of message.)
- It can suppress or reroute only messages that use the message domain.
You can deduce which messages this applies to from the CICS Messages and Codes manual: the description of each message that causes
XMEOUT to be driven contains a list of "XMEOUT parameters"; if no
XMEOUT parameters are listed for a message, the latter does not cause the
exit to be driven. For example, message ‘DFHDX8320’ causes XMEOUT
to be invoked, but message ‘DFHDU0205’ does not.
- It cannot change the text of a message, nor the message inserts. (If it
tries to do so, CICS ignores the changes.)
- It cannot suppress or reroute messages issued during the early stages
of CICS initialization (because the exit cannot be enabled then).
- It cannot reroute a message to transient data queues during CICS shutdown unless
the original message destination included one or more transient data queues.
If it attempts to do so, the message in question is routed to its original
destination, and message DFHME0120I is issued to the console. Message DFHME0120I
cannot be re-routed by the user exit program but it may be suppressed.
This restriction is necessary because the message domain is required to handle
messages during CICS shutdown even after the transient data queue function
has ended.
To discover
whether CICS shutdown has started, your exit program can check for the first
instance of message DFHME0120. It can stop rerouting messages to TD queues
after DFHME0120 has been issued.
For CICSPlex SM, XMEOUT is invoked only for messages that have
a destination of EYULOG. Check the CICSPlex® System Manager Messages and Codes manual to see which messages this applies to.
For CICSPlex SM, it cannot suppress or reroute messages sent
to EYULOG.
It cannot reroute or suppress CICSPlex SM web user interface
messages.
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:
- Any DFHTDxxxx messages, produced by the transient data program.
- User domain messages in the range DFHUS0002-DFHUS0006, plus message
DFHUS0150.
- Transaction manager messages DFHXM0212, DFHXM0213, DFHXM0304 and DFHXM0308.
- Application messages DFHAP0001, DFHAP0002, DFHAP0004, DFHAP0601, DFHAP0602,
and DFHAP0603.
- Any user domain (DFHUSxxxx) messages to an intrapartition
queue defined with a TRIGLEV value of anything other than zero, if the messages
are produced while the user domain is performing error recovery processing.
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.
It 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).
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.
- 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.
For CICSPlex SM messages, this field contains binary zeros.
- UEPMDOM
- Address of a 2-byte field containing the domain identifier of the CICS message.
For CICSPlex
SM messages, this field contains binary zeros.
- 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.
UEPCPID
Address of 3-byte product ID. The possible values are:
- DFH
- CICS messages.
- EYU
- CICSPlex SM messages.
UEPCPDOM
Address of a 2-byte field containing the domain identifier of the message.
UEPCPNUM
Address of a 4-byte field containing the message number.
UEPCPSEV
Address of the message severity code.
- Return codes
-
- UERCNORM
- Continue processing.
- UERCBYP
- Suppress the message for all destinations.
Note that CICSPlex SM messages cannot be suppressed. For these messages,
a response of UERCBYP is treated as UERCNORM.
- XPI calls
- WAIT_MVS can be used. Do not use any other calls.
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.
[[ Contents Previous Page | Next Page Index ]]