CDCN (Application Diagnosis Configuration) for AIX only

Turns the IBM Distributed Debugger on and off.

Syntax

CDCN [TERMID=termId] [SYSID=sysId] [TRANSID=transId] [PROGRAM=programName ] [DISPLAY=display] [ ON | OFF ]

Description

CDCN is a CICS-supplied transaction that turns the IBM Distributed Debugger on and off. CDCN is not supported on Windows.

The IBM Distributed Debugger can be used to diagnose errors in a transaction that is identified by naming a resource in one of the following classes:

Terminal (identified by its termid)
System (identified by its sysid)
Transaction (identified by its transid)
Program (identified by its program name)

When a transaction meets one or more of the criteria that CDCN sets, the IBM Distributed Debugger starts. To distinguish between different configurations, CDCN stores data on a per-user principle. Users must sign on with their user IDs before accessing CDCN. This prevents conflicts in configuration. For example, user A should not be able to change user B's configuration. Every CDCN configuration data is stored in a file. If the region is stopped and restarted, CDCN configuration data is loaded and the resources that were configured for debugging are available for debugging again. CDCN configuration is stored in debug.cfg file which resides in the region’s data directory. This file is only for internal use of TXSeries. It should not be opened in any editor or edited manually.

Options

TERMID=termId: Specifies the four-character identifier of the terminal on which the transaction that is to be tested will be run. This might or might not be the terminal on which CDCN is invoked. If no other resources are specified, termId defaults to the identifier of the current terminal. This terminal must be defined in the Terminal Definitions (WD), unless it is generated from a terminal autoinstall. The terminal must be a terminal in the same region as the current terminal.
To find the identifier of an autoinstalled terminal, you can run the CEMT INQ TERMINAL transaction, which lists all the terminals that are logged on to the CICS® region. Alternatively, you can look at the autoinstall message in the CSMT log, in the file /var/cics_regions/region_name/data/CSMT.out.
SYSID=sysId: Specifies the four-character identifier of the remote region where the transaction that is to be diagnosed will originate. This region must be defined in the Communications Definitions (CD).
TRANSID=transId: Specifies the identifier of the transaction that is to be diagnosed. This transaction must be defined in the Transaction Definitions (TD).
PROGRAM=programName: Specifies the name of the program that is to be diagnosed. This program must be defined in the Program Definitions (PD). The program source must be in the directory as specified in the DER_DBG_PATH environment variable. For more information, see Configuring the IBM Distributed Debugger with TXSeries CICS.
DISPLAY=display: Specifies the IP address of the machine and the port where the distributed debugger user interface is running.
ON: Specifies that the IBM Distributed Debugger is to be turned on for the named resources. This is the default if neither ON nor OFF is specified.
OFF: Specifies that the IBM Distributed Debugger is to be turned off for the named resources.

Using the CDCN screen

You need to set the value of AllowDebugging attribute in the Region Definitions (RD) to yes to use CDCN.

If you enter CDCN without specifying the DISPLAY parameter or if the command line is not valid or incomplete, the following screen is displayed:

 CDCN              CICS Debugging Configuration Transaction
 
 
        DISPLAY :(         )                               DEBUG  : ON
 
 
 To configure for a terminal specify the TERMID            TERMID : (    )
 
 
 To configure for a system specify the SYSID               SYSID  : (    )
 
 
 To configure for a transaction specify the TRANSID        TRANSID: (    )
 
 
 To configure for a program specify the PROGRAM            PROGRAM: (    )
 
 
 
 ENTER:    COMMIT SELECTION
 PF1 : HELP                PF2 : DEBUG ON/OFF        PF3 : EXIT
 PF4 : MESSAGES            PF5 : UNDEFINED           PF6 : UNDEFINED
 PF7 : UNDEFINED           PF8 : UNDEFINED           PF9 : UNDEFINED
 PF10: UNDEFINED           PF11: UNDEFINED           PF12: UNDEFINED

The data entry fields, which are indicated by parentheses, are where you can enter data that corresponds to the parameters.

After you have filled in the fields that you want, press ENTER from the main screen.

Program Function Keys

The program function keys have the following functions:

PF1: Displays help.
PF2: Toggles the IBM Distributed Debugger on and off.
PF3: Exits from CDCN.
PF4: Messages.

Using CDCN

When you use CDCN to turn on the IBM Distributed Debugger for a named resource, it does not cause the IBM Distributed Debugger to start immediately. If you satisfy the security checks, and you are able both to run the CDCN transaction and to access the region database entries to turn on the IBM Distributed Debugger for the resource, the resource that you name acts as a “trigger”. Startup of the IBM Distributed Debugger is triggered later, depending on the type of resource that is involved:

Resource	Startup of the IBM Distributed Debugger triggered by
termid	The next transaction that is run on that terminal
sysid	The next transaction that is run as a result of a request from that system
transid	The next invocation of that transaction
program	The next invocation of that program

When the IBM Distributed Debugger is first started, it remains attached to the CICS application server (cicsas) process, debugging one or more programs, until the end of the transaction (even when it has been triggered to debug a program), or until you choose to quit from the IBM Distributed Debugger. The IBM Distributed Debugger is “attached” when it is attached to the cicsas process (that is, actually debugging one or more programs); the IBM Distributed Debugger is “detached” when it is no longer attached to the cicsas process (that is, when it has finished debugging a transaction and is waiting to be triggered again). When the IBM Distributed Debugger has started, it can be terminated only in one of two ways:

When the IBM Distributed Debugger is attached, by using the quit facility of the IBM Distributed Debugger itself.
When the IBM Distributed Debugger is detached, by using CDCN.

Each “trigger resource” can have only one session of the IBM Distributed Debugger started for it, and the implied sequence of precedence is as follows:

termid
sysid
transaction
program

This means, for example, that, if you turn on debugging both for a terminal that has identifier AR01 and for a transaction that has identifier ALAN, and you run transaction ALAN on terminal AR01, only one session of the IBM Distributed Debugger is started (that associated with terminal AR01), because two debug sessions cannot debug the same physical copy of the code, and the terminal trigger takes precedence over the transaction trigger. A second invocation of ALAN that is run from a different terminal, however, will also start a session of the IBM Distributed Debugger (that associated with transaction ALAN). It is therefore possible to have multiple copies of the same program code being debugged at the same time.

Note that only programs that are compiled for debug produce symbolic output from the IBM Distributed Debugger when run under control of the IBM Distributed Debugger. If the IBM Distributed Debugger is triggered for a program that has not been compiled for debug, the IBM Distributed Debugger displays the program as assembler statements.