Finding where a program check occurred

When a transaction abends with code ASRA or ASRD and a system dump of the program check has been produced, the first thing you need to do is to find out where the program check occurred. CICS® attempts to establish this for you.

1. Find the offset of the program check within the program load module.
   The offset indicates the point in the program at which the program check occurred. Note that the offset is derived from the PSW next sequential instruction address and so may indicate the instruction after the one that failed.
   • If the offset is not X'FFFFFFFF', go to What type of program check occurred?.
   • If the offset is X'FFFFFFFF', CICS was unable to establish the location of the program check. In this situation, you have to use the PSW to obtain the next sequential instruction address. To locate the PSW and the registers for the program check. Continue with step 2.
2. Locate the PSW.
   The PSW can be found in the following places:

   • The TACB for the abend
   • At the head of the formatted transaction dump
   • Within the kernel error data block traced by exception trace point IDs AP 0781 or AP 0783
   1. Enter option 0 from the IPCS primary option menu to display the IPCS default values panel.

      IPCS PRIMARY OPTION MENU - z/OS 
      OPTION  ===> 0                                            
                                                               
         0  DEFAULTS    - Specify default dump and options     
         1  BROWSE      - Browse dump data set                 
         2  ANALYSIS    - Analyze dump contents                
         3  UTILITY     - Perform utility functions            
         4  INVENTORY   - Inventory of problem data            
         5  SUBMIT      - Submit problem analysis job to batch 
         6  COMMAND     - Enter subcommand, CLIST or REXX exec 

   2. Enter DSNAME('xxxxx.xxxxx.xxxx') to the right of Source where xxxxx.xxxxx.xxxx is the dump dataset name. Then, enter Enter and F3 to return to the IPCS primary option menu.

      Source  ==> DSNAME('ONTOP.CICSPD.LABDUMPS.BEAR0C1.DUMP730')

   3. Enter option 6 from the IPCS primary option menu to display the IPCS Subcommand Entry panel.

      IPCS PRIMARY OPTION MENU - z/OS 
      OPTION  ===> 6                                            
                                                               
         0  DEFAULTS    - Specify default dump and options     
         1  BROWSE      - Browse dump data set                 
         2  ANALYSIS    - Analyze dump contents                
         3  UTILITY     - Perform utility functions            
         4  INVENTORY   - Inventory of problem data            
         5  SUBMIT      - Submit problem analysis job to batch 
         6  COMMAND     - Enter subcommand, CLIST or REXX exec 

   4. Enter IPCS command verbx dfhpdxxx 'ke' where xxx is the version and release for the CICS dump (for example, 730 for CICS TS 5.6).

      This command formats the dump and displays to the Kernel Domain KE_TASK Summary.

      ------------------------- IPCS Subcommand Entry -----------------------------
      Enter a free-form IPCS subcommand or a CLIST or REXX exec invocation below:  
                                                                                   
      ===> verbx dfhpd730 'ke'

      The following table lists CICS TS versions and corresponding product levels for your reference.

      Table 1. CICS TS versions and corresponding product levels

      CICS TS Version	Level
      CICS TS 5.6	730
      CICS TS 5.5	720
      CICS TS 5.4	710
      CICS TS 5.3	700
      CICS TS 5.2	690
      CICS TS 5.1	680
      CICS TS 4.2	670

   5. Enter f *YES* to get to the running task that had the program check.
      There might be more than one. In the example below, there is one task with *YES* under ERROR (KE_NUM 0157).

      
      ===KE: Kernel Domain KE_TASK Summary
      KE_NUM  KE_TASK   STATUS       TCA_ADDR  TRAN_#  TRANSID  DS_TASK   KE_KTCB   ERROR   TCB      CURRENT_PSW
      0001    22FEA000  KTCB Step    00000000                   00000000  2302E038         AFF208  078D1000_A2E702A4
      0002    22FEA630  KTCB QR      00000000                   23017F00  230311B8         AE68F8  070C4000_818481CC
      0003    22FE9000  KTCB RO      00000000                   23026E00  23030138         AE6B28  078D1000_A2E1857E
      0157    24b15100  ***Running** 232D3100  00383   ABCD     5B6A6C80  230311B8  *YES*  AE68F8  070C4000_818481CC
      

   6. Make a note of the KE_NUM, TCA_ADDR and the TRANSID of the tasks in error.
   7. Enter f table to find the KE Domain Error Table Summary.
      This is a summary containing the last 50 abends in the region since it was started. Generally, you are interested in the most recent errors when you are looking at the summary (the last entries of the table) for your running task. If there are multiple program checks for your task, focus on the first program check because the other program checks are probably a result of the first program check.

      
      ===KE: Kernel Domain Error Table Summary
      ERR_NUM    ERR_TIME   KE_NUM   ERROR TYPE             ERR_CODE   MODULE   OFFSET
      =======    ========   ======   ==========             ========   ======   ======
      0000005B   14:19:59    0158    TRAN_ABEND_PERCOLATE   ---/AJ04   DFHPCP   00000696
      0000005C   14:19:59    0158    TRAN_ABEND_PERCOLATE   ---/AJ04   UNKNOWN  UNKNOWN
      0000005D   14:19:59    0158    TRAN_ABEND_PERCOLATE   ---/AJ04   DFHEPC   00000226
      0000005E   14:19:59    0157    PROGRAM_CHECK          0C4/AKEA   DFHYI730 000002F2
      

   8. Enter ip st sys on the command line to determine the local time and date that the dump was taken.
   9. Make a note of the ERR_NUM associated with the program check that has an ERR_TIME matching the time the dump was taken and a KE_NUM matching the KE_NUM found in the Kernel Domain KE_TASK Summary. If there is more than one program check for the same ERR_TIME and KE_NUM, focus on the first program check. The other program checks are probably a result of the first program check.
   10. Enter f 'Number: xxxxxxxx' where xxxxxxxx is the ERR_NUM of the program check you have decided to focus on.
       This operation displays the entry in the KE Domain Error table for the error number you specify.

       
   11. Compare the addresses at offset X'4C' and offset X'134' in the KERNEL ERROR DATA.

       The address at offset X'4C' is the fourth word of the CICS PSW, and the address at offset X'134' is the fourth word of the z/OS® PSW. If the addresses are different, use the z/OS PSW and registers. Otherwise, use the CICS PSW and registers.

       The CICS PSW starts at offset x'40' and is 4 words in length. The CICS registers, 0 through 15, start at offset X'68' and each register is 2 words in length.

       The z/OS PSW starts at offset x'128' and is 4 words in length. The z/OS registers, 0 through 15, start at offset x'150' and each register is 2 words in length.

   12. Use F8 to scroll down to see the formatted CICS PSW and registers.

       IPCS CICS VERBX will format the z/OS PSW and registers if the z/OS PSW is different from the CICS PSW. If the PSWs are the same, CICS VERBX does not duplicate the information.

       
       CICS Registers and PSW
         PSW:  079D1000 80000000 00000000 27ED52F2    Instruction Length:  4     Interrupt Code:   04
         Exception Address:  00000000_00000000
         Execution key at Program Check/Abend:  9     Addressing Mode:  31
         Space at Program Check/Abend:  Basespace
         Breaking Event Address:  00000000_27ED52CC - offset 000002CC in module DFYI730
         64-BIT REGISTERS 0-15
         GPR 0-3  00000000_24F3A890  00000000_24F30050  00000000_24F3BB08  00000000_00000000
         GPR 4-7  00000000_27ED5060  00000000_24AEE7C0  00000000_24AEE778  00000000_00000000
         GPR 8-B  00000000_24F339F0  00000000_24F3B938  00000000_27ED5130  00000000_27ED5264
         GPR C-F  00000000_27ED5124  00000000_24F3A748  00000000_24F3BA8C  00000000_00000000
       

       The Breaking Event Address, formatted from the Breaking Event Address Register (BEAR), gives you the address of the last successful branch before the program check, and can be very useful in diagnosing wild-branch types of problems that typically result in 0C1 or 0C4 abends, if available. When the Kernel domain is formatted in a CICS dump, the BEAR data is formatted in the Kernel error information with the title Breaking Event Address. The CICS dump formatter attempts to identify the module and offset of the BEAR, and attempts to format the data at the PSW, called PSWDATA, and the data at the BEAR, called BEARDATA.

       CICS VERBX attempts to determine the failing module from the PSW and displays the module name and offset if possible. The offline dump formatter uses more information than the original failure message, and so often, when the original failure message is unhelpful (offset FFFFFFFF in module) the dump formatter is more informative.

       By scrolling down from the panel, you can often get the failing module printed from the start to the interrupt address plus 256 bytes. CICS VERBX also assumes that the values in the general registers are addresses and prints the storage before and after these addresses, using 64-bit, 31-bit, and 24-bit addresses.

