TITLE 'HZSSCHKR - IBM Health Checker for z/OS Sample Checks' */* START OF SPECIFICATIONS ******************************************* * *01* MODULE-NAME: HZSSCHKR * *01* CSECT NAME: HZSSCHKR * *01* DESCRIPTIVE-NAME: Sample check routines for the IBM Health * Checker for z/OS (health checker) * * *01* PROPRIETARY STATEMENT= * * **PROPRIETARY_STATEMENT********************************************* * * * * * LICENSED MATERIALS - PROPERTY OF IBM * * 5694-A01 COPYRIGHT IBM CORP. 2005,2008 * * * * STATUS= HBB7750 * * * * **END_OF_PROPRIETARY_STATEMENT************************************** * * * * *01* FUNCTION: * * This module contains two check routines, differentiated by * entry code. * Entry code 1: HZS_SAMPLE_ONE_TIME * - Produces a report consisting of a "header" and multiple * entries * - Produces an exception message or a success message * Entry code 2: HZS_SAMPLE_ONE_INTERVAL * *02* OPERATION: HZSSCHKR * * HZSSCHKR * *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: HZSSCHKR *03* TYPE: Reentrant *03* AMODE: 31 *03* RMODE: Any * *********************************************************************** * *01* ENTRY-POINT: HZSSCHKR * *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 'HZSSCHKR - IBM Health Checker for z/OS Sample Checks' HZSSCHKR CSECT HZSSCHKR AMODE 31 HZSSCHKR 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 R10 EQU 10 Available for use R11 EQU 11 Available for use R12 EQU 12 Static area Base R13 EQU 13 Dynamic area Base R14 EQU 14 Work Register R15 EQU 15 Work Register ENTRY_CODE_HZS_SAMPLE_ONE_TIME EQU 1 ENTRY_CODE_HZS_SAMPLE_INTERVAL EQU 2 SYSSTATE ARCHLVL=1 * The check routine is not required to save regs USING HZSSCHKR,R15 J Chk_Over_ID Jump over the identifier DC CL8'HZSSCHKR' ... Program Name DC CL8'&SYSDATE' ... Assembly Date Chk_Over_ID DC 0H LA R12,STATAREA 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 LR R13,R15 4K dynamic area address USING Dynamic_Work,R13 ST R14,RETURN_ADDR Save return address L R2,0(,R1) Access PQE address USING HZSPQE,R2 LA R3,AreaForMGB ST R3,Addr_Of_MGB Using HZSMGB,AreaForMGB XC DynareaToClear(DynareaToClear_Len),DynareaToClear * * Code should use relative branch for maximum addressability * *********************************************************************** * Check the entry code to determine which check to process * *********************************************************************** CLC PQE_Entry_Code,=A(Entry_Code_HZS_Sample_One_Time) JNE Not_Sample_One_Time *********************************************************************** * Process HZS_Sample_One_Time * *********************************************************************** *********************************************************************** * Check the function code to determine what to do * *********************************************************************** * Look for Init function * *********************************************************************** CLC PQE_Function_Code,=A(PQE_Function_Code_Init) JNE One_Time_Not_Init *********************************************************************** * Put code here for Init processing for HZS_Sample_One_Time * * 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 * *********************************************************************** One_Time_Not_Init DS 0H CLC PQE_Function_Code,=A(PQE_Function_Code_Check) JNE One_Time_Not_Check *********************************************************************** * Put code here for Check processing for HZS_Sample_One_Time * *********************************************************************** * Process parameters * *********************************************************************** TM PQE_MoreFlags,PQE_LookAtParms JZ One_Time_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 the required parameter string is LIMIT(nnn) where * nnn is a 3-digit decimal number. The processing converts this * from character to decimal and saves in field "Parm_Limit" which * is retained from one check iteration to the next. * - Bit ParameterError in byte Flags is set upon detecting an error *********************************************************************** * Check that parameter length is 10 * *********************************************************************** CLC PQE_ParmLen,=H'10' JNE One_Time_SetParmError *********************************************************************** * Check that parameter begins with "LIMIT(" * *********************************************************************** CLC PQE_ParmArea(6),=CL6'LIMIT(' JNE One_Time_SetParmError *********************************************************************** * Check that nnn is valid decimal * *********************************************************************** CLI PQE_ParmArea+6,C'0' JL One_Time_SetParmError CLI PQE_ParmArea+6,C'9' JH One_Time_SetParmError CLI PQE_ParmArea+7,C'0' JL One_Time_SetParmError CLI PQE_ParmArea+7,C'9' JH One_Time_SetParmError CLI PQE_ParmArea+8,C'0' JL One_Time_SetParmError CLI PQE_ParmArea+8,C'9' JH One_Time_SetParmError *********************************************************************** * Check that parameter ends with ")" * *********************************************************************** CLI PQE_ParmArea+9,C')' JNE One_Time_SetParmError *********************************************************************** * Convert from character * *********************************************************************** PACK Packed(8),PQE_ParmArea+6(3) CVB R15,Packed ST R15,Parm_Limit J One_Time_No_ParameterError One_Time_SetParmError DS 0H OI Flags,ParameterError * * If a parameter error is detected, 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 One_Time_No_ParameterError DS 0H One_Time_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_One_Time here. * *********************************************************************** * .... *********************************************************************** * Set up the MGB insert addresses so that any message can put * * its insert values into the InsertN variables and not have to reset * * the MGB_InsertAddr array. * *********************************************************************** LA R4,Insert1 Address of first insert LA R5,Insert2 Address of second insert LA R6,Insert3 Address of third insert LA R7,Insert4 Address of fourth insert ST R4,MGB_InsertAddr Save insert 1 addr in MGB ST R5,MGB_InsertAddr+4 Save insert 2 addr in MGB ST R6,MGB_InsertAddr+8 Save insert 3 addr in MGB ST R7,MGB_InsertAddr+12 Save insert 4 addr in MGB * *********************************************************************** * Having determined the need to write a report with data that * * consists of a report line and two report entries, and having * * put the values into variables Avail1, Inuse1, Avail2, Inuse2, * * use HZSFMSG to write the messages * *********************************************************************** * Write the report header * *********************************************************************** MVC MGB_ID,=F'2' Message with XREFTEXT=002 MVC MGB_insert_cnt,=F'0' No inserts. HZSFMSG REQUEST=CHECKMSG,MGBADDR=Addr_Of_MGB, * MF=(E,HZSFMSG_List) *********************************************************************** * Write line 1 which has the type, num-avail, num-inuse * *********************************************************************** * Set up the MGB header * *********************************************************************** MVC MGB_ID,=F'3' Message with XREFTEXT=003 MVC MGB_insert_cnt,=F'3' Three inserts *********************************************************************** * Set up the inserts * *********************************************************************** Push Using Using MGB_MsgInsertD,Insert1 MVC MGB_MsgILen,=AL2(L'Type1) MVC MGB_MsgIVal(L'Type1),Type1 Pop Using Push Using Using MGB_MsgInsertD,Insert2 MVC MGB_MsgILen,=AL2(L'Avail1) MVC MGB_MsgIVal(L'Avail1),Avail1 Pop Using Push Using Using MGB_MsgInsertD,Insert3 MVC MGB_MsgILen,=AL2(L'Inuse1) MVC MGB_MsgIVal(L'Inuse1),Inuse1 Pop Using *********************************************************************** * Issue HZSFMSG to write the message * *********************************************************************** HZSFMSG REQUEST=CHECKMSG,MGBADDR=Addr_Of_MGB, * MF=(E,HZSFMSG_List) *********************************************************************** * Write line 2 which has the type, num-avail, num-inuse * *********************************************************************** * Note that we did not have to set up the MGB header again, since the * * values from the previous call are what we need for this call * *********************************************************************** * Set up the inserts * *********************************************************************** Push Using Using MGB_MsgInsertD,Insert1 MVC MGB_MsgILen,=AL2(L'Type2) MVC MGB_MsgIVal(L'Type2),Type2 Pop Using Push Using Using MGB_MsgInsertD,Insert2 MVC MGB_MsgILen,=AL2(L'Avail2) MVC MGB_MsgIVal(L'Avail2),Avail2 Pop Using Push Using Using MGB_MsgInsertD,Insert3 MVC MGB_MsgILen,=AL2(L'Inuse2) MVC MGB_MsgIVal(L'Inuse2),Inuse2 Pop Using *********************************************************************** * Issue HZSFMSG to write the message * *********************************************************************** HZSFMSG REQUEST=CHECKMSG,MGBADDR=Addr_Of_MGB, * MF=(E,HZSFMSG_List) *********************************************************************** * Place code here to determine whether to write exception message(s) * * or an "all is OK" message. * *********************************************************************** * .... *********************************************************************** * Assuming the code above detected an exception situation, * * Build and write exception message * *********************************************************************** * Set up the MGB header * *********************************************************************** MVC MGB_ID,=F'1' Message with XREFTEXT=001 MVC MGB_insert_cnt,=F'4' Four inserts *********************************************************************** * Set up the inserts * * Note that because the message uses the "available" value twice, * * we must provide it twice as inserts. Similarly, the message uses * * the "limit" value twice so we provide it twice as inserts. * *********************************************************************** Push Using Using MGB_MsgInsertD,Insert1 MVC MGB_MsgILen,=AL2(L'Avail2) MVC MGB_MsgIVal(L'Avail2),Avail2 Pop Using Push Using Using MGB_MsgInsertD,Insert2 MVC MGB_MsgILen,=AL2(L'Avail2) MVC MGB_MsgIVal(L'Avail2),Avail2 Pop Using Push Using Using MGB_MsgInsertD,Insert3 MVC MGB_MsgILen,=AL2(L'Parm_Limit) MVC MGB_MsgIVal(L'Parm_Limit),Parm_Limit Pop Using Push Using Using MGB_MsgInsertD,Insert4 MVC MGB_MsgILen,=AL2(L'Parm_Limit) MVC MGB_MsgIVal(L'Parm_Limit),Parm_Limit Pop Using *********************************************************************** * Issue HZSFMSG to write the message * *********************************************************************** HZSFMSG REQUEST=CHECKMSG,MGBADDR=Addr_Of_MGB, * MF=(E,HZSFMSG_List) J EndMainline *********************************************************************** * Assuming the code above did not detect an exception situation, * * Write "all is OK" message * *********************************************************************** One_Time_No_Exception DS 0H MVC MGB_ID,=F'4' Message with XREFTEXT=004 MVC MGB_insert_cnt,=F'0' No inserts. HZSFMSG REQUEST=CHECKMSG,MGBADDR=Addr_Of_MGB, * MF=(E,HZSFMSG_List) J EndMainline *********************************************************************** * End of Check Function * *********************************************************************** *********************************************************************** * Look for Cleanup function * *********************************************************************** One_Time_Not_Check DS 0H CLC PQE_Function_Code,=A(PQE_Function_Code_Cleanup) JNE One_Time_Not_Cleanup *********************************************************************** * Put code here for Cleanup processing for HZS_Sample_One_Time * *********************************************************************** * 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 One_Time_DifferentTask ICM R1,B'1111',TransientResourceAddr JZ One_Time_Transient_No_Free FREEMAIN RU,SP=229,LV=4096,A=(1) One_Time_Transient_No_Free DS 0H One_Time_DifferentTask DS 0H J EndMainline *********************************************************************** * End of Cleanup Function * *********************************************************************** *********************************************************************** * Look for Delete function * *********************************************************************** One_Time_Not_Cleanup DS 0H CLC PQE_Function_Code,=A(PQE_Function_Code_Delete) JNE One_Time_Not_Delete *********************************************************************** * Put code here for Delete processing for HZS_Sample_One_Time * * Release life-of-the-check resources that were obtained * *********************************************************************** ICM R1,B'1111',LifeOfCheckResourceAddr JZ One_Time_No_Free FREEMAIN RU,SP=251,LV=4096,A=(1) One_Time_No_Free DS 0H J EndMainline *********************************************************************** * End of Delete function * *********************************************************************** *********************************************************************** * We will never get here, but if we did, we would do nothing * *********************************************************************** One_Time_Not_Delete DS 0H J EndMainline Not_Sample_One_Time DS 0H CLC PQE_Entry_Code,=A(Entry_Code_HZS_Sample_Interval) JNE Not_Sample_Interval *********************************************************************** * Process HZS_Sample_Interval * *********************************************************************** *********************************************************************** * Put code here for HZS_Sample_Interval, * * analogous to HZS_Sample_One_Time * *********************************************************************** J EndMainline Not_Sample_Interval DS 0H * *********************************************************************** * Put code here if you want to account for an unexpected entry code * *********************************************************************** * 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 Type1 DC C'Normal ' Type2 DC C'Special' LTORG literals * 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 Packed DS D Workarea for PACK and CVB Return_Addr DS A Addr_Of_MGB DS A * DynareaToClear EQU * Flags DS X ParameterError EQU X'80' Parameter error detected Avail1 DS F InUse1 DS F Avail2 DS F InUse2 DS F DynareaToClear_Len EQU *-DynareaToClear * Insert1 DS CL(L'MGB_MsgInsertD_Header+Insert1Len) Area * for Insert1 Insert1Len EQU 16 Max Insert1 length is 16 Insert2 DS CL(L'MGB_MsgInsertD_Header+Insert2Len) Area * for Insert2 Insert2Len EQU 4 Max Insert2 length is 4 Insert3 DS CL(L'MGB_MsgInsertD_Header+Insert3Len) Area * for Insert3 Insert3Len EQU 4 Max Insert3 length is 4 Insert4 DS CL(L'MGB_MsgInsertD_Header+Insert4Len) Area * for Insert4 Insert4Len EQU 4 Max Insert4 length is 4 AreaForMGB DS CL(L'MGB_Insert_Structure_Header+(MaxInserts-1)*L'* MGB_Inserts) MaxInserts EQU 4 Maximum number of inserts needed* by any message in HZSSMSGT that * this check might issue. If any * message is subsequently defined * with more inserts, change this * equate to match HZSFMSG MF=(L,HZSFMSG_List) Area for HZSFMSG parm list 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 Parm_Limit DS F The parameter value 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 HZSSCHKR