 |
Topics for This Exit Appear as Follows:
Through the IXC_ELEM_RESTART exit, your installation can modify
or cancel the automatic restart management-initiated restart of an
element. Your installation may use this exit to coordinate the restart
of an element with other automation routines, and to make decisions
about how, or if, it will be restarted. Automatic restart management
(ARM) invokes this exit once for each element that is to be restarted,
on the system where it will be restarted.
Installing the Exit Routine IXC_ELEM_RESTART
must be a load module in LPA or in an APF-authorized library in the
LNKLST concatenation on all the systems in the sysplex that are, or
may be, connected to the ARM couple data set. This exit must be linkedited
as reentrant.
For general instructions on installing a dynamic
exit routine, see Link editing a Dynamic Exit Routine into a Library.
Exit Routine Environment The
element restart exit receives control on the system where the element
is to be restarted, in the following environment: - Task mode
- Supervisor state with PSW key 0
- 31-bit addressing mode
- Primary ASC mode
- Enabled for interrupts
- No locks held
Exit Recovery: Your installation must provide recovery
for this exit, if it is critical for the exit to successfully complete
its processing. If you do not provide recovery and the exit ends
abnormally, MVS™ restarts proceed without modification.
Exit Routine Processing MVS invokes
the IXC_ELEM_RESTART exit on the system on which the element is to
be restarted, just before restarting the element. When MVS is
restarting a group of elements from a failing system in the sysplex, MVS first
invokes the IXC_WORK_RESTART exit once, so the installation can prepare
the new system for additional work, and then invokes the IXC_ELEM_RESTART
exit once for each element to be restarted.
When the
exit routine receives control, MVS passes
a parameter list (mapped by the IXCYERE macro) that contains such
information as the name of the element to be restarted, the reason
for the restart, and the restart method. Based on your knowledge
of the installation, the systems in its sysplex, its automation packages
and production controllers, and the elements registered with the automatic
restart manager, you can design the element restart exit to use the
parameter list information to do one of the following:
- Allow MVS to proceed without changes by setting a return
code of 0.
- Select a different restart method; for example, request that MVS use
a START command instead of persistent JCL.
- Check to see what restart methods are available in the EREFLAGS
field.
- Update the EREJCLDATASET with the name of the data set that contains
the JCL that should be used, or update ERESTARTTXT with the new START
text that should be used.
- Indicate the change in the ERERESTARTTYPE field.
- Set a return code of 4.
- Modify the current restart method.
- Modify the START command text in ERESTARTTXT, or the JCL in EREJCLDATASET,
whichever is appropriate.
- Set a return code of 4.
- Cancel the restart of the element.
- Indicate in the ERERESTARTTYPE field that the element should not
be restarted.
- Set a return code of 4.
Programming Considerations Entry Specifications MVS passes
to IXC_ELEM_RESTART the address of the parameter list mapped by IXCYERE.
Registers
at Entry: The contents of the registers on entry to the exit are
as follows.
- Register
- Contents
- 0
- Does not contain any information for use by the exit
- 1
- Address of the IXCYERE parameter list
- 2-12
- Does not contain any information for use by the exit
- 13
- Register save area
- 14
- Return address
- 15
- Entry point address of IXC_ELEM_RESTART
Parameter List Contents: Register 1 contains
the address of the element restart exit parameter list, which is mapped
by the IXCYERE mapping macro. The parameter list contains:
- The job name, element name, and element type.
- An indication of whether the element registered with the ELEMBIND=CURSYS
option.
- START command text, persistent JCL, or the data set name containing
the JCL that MVS will use to restart the element.
- An indication of how MVS will restart the element (START
command, persistent JCL, or JCL in a data set).
- The name of the system where the element will be restarted.
- The name of the system the element was running on when the failure
occurred.
- An indication of whether persistent restart text is available or
is not available for this element. Persistent restart text
is either the JCL or the started task command that was used to previously
start this element.
- An indication of whether the exit must supply restart text or
the restart will fail and the element will be deregistered.
The IXCYERE mapping is described in z/OS MVS Data
Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.
Return Specifications MVS expects
the exit to return a return code of 0 if no changes to the restart
method were requested, or a return code of 4 if a change to the restart
method was requested in the ERERESTARTTYPE field of IXCYERE. ERERESTARTTYPE
may also be used to indicate that the automatic restart manager should
not restart an element.
Registers at Exit: Upon return
from the exit processing, the register contents must be as follows.
- Register
- Contents
- 0-14
- The exit does not have to place any information in these registers,
and does not have to restore their contents to what they were when
the exit received control.
- 15
- Return code
- 0
- No changes to the restart method
- 4
- The automatic restart manager should change the restart method
as indicated in the IXCYERE parameter list.
Coded Example of the Exit Routine The
following is an example of an IXC_ELEM_RESTART exit. TITLE 'ELEMEXIT - SAMPLE AUTOMATIC RESTART MANAGER ELEMENT RESTART EXIT'
***START OF SPECIFICATIONS*********************************************
* *
* MODULE NAME = ELEMEXIT *
* *
* DESCRIPTIVE NAME = SAMPLE AUTOMATIC RESTART MANAGER ELEMENT *
* RESTART EXIT. *
* *
* FUNCTION = THIS EXIT WILL PROHIBIT RESTARTS FOR ELEMENT *
* TERMINATIONS BUT WILL ALLOW RESTARTS FOR *
* SYSTEM TERMINATIONS. *
* *
* OPERATION = DETERMINES THE TERMINATION TYPE FROM THE *
* EVENT CODE IN THE ELEMENT RESTART EXIT *
* PARAMETER LIST. IF AN ELEMENT TERMINATION IS *
* INDICATED, THE RESTART TYPE IN THE PARAMETER *
* LIST WILL BE SET TO RESTART OF NONE AND THE *
* EXIT'S RETURN CODE WILL BE SET TO FOUR. *
* IF A SYSTEM TERMINATION IS INDICATED, THE *
* PARAMETER LIST WILL NOT BE CHANGED AND THE *
* EXIT'S RETURN CODE WILL BE SET TO ZERO. *
* *
* ENTRY POINT = ELEMEXIT *
* *
* PURPOSE = TO DETERMINE THE WAY IN WHICH AN ELEMENT *
* WILL BE RESTARTED. *
* *
* LINKAGE = BALR *
* *
* INPUT DATA = REG1 ADDRESS OF THE IXCYERE 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 - NOT USED *
* REG3 - WORK REGISTER *
* REG4 - NOT USED *
* REG5 - POINTER TO IXCYERE *
* REG6 - NOT USED *
* REG7 - NOT USED *
* REG8 - NOT USED *
* REG9 - NOT USED *
* REG10 - NOT USED *
* REG11 - NOT USED *
* REG12 - MODULE BASE REGISTER *
* REG13 - POINTER TO A STANDARD SAVE AREA *
* REG14 - RETURN POINT *
* REG15 - RETURN CODE *
* *
* REGISTERS RESTORED = REG0 - REG14 *
* *
* CONTROL BLOCKS = *
* NAME MAPPING MACRO REASON USED USAGE *
* ---- ------------- ----------- ------- *
* ERE IXCYERE EXIT PARAMETER LIST R,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 *
* *
***********************************************************************
EJECT
ELEMEXIT CSECT
ELEMEXIT AMODE 31 31-BIT ADDRESSING MODE
ELEMEXIT 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
EREPTR EQU 5 REGISTER 5 - POINTS TO ERE
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
REG12 EQU 12 REGISTER 12
BASEREG EQU 12 REGISTER 12 - MODULE BASE
REG13 EQU 13 REGISTER 13
REG14 EQU 14 REGISTER 14
REG15 EQU 15 REGISTER 15
EJECT
***********************************************************************
* *
* STANDARD ENTRY LINKAGE *
* *
***********************************************************************
STM REG14,REG12,12(REG13) SAVE CALLER'S REGISTERS
BALR BASEREG,REG0 ESTABLISH MODULE BASE
USING *,BASEREG ESTABLISH ADDRESSABILITY
LR EREPTR,REG1 ESTABLISH ADDRESSABILITY
USING ERE,EREPTR TO THE ERE
***********************************************************************
* *
* DETERMINE THE TERMINATION TYPE BASED ON THE INPUT *
* EVENT CODE. *
* *
***********************************************************************
SPACE 1
LA REG3,EREELEMTERM
CH REG3,EREEVENTCODE ELEMENT TERMINATION?
BNE SYSTERM NO, GO TO SYSTEM TERMINATION
***********************************************************************
* *
* IF ELEMENT TERMINATION IS INDICATED, THE RESTART TYPE IN *
* THE PARAMETER LIST IS SET TO RESTART OF NONE AND THE *
* EXIT'S RETURN CODE IS SET TO FOUR. *
* *
***********************************************************************
MVI ERERESTARTTYPE,ERERESTARTNONE SET RESTART TO NONE
L REG15,FOUR SET RETURN CODE TO FOUR
B FINISHED GO TO FINISHED
***********************************************************************
* *
* IF SYSTEM TERMINATION IS INDICATED, THE PARAMETER LIST *
* IS NOT CHANGED AND THE EXIT'S RETURN CODE IS SET TO ZERO. *
* *
***********************************************************************
SYSTERM EQU *
L REG15,ZERO SET RETURN CODE TO ZERO
***********************************************************************
* *
* STANDARD EXIT LINKAGE, AND EXIT FROM THIS MODULE *
* *
***********************************************************************
FINISHED EQU *
L 14,12(REG13) RESTORE CALLER'S
LM 0,12,20(REG13) REGISTERS
BR REG14 RETURN TO CALLER
EJECT
***********************************************************************
* CONSTANTS *
***********************************************************************
DS 0F
ZERO DC F'0' ZERO
FOUR DC F'4' FOUR
EJECT
IXCYERE ERE
EJECT
END ELEMEXIT
|
z/OS MVS Installation Exits
Copyright IBM Corporation 1990, 2014