Rational Developer for System z, Version 7.6

Debugging CICS programs

This topic describes tasks you can do while debugging CICS® programs, and describes some restrictions.

Before you can debug your programs under CICS, verify that you have completed the following tasks:

Displaying the contents of channels and containers

You can display the contents of CICS channels by using the DESCRIBE CHANNEL command and the contents of a container by using the LIST CONTAINER command.

The section "Enhanced inter-program data transfer: channels as modern-day COMMAREAs" in the CICS Application Programming Guide describes the benefits of containers and channels and how to use them in your programs.

To display a list of containers in the current channel, enter the command DESCRIBE CHANNEL. To display a list of containers in another channel, enter the command DESCRIBE CHANNEL channel_name, where channel_name is the name of a specific channel. In either case, Debug Tool displays a list similar to the following list:

 COBOL    LOCATION: ZCONPRGA :> 274.1                                           
 Command ===>                                                   Scroll ===> PAGE
 MONITOR -+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 2
 ******************************* TOP OF MONITOR ********************************
                                   ----+----1----+----2----+----3----+----4---- 
 0001  1 ********** AUTOMONITOR **********                                      
 0002    01 DFHC0160               'PrgA-ChanB-ContC'                           
 ****************************** BOTTOM OF MONITOR ******************************
                                                                                
 SOURCE: ZCONPRGA -1----+----2----+----3----+----4----+----5--- LINE: 272 OF 307
      272       *              FLENGTH(LENGTH OF PrgA-ChanB-XXXXX)             .
      273       *              END-EXEC                                        .
      274            Move 'PrgA-ChanB-ContC' to dfhc0160                       .
      275            Move 'PrgA-CHANB' to dfhc0161                             .
      276            Call 'DFHEI1' using by content x'341670000720000002000000 .
      277       -    '00f0f0f0f5f3404040' by content x'0000' by reference      .
      278            PrgA-ChanB-XXXXX by reference dfhc0160 by content LENGTH  .
      279            PrgA-ChanB-XXXXX by content x'0000' by content x'0000' by .
      280            content x'0000' by content x'0000' by content x'0000' by  .
      281            content x'0000' by content x'0000' by content x'0000' by  .
      282            content x'0000' by content x'0000' by content x'0000' by  .
      283            content x'0000' by content x'0000' by content x'0000' by  .
 LOG 0----+----1----+----2----+----3----+----4----+----5----+-- LINE: 147 OF 289
 0147  DESCRIBE CHANNEL * ;                                                     
 0148 CHANNEL                 PrgA-ChanB                                        
 0149 CONTAINER NAME                  SIZE                                      
 0150 ------------------------------------                                      
 0151 PrgA-ChanB-ContC                  21                                      
 0152 PrgA-ChanB-ContB                  21                                      
 0153 PrgA-ChanB-ContA                  21                                      
 0154 CHANNEL                 PRGA-CHANA                                        
 0155 CONTAINER NAME                  SIZE                                      
 0156 ------------------------------------                                      
 0157 PRGA-CHANA-CONTC                  21                                      
 PF  1:?          2:STEP       3:QUIT       4:LIST       5:FIND       6:AT/CLEAR
 PF  7:UP         8:DOWN       9:GO        10:ZOOM      11:ZOOM LOG  12:RETRIEVE

