To prepare a CICS® program for debugging, you must do the following tasks:
If you are using versions of CICS earlier than CICS Transaction Server for z/OS® Version 3 Release 1, you can prepare non-Language Environment COBOL programs for debugging, as described in Preparing a non-Language Environment COBOL program.
Debug Tool provides an Language Environment CEEBXITA assembler exit called EQADCCXT to help you activate, by using the DTCN transaction, a debugging session under CICS. You do not need to use this exit if you are running either of the following options:
When you use EQADCCXT, be aware of the following conditions:
After you link-edit your program, use the DTCN transaction to create a profile that specifies the combination of resource IDs that you want to debug. See Creating and storing a DTCN profile.
The DTCN transaction stores debugging profiles in a repository. The repository can be either a CICS temporary storage queue or a VSAM file. The following list describes the differences between using a CICS temporary storage queue or a VSAM file:
Debug Tool determines which storage method is used based on the presence of a debugging profile VSAM file. If Debug Tool finds a debugging profile VSAM file allocated to the CICS region, it assumes you are using a VSAM file as the repository. If it doesn't find a debugging profile VSAM file, it assumes you are using a CICS temporary storage queue as the repository. See the Debug Tool Customization Guide or contact your system programmer for more information about how the VSAM files are created and managed.
If the repository is a temporary storage queue, each profile is retained in the repository until one of the following events occurs:
If the repository is a VSAM file, each profile is retained until it is explicitly deleted. The DTCN transaction uses the user ID to identify a profile. Therefore, each user ID can have only one profile stored in the VSAM file.
Profiles are either active or inactive. If a profile is active, DTCN tries to match it with a transaction that uses the resources specified in the profile. DTCN does not try to match a transaction with an inactive profile. To make a profile active or inactive, use the Debug Tool CICS Control - Primary Menu panel (the main DTCN panel) to make the profile active or inactive, then save it. If the repository is a VSAM file, when DTCN detects that the terminal is disconnected, it makes the profile inactive.
To create and store a DTCN profile:
DTCN Debug Tool CICS Control - Primary Menu S07CICPD
* VSAM storage method * 1
Select the combination of resources to debug (see Help for more information)
Terminal Id ==> 0090
Transaction Id ==>
Program Id(s) ==> ==> ==> ==>
==> ==> ==> ==>
User Id ==> CICSUSER
NetName ==>
IP Name/Address ==>
Select type and ID of debug display device
Session Type ==> MFI MFI, TCP
Port Number ==> TCP Port
Display Id ==> 0090
Generated String: TEST(ALL,'*',PROMPT,'MFI%0090:*')
Repository String: No string currently saved in repository
Profile Status: No Profile Saved. Press PF4 to save current settings.
PF1=HELP 2=GHELP 3=EXIT 4=SAVE 5=ACT/INACT 6=DEL 7=SHOW 8=ADV 9=OPT 10=CUR TRM
Line 1 displays a message to indicate that DTCN will store the profile in a temporary storage queue or in a VSAM file. Some of the entry fields are filled in with values from one of the following sources:
If you do not want to change these fields, you can skip the next two steps and proceed to step 4. If you want to change the settings on this panel, continue to the next step.
DTCN Debug Tool CICS Control - Menu 2 S07CICPD Select Debug Tool options Test Option ==> TEST Test/Notest Test Level ==> ALL All/Error/None Commands File ==> * Prompt Level ==> PROMPT Preference File ==> * Any other valid Language Environment options ==> PF1=HELP 2=GHELP 3=RETURN
Some of the entry fields are filled in with default values that start Debug Tool, in full-screen mode, for tasks running on this terminal. If you do not want to change the defaults, you can skip the rest of this step and proceed to step 5. If you want to change the settings on this panel, continue with this step.
DTCN Debug Tool CICS Control - Advanced Options S07CICPD
Select advanced program interruption criteria:
Commarea Offset ==> 0
Commarea Data ==>
Container Name ==>
Container Offset ==> 0
Container Data ==>
URM Debugging ==> NO
Default offset and data representation is decimal/character.
See Help for more information.
PF1=HELP 2=GHELP 3=RETURN You
can specify data in the COMMAREA or containers, but not both. You
can also use this panel to indicate whether you want to debug user
replaceable modules (URMs). For more information about these fields,
do one of the following tasks:
Now, any tasks that run in the CICS system and match the resource IDs that you specified in the previous steps will start Debug Tool.
Refer to the following topics for more information related to the material discussed in this topic.
To display all of the active DTCN profiles in the CICS region, do the following steps:
DTCN Debug Tool CICS Control - All Sessions S07CICPD
Overtype "_" with "D" to delete, "A" to activate, "I" to inactivate a profile.
Owner Sta Term Tran User Id NetName Applid Display Id
_ 0090 ACT 0090 TRN1 USER1 0072 S07CICPD 0090
Program(s) CIC9060 CS9060 CBLAC?3 *9361
________ ________ ________ ________
IP Name/Addr ______________________________________________
The column titles are defined below:
DTCN also reads the Language Environment NOTEST option supplied to the CICS region in CEECOPT or CEEROPT. You can supply suboptions, such as the name of a preferences file, with the NOTEST option to supply additional defaults to DTCN.
Refer to the following topics for more information related to the material discussed in this topic.
This topic describes the fields that are displayed on the DTCN Primary Menu screen.
The following list describes the resources you can specify to help identify the program or transaction that you want to debug:
To start Debug Tool at the desired program that the transaction runs, specify the program name in the Program Id(s) field. If the DTCNFORCETRANID option in EQAOPTS is set to YES, this field must be specified. See Debug Tool Customization Guide for a description of these options.
If Debug Tool was started by another program before the EXEC CICS LOAD command that starts this non-Language Environment assembler program, you need to enter one of the following commands so that Debug Tool gains control of this program:
When you specify a program ID for C/C++ and Enterprise PL/I programs (languages that use a fully qualified data set name as the compile unit name), you must specify the correct part of the compile unit name in the program ID field. Use the following rules to determine which part of the compile unit name you need to specify:
Specifying a CICS program in the Program Id(s) field is similar to setting a breakpoint by using the AT ENTRY command and Debug Tool stops each time you enter this program.
If Debug Tool is already running and it cannot find the separate debug file, then Debug Tool does not stop at the CICS program specified in the Program Id(s) field. Use the AT APPEARANCE or AT ENTRY command to stop at this CICS program.
If the DTCNFORCEPROGID option in EQAOPTS is set to YES, this field must be specified. See Debug Tool Customization Guide for a description of these options.
The following list describes the fields that you can use to indicate which type of debugging session you want to run.
If you entered TCP in the Session Type field, determine the IP address or host name of the workstation that is running the remote debugger. Change the value in the Display Id field by doing the following steps:
If you entered MFI in the Session Type field, DTCN fills in the Display Id field according to the following rules:
You can use one of the following terminal modes to display Debug Tool on a 3270 terminal:
The following list describes the fields that you can use to specify the TEST runtime options, other runtime options, commands file, and preferences file that you want to use for the debugging session:
The following list describes the fields that you can use to specify the data passed through COMMAREA or containers that can help identify transactions and programs that you want to debug:
CADP is an interactive transaction supplied by CICS Transaction Server for z/OS Version 2 Release 3, or later. CADP helps you maintain persistent debugging profiles. These profiles contain a pattern of CICS resource names that identify a task that you want to debug. When CICS programs are started, CICS tries to match the executing resources to find a profile whose resources match those that are specified in a CADP profile. During this pattern matching, CICS selects the best matching profile, which is the one with greatest number of resource IDs that match the active task.
Before using CADP, verify that you have done the following tasks:
See CICS Supplied Transactions for instructions on how to use the CADP utility transaction. If you are going to debug user-replaceable modules (URMs), specify ENVAR("INCLUDEURM=YES") in the Other Language Environment Options field.
Refer to the following topics for more information related to the material discussed in this topic.
You can start Debug Tool to debug a program that does not run in the Language Environment run time by using the existing debug profile maintenance transactions DTCN and CADP. You must use DTCN with versions of CICS prior to CICS Transaction Server for z/OS Version 2 Release 3.
To debug CICS non-Language Environment programs, the Debug Tool non-Language Environment Exits must have been previously started.
To debug non-Language Environment assembler programs or non-Language Environment COBOL programs that run under CICS, you must start the required Debug Tool global user exits before you start the programs. Debug Tool provides the following global user exits to help you debug non-Language Environment applications: XPCFTCH, XEIIN, XEIOUT, XPCTA, and XPCHAIR. The exits can be started by using either the DTCX transaction (provided by Debug Tool), or using a PLTPI program that runs during CICS region startup. DTCXXO activates the non-Language Environment Exits for Debug Tool in CICS. DTCXXF inactivates the non-Language Environment Exits for Debug Tool in CICS.
Refer to the following topics for more information related to the material discussed in this topic.
When you define your debugging profile using the DTCN Options Panel (PF9) or the CADP Create/Modify Debugging Profile Panel, you can pass a limited set of runtime options that will take effect during your debugging session when you debug programs that do not run in Language Environment. You can pass the following runtime optionss:
Refer to the following topics for more information related to the material discussed in this topic.