Rational Developer for System z, Version 7.6

Preparing a CICS program

To prepare a CICS® program for debugging, you must do the following tasks:

  1. Complete the program preparation tasks for assembler, C, C++, COBOL, or PL/I, as described in the following sections:

    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.

  2. Determine if your site uses CADP or DTCN debugging profiles and verify that your system has been configured to use the chosen debugging profile.
  3. Determine if you need to link edit EQADCCXT into your program by reviewing the instructions in Link-editing EQADCCXT into your program.
  4. Do one of the following tasks:

Link-editing EQADCCXT into your 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.

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:

  1. Log on to a CICS terminal and enter the transaction ID DTCN. The DTCN transaction displays the main DTCN screen, Debug Tool CICS Control - Primary Menu, shown below.
     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.

  2. Specify the combination of resource IDs that identify the transaction or program that you want to debug. For more information about these fields, do one of the following tasks:
  3. Specify the type of debugging session you want to run and the ID of the device that displays the debugging session. For more information about these fields, do one of the following tasks:
  4. Specify the TEST runtime options, other runtime options, commands file, and preferences file that you want to use for the debugging session by pressing PF9 to display the secondary options menu, which looks like the following example:
     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.

  5. Press PF3 to return to the main DTCN panel.
  6. If you want to use data passed through COMMAREA or containers to help identify transactions and programs that you want to debug, press PF8. The Advanced Options panel is displayed, which looks like the following example:
     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:
  7. Press PF3 to return to the main DTCN panel.
  8. Press PF4 to save the profile. DTCN performs data verification on the data that you entered in the DTCN panel. When DTCN discovers an error, it places the cursor in the erroneous field and displays a message. You can use context-sensitive help (PF1) to find what is wrong with the input.
  9. Press PF5 to change the status from active to inactive, or from inactive to active. A profile has three possible states:
    No profile saved
    A profile has not yet been created for this terminal.
    Active
    The profile is active for pattern matching.
    Inactive
    Pattern matching is skipped for this profile.
  10. After you save the profile in the repository, DTCN shows the saved TEST string in the display field Repository String. If you are satisfied with the saved profile, press PF3 to exit DTCN.

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.

Displaying a list of active DTCN profiles and managing DTCN profiles

To display all of the active DTCN profiles in the CICS region, do the following steps:

  1. If you have not started the DTCN transaction, Log on to a CICS terminal and enter the transaction ID DTCN. The DTCN transaction displays the main DTCN screen, Debug Tool CICS Control - Primary Menu.
  2. Press PF7. The Debug Tool CICS Control - All Sessions screen displays, shown below.
      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:

    Owner
    The ID of the terminal that created the profile by using DTCN.
    Sta
    Indicates if the profile is active (ACT) or inactive (INA).
    Term
    The value that was entered on the main DTCN screen in the Terminal Id field.
    Tran
    The value that was entered on the main DTCN screen in the Transaction Id field.
    User Id
    The value that was entered on the main DTCN screen in the User Id field.
    Netname
    The value the entered on the main DTCN screen in the Netname field.
    Applid
    The application identifier associated with this profile.
    Display Id
    Identifies the target destination for Debug Tool information.
    Program(s)
    The values that were entered on the main DTCN screen in the Program Ids field.
    IP Name/Addr
    The value that was entered on the main DTCN screen in the IP Name/Address field.

    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.

  3. To delete a profile, move your cursor to the underscore character (_) that is next to the profile you want to delete. Type in "D" and then press Enter.
  4. To make a profile inactive, move your cursor to the underscore character (_) that is next to the profile you want to make inactive. Type in "I" and then press Enter.
  5. To make a profile active, move your cursor to the underscore character (_) that is next to the profile you want to make active. Type in "A" and then press Enter.
  6. To leave this panel and return to the DTCN primary menu, press PF3.

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

Description of fields on the DTCN Primary Menu screen

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:

