IXC_ELEM_RESTART — Element Restart Exit
Topics for This Exit Appear as Follows:
- Installing the Exit Routine
- Exit Routine Environment
- Exit Recovery
- Exit Routine Processing
- Programming Considerations
- Entry Specifications
- Registers at Entry
- Parameter List Contents
- Return Specifications
- Registers at Exit
- Coded Example of the Exit Routine
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
- 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
- Code IXC_ELEM_RESTART to be reentrant.
- If you provide new restart text (either a JCL data set name or a started task command), and you use any symbolic substitution parameters (such as &SYSCLONE.), they will be resolved using the values from the system on which the element initially registered. If you use symbolic substitution parameters, retrieve the replication ID of the system the element initially registered on, the system the element was previously running on, or the system the element is to be restarted on from the EREHOMESYSTEM field, the EREFROMSYSTEM field, or the ERETOSYSTEM field in IXCYERE.
- Do not code the IXC_ELEM_RESTART exit to perform the restart itself,
because the element might not be able to reregister. Use this exit
to notify automatic restart management that it should not restart
the element. Use a separate program to restart the element, after
it has been deregistered. To indicate that this element should not
be restarted by automatic restart management, code the following in
the IXC_ELEM_RESTART exit:
- Set ERERESTARTTYPE to X'01' to indicate that automatic restart management should not restart the element.
- Set a return code of X'4' in register 15.
From another program, use the ENFREQ macro to listen for the deregister ENF signal for the element. Restart the element.
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
- 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 the z/OS Internet library.
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
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