To display the contents of a container in the current channel, enter the command LIST CONTAINER container_name, where container_name is the name of a particular channel. To display the contents of a container in another channel, enter the command LIST CONTAINER channel_name container_name, where channel_name is the name of another channel. In either case, Debug Tool displays the contents of the container in a format similar to the following diagram:

 COBOL    LOCATION: ZCONPRGA :> 211.1                                           
 Command ===>                                                   Scroll ===> PAGE
 MONITOR -+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 2
 ******************************* TOP OF MONITOR ********************************
                                   ----+----1----+----2----+----3----+----4---- 
 0001  1 ********** AUTOMONITOR **********                                      
 0002    01 DFHC0160               'PRGA-CHANA-CONTC'                           
 ****************************** BOTTOM OF MONITOR ******************************
                                                                                
 SOURCE: ZCONPRGA -1----+----2----+----3----+----4----+----5--- LINE: 209 OF 307
      209       *              FLENGTH(LENGTH OF PrgA-ChanB-ContA)             .
      210       *              END-EXEC                                        .
      211            Move 'PrgA-ChanB-ContA' to dfhc0160                       .
      212            Move 'PrgA-ChanB' to dfhc0161                             .
      213            Call 'DFHEI1' using by content x'341670000720000002000000 .
      214       -    '00f0f0f0f3f5404040' by content x'0000' by reference      .
      215            PrgA-ChanB-ContA by reference dfhc0160 by content LENGTH  .
      216            PrgA-ChanB-ContA by content x'0000' by content x'0000' by .
      217            content x'0000' by content x'0000' by content x'0000' by  .
      218            content x'0000' by content x'0000' by content x'0000' by  .
      219            content x'0000' by content x'0000' by content x'0000' by  .
      220            content x'0000' by content x'0000' by content x'0000' by  .
 LOG 0----+----1----+----2----+----3----+----4----+----5----+---- LINE: 15 OF 25
 0015  STEP ;                                                                   
 0016  DESCRIBE CHANNEL * ;                                                     
 0017 CHANNEL                 PRGA-CHANA                                        
 0018 CONTAINER NAME                  SIZE                                      
 0019 ------------------------------------                                      
 0020 PRGA-CHANA-CONTC                  21                                      
 0021 PRGA-CHANA-CONTB                  21                                      
 0022 PRGA-CHANA-CONTA                  21                                      
 0023  LIST CONTAINER PRGA-CHANA PRGA-CHANA-CONTC ;                             
 0024 000C7F78  D7D9C7C1 60C3C8C1 D5C160C3 D6D5E3C3   *PRGA-CHANA-CONTC*        
 0025 000C7F88  60C4C1E3 C1                           *-DATA           *        
 PF  1:?          2:STEP       3:QUIT       4:LIST       5:FIND       6:AT/CLEAR
 PF  7:UP         8:DOWN       9:GO        10:ZOOM      11:ZOOM LOG  12:RETRIEVE

Refer to the following topics for more information related to the material discussed in this topic.

Controlling pattern-match breakpoints with the DISABLE and ENABLE commands

This topic describes how you can use the DISABLE and ENABLE commands to control pattern-match breakpoints. A pattern-match breakpoint is a breakpoint that is identified by the name, or part of the name, of a program or compile unit specified in a DTCN or CADP profile.

The DISABLE command works with the debugging profile that started the current debugging session to prevent programs from being debugged. When you enter the DISABLE command, you specify the name, or part of the name, of a program or compile unit that you do not want to debug. When Debug Tool finds a program or compile unit whose name matches the name or part of the name (a pattern) that you specified, Debug Tool does not debug that program. When you enter the ENABLE command, you specify the pattern (the full name or part of a name of a program or compile unit) that you want to debug. The pattern must match the name of a program or compile unit that you specified in a previously entered DISABLE command.

Before you begin, verify that you know which debugging profile started Debug Tool (DTCN or CADP) and the names you specified in the Program Id field (for DTCN) or the Program field, Compile Unit field, or both (for CADP).

To use the DISABLE command to prevent Debug Tool from debugging a program, do the following steps:

  1. If you don't remember what programs you might have disabled, enter the command LIST DTCN or LIST CADP. This command lists the programs you have already disabled. This step reminds you of the names of programs or compile units you already disabled.
  2. If you are running with a CADP profile, enter the command DISABLE CADP PROGRAM program_name CU compile_unit_name. program_name is the name of the program, or it matches the pattern of the name of a program, that you specified in the Program field and it is the program that you do not want to debug. compile_unit_name is the name of the compile unit, or it matches the pattern of the name of a compile unit, that you specified in the Compile field and it is the compile unit that you do not want to debug. You can specify a program or a compile unit or both.

    For example, if you have the following circumstances, enter the command DISABLE CADP PROGRAM ABD2 to prevent Debug Tool from debugging the program ABD2:

  3. If you are running with a DTCN profile, enter the command DISABLE DTCN PROGRAM program_name, where program_name is the name of the program, or it matches the pattern of the name of a program, that you specified in the Program Id field and it is the program that you do not want to debug.

    For example, if you have the following circumstances, enter the command DISABLE DTCN PROGRAM STAR2 to prevent Debug Tool from debugging the program STAR2:

