TITLE 'HZSSCHKP - IBM Health Checker for z/OS Sample Checks' */* START OF SPECIFICATIONS ******************************************* * *01* MODULE-NAME: HZSSCHKP * *01* CSECT NAME: HZSSCHKP * *01* DESCRIPTIVE-NAME: Sample check routine for the IBM Health * Checker for z/OS (health checker) * Use of HZSPREAD and HZSPWRIT * * *01* PROPRIETARY STATEMENT= * * **PROPRIETARY_STATEMENT********************************************* * * * * * LICENSED MATERIALS - PROPERTY OF IBM * * 5694-A01 COPYRIGHT IBM CORP. 2006,2008 * * * * STATUS= HBB7750 * * * * **END_OF_PROPRIETARY_STATEMENT************************************** * * * * *01* FUNCTION: * * This module contains a check routine that demonstrates * - Use of HZSFMSG REQUEST=PARS1217 * - Use of the data space provided to a local check routine * - Use of the HZSPREAD service * - Use of the HZSPWRIT service * *02* OPERATION: HZSSCHKP * * HZSSCHKP * *02* OPERATION: SUBROUTINES * * *02* RECOVERY-OPERATION: * * The IBM Health Checker for z/OS provides recovery around * calls. If the check routine abends while performing * the PQE_Check function, the IBM Health Checker for z/OS * will call with the Pqe_Cleanup function code. * *********************************************************************** * *01* NOTES: * * None * *02* DEPENDENCIES: * * None * *02* RESTRICTIONS: * * None * *02* REGISTER-CONVENTIONS: * *03* REGISTERS SAVED: 14 *03* REGISTERS RESTORED: 14 *03* CODE REGISTER: None (Relative Branch) *03* STATIC Data REGISTER: R12 *03* DYNAMIC DATA REGISTER: R13 * *02* PATCH-LABEL: None * *01* MODULE-TYPE: Procedure * *02* PROCESSOR: High Level Assembler * *02* MODULE-SIZE: See External Symbol Dictionary * *02* ATTRIBUTES: * *03* LOCATION: Authorized Link List Library *03* LOAD MOD: HZSSCHKP *03* TYPE: Reentrant *03* AMODE: 31 *03* RMODE: Any * *********************************************************************** * *01* ENTRY-POINT: HZSSCHKP * *02* PURPOSE: See FUNCTION section for this module. * *03* OPERATION: See OPERATION section for this module. * *02* ATTRIBUTES: * *03* ENTRY * *04* MODE: Enabled *04* STATE: Supervisor *04* KEY: 8 *04* AMODE: 31 *04* LOCKS HELD: None *04* ASCMODE: Primary *04* MEMORY MODE: P=S=H *04* DISPATCH MODE: Task *04* ADDRESS SPACE: IBM Health Checker for z/OS * *03* EXECUTION * *04* MODE: Enabled *04* STATE: Supervisor *04* KEY: 8 *04* AMODE: 31 *04* LOCKS OBTAINED: NONE *04* ASCMODE: Primary *04* MEMORY MODE: P=S=H *04* ADDRESS SPACE: IBM Health Checker for z/OS * *02* LINKAGE: Branch Entry * *03* CALLERS: * * IBM Health Checker for z/OS * *02* INPUT: * * 1) Register 0. Address of 4K dynamic work area * Register 1. Address of an 8 byte parameter list containing: * +0 The 4 byte address of the HZSPQE for the check * +4 The 4 byte address of the 4K dynamic work area * *03* ENTRY-REGISTERS: * * Reg 0 - Address of the 4K dynamic work area * Reg 1 - Address of 8 byte parameter list * Reg 13 - Address of a 144 byte save area * Reg 14 - Return address. * Reg 15 - Address of the check routine * *02* OUTPUT: * * 1) Messages issued via HZSFMSG * *02* EXIT-NORMAL: RETURN TO CALLER * *03* CONDITIONS: Successful completion * *03* EXIT-REGISTERS: * * R0 - R13 - Unpredictable * R14 - Unchanged * R15 - Unpredictable * *03* RETURN-CODES: None * *02* EXIT-ERROR: None * *********************************************************************** * *01* EXTERNAL-REFERENCES : * *02* ROUTINES: * * None * *02* DATA-AREAS: * * None * *02* CONTROL-BLOCKS: * * Name Mapping Use Description * -------- -------- ---- ------------ * MGB HZSMGB C IBM Health Checker for z/OS Message Block * PQE HZSPQE R IBM Health Checker for z/OS Process Queue * Element * * Legend: C=Create, R=Read, W=Write, D=Delete * *01* MACROS-EXECUTABLE: * * HZSFMSG - IBM Health Checker for z/OS Message Macro * *01* SERIALIZATION: * * None * *01* MESSAGES: * * HZSH0011E * HZSH0021I * HZSH0022I * HZSH0031I * * *01* ABEND-CODES: None * *01* WAIT-STATE-CODES: * * None * *01* CHANGE-ACTIVITY: * * $L0=HCHECK ,HBB7720,050701,PDXB: Sample Healh Checker checks * **** END OF SPECIFICATIONS *******************************************/ TITLE 'HZSSCHKP - IBM Health Checker for z/OS Sample Checks' HZSSCHKP CSECT HZSSCHKP AMODE 31 HZSSCHKP RMODE ANY R0 EQU 0 Work Register R1 EQU 1 Work Register R2 EQU 2 Address of PQE and retained data R3 EQU 3 Work Register R4 EQU 4 Work Register R5 EQU 5 Work Register R6 EQU 6 Work Register R7 EQU 7 Work Register R8 EQU 8 Available for use R9 EQU 9 Available for use PReadBufReg EQU 10 Address of HZSPREAD buffer PWritBufReg EQU 11 Address of HZSPWRIT buffer R12 EQU 12 Static area Base R13 EQU 13 Dynamic area Base R14 EQU 14 Work Register R15 EQU 15 Work Register PReadStart EQU X'1000' We know that we can start using * the data space at x'1000' PWritStart EQU X'40000000' Start the "write" area halfway * into the data space SYSSTATE ARCHLVL=1 * The check routine is not required to save regs USING HZSSCHKP,R15 J Chk_Over_ID Jump over the identifier DC CL8'HZSSCHKP' ... Program Name DC CL8'&SYSDATE' ... Assembly Date Chk_Over_ID DC 0H LAE R12,STATAREA Address and ALET DROP R15 USING STATAREA,R12 LR R15,R0 Copy dynamic area for use * Chain saveareas (even though we did not save regs) ST R0,8(,R13) Chain new area to previous ST R13,4(,R15) Chain previous area to new LAE R13,0(R15,0) 4K dynamic area address USING Dynamic_Work,R13 ST R14,RETURN_ADDR Save return address L R2,0(,R1) Access PQE address LAE R2,0(R2,0) 0 ALET for later AR mode USING HZSPQE,R2 XC DynareaToClear(DynareaToClear_Len),DynareaToClear * * Code should use relative branch for maximum addressability * *********************************************************************** * Process HZS_Sample_Persist * *********************************************************************** *********************************************************************** * Check the function code to determine what to do * *********************************************************************** * Look for Init function * *********************************************************************** CLC PQE_Function_Code,=A(PQE_Function_Code_Init) JNE Persist_Not_Init *********************************************************************** * Put code here for Init processing for HZS_Sample_Persist * * Obtain resources that must persist for the life of the check. * * They cannot be associated with the check task, but instead with the * * jobstep task. * * This could also be done in the Check processing if you keep track of* * whether or not this is the first iteration of the Check processing * *********************************************************************** * As a sample jobstep-task resource, get storage in subpool 251 * *********************************************************************** GETMAIN RU,SP=251,LV=4096 ST R1,LifeOfCheckResourceAddr J EndMainline *********************************************************************** * End of Init Function * *********************************************************************** *********************************************************************** * Look for Check function * *********************************************************************** Persist_Not_Init DS 0H CLC PQE_Function_Code,=A(PQE_Function_Code_Check) JNE Persist_Not_Check *********************************************************************** * Put code here for Check processing for HZS_Sample_Persist * *********************************************************************** * Process parameters * *********************************************************************** TM PQE_MoreFlags,PQE_LookAtParms JZ Persist_No_Parms_Change * * Put code here to process the parameters in PQE_ParmArea. The * length of the parameters is in PQE_ParmLen. * For our example, * - assume that no parameters are allowed. *********************************************************************** * Check that parameter length is not 0 * *********************************************************************** CLC PQE_ParmLen,=H'0' JE Persist_No_ParameterError *********************************************************************** * Indicate problem with the parameter * *********************************************************************** HZSFMSG REQUEST=HZSMSG,REASON=PARS1217, * MF=(E,HZSFMSG_LIST) * * Stop calling the check. * IBM Health Checker for z/OS will write a message. * HZSFMSG REQUEST=STOP,REASON=BADPARM, * MF=(E,HZSFMSG_LIST) J EndMainline Persist_No_ParameterError DS 0H Persist_No_Parms_Change DS 0H *********************************************************************** * Obtain resources that are transient and should be released when this* * check iteration ends. Usually, these would be resources owned by the* * current task so that if the current task unexpectedly terminates, * * the system would free the resource. If the system will not * * automatically free the resource on termination of this task, * * the Cleanup processing must free the resource. * *********************************************************************** GETMAIN RU,SP=229,LV=4096 ST R1,TransientResourceAddr *********************************************************************** * Put the body of Check processing for HZS_Sample_Persist here. * *********************************************************************** * .... *********************************************************************** * Read the persistent data from the previous IPL * * In this case, we assume that the data to be read is * * less than the maximum size that we can obtain. * *********************************************************************** SAC 512 Enter AR-ASC mode SYSSTATE ASCENV=AR LHI PReadBufReg,PReadStart LAM PReadBufReg,PReadBufReg,PQE_DataspaceALET HZSPREAD CHECKOWNER=CK_Owner,CHECKNAME=CK_Name, * IPL=PRIOR,INSTANCE=FIRST, * BUFFER=(PReadBufReg),DATALEN==A(x'7FFFF000'), * STARTBYTE=0, * BYTESAVAIL=PReadBytes, * RETCODE=HZSPREAD_RC,RSNCODE=HZSPREAD_RSN, * MF=(E,HZSPREAD_LIST) LTR R15,R15 JZ HavePriorIPLData NILH R0,X'0000' Clear high 2 bytes of rsncode CHI R0,HzspreadRsn_NoMatch JE NoPriorIPLDataExists *********************************************************************** * Place code here to process the likely programming error * *********************************************************************** * .... HavePriorIPLData DS 0H *********************************************************************** * Place code here to process the persistent data, probably * * comparing it to the current data, looking for exceptions. * *********************************************************************** * .... NoPriorIPLDataExists DS 0H *********************************************************************** * Place code here to build the persistent data to be written * * In this example, we use the second half of the data space for * * the "Write" buffer, and the number of bytes to be written is * * stored in fullword PWritBytes. * *********************************************************************** L PWritBufReg,=A(PWritStart) LAM PWritBufReg,PWritBufReg,PQE_DataspaceALET * .... *********************************************************************** * Write the persistent data * * The number of bytes to write, in this sample, must have been * * placed into field PWritBytes. * *********************************************************************** HZSPWRIT BUFFER=(PWritBufReg),DATALEN=PWritBytes, * RETCODE=HZSPWRIT_RC,RSNCODE=HZSPWRIT_RSN, * MF=(E,HZSPWRIT_LIST) LTR R15,R15 JZ HZSPWRIT_Successful *********************************************************************** * Place code here to process the likely programming error * *********************************************************************** * .... HZSPWRIT_Successful DS 0H *********************************************************************** * Now that we are done with the data space, release pages since * * this check will not run again until the next interval (or never * * again, if it was "OneTime"). * * * * Rather than calculating the individual areas, it is most effective * * simply to tell DSPSERV to release the entire data space. * * x'7FFFF' represents the number of x'1000'-byte blocks in a 2G * * data space that starts at address x'1000' and thus covers any * * amount we might actually have used. * *********************************************************************** DSPSERV RELEASE,STOKEN=PQE_DataspaceSTOKEN, * INLIST=NO,START==A(x'1000'),BLOCKS==A(x'7FFFF'), * MF=(E,DSPSERV_LIST) SYSSTATE ASCENV=P SAC 0 Back to primary ASC mode *********************************************************************** * Place code here to determine whether to write exception message(s) * * or an "all is OK" message. * *********************************************************************** * .... J EndMainline *********************************************************************** * End of Check Function * *********************************************************************** *********************************************************************** * Look for Cleanup function * *********************************************************************** Persist_Not_Check DS 0H CLC PQE_Function_Code,=A(PQE_Function_Code_Cleanup) JNE Persist_Not_Cleanup *********************************************************************** * Put code here for Cleanup processing for HZS_Sample_Persist * *********************************************************************** * Release transient resources. * * Task-owned resources need only be released if we are still running * * under the same task where we obtained them. * *********************************************************************** TM PQE_Check_StatusB3,PQE_CleanupInDifferentTaskThanCheck JNZ Persist_DifferentTask ICM R1,B'1111',TransientResourceAddr JZ Persist_Transient_No_Free FREEMAIN RU,SP=229,LV=4096,A=(1) Persist_Transient_No_Free DS 0H Persist_DifferentTask DS 0H J EndMainline *********************************************************************** * End of Cleanup Function * *********************************************************************** *********************************************************************** * Look for Delete function * *********************************************************************** Persist_Not_Cleanup DS 0H CLC PQE_Function_Code,=A(PQE_Function_Code_Delete) JNE Persist_Not_Delete *********************************************************************** * Put code here for Delete processing for HZS_Sample_Persist * * Release life-of-the-check resources that were obtained * *********************************************************************** ICM R1,B'1111',LifeOfCheckResourceAddr JZ Persist_No_Free FREEMAIN RU,SP=251,LV=4096,A=(1) Persist_No_Free DS 0H J EndMainline *********************************************************************** * End of Delete function * *********************************************************************** *********************************************************************** * We will never get here, but if we did, we would do nothing * *********************************************************************** Persist_Not_Delete DS 0H * EndMainline DS 0H * * The check routine is not required to restore regs L R14,RETURN_ADDR Restore return reg BR R14 Return to caller STATAREA DS 0D Static area CK_Owner DC CL16'IBMSAMPLE' Owner of these health checks CK_Name DC CL32'HZS_SAMPLE_PERSIST' Check name LTORG literals * Dynamic_Work * Room for 4096 bytes using the input area in reg 0 * * Dynamic Working Area Map - This maps the area provided by the * IBM Health Checker for z/OS that is different every time this * Check Routine is called. * Dynamic_Work DSECT SaveArea DS CL72 Save Area Return_Addr DS A * DynareaToClear EQU * PReadBytes DS F Bytes read via HZSPREAD PWritBytes DS F Bytes written via HZSPWRIT NumBlocks DS F Number 4K dataspace blocks DynareaToClear_Len EQU *-DynareaToClear HZSPREAD_RC DS F HZSPREAD_RSN DS F HZSPWRIT_RC DS F HZSPWRIT_RSN DS F Parmlists DS 0D HZSFMSG MF=(L,HZSFMSG_List) Area for HZSFMSG plist ORG Parmlists HZSPREAD MF=(L,HZSPREAD_List) Area for HZSPREAD plist ORG Parmlists HZSPWRIT MF=(L,HZSPWRIT_List) Area for HZSPWRIT plist ORG Parmlists DSPSERV MF=(L,DSPSERV_List) Area for DSPSERV plist ORG * Dynamic_Work_Len EQU *-Dynamic_Work Length of used work area * * The dynamic work area provided on input is 4096 bytes. If the size * of the Dynamic_Work DSECT exceeds that length, the following * statement will cause an assembly error. * DS 0XL(4096-Dynamic_Work_Len) HZSPQE , PQE data area * * Retained Working Area Map - This maps the area provided by the * IBM Health Checker for z/OS in field PqeChkWork. The values * placed into this area are retained from call to call. * Thus the name Retained. * * HZSPQE DSECT Within HZSPQE ORG PQECHKWORK Persistent Data (x'800' bytes) Retained_Work DS 0D LifeOfCheckResourceAddr DS A Addr of life of check resource TransientResourceAddr DS A Address of transient resource * It is "retained" so that we can * access it in the Cleanup * function routine Retained_Work_Len EQU *-Retained_Work * * The PqeChkWork area is 2048 bytes. If the size of the Retained_Work * area which maps this routine's use of PqeChkWork exceeds that * length, the following statement will cause an assembly error. * DS 0XL(2048-Retained_Work_Len) HZSMGB , MGB data area HZSZCONS , Return and Reason codes END HZSSCHKP