Terminal Id
Specify the CICS terminal identifier associated with the transaction you want to debug. By default, DTCN sets the ID by one of the following rules: If the DTCNFORCETERMID option in EQAOPTS is set to YES, you must specify a terminal identifier. See Debug Tool Customization Guide for a description of these options.
Transaction Id
Specify the CICS transaction to debug. If you specify a transaction ID without any other resource, Debug Tool is started every time any of the following situations occurs:

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.

Program Id(s)
Specify the program or programs that you want to debug. You can specify any of the following programs:

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.

User Id
Specify the user identifier associated with the transaction you want to debug. The following list can help you decide what to enter in this field: If the DTCNFORCEUSERID option in EQAOPTS is set to YES, you must specify a user identifier. See Debug Tool Customization Guide for a description of these options.
NetName
Specify the four character name of a CICS terminal or a CICS system that you want to use to run your debugging session. This name is used by VTAM® to identify the CICS terminal or system. If the DTCNFORCENETNAME option in EQAOPTS is set to YES, this field must be specified. See Debug Tool Customization Guide for a description of these options.
IP Name/Address
The client IP name or IP address that is associated with a CICS application. All IP names are treated as upper case. Wildcards (* and ?) are permitted. Debug Tool is invoked for every task that is started for that client. If the DTCNFORCEIP 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.

Session Type
Select one of the following options:
MFI
Indicates that Debug Tool initializes on a 3270 type of terminal.
TCP
Indicates that you want to interact with Debug Tool from your workstation using TCP/IP and a remote debugger.
Port Number
Specifies the TCP/IP port number that is listening for debug sessions on your workstation. By default, the following products use port 8001:
Display Id
Identifies the target destination for Debug Tool.

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:

  1. Place your cursor on the Display Id field
  2. Type in the IP address or host name of the workstation that is running the remote debugger
  3. To save the profile with this new value, press PF4.

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:

Description of fields on the DTCN Menu 2 screen

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:

Test Option
TEST/NOTEST specifies the conditions under which Debug Tool assumes control during the initialization of your application.
Test Level
ALL/ERROR/NONE specifies what conditions need to be met for Debug Tool to gain control.
Command File
A valid fully qualified data set name that specifies the primary commands file for this run.
Note:
Do not enclose the name of the data set in quotation marks (") or apostrophes (').
Prompt Level
Specifies whether Debug Tool is started at Language Environment initialization.
Preference File
A valid fully qualified data set name that specifies the preferences file to be used. Do not enclose the name of the data set in quotation marks (") or apostrophes (').
Any other valid Language Environment Options
You can change any Language Environment option that your site has defined as overrideable except the STACK option. For additional information about Language Environment options, see z/OS Language Environment Programming Reference or contact your CICS system programmer.

Description of fields on the DTCN Advanced Options screen

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:

Commarea offset
Specifies the offset of data within a commarea passed to a program on invocation. You can specify the offset in decimal format (for example, 13) or in hexadecimal format (for example, X'D'). If you specify data in hexadecimal format, you must specify an even number of hexadecimal digits.
Commarea data
Specifies the data within a commarea that is passed to a program on invocation. You can specify the data in character format (for example, "ABC") or in hexadecimal format (for example, X'C1C2C3').
Container name
Specifies the name of a container within the current channel passed to a program on invocation. Container names are case sensitive.
Container offset
Specifies the offset of data in the named container passed to a program in the current channel on invocation. You can specify the offset in decimal format (for example, 13) or in hexadecimal format (for example, X'D').
Container data
Specified the data in the named container passed to a program in the current channel on invocation. You can specify the data in character format (for example, "ABC") or in hexadecimal format (for example, X'C1C2C3'). If you specify data in hexadecimal format, you must specify an even number of hexadecimal digits.
URM debugging
Specifies whether you want Debug Tool to include the debugging of URMs as part of the debug session. Choose from the following options:
YES
Debug Tool debugs URMs which match normal Debug Tool debugging criteria.
NO
Debug Tool excludes URMs form debugging sessions.

Creating and storing debugging profiles with CADP

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.

Starting Debug Tool for non-Language Environment programs under CICS

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.

Passing runtime parameters to Debug Tool for non-Language Environment programs under CICS

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.


Terms of use | Feedback

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