Debugging checks

Naturally, we hope you'll never need this section and that all your checks will run perfectly the very first time. However, if you do run into trouble, this section will help you debug your check routine and HZSADDCHECK exit routine.

Was my check added to the system? Use the F hzsproc,DISPLAY CHECK(checkowner,checkname) to display the check you're adding to the system. If your check shows up, it was successfully added to the system. If it does not show up, it was not added to the system.

You can also check the return code from the HZSADDCK invocation in your HZSADDCHECK exit routine (for local checks) or check routine (for remote checks). A return code greater than 4 often indicates that there was a problem adding the check to the system. See HZSADDCK macro — HZS add a check.

Turn on debug mode: Running in debug mode can help you debug your check, because in debug mode:

Each message line is prefaced by a message ID, which can be helpful in pinpointing the problem. For example, report messages are not prefaced by message IDs unless a check is running in debug mode.
Debug messages, which may contain information about the error, are issued only when the check is in debug mode.

You can turn on debug mode for a check that is not running properly using the DEBUG parameter in the MODIFY hzsproc command, in HZSPRMxx, or by overtyping the DEBUG field in SDSF to ON.

Create a recovery routine for your check routine if you need additional diagnostic data for your check routine. See Establishing a recovery routine for a check.

Debug HZSFMSG abends: If the system finds an error in a HZSFMSG macro call to issue a message, the system issues system abend X'290' with a unique reason code and creates a logrec error record. See the information for abend X'290' in z/OS MVS System Codes for a description of the abend reason codes.

If the abend is caused by an incorrect macro call, the system issues the following accompanying information:

Logrec error record. Use EREP to view logrec errors, see "Using EREP to Obtain Records from the Logrec Log Stream " in z/OS MVS Diagnosis: Tools and Service Aids.
A symptom dump written to the console and to the system log
A SYSMDUMP, if you add a SYSMDUMP DD statement to hzsproc, the IBM® Health Checker for z/OS® procedure.
Note that the contents and data set disposition of your SYSMDUMP depends on the DISP= option you use on the DD statement. See "Obtaining ABEND dumps" in z/OS MVS Diagnosis: Tools and Service Aids.
There may be additional diagnostic data in the register at time of the abend that can help with debugging. See ABEND Codes for the kinds of diagnostic data that may be available.
If your check routine has a recovery routine, the SDWA for the recovery routine will contain these registers in the SDWAGRSV field.

If the abend is caused by the system, the system issues an SVC dump.

Where is my check routine? I need to locate it for debugging. If you do not receive an abend for a problem, you can locate a local check routine and message table (to use in a SLIP trap, for example) using the DIAG parameter on the F hzsproc,DISPLAY command. For example, you can use the f hzsproc,display,check(IBMGRS,grs_mode),detail,diag command. Note the diagnostic information, including the location of the check routine and message table in the output example below:

HZS0201I 13.06.05 CHECK DETAIL     716                               
CHECK(IBMGRS,GRS_MODE)                                               
 STATE: ACTIVE(ENABLED)     GLOBAL  STATUS: SUCCESSFUL               
 EXITRTN: ISGHCADC                                                   
 LAST RAN: 07/06/2005 12:49    NEXT SCHEDULED: (NOT SCHEDULED)       
 INTERVAL: ONETIME              SEVERITY: LOW                        
 WTOTYPE: INFORMATIONAL                                              
 SYSTEM DESCCODE: 12                                                 
 DEFAULT PARAMETERS:       STAR                                      
 REASON FOR CHECK:  GRS should run in STAR mode to improve           
                    performance.                                     
 MODIFIED BY: N/A                                                    
 DEFAULT DATE: 20050105                                              
 DEBUG MODE: OFF                                                     
 INTERNAL DIAGNOSTICS -  CHECK TOKEN: 01020038.7FE9F000              
 ROUTINE: ISGHCGRS-7F2B4BC8  MSGTBL: ISGHCMSG-7F222120  FUNC: CLEANUP
 LAST CPU TIME: 0.041  MAX CPU TIME: 0.041

Where is my HZSADDCHECK exit routine? If you need to locate the address of your HZSADDCHECK exit routine for a local check, to set a SLIP trap, for example, use the display command following:

DISPLAY PROG,EXIT,EXITNAME=HZSADDCHECK_exit_routine,DIAG

The system issues message CSV464I displaying information about the exit, including the exit entry point address, the load point address of the exit routine module, and other diagnostic information for exit routine.

Using SLIP traps for debugging: If you need to set a SLIP trap for either your check routine or HZSADDCHECK exit routine, we suggest that you set a SLIP trap on any error event in the IBM Health Checker for z/OS address space instead of setting it on an abend X'290'. This will give you the information you need to handle both the X'290' abend and any other unexpected problem.

Use the two hints directly above this one to find the addresses of your check routine and HZSADDCHECK exit routine, for use in setting SLIP traps.