TITLE 'XCNSGY20- Sample IXCSYSCL macro usage'
XCNSGY20 CSECT
XCNSGY20 AMODE 31
XCNSGY20 RMODE ANY
*/* START OF SPECIFICATIONS *******************************************
*
*
*01* MODULE-NAME = XCNSGY20
*
*02* DESCRIPTIVE-NAME = Sample IXCSYSCL macro usage
*
* STATUS = HBB5520
*
*01* FUNCTION =
* Sample program to illustrate use of IXCSYSCL macro by a
* multi-system application that becomes a XCF group member and
* needs to perform system-wide cleanup after a system leaves
* the sysplex.
*
*02* OPERATION =
*
* (1) Get into Supervisor state Key 0
*
* (2) Load group exit routine
*
* (3) Join a XCF group and tell XCF that this group member
* performs system-wide cleanup after a system leaves the
* sysplex. This is done by invoking IXCJOIN macro with
* SYSCLEANUPMEM=YES and specifying a group exit such that
* XCF can notify us that a system has left the sysplex.
*
* (4) Wait for our group exit to tell us that it is time to
* do system-wide cleanup for a system that has left the
* sysplex. This will be done by waiting on the ECB passed
* to the group exit.
*
* (5) Do the necessary system-wide cleanup. This example will
* just issue a WTO saying it is doing system_wide cleanup.
*
* (6) Tell XCF this XCF group member has completed system-wide
* cleanup. This is accomplished by invoking the IXCSYSCL
* macro service and telling XCF which system the member has
* completed system-wide cleanup for.
*
* (7) Leave the XCF group.
*
* (8) Delete group exit routine
*
* (9) Return to problem state key 8
*
*
***********************************************************************
*
*02* RECOVERY-OPERATION = This program functions without recovery.
*
***********************************************************************
*
*01* NOTES =
*
* (1) Sample install Linkedit JCL:
*
* //LINK EXEC PGM=IEWL,
* // PARM='RENT,REFR,XREF,LET,LIST,NCAL,SIZE=(750K,200K)'
* //SYSUT1 DD UNIT=SYSDA,SPACE=(1024,(200,20))
* //OBJLIB DD DSN=userid.my.obj,DISP=SHR
* //SYSLMOD DD DSN=lnklst.lib,DISP=OLD
* //SYSPRINT DD SYSOUT=*
* //SYSLIN DD *
* INCLUDE OBJLIB(XCNSGY20)
* ENTRY XCNSGY20
* NAME XCNSGY20(R)
*
* (2) Sample execution JCL to run the example out of a authorized
* library in the linklist concatenation:
*
* //RUNIT EXEC PGM=XCNSGY20
* //SYSABEND DD SYSOUT=*
*
*
*02* DEPENDENCIES = None
*
*02* RESTRICTIONS =
* None
*
*02* REGISTER-CONVENTIONS =
*
*03* REGISTER-USAGE = See register declarations in code
*
*02* PATCH-LABEL = None
*
*01* MODULE-TYPE = CSECT
*
*02* PROCESSOR = Assembler-H
*
*02* MODULE-SIZE = See assembler External Symbol Dictionary
*
*02* ATTRIBUTES =
*
*03* LOCATION = User private
*
*03* RMODE = Any
*
*03* TYPE = Reentrant
*
**********************************************************************
*
*01* ENTRY-POINT = XCNSGY20
*
*02* PURPOSE = See FUNCTION section for this module.
*
*03* OPERATION = See OPERATION section for this module.
*
*02* LINKAGE = BALR
*
*03* CALLERS = Any
*
*02* ATTRIBUTES =
*
*03* ENTRY
*
*04* ENABLED
*04* STATE = Problem program
*04* KEY = User key
*04* AMODE = 31
*04* LOCKS HELD = None
*04* ASC MODE = Primary
*04* MEMORY MODE = Primary equal to Secondary equal to Home
*04* DISPATCH MODE = Task
*
*03* EXECUTION
*
*04* ENABLED
*04* STATE = Supervisor State
*04* KEY = Key zero
*04* AMODE = 31
*04* LOCKS OBTAINED = None
*04* ASC MODE = Primary
*04* MEMORY MODE = Primary equal to Secondary equal to Home
*02* SERIALIZATION = None
*
*02* INPUT = None
*
*03* ENTRY-REGISTERS =
*
* R0 = Irrelevant
* R1 = Irrelevant
* R2 - R12 = Irrelevant
* R13 = Address of a standard save area
* R14 = Return address
* R15 = Entry point address
*
*02* OUTPUT = WTOs
*
*
*02* EXIT-NORMAL = Return to caller
*
*03* CONDITIONS = The multisystem application has performed
* system-wide cleanup for a system removed from the
* sysplex.
*
*03* EXIT-REGISTERS = N/A
*
*03* RETURN-CODES =
* R15 - 00 if expected return codes from IXCJOIN, IXCSYSCL
* and IXCLEAVE macro services
*
* - 08 if unexpected return codes from IXCJOIN,
* IXCSYSCL, and IXCLEAVE macro services
*
*02* EXIT-ERROR = None
*
***********************************************************************
*
*01* EXTERNAL-REFERENCES =
*
*
*02* ROUTINES = None
*
*02* DATA-AREAS = None
*
*02* CONTROL-BLOCKS =
*
* Common Mapping
* Name Macro Usage Full Name
* ------ -------- ------------- ----------------------------------
* QUAA IXCYQUAA Read IXCYQUAA Macro Service ANSAREA
* mappings
*
*
*
*01* MACROS-EXECUTABLE =
* IXCJOIN
* IXCLEAVE
* IXCSYSCL
* STORAGE
* WTO
*
*01* SERIALIZATION = None.
*
*01* MESSAGES =
* The following WTOs may be issued to job log:
* XCNSGY20 IXCJOIN RETCODE=rrrrrrrr RSNCODE:ssssssss
* XCNSGY20 NOW IN GROUP=gggggggg MEMBER=mmmmmmmmmmmmmmmm
* XCNSGY20 DOING SYSTEM-WIDE CLEANUP FOR cccccccc
* XCNSGY20 IXCSYSCL RETCODE=rrrrrrrr RSNCODE:ssssssss
* XCNSGY20 IXCLEAVE RETCODE=rrrrrrrr RSNCODE:ssssssss
*
*01* ABEND-CODES = None
*
*01* WAIT-STATE-CODES = None
*
*01* CHANGE-ACTIVITY = None
*
**** END OF SPECIFICATIONS *******************************************/
EJECT
***********************************************************************
* *
* Standard entry linkage *
* *
***********************************************************************
STM R14,R12,12(R13)
BALR BASEREG1,0 Establish addressability
USING *,BASEREG1
MODID BR=YES
LR R3,R13 Save callers savearea address
STORAGE OBTAIN,ADDR=(DATAREG1),SP=0,LENGTH=DYNASIZE
LA DATAREG2,4095(,DATAREG1) Set Second Data Register
USING DYNA,DATAREG1 First Data Register
USING DYNA+4095,DATAREG2 Second Data Register
ST R3,SAVEAREA+4 Save @ of callers savearea
ST DATAREG1,8(,R3) Chain our savearea to callers
EJECT
***********************************************************************
* *
* Initialize variables *
* *
***********************************************************************
MVC EXITRC,=AL4(GOODRETC) * Initialize return code
MVC WTOEXEC(LENWTOS),WTOS * Copy static parmlist to dynamic
MVC WTOTXTD1(L'WTOTXTD1),WTOTXTS1 * Prime WTO text length
*--------------------------------------------------------------------
* Set up MEMDATA for the XCF group member
*--------------------------------------------------------------------
XC DATAGE(16),DATAGE Clear area used by group exit
LA R3,MYECB Get address of ECB
ST R3,MYECB_PTR Save address for group exit
LA R3,DATAGE Get address of data area to
* be used by group exit to pass
* information back to this task
ST R3,DATAGE_PTR Save address in first word of
* data area to be used by group
* exit to pass info back to this
* task
EJECT
***********************************************************************
* (1) Get into Key 0 , Supervisor State *
* *
***********************************************************************
MODESET KEY=ZERO,MODE=SUP
EJECT
***********************************************************************
* (2) Load Group exit routine. *
* *
***********************************************************************
LOAD EP=XCNSGY21
LR R2,R0 Save address of group exit
EJECT
***********************************************************************
* (3) Join a XCF group and tell XCF that this group member *
* performs system-wide cleanup after a system leaves the *
* sysplex. This is done by invoking IXCJOIN macro with *
* SYSCLEANUPMEM=YES and specifying a group exit such that *
* XCF can notify us that a system has left the sysplex. *
* *
***********************************************************************
IXCJOIN GRPNAME=MYGRPNAM, Name of XCF group to be used +
MEMNAME=MYMEMNAM, Member name to be used +
GRPEXIT=(R2), Group exit routine +
ANSLEN=QUAMLENG, Answer area length : One QUAMEM +
ANSAREA=QUAMEM, Answer area (returned QUAMEM) +
MEMDATA=MYMDATA, Member data +
SYSCLEANUPMEM=YES, Member does System-wide cleanup +
RETCODE=SAVERET, Return code +
RSNCODE=SAVERSN, Reason code +
MF=(E,JOINPL)
*
* Issue a WTO that shows the IXCJOIN RETCODE/RSNCODE
MVC WTOTXTD2(L'WTOTXTD2),WTOSERVC * Set message text
MVC MAPSERV(8),=CL8'IXCJOIN ' * Service invoked
* Convert hex return code to printable hex
MVC PHEXIN(4),SAVERET Hex return code to convert
UNPK PHEXOUT,PHEXIN Unpack the data
MVC MAPRETC(8),PHEXOUT+1 Store unpacked data into target
TR MAPRETC(8),TRTBL-240 Translate to printable hex
* Convert hex reason code to printable hex
MVC PHEXIN(4),SAVERSN Hex reason code to convert
UNPK PHEXOUT,PHEXIN Unpack the data
MVC MAPRSNC(8),PHEXOUT+1 Store unpacked data into target
TR MAPRSNC(8),TRTBL-240 Translate to printable hex
BAL R14,ISSUEWTO Tell user IXCJOIN RETCODE/RSNCODE
***********************************************************************
* Check for successfully joining XCF group. *
* *
***********************************************************************
L R3,SAVERET Get return code
C R3,=AL4(4) Member is now in active state
BH BADJOIN Bad return code from IXCJOIN
***********************************************************************
* Joined XCF group successfully. *
* *
***********************************************************************
MVC MYMEMTOK(8),QUAMTOKN Save my XCF member token
*
* Issue a WTO that shows the XCF group and member name join was for
MVC WTOTXTD2(L'WTOTXTD2),WTOJOIN * Set message text
MVC MAPGRPNM(8),MYGRPNAM * Set group name
MVC MAPMEMNM(16),MYMEMNAM * Set member name
BAL R14,ISSUEWTO Tell user XCF group & member name
EJECT
***********************************************************************
* (4) Wait for our group exit to tell us that it is time to *
* do system-wide cleanup for a system that has left the *
* sysplex. This will be done by waiting on the ECB passed *
* to the group exit. *
* *
***********************************************************************
LA R3,MYECB Point to ECB to wait on
WAIT ECB=(R3) Wait for group exit to tell us it
* is time to do system-wide cleanup
* for some other system
SPACE 2
***********************************************************************
* (5) Do the necessary system-wide cleanup. This example will *
* just issue a WTO saying it is doing system_wide cleanup and *
* identify name of system that group exit told us we are cleaning *
* up for. Group exit sets the value of SYSNAME. *
* *
***********************************************************************
*
* Issue a WTO that shows that member is doing system-wide cleanup
MVC WTOTXTD2(L'WTOTXTD2),WTOCLEAN * Set message text
MVC MAPSYSNM(8),SYSNAME Copy Sysname to WTO text area
BAL R14,ISSUEWTO Say doing system-wide cleanup
EJECT
***********************************************************************
* (6) Tell XCF this XCF group member has completed system-wide *
* cleanup. This is accomplished by invoking the IXCSYSCL *
* macro service and telling XCF which system the member has *
* completed system-wide cleanup for. *
* *
***********************************************************************
IXCSYSCL MEMTOKEN=MYMEMTOK, XCF group member token +
FAILEDSYS=MYSYSTOK, Failed system's system token +
RETCODE=SAVERET, Return code from IXCSYSCL +
RSNCODE=SAVERSN, Reason code from IXCSYSCL +
MF=(E,SYSCLPL)
*
* Issue a WTO that shows the IXCSYSCL RETCODE/RSNCODE
MVC WTOTXTD2(L'WTOTXTD2),WTOSERVC * Set message text
MVC MAPSERV(8),=CL8'IXCSYSCL' * Service invoked
* Convert hex return code to printable hex
MVC PHEXIN(4),SAVERET Hex return code to convert
UNPK PHEXOUT,PHEXIN Unpack the data
MVC MAPRETC(8),PHEXOUT+1 Store unpacked data into target
TR MAPRETC(8),TRTBL-240 Translate to printable hex
* Convert hex reason code to printable hex
MVC PHEXIN(4),SAVERSN Hex reason code to convert
UNPK PHEXOUT,PHEXIN Unpack the data
MVC MAPRSNC(8),PHEXOUT+1 Store unpacked data into target
TR MAPRSNC(8),TRTBL-240 Translate to printable hex
BAL R14,ISSUEWTO Tell user IXCSYSCL RETCODE/RSNCODE
EJECT
***********************************************************************
* Check for successfully telling XCF that this member has *
* completed system-wide cleanup for the failed system. *
***********************************************************************
L R3,SAVERET Get return code
C R3,=AL4(0) Request was accepted by XCF
BE LEAVEGRP Good return code from IXCSYSCL
***********************************************************************
* XCF did not accept the IXCSYSCL macro response. *
***********************************************************************
MVC EXITRC,=AL4(BADRETC) Set bad return code
EJECT
***********************************************************************
* (7) Leave the XCF group. *
* *
***********************************************************************
LEAVEGRP EQU * Label to leave XCF group
IXCLEAVE MEMTOKEN=MYMEMTOK, XCF member token +
RETCODE=SAVERET, Return code from IXCLEAVE +
RSNCODE=SAVERSN Reason code from IXCLEAVE +
MF=(E,LEAVEPL)
*
* Issue a WTO that shows the IXCLEAVE RETCODE/RSNCODE
MVC WTOTXTD2(L'WTOTXTD2),WTOSERVC * Set message text
MVC MAPSERV(8),=CL8'IXCLEAVE' * Service invoked
* Convert hex return code to printable hex
MVC PHEXIN(4),SAVERET Hex return code to convert
UNPK PHEXOUT,PHEXIN Unpack the data
MVC MAPRETC(8),PHEXOUT+1 Store unpacked data into target
TR MAPRETC(8),TRTBL-240 Translate to printable hex
* Convert hex reason code to printable hex
MVC PHEXIN(4),SAVERSN Hex reason code to convert
UNPK PHEXOUT,PHEXIN Unpack the data
MVC MAPRSNC(8),PHEXOUT+1 Store unpacked data into target
TR MAPRSNC(8),TRTBL-240 Translate to printable hex
BAL R14,ISSUEWTO Tell user IXCLEAVE RETCODE/RSNCODE
B DELGEXIT Delete the group exit
BADJOIN EQU * IXCJOIN got a bad return code
MVC EXITRC,=AL4(BADRETC) Set bad return code
EJECT
***********************************************************************
* (8) Delete Group exit routine *
* *
***********************************************************************
DELGEXIT EQU *
DELETE EP=XCNSGY21
EJECT
***********************************************************************
* (9) Return to Key 8, Problem State *
* *
***********************************************************************
COMPLETE EQU *
MODESET KEY=NZERO,MODE=PROB
EJECT
***********************************************************************
* Exit linkage *
* *
***********************************************************************
L R2,SAVEAREA+4 Save caller's save area address
L R3,EXITRC Save testcase return code
STORAGE RELEASE,ADDR=((DATAREG1)),LENGTH=DYNASIZE
LR R13,R2 Restore caller's save area address
L R14,12(R13) Restore Return address
LR R15,R3 Set testcase return code
LM R0,R12,20(R13) Restore Registers R0-R12
BR R14 Return to caller
***********************************************************************
* *
* Subroutine: ISSUEWTO *
* *
* Function : This routine is called to issue a WTO. *
* *
* Input : WTOTXTD1 contains text for WTO message to be issued *
* *
* *
***********************************************************************
ISSUEWTO EQU *
STM R14,R12,SAVE1 Save callers regs
LA R5,WTOTXTD1 Address WTO parmlist
WTO TEXT=(R5),ROUTCDE=(11),MF=(E,WTOEXEC) * Issue WTO
LM R14,R12,SAVE1 Restore callers regs
BR R14 Return to caller
EJECT
***********************************************************************
* *
* Register declares *
* *
***********************************************************************
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10 Reserved for future expansion
* of the code or the dynamic area
DATAREG2 EQU 11 Second data register
BASEREG1 EQU 12 Code register
R12 EQU 12
DATAREG1 EQU 13 First data register
R13 EQU 13
R14 EQU 14
R15 EQU 15
EJECT
***********************************************************************
* *
* Static data *
* *
***********************************************************************
DS 0F
TRTBL DC CL16'0123456789ABCDEF' * Translate table
ZERO DC F'0' * Constant zero for comparisons
SPACE 1
***********************************************************************
* *
* Static WTO data *
* *
***********************************************************************
WTOS WTO TEXT=,ROUTCDE=(11),MF=L * Static form of WTO
LENWTOS EQU *-WTOS * Length of WTO parmlist
WTOTXTS1 DC AL2(L'WTOTXTD2) * WTO text length
WTOSERVC DC CL65'XCNSGY20 mmmmmmmm RETCODE=rrrrrrrr RSNCODE=ssssssss'
MAPSERV EQU WTOTXTD2+9,8,C'C' * Map service WTO insert
MAPRETC EQU WTOTXTD2+26,8,C'C' * Map service RETCODE insert
MAPRSNC EQU WTOTXTD2+43,8,C'C' * Map service RETCODE insert
WTOCLEAN DC CL65'XCNSGY20 DOING SYSTEM-WIDE CLEANUP FOR cccccccc '
MAPSYSNM EQU WTOTXTD2+39,8,C'C' * Map system name insert
WTOJOIN DC CL65'XCNSGY20 NOW IN GROUP=gggggggg MEMBER=mmmmmmmmmmmmmmmm'
MAPGRPNM EQU WTOTXTD2+22,8,C'C' * Map group name insert
MAPMEMNM EQU WTOTXTD2+38,8,C'C' * Map member name insert
EJECT
***********************************************************************
* *
* Constants used to identify the application to XCF. *
* *
***********************************************************************
MYGRPNAM DC CL8'XCNSGY20' Application group name to join
* XCF group with
MYMEMNAM DC CL16'M1 ' Application member name to join
* XCF group with
* WTOTXTD2 fields)
LTORG
EJECT
***********************************************************************
* *
* Dynamic data *
* *
***********************************************************************
DYNA DSECT
SAVEAREA DS 18F Standard savearea (first field)
SPACE 1
***********************************************************************
* Member data passed to group exit via MEMDATA keyword *
***********************************************************************
DS 0D Ensure boundary alignment
MYMDATA DS CL8 Member data provided to group
* when member needs to do
* system-wide cleanup
DATAGE_PTR EQU MYMDATA+0,4,C'A' Address of data area to be used
* by group exit to pass info back
* to this task
SPACE 1
***********************************************************************
* Data area to be used by group exit to pass info back to this task *
***********************************************************************
DS 0D Ensure boundary alignment
DATAGE DS CL16 Data area to be used by
* group exit to pass info back to
* this task
SYSNAME EQU DATAGE+0,8,C'C' System name being cleanup up for
MYSYSTOK EQU DATAGE+8,4,C'F' System token to cleanup for
MYECB_PTR EQU DATAGE+12,4,C'A' ECB that group exit should post
SPACE 1
DS 0D Ensure boundary alignment
MYGE_ADDR DS A Address of group exit
MYMEMTOK DS XL8 Member token of XCF group member
PHEXIN DS CL5 Work area for printable hex conv
PHEXOUT DS CL10 Work area for printable hex conv
MYECB DS F ECB for group exit to post
SAVERET DS F Save macro service return code
SAVERSN DS F Save macro service reason code
SAVE1 DS 15F First level subroutine savearea
SAVE2 DS 15F Second level subroutine savearea
EXITRC DS F Module Return code
BADRETC EQU 8 Bad return code from testcase
GOODRETC EQU 0 Good return code from testcase
EJECT
***********************************************************************
* *
* Dynamic WTO storage *
* *
***********************************************************************
WTOEXEC WTO TEXT=,ROUTCDE=(11),MF=L * List form of WTO parmlist
WTOTXTD1 DC AL2(L'WTOTXTD1) * WTO text length
WTOTXTD2 DC CL65' ' * WTO text
SPACE 2
***********************************************************************
* Dynamic storage for parmlists *
***********************************************************************
SPACE 2
IXCJOIN MF=(L,JOINPL)
IXCSYSCL MF=(L,SYSCLPL)
IXCLEAVE MF=(L,LEAVEPL)
***********************************************************************
* Dynamic storage for a answer area to hold a QUAMEM record *
* recorded by IXCJOIN. *
***********************************************************************
IXCYQUAA DSECT=NO,HEADER=NO,MEMBER=YES,SYSTEM=NO, +
GROUP=NO,CF=NO,CFSC=NO,CFSTR=NO,STR=NO, +
STRPL=NO,STRXL=NO,STRCF=NO,STRUSER=NO,ARMS=NO
SPACE 2
***********************************************************************
* *
* End of dynamic storage *
* *
***********************************************************************
DYNASIZE EQU *-DYNA Total size of dynamic storage
EJECT
END
z/OS MVS Programming: Sysplex Services Reference
Copyright IBM Corporation 1990, 2014