Topics for This Exit Appear as Follows:
Code a CNZ_WTOMDBEXIT exit routine when you want to
view all messages being sent by WTO or WTOR. Information in the message
is readonly; you can not modify the message contents.
CNZ_WTOMDBEXIT receives control from the system when
a message is sent by a single-line WTO, a multi-line WTO, or a WTOR.
Every single-line message that is sent by WTO or WTOR will be passed
to the exit routines active at the exit point. Multi-line messages
will be presented only when all lines have been completed. For example,
a multi-line message with 1 major and 3 minor lines will result in
the exit routine receiving control one time.
Controlling the Exit Routine Through the
Dynamic Exits Facilities
IBM® has
defined the CNZ_WTOMDBEXIT exit to the dynamic exits facility. You
can refer to the exit by the name CNZ_WTOMDBEXIT. You can use the
EXIT statement of the PROGxx parmlib member, the SETPROG EXIT operator
command, or the CSVDYNEX macro to control this exit and its exit routines.
You
can use the ADDABENDNUM and ABENDCONSEC parameters on the CSVDYNEX
REQUEST=ADD macro or the ABENDNUM parameter of the SETPROG EXIT operator
command to limit the number of times the exit routine abnormally ends
before it becomes inactive. An abend is counted when both of the following
conditions exist:
- The exit routine does not provide recovery, or the exit routine
does provide recovery but percolates the error.
- The system allows a retry; that is, the recovery routine is entered
with bit SDWACLUP off.
By default, the system disables the exit routine after one
abend.
Exit Routine Environment
The
exit receives control in the following environment:
- Enabled for interrupts.
- In supervisor state with PSW key 0.
- In AMODE 31.
- With no locks or ENQs held.
- In the address space of the WTO or WTOR issuer, unless
the message was a branch-entry message or was a multi-line message
that timed out. In both of those cases, the exit receives control
in the CONSOLE address space.
Exit Recovery: If the exit routine abnormally terminates,
and the exit routine does not provide its own recovery, or the error
percolates beyond the exit's recovery routine, a system recovery routine
will get control.
Whether or not the exit routine continues
to be invoked depends on the abend processing of the dynamic exits
facility.
Exit Routine Processing
MVS™ invokes the CNZ_WTOMDBEXIT exit
routine every time a WTO or WTOR single-line or completed multi-line
message is sent. If any CNZ_WTOMDBEXIT routines are specified to the
dynamic exits facility, a parameter list (mapped by macro CNZMYWMX)
is passed that contains information about the message, such as:
- Whether the message is a single-line WTO
- Whether the message is a multi-line WTO
- Whether the message is a branch-entry WTO
- Whether the message is a WTOR
- First line of the message text, where the first 12
characters are typically the message identifier.
- Pointer to the message data block (MDB), mapped by macro IEAVM105
Also passed to CNZ_WTOMDBEXIT is the address of a 4K
workarea for use by the exit routine.
Programming Considerations
- All received messages are "completed" messages, in that control
is received after the subsystem interface.
- The exit routine will not affect the content of the message itself.
The original message text and attributes (for example, routing and
descriptor codes) remain intact. This exit routine cannot suppress
a message.
- Do not code an exit routine that receives control for a message
that the exit issues; this causes an endless loop. The exit must be
coded so that when it receives control for that message, it does not
issue the message again.
- If an exit routine needs to issue a message it should
issue it as a branch entry message. Similarly, if an exit routine
needs to DOM a message it should issue the DOM as branch entered.
- Code the exit routine to be re-entrant.
Performance Considerations
WTO
message processing can impact performance; therefore, consider the
following recommendations so that system performance is not degraded:
- Do not code an exit routine that contains an explicit or implicit
WAIT or other processing of potentially long duration, for example,
issuing requests for large amounts of dynamic storage, or issuing
I/O requests. Exits that do this can adversely affect both application
and overall system performance.
- To reduce the need for storage requests, the system provides a
4K workarea that your exit routine can use for dynamic storage. The
second word of the input parameter list points to the 4K workarea.
The exit routine should clear what they put in the workarea before
exiting, because all exit routines installed at the CNZ_WTOMDBEXIT
exit point use the same workarea. Use this workarea for your program's
working storage (for example, variables) and avoid doing a GETMAIN
or STORAGE OBTAIN in the exit routine.
- If recovery is necessary, set up an EUT functional recovery routine
(FRR) instead of an ESTAE-type recovery routine for shortened path
length of the exit routine. If it is not possible to use FRR recovery,
then IEAARR should be used because it has the best set/delete performance
for Estae-type recovery routines.
Entry Specifications
The system
passes the address of the exit parameter list to the exit routine.
Registers
at Entry: The contents of the registers on entry to the exit are
as follows.
- Register
- Contents
- 0
- Not applicable
- 1
- Address of a pointer to the exit parameter list
- 2-12
- Not applicable
- 13
- Register save area
- 14
- Return address
- 15
- Entry point address of the exit
Parameter Descriptions: Register 1 points
to the following:
- Word 1
- Address of the WMDX, mapped by macro CNZMYWMX
- Word 2
- Address of a 4K work area
Figure 1. CNZ_WTOMDBEXIT input parameter
structure
Return Specifications
Registers
at Exit: Upon return from the exit processing, the register contents
must be as follows.
- Register
- Contents
- 0-15
- Restored to contents at entry
Coded Example of the Exit Routine
The
following is an example of an CNZ_WTOMDBEXIT exit:
TITLE 'WMXEXIT - SAMPLE WTO MDB EXIT'
***START OF SPECIFICATIONS**************************************
* *
* MODULE NAME = WMXEXIT *
* *
* DESCRIPTIVE NAME = SAMPLE WTO MDB EXIT (FOR ACTIVATION *
* ON CNZ_WTOMDBEXIT). *
* *
* FUNCTION = THIS EXIT DEMONSTRATES HOW TO *
* USE THE DATA IN THE WMDX PARAMETER *
* LIST TO IDENTIFY DIFFERENT TYPES OF *
* MESSAGES. *
* *
* OPERATION = THIS SAMPLE EXIT DETERMINES IF THE MESSAGE *
* DESCRIBED BY THE WMDX IS FOR A SPECIFIC *
* MESSAGE ID, A WTOR, SINGLE LINE MESSAGE, OR *
* MULTIPLE LINE MESSAGE AND PUTS TEXT IN THE *
* WMDX USER WORKAREA INDICATING WHAT IT FOUND. *
* *
* NOTE1: THE WMDX PARAMETER LIST PROVIDES THE FIRST LINE OF *
* MESSAGE TEXT. IN ORDER TO OBTAIN SUBSEQUENT TEXT LINES *
* OF A MULTI-LINE MESSAGE USE THE MDB POINTER (IN THE *
* WMDX) TO ACCESS THE MESSAGE DATA BLOCK (MDB), WHICH *
* CONTAINS DATA DESCRIBING THE MESSAGE, AND ALLOWS YOU *
* TO ACCESS THE SUBSEQUENT LINES. SEE "RECEIVING *
* MESSAGES AND COMMAND RESPONSES" IN "Z/OS MVS *
* ASSEMBLER SERVICES GUIDE", SA22-7608-08 FOR *
* INFORMATION ABOUT USING THE MDB. A GOOD EXAMPLE *
* PROGRAM USING THE MDB IS IEAEXMCS IN SAMPLIB. *
* *
* ENTRY POINT = WMXEXIT *
* *
* PURPOSE = DEMONSTRATE HOW TO USE THIS EXIT. *
* *
* LINKAGE = REGISTER 1 CONTAINS THE ADDRESS OF A PARAMETER *
* LIST, WHICH CONTAINS (1) THE ADDRESS THE WMDX *
* (MAPPED BY CNZMYWMX), AND (2) THE ADDRESS OF A *
* 4K WORKAREA. *
* *
* NOTE2: THERE IS ONLY ONE COPY OF THE WMDX AND WORKAREA *
* PER MESSAGE FOR ALL USERS OF CNZ_WTOMDBEXIT. CARE *
* MUST BE TAKEN TO MAKE SURE THE WMDX DATA IS NOT *
* MODIFIED. THE WORKAREA IS NOT CLEARED BEFORE IT IS *
* PASSED TO SUBSEQUENT EXITS SO THE USER MUST CLEAR *
* IT IF IT CONTAINS SENSITIVE DATA. *
* *
* INPUT DATA = REG1 ADDRESS OF THE PARAMETER LIST *
* REG13 ADDRESS OF STANDARD SAVE AREA *
* REG14 RETURN ADDRESS *
* REG15 ENTRY POINT ADDRESS *
* *
* REGISTERS SAVED = REG0 - REG15 *
* *
* REGISTER USAGE = REG0 - USED FOR BASING *
* REG1 - PARAMETER REGISTER *
* REG2 - WORK REGISTER *
* REG3 - WORK REGISTER *
* REG4 - WORK REGISTER *
* REG5 - WORK REGISTER *
* REG6 - POINTER TO PARAMETER LIST *
* REG7 - POINTER TO WMDX *
* REG8 - NOT USED *
* REG9 - NOT USED *
* REG10 - NOT USED *
* REG11 - POINTER TO 4K WORK AREA *
* REG12 - MODULE BASE REGISTER *
* REG14 - RETURN POINT *
* REG15 - NOT USED *
* REGISTERS RESTORED = REG0 - REG14 *
* *
* CONTROL BLOCKS = *
* NAME MAPPING MACRO REASON USED USAGE *
* ---- ------------- ----------- ------- *
* WMDX CNZMYWMX EXIT PARAMETER LIST R *
* WORKAREA NOT MAPPED FOR USER W *
* *
* KEY = R-READ, W-WRITE, C-CREATE, D-DELETE *
* *
* TABLES = NONE *
* *
* MACROS = NONE *
* *
* MESSAGES = NONE *
* *
* MODULE TYPE = CSECT *
* *
* ATTRIBUTES = REENTRANT, REUSABLE, AMODE 31, *
* RMODE ANY *
* *
*01* DISCLAIMER = *
* *
* THIS SAMPLE PROGRAM IS PROVIDED FOR TUTORIAL PURPOSES ONLY. *
* A COMPLETE HANDLING OF ERROR CONDITIONS HAS NOT BEEN SHOWN *
* OR ATTEMPTED, AND THIS SOURCE HAS NOT BEEN SUBMITTED TO *
* FORMAL IBM TESTING. THIS SOURCE IS DISTRIBUTED ON AN *
* 'AS IS' BASIS WITHOUT ANY WARRANTIES EITHER EXPRESSED OR *
* IMPLIED. *
* *
****************************************************************
EJECT
WMXEXIT CSECT
WMXEXIT AMODE 31 31-BIT ADDRESSING MODE
WMXEXIT RMODE ANY 31-BIT RESIDENCE
SPACE 1
****************************************************************
* *
* REGISTER ASSIGNMENTS *
* *
****************************************************************
REG0 EQU 0 REGISTER 0
REG1 EQU 1 REGISTER 1
REG2 EQU 2 REGISTER 2
REG3 EQU 3 REGISTER 3
REG4 EQU 4 REGISTER 4
REG5 EQU 5 REGISTER 5
REG6 EQU 6 REGISTER 6
WMDXPPTR EQU 6 REGISTER 6 - PLIST
REG7 EQU 7 REGISTER 7
WMDXPTR EQU 7 REGISTER 6 - WMDX ADDRESS
REG8 EQU 8 REGISTER 8
REG9 EQU 9 REGISTER 9
REG10 EQU 10 REGISTER 10
REG11 EQU 11 REGISTER 11
DATAREG EQU 11 REGISTER 11 - 4K WORKAREA ADDR
REG12 EQU 12 REGISTER 12
BASEREG EQU 12 REGISTER 12 - MOD BASE
REG13 EQU 13 REGISTER 13
REG14 EQU 14 REGISTER 14
REG15 EQU 15 REGISTER 15
****************************************************************
* *
* STANDARD ENTRY LINKAGE *
* *
****************************************************************
SAVE (14,12) SAVE REGISTERS
BASR BASEREG,REG0 ESTABLISH MODULE BASE
USING *,BASEREG
LR WMDXPPTR,REG1 PARAMETER LIST
SPACE 1
****************************************************************
* *
* ESTABLISH ADDRESABILITY *
* *
****************************************************************
L WMDXPTR,0(,WMDXPPTR) GET ADDRESSABILITY
USING WMDX,WMDXPTR TO WMDX
L DATAREG,4(,WMDXPPTR) GET ADDRESSABILITY
USING WORKAREA,DATAREG TO 4K WORKAREA
SPACE 1
****************************************************************
* *
* CHECK FOR A SPECIFIC MESSAGE. IN THIS EXAMPLE, *
* IEE114I (RESPONSE TO D A,L COMMAND) IS USED. *
* *
****************************************************************
CLC WMDX_MSGTEXT(8),=C'IEE114I ' IS THIS CORRECT MSG
BNE CHKWTOR NO, CONTINUE
*
* DO STUFF NOW THAT WE KNOW THE MESSAGE IS CORRECT MSG
*
MVC WORKATXT(L'WORKATXT),=C'MESSAGE IS IEE114I. '
B FINISHED DONE
SPACE 1
****************************************************************
* *
* CHECK FOR A WTOR *
* *
****************************************************************
CHKWTOR EQU *
TM WMDX_FLAGS,WMDX_WTOR IS MESSAGE A WTOR
BNO CHKSLWTO NO, CONTINUE
*
* DO STUFF NOW THAT WE KNOW THE MESSAGE IS A WTOR
*
MVC WORKATXT(L'WORKATXT),=C'MESSAGE IS A WTOR. '
B FINISHED DONE
SPACE 1
****************************************************************
* *
* CHECK FOR A SINGLE LINE MESSAGE *
* *
****************************************************************
CHKSLWTO EQU *
TM WMDX_FLAGS,WMDX_SLWTO IS MESSAGE A SLWTO
BNO MULTLINE NO, MSG IS A MULTILINE
*
* DO STUFF NOW THAT WE KNOW THE MESSAGE IS A SINGLE LINE
*
MVC WORKATXT(L'WORKATXT),=C'MESSAGE IS A SINGLE LINE.'
B FINISHED DONE
SPACE 1
MULTLINE EQU *
****************************************************************
* *
* PERFORM MULTIPLE LINE MESSAGE PROCESSING. *
* NOTE THAT WMDX_MLWTO COULD HAVE BEEN USED TO *
* DETERMINE IF MESSAGE IA A MULTI-LINE. *
* *
****************************************************************
*
* DO STUFF NOW THAT WE KNOW THE MESSAGE IS A MULTILINE
*
* SEE NOTE1 in this topic ON HOW TO LOCATE THE REMAINING LINES IN
* THE MDB.
*
MVC WORKATXT(L'WORKATXT),=C'MESSAGE IS A MULTI-LINE. '
B FINISHED DONE
SPACE 1
****************************************************************
* *
* EXIT FROM THIS MODULE *
* *
****************************************************************
FINISHED EQU *
RETURN (14,12) RESTORE REGISTERS
EJECT
****************************************************************
* *
* 4K WORKAREA DEFINITIONS *
* NOTE: THIS SAMPLE ONLY USES 25 BYTES OF THE WORKAREA *
* *
****************************************************************
WORKAREA DSECT
DS 0H
WORKATXT DS CL25 MESSAGE TEXT AREA
WORKREST DS CL4071 AVAILABLE WORKAREA
DS 0H
ORG
WORKAEND EQU *-WORKAREA
EJECT
****************************************************************
* *
* PARAMETER LIST MAPPING *
* *
****************************************************************
CNZMYWMX WMDX PARAMETER LIST
SPACE 2
END WMXEXIT
z/OS MVS Installation Exits
Copyright IBM Corporation 1990, 2014