To use the ENABLE command to allow a previously disabled program to be debugged, do the following steps:

  1. If you don't remember the exact name of the disabled program or compile unit, enter the command LIST DTCN or LIST CADP. This command lists the programs you have disabled. Write down the name of the program, compile unit, or both that you want to debug.
  2. If you are running with a CADP profile, enter the command ENABLE CADP PROGRAM program_name CU compile_unit_name, where program_name is the name of the program and compile_unit_name is the name of the compile unit that you wrote down from step 1. If you only need to specify a program name, you do not have to type in the CU compile_unit_name portion of the command. If you only need to specify a compile unit name, you do not have to type in the PROGRAM program_name portion of the command.
  3. If you are running with a DTCN profile, enter the command ENABLE DTCN PROGRAM program_name, where program_name is the name of the program you noted in step 1.

Refer to the following topics for more information related to the material discussed in this topic.

Preventing Debug Tool from stopping at EXEC CICS RETURN

Debug Tool stops at EXEC CICS RETURN and displays the following message:

CEE0199W The termination of a thread was signaled due to a STOP statement.

To prevent Debug Tool from stopping at every EXEC CICS RETURN statement in your application and suppress this message, set the TEST level to ERROR by using the SET TEST ERROR command.

Early detection of CICS storage violations

CICS can detect various types of storage violations. The CICS Problem Determination Guide describes the types of storage violations that CICS can detect and when CICS detects them automatically. You can request that Debug Tool detect one type of storage violation (whether the storage check zone of a user-storage element has been overlaid). You can make this request at any time.

To instruct Debug Tool to check for storage violations, enter the command CHKSTGV. Debug Tool checks the task that you are debugging for storage violations.

You can instruct Debug Tool to check for storage violations more frequently by including the command as part of a breakpoint. For example, the following commands check for a storage violation at each statement in a COBOL program and causes Debug Tool to stop if a violation is detected in the current procedure:

AT STATEMENT *
  PERFORM
    CHKSTGV ;
    IF %RC = 0 THEN
      GO ;
    END-IF ;
  END-PERFORM ;

If you plan on running a check at every statement, run it on as few statements as possible because the check causes overhead that can affect performance.

Refer to the following topics for more information related to the material discussed in this topic.

Saving settings while debugging a pseudo-conversational CICS program

If you change the Debug Tool display settings (for example, color settings) while you debug a pseudo-conversational CICS program, Debug Tool might restore the default settings. To ensure that your changes remain in effect every time your program starts Debug Tool, store your display settings in the preferences file or the commands file.

Saving and restoring breakpoints and monitor specifications for CICS programs

When you set any of the following specifications to AUTO, these specifications are used to control the saving and restoring of breakpoints and LOADDEBUGDATA specifications between Debug Tool settings:

You set switches by using the SET command. The SAVE BPS and SAVE MONITORS switches enable the saving of breakpoints and monitor specifications between debugging sessions. The RESTORE BPS and RESTORE MONITORS switches control the restoring of breakpoints and monitor specifications at the start of subsequent debugging sessions. Setting these switches to AUTO enables the automatic saving and restoring of this information. You must also enable the SAVE SETTING AUTO switch so that these settings are in effect at the start of subsequent debugging sessions.

While you run in CICS, consider the following requirements:

When you activate a DTCN profile for a full-screen debugging session and SAVE BPS, SAVE MONITORS, RESTORE BPS, and RESTORE MONITORS all specify NOAUTO, Debug Tool saves most of the breakpoint and LOADDEBUGDATA information for that session into the profile. When the DTCN profile is deleted, the breakpoint and LOADDEBUGDATA information is deleted.

See Performance considerations in multi-enclave environments for information about performance savings and restoring settings, breakpoints, and monitors under CICS.

Refer to the following topics for more information related to the material discussed in this topic.

Restrictions when debugging under CICS

The following restrictions apply when debugging programs with the Debug Tool in a CICS environment.

Accessing CICS resources during a debugging session

You can gain access to CICS temporary storage and transient data queues during your debugging session by using the CALL %CEBR command. You can do all the functions you can currently do while in the CICS-supplied CEBR transaction. For access to general CICS resources (for example, information about the CICS system you are debugging on or opening and reading a VSAM file) you can use the CALL %CECI command. This command gives control to the CICS-supplied CECI transaction. Press PF3 from inside CEBR or CECI to return to the debug session. For more information about CEBR and CECI, see CICS Supplied Transactions.

Accessing CICS storage before or after a debugging session

You can uses the DTST transaction to display and modify CICS storage. See Appendix F. Displaying and modifying CICS storage with DTST for more information.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)