 |
Topics for This Exit Appear as Follows:
CNZ_MSGTOSYSLOG receives control from the system when a message
is sent to the SYSLOG. Every message line that is sent to syslog will
be passed to the exit routines active at the exit point. Multi-line
messages will be presented as major line first, then major and each
minor (one at a time). For example, a multi-line message with 1 major
and 3 minor lines will result in the exit routines receiving control
4 times: - 1st Time - For the major line
- 2nd Time - For the first minor line
- 3rd Time - For the second minor line
- 4th Time - For the last minor line
Code a CNZ_MSGTOSYSLOG exit routine when you want to view all messages
being sent to the SYSLOG.
Controlling the Exit Routine Through the
Dynamic Exits Facilities IBM® has
defined the CNZ_MSGTOSYSLOG exit to the dynamic exits facility. You
can refer to the exit by the name CNZ_MSGTOSYSLOG. 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 CONSOLE address space.
Exit Recovery: The exit routine should NOT provide
its own recovery. If recovery is necessary, set up an EUT functional
recovery routine (FRR) instead of an ESTAE-type recovery routine.
This will improve system performance by shortening the path length
of the exit routine.
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_MSGTOSYSLOG exit
routine every time a message is sent to the SYSLOG. If any CNZ_MSGTOSYSLOG
routines are specified to the dynamic exits facility, a parameter
list (mapped by macro CNZMYM2S) is passed that contains the following
information about the message: Programming Considerations Observe
the following conventions when coding the CNZ_MSGTOSYSLOG exit routine: - Code the exit routine to be reentrant.
- Do not code the exit routine to issue messages to the SYSLOG.
Performance Considerations Message
to syslog processing may impact performance; therefore, consider the
following recommendations so that system performance is not degraded: - Exit routines installed at the CNZ_MSGTOSYSLOG exit point should
not perform operations that might degrade system performance, such
as issuing WAIT requests, issuing requests for large amounts of dynamic
storage, or issuing I/O requests. To reduce the need for storage
requests, the system provides a 4K workarea that your exit routine
can use for dynamic storage. The M2SL_WorkArea@ field in the CNZMYM2S
parameter mapping points to the 4K workarea. The exit routine must
clear the workarea before using it, because all exit routines installed
at the CNZ_MSGTOSYSLOG exit point use the same workarea.
- The exit routine should NOT provide its own recovery. If recovery
is necessary, set up an EUT functional recovery routine (FRR) instead
of an ESTAE-type recovery routine. This will improve system performance
by shortening the path length of the exit routine.
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 contains
the address of a pointer to the exit parameter list, the M2SL, which
is mapped by macro CNZMYM2S.
Return SpecificationsRegisters
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_MSGTOSYSLOG exit: TITLE 'M2SLEXIT - SAMPLE MESSAGE TO SYSLOG EXIT'
***START OF SPECIFICATIONS**************************************
* *
* MODULE NAME = M2SLEXIT *
* *
* DESCRIPTIVE NAME = SAMPLE MESSAGE TO SYSLOG EXIT. *
* *
* FUNCTION = THIS EXIT WILL DEMONSTRATE HOW TO *
* PROCESS THE DATA IN THE PARAMETER *
* LIST. *
* *
* OPERATION = IDENTIFIES THE MESSAGE LINE PASSED IN *
* THE PARAMETER LIST AND BRANCHES TO *
* THE APPROPRIATE SECTION TO PERFORM *
* PROCESSING BASED ON THE MESSAGE LINE. *
* *
* ENTRY POINT = M2SLEXIT *
* *
* PURPOSE = DEMONSTRATE HOW TO USE THIS EXIT. *
* *
* LINKAGE = BALR *
* *
* 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 - NOT USED *
* REG8 - NOT USED *
* REG9 - NOT USED *
* REG10 - NOT USED *
* REG11 - POINTER TO 4K WORK AREA *
* REG12 - MODULE BASE REGISTER *
* REG13 - POINTER TO STANDARD SAVE AREA *
* REG14 - RETURN POINT *
* REG15 - NOT USED *
* *
* REGISTERS RESTORED = REG0 - REG14 *
* *
* CONTROL BLOCKS = *
* NAME MAPPING MACRO REASON USED USAGE *
* ---- ------------- ----------- ------- *
* M2SL CNZMYM2S EXIT PARAMETER LIST R *
* WQE IHAWQE WTO QUEUE ELEMENT R *
* *
* 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 *
* *
****************************************************************
EJECT
M2SLEXIT CSECT
M2SLEXIT AMODE 31 31-BIT ADDRESSING MODE
M2SLEXIT 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
M2SLPTR EQU 6 REGISTER 6 - PTR TO M2SL
REG6 EQU 6 REGISTER 6
REG7 EQU 7 REGISTER 7
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 - WORKAREA
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 ESTABLISH ADDRESSABILITY
LR M2SLPTR,REG1 ESTABLISH ADDRESSABILITY
USING M2SL,M2SLPTR TO THE PARAMETER LIST
****************************************************************
* *
* SET ADDRESSABILITY AND INITIALIZE 4K WORKAREA *
* *
****************************************************************
L DATAREG,M2SL_WORKAREA@ ESTABLISH ADDRESSABILITY
USING DATAAREA,DATAREG TO 4K WORKAREA
LR REG2,DATAREG ADDRESS OF 4K WORKAREA
L REG3,LEN4K SIZE OF WORKAREA
LR REG4,REG2 ADDRESS OF 4K WORKAREA
SR REG5,REG5 CLEAR PADDING BYTE
MVCL REG2,REG4 INITIALIZE WORKAREA
****************************************************************
* *
* CHECK WHAT THE PARAMETER LIST PASSED US. *
* *
****************************************************************
SPACE 1
TM M2SL_FLAGS,M2SL_MLWTO MESSAGE IS MLWTO?
BZ SINGLINE NO, SINGLE LINE...
TM M2SL_FLAGS,M2SL_MINORLINE MINOR LINE?
BZ MAJRLINE NO, MAJOR LINE...
****************************************************************
* *
* PROCESSING A MINOR WQE LINE. *
* *
****************************************************************
MINRLINE EQU *
L REG3,M2SL_WQE@ ESTABLISH ADDRESSABILITY
USING WMJM,REG3 TO THE MAJOR WQE
L REG4,M2SL_WMNM@ ESTABLISH ADDRESSABILITY
USING WMNM,REG4 TO THE MINOR WQE
*
* DO STUFF NOW THAT WE KNOW THIS IS A MINOR WQE LINE.
*
MVC DYNAMTXT,WMNMTXT1 COPY MESSAGE TEXT
DROP REG3 DROP ADDRESSABILITY
DROP REG4 DROP ADDRESSABILITY
TM M2SL_FLAGS,M2SL_LASTLINE LAST LINE?
BNZ COMPLETE YES, MLWTO IS COMPLETE
B FINISHED PROCESSED MINOR, QUIT
****************************************************************
* *
* PROCESSING A MAJOR WQE LINE. *
* *
****************************************************************
MAJRLINE EQU *
L REG3,M2SL_WQE@ ESTABLISH ADDRESSABILITY
USING WMJM,REG3 TO THE MAJOR LINE
*
* DO STUFF NOW THAT WE KNOW THIS IS A MAJOR WQE LINE.
*
MVC DYNAMTXT,WMJMTXT COPY MESSAGE TEXT
DROP REG3 DROP ADDRESSABILITY
TM M2SL_FLAGS,M2SL_LASTLINE LAST LINE?
BNZ COMPLETE YES, MLWTO IS COMPLETE
B FINISHED PROCESSED MAJOR, QUIT
****************************************************************
* *
* PROCESSING A SINGLE WQE LINE. *
* *
****************************************************************
SINGLINE EQU *
L REG3,M2SL_WQE@ ESTABLISH ADDRESSABILITY
USING WQE,REG3 TO THE SINGLE WQE
*
* DO STUFF NOW THAT WE KNOW THIS IS A SINGLE WQE LINE.
*
MVC DYNAMTXT,WQETXT COPY MESSAGE TEXT
DROP REG3 DROP ADDRESSABILITY
B COMPLETE MESSAGE IS COMPLETE
****************************************************************
* *
* WE HAVE PROCESSED A COMPLETE MESSAGE. *
* *
****************************************************************
COMPLETE EQU *
*
* DO STUFF NOW THAT WE KNOW THE MESSAGE IS COMPLETE.
*
B FINISHED DONE PROCESSING, QUIT
****************************************************************
* *
* EXIT FROM THIS MODULE *
* *
****************************************************************
FINISHED EQU *
RETURN (14,12) RESTORE REGISTERS
EJECT
****************************************************************
* *
* 4K WORKAREA DEFINITIONS *
* NOTE: THIS SAMPLE ONLY USES 128 BYTES OF THE WORKAREA *
* *
****************************************************************
LEN4K DC F'4096'
DATAAREA DSECT
DS 0H
DYNAMTXT DS CL128 MESSAGE TEXT AREA
DATAAVAL DS CL3968 AVAILABLE WORKAREA
DS 0H
ORG
DATAEND EQU *-DATAAREA
SPACE 2
****************************************************************
* *
* PARAMETER LIST MAPPING *
* *
****************************************************************
IHAWQE FORMAT=NEW WTO QUEUE ELEMENT
CNZMYM2S M2SL PARAMETER LIST
EJECT
END M2SLEXIT
|
z/OS MVS Installation Exits
Copyright IBM Corporation 1990, 2014