3. Knowing the PSW, determine the module in which the failure is occurring:
   1. Enter option 1 from the IPCS primary option menu to browse the dump data set.
   2. Enter the fourth word of the PSW into the Pointer Address field.
   3. If the storage displays, enter F7 to scroll up until you see an eye catcher for a load module. Load module names are usually followed by a date and time stamp. Calculate an offset within the module by subtracting the load point from the PSW address. This is the offset where the abend occurred.
   4. If storage not available displays, enter ip where nnnnnnnn where nnnnnnnn is the fourth word of the PSW. If the module has been loaded by the operating system from the LPA or Nucleus, this will display the module name and the offset within the module.

DFHAP0001 DFHAPDM 0C4

4. Note down the start and end addresses of the different program areas in the transaction dump.
   Is the next sequential instruction address from the PSW in any of the programs? If so, then that is the program in which the interrupt occurred. Use the procedure described in Locating the last command or statement to identify the last command executed.
   If the address is outside all of the programs, one of two things is likely to have happened.

   • The program in which the program check occurred was running on your behalf (for example, VSAM or DL/I), but not under CICS control. This is usually caused by incorrect parameters being passed to the program, or parameters being passed in the wrong sequence. These are usually caught and flagged with an appropriate return code, but certain combinations can cause problems.
   • Your program might have taken a wild branch into some other piece of storage. If the address from the PSW ends in an odd number, this is probably the case, as valid instructions are always on an even address. The address could be within the CICS address space, or anywhere else in virtual storage.

     Often, a wild branch is taken to address zero, because the register that should contain the branch address is set to zero. The PSW usually contains address X'00000004' after such a branch has occurred.

5. Check the register contents to see whether any of them contains the next sequential instruction address from the PSW, or something close to it.
   This might help you find out how you got to the wrong address.

   If the PSW does point to an instruction in one of your programs, the next thing to consider is the type of program check that occurred. Otherwise, turn directly to Analyzing the problem further.