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:
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.
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:
For example, if you have the following circumstances, enter the command DISABLE CADP PROGRAM ABD2 to prevent Debug Tool from debugging the program ABD2:
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:
Refer to the following topics for more information related to the material discussed in this topic.
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.
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.
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.
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.
The following restrictions apply when debugging programs with the Debug Tool in a CICS environment.
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.
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.