IXC_WORK_RESTART — Workload 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
- Coded Example of the Exit Routine
Through the IXC_WORK_RESTART exit, your installation can prepare a system to receive additional workload from a failing system in the sysplex. MVS™ invokes IXC_WORK_RESTART one time on each system that is selected to restart work from a failing system. MVS selects the system most capable of handling the additional work. Because of the system's resources or unusual workload, your installation might want to improve this system's capability. Your installation can do so by coding the workload restart exit to perform tasks such as cancelling lower priority work.
This exit cannot cancel or change the restart of an element. To prevent the restart of an element, or to change how an element will be restarted, see IXC_ELEM_RESTART — Element Restart Exit.
Installing the Exit Routine
IXC_WORK_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 automatic restart management (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
workload restart exit receives control on the system where the work
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_WORK_RESTART exit once on each system where elements from a failed system are to be restarted, just prior to any restarts. MVS passes to the exit a parameter list that contains information about the failing system and the elements to be restarted. Design this exit to use the parameter list information, and information about this system and its current workload and resources, to cancel lower priority work or take any other actions necessary to lessen the impact of or prepare for additional work on this system.
You cannot use IXC_WORK_RESTART to cancel or redirect the elements to another system. MVS expects no information on return from this exit, and so will not alter the restarts.
Programming Considerations
- Code IXC_WORK_RESTART to be reentrant.
- Because MVS expects no information on return from the exit, you might want to code the exit to issue a message to indicate successful or unsuccessful processing. You might also code it to issue messages to report whatever actions the exit has taken to prepare the system for the restarts.
Entry Specifications
MVS passes to IXC_WORK_RESTART the address of the parameter list mapped by IXCYWRE.
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 IXCYWRE 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_WORK_RESTART
Parameter List Contents: Register 1 contains
the address of the workload restart exit parameter list, which is
mapped by the IXCYWRE mapping macro. The parameter list contains:
- The name of the failing system.
- The number of elements that are to be restarted on this system.
- The names of the elements that are to be restarted on this system.
IXCYWRE is described in z/OS MVS Data Areas in the z/OS Internet library.
Return Specifications
No information is expected on return to MVS.
Registers at Exit: MVS does not use any register contents returned from this exit, so you are not required to place any specific contents in the registers.
Coded Example of the Exit Routine
The
following is an example of an IXC_WORK_RESTART exit.
TITLE 'WORKLOAD - SAMPLE AUTOMATIC RESTART MANAGER WORKLOAD RESTART EXIT'
***START OF SPECIFICATIONS*********************************************
* *
* MODULE NAME = WORKLOAD *
* *
* DESCRIPTIVE NAME = SAMPLE AUTOMATIC RESTART MANAGER WORKLOAD *
* RESTART EXIT. *
* *
* FUNCTION = BASED ON THE NUMBER OF ELEMENTS TO BE *
* RESTARTED, THIS EXIT WILL CANCEL THE SAME *
* NUMBER OF JOBS ON THE SYSTEM. *
* *
* OPERATION = DETERMINES THE NUMBER OF ELEMENTS TO BE *
* RESTARTED FROM THE INPUT PARAMETER LIST. IF *
* THE NUMBER IS LARGER THAN 10, 10 JOBS WILL BE*
* CANCELLED. OTHERWISE, THE NUMBER OF JOBS TO *
* BE CANCELLED WILL BE THE SAME AS THE NUMBER *
* TO BE RESTARTED. *
* *
* THE JOB NAMES WILL BE OBTAINED FROM AN *
* INTERNAL LIST AND EACH WILL BE CANCELLED VIA *
* THE MGCRE MACRO. A WTO WILL BE ISSUED *
* INDICATING THAT EACH JOB IS BEING CANCELLED. *
* *
* ENTRY POINT = WORKLOAD *
* *
* PURPOSE = TO FREE RESOURCES BY CLEANING UP LOW PRIORITY*
* WORK ON THE SYSTEM PRIOR TO RESTART. *
* *
* LINKAGE = BALR ** *
* INPUT DATA = REG1 ADDRESS OF THE IXCYWRE PARAMETER LIST *
* REG13 ADDRESS OF STANDARD SAVE AREA *
* REG14 RETURN ADDRESS *
* REG15 ENTRY POINT ADDRESS *
* *
* REGISTERS SAVED = REG0 - REG15 *
* *
* REGISTER USAGE = REG0 - PARAMETER REGISTER *
* REG1 - PARAMETER REGISTER *
* REG2 - NOT USED *
* REG3 - WORK REGISTER *
* REG4 - WORK REGISTER *
* REG5 - POINTER TO WRE *
* REG6 - WORK REGISTER *
* REG7 - WORK REGISTER *
* REG8 - WORK REGISTER *
* REG9 - RETURN REGISTER FOR SUBROUTINES *
* REG10 - NOT USED *
* REG11 - MODULE DATA REGISTER *
* REG12 - MODULE BASE REGISTER *
* REG13 - POINTER TO A STANDARD SAVE AREA *
* REG14 - RETURN POINT *
* REG15 - PARAMETER REGISTER *
* *
* REGISTERS RESTORED = REG0 - REG15 *
* *
* CONTROL BLOCKS = *
* NAME MAPPING MACRO REASON USED USAGE *
* ---- ------------- ----------- ------- *
* WRE IXCYWRE EXIT PARAMETER LIST R *
* *
* KEY = R-READ, W-WRITE, C-CREATE, D-DELETE *
* *
* TABLES = JOB NAME TABLE *
* *
* MACROS = GETMAIN, FREEMAIN, MGCRE, WTO *
* *
* MESSAGES = USER001I *
* *
* MODULE TYPE = CSECT *
* *
* ATTRIBUTES = REENTRANT, REUSABLE, AMODE 31, RMODE ANY *
* *
***********************************************************************
EJECT
WORKLOAD CSECT
WORKLOAD AMODE 31 31-BIT ADDRESSING MODE
WORKLOAD 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
WREPTR EQU 5 REGISTER 5 - POINTS TO WRE
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 - CURRENTLY UNUSED
DATAREG EQU 11 REGISTER 11 - DYNAMIC DATA AREA
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
SPACE 1
***********************************************************************
* *
* EQUATES *
* *
***********************************************************************
SPINPRVT EQU 230 SUBPOOL VALUE FOR GETMAIN
EJECT
***********************************************************************
* *
* STANDARD ENTRY LINKAGE *
* *
***********************************************************************
STM REG14,REG12,12(REG13) SAVE CALLER'S REGISTERS
BALR BASEREG,REG0 ESTABLISH MODULE BASE
USING *,BASEREG ESTABLISH ADDRESSABILITY
LR WREPTR,REG1 ESTABLISH ADDRESSABILITY
USING WRE,WREPTR TO THE WRE
***********************************************************************
* *
* OBTAIN DYNAMIC STORAGE *
* *
***********************************************************************
SPACE 1
LA REG0,DATAEND LENGTH OF DATA AREAS
GETMAIN RU,LV=(REG0),SP=SPINPRVT OBTAIN DYNAMIC STORAGE
LR DATAREG,REG1 ADDRESS RETURNED IN REG1
USING DATAAREA,DATAREG ADDRESSABILITY TO DYNAMIC X
STORAGE***********************************************************************
* *
* DETERMINE THE NUMBER OF JOBS TO CANCEL BASED ON THE INPUT *
* NUMBER OF ELEMENTS TO BE RESTARTED. IF THE NUMBER IS *
* LARGER THAN 10, 10 WILL BE USED. *
* *
***********************************************************************
SPACE 1
LA REG3,10 MAX NUMBER OF JOBS TO CANCEL
L REG4,WRENUMBEROFELEMENTS NUMBER OF ELEMENTS TO RESTART
CR REG4,REG3 IS NUMBER GREATER THAN MAX?
BL CANCEL NO, GO TO CANCEL
LR REG4,REG3 USE THE MAX
***********************************************************************
* *
* CANCEL THE JOBS SPECIFIED IN THE INTERNAL TABLE VIA THE *
* MGCRE MACRO. ISSUE A WTO INDICATING EACH JOB THAT IS *
* CANCELLED. *
* *
***********************************************************************
CANCEL EQU *
ST REG4,JOBNUM SAVE THE NUMBER OF JOBS
LA REG3,0 SET COUNTER TO ZERO
LOOP EQU *
LR REG7,REG3 MANIPULATE COUNTER VALUE TO
M REG6,ENTRYLNG OBTAIN JOBS INDEX VALUE
LA REG6,JOBS GET ADDRESS OF JOBS TABLE
AR REG7,REG6 ADD THE DISPLACEMENT
MVC JOBNAME(8),0(REG7) STORE JOB NAME TO BE CANCELLED
BAL REG9,ISSMGCRE ISSUE CANCEL COMMAND
BAL REG9,ISSUWTO ISSUE MESSAGE USER001I
A REG3,ONE INCREMENT COUNTER BY ONE
C REG3,JOBNUM IF COUNTER IS LESS THAN NUMBER
BL LOOP OF ELEMENTS, LOOP
EJECT ,
***********************************************************************
* RETURN THE DYNAMIC STORAGE OBTAINED *
***********************************************************************
LA REG0,DATAEND LENGTH OF DATA AREAS
FREEMAIN RU,LV=(REG0),A=(DATAREG),SP=SPINPRVT X
FREE THE DYNAMIC STORAGE AREA
***********************************************************************
* *
* STANDARD EXIT LINKAGE, AND EXIT FROM THIS MODULE *
* *
***********************************************************************
FINISHED EQU *
LM REG14,REG12,12(REG13) RESTORE CALLER'S X
REGISTERS
BR REG14 RETURN TO CALLER
EJECT***********************************************************************
* *
* PROCEDURE - ISSMGCRE *
* *
* FUNCTION - ISSUES A CANCEL COMMAND FOR A JOB *
* *
* INPUT - REGISTER 11 POINTS TO THE DYNAMIC AREA WHICH CONTAINS *
* STORAGE FOR THE MGCRE PARAMETER LIST *
* *
* OUTPUT - A CANCEL COMMAND IS ISSUED VIA MGCRE *
* *
* NOTES - LIST AND EXECUTE FORMS OF MGCRE ARE REQUIRED. *
* *
***********************************************************************
SPACE 1
ISSMGCRE EQU *
LA REG7,DYNCMDR1 ADDRESS COMMAND REPLY AREA
MVI 0(REG7),BLANK BLANK FIRST MESSAGE CHARACTER
MVC 1(CMDRLENG-1,REG7),0(REG7) BLANK ENTIRE MESSAGE FIELD
MVC 0(L'CMDLNGTH,REG7),CMDLNGTH INITIALIZE COMMAND LENGTH
MVC L'CMDLNGTH(L'TXINSRT1,REG7),TXINSRT1
* MOVE CANCEL VERB TO AREA
***********************************************************************
* JOBNAME CONTAINS THE JOB NAME VALUE. ENTRYLNG *
* CONTAINS THE LENGTH OF THE JOB NAME. USE THESE FIELDS TO *
* MOVE THE JOB NAME INTO THE TEXT AREA *
***********************************************************************
LH REG8,ENTRYLNG JOB NAME LENGTH
BCTR REG8,0 DECREMENT BY 1 FOR EXECUTE
EX REG8,MOVEJOBN MOVE JOB NAME VALUE INTO TEXT
LA REG4,DYNMGCRE ADDRESS MGCRE PARAMETER LIST
MVC 0(REPLEN,REG4),REPAREA COPY MGCRE LIST TO DYNAMIC
XR REG6,REG6 CONSOLE ID VALUE OF ZERO
MGCRE TEXT=(REG7),CONSID=(REG6),MF=(E,(REG4))
BR REG9 RETURN TO CALLER
***********************************************************************
* OBJECT OF AN EXECUTE *
***********************************************************************
MOVEJOBN MVC TXINSRT2-CMDCANCL(0,REG7),JOBNAME MOVE JOB NAME
* INTO CANCEL COMMAND
EJECT
***********************************************************************
* *
* PROCEDURE - ISSUWTO *
* *
* FUNCTION - ISSUES A MESSAGE INFORMING OPERATOR THAT A JOB IS *
* BEING CANCELLED *
* *
* INPUT - NONE *
* *
* OUTPUT - MESSAGE STATING JOB CANCELLED *
* *
***********************************************************************
SPACE 1
ISSUWTO EQU ************************************************************************
* INITIALIZE MESSAGE TEXT FOR TEXT= PARAMETER ON WTO *
***********************************************************************
LA REG8,DYNAMTXT DYNAMIC MESSAGE AREA
MVC 0(USERLENG,REG8),USERMSG1 INITIALIZE MESSAGE TEXT
MVC USERM1VB-USERMSG1(L'USERM1VB,REG8),JOBNAME JOB NAME
MVC DYNUSERS,USERSTAT MOVE WTO STATIC AREA
SR REG0,REG0 INITIALIZE REGISTER 0 TO ZERO
WTO TEXT=(REG8),ROUTCDE=(11),DESC=(6),MF=(E,DYNUSERS)
* ISSUE THE MESSAGE
BR REG9 RETURN TO CALLER
EJECT
***********************************************************************
* *
* JOB NAME TABLE *
* *
***********************************************************************
JOBS DC CL8'JOB1 '
DC CL8'JOB2 '
DC CL8'JOB3 '
DC CL8'JOB4 '
DC CL8'JOB5 '
DC CL8'JOB6 '
DC CL8'JOB7 '
DC CL8'JOB8 '
DC CL8'JOB9 '
DC CL8'JOB10 '
SPACE 1
***********************************************************************
* LENGTH AND TEXT OF CANCEL COMMAND *
***********************************************************************
CMDCANCL EQU *
CMDLNGTH DC XL2'0F' LENGTH OF CANCEL COMMAND
TXINSRT1 DC CL7'CANCEL ' FIRST STATIC INSERT
TXI1LENG EQU *-CMDCANCL OFFSET TO TXINSRT1
TXINSRT2 DC CL8'XXXXXXXX' PLACE JOB NAME HERE
CMDRLENG EQU *-CMDCANCL COMMAND LENGTH
EJECT ,
***********************************************************************
* *
* LIST FORM OF MGCRE MACRO (STATIC) *
* *
***********************************************************************
USERREP DS 0H
REPAREA MGCRE MF=L LIST FORM OF MACRO
REPLEN EQU *-USERREP LENGTH OF MGCRE PARAMETER LIST***********************************************************************
* *
* LIST FORM OF WTO MACRO (STATIC) *
* *
***********************************************************************
USERSTAT DS 0H
WTO TEXT=USERMSG1,ROUTCDE=(11),DESC=(6),MF=L
CNCLMSGL EQU *-USERSTAT LENGTH OF PARAMETER LIST
SPACE 1
***********************************************************************
* CONSTANTS *
***********************************************************************
DS 0F
ENTRYLNG DC F'8' LENGTH OF JOB NAME TABLE ENTRY
ONE DC F'1' ONE
BLANK EQU X'40' BLANK CHARACTER
SPACE 1
***********************************************************************
* LAYOUT OF MESSAGE TEXT FOR USER001I *
***********************************************************************
USERMSG1 DS 0H
USERM1LN DC XL2'1C' LENGTH OF MESSAGE (IN HEX)
USERM1S1 DC C'USER001I CANCELLING ' FIRST STATIC FIELD
USERM1VB DC CL8' ' JOB NAME
USERLENG EQU *-USERMSG1 LENGTH OF AREA FOR GETMAIN
EJECT
***********************************************************************
* *
* STORAGE DEFINITIONS *
* *
***********************************************************************
DATAAREA DSECT
DS 0F
JOBNUM DS F
JOBNAME DS CL8
DYNMGCRE DS CL(REPLEN) DYNAMIC MGCRE AREA
DYNAMTXT DS CL(USERLENG) DYNAMIC MESSAGE TEXT AREA
DYNUSERS DS CL(CNCLMSGL) WTO MACRO AREA
DYNUMSG1 DS CL(USERLENG) DYNAMIC USER001I MESSAGE
DYNCMDR1 DS CL(CMDRLENG) DYNAMIC COMMAND REPLY AREA
DS 0H
ORG
DATAEND EQU *-DATAAREA
EJECT
IXCYWRE WRE
EJECT
END WORKLOAD