Creating a debug profile for a CICS application

To debug a CICS® application, you must create and activate a CICS profile. The CICS profile describes filters to trigger the debugger and other debug configuration options. Each user can have only one active CICS profile for each region at any time.

Procedure

  1. Open the z/OS Debugger Profiles view.
  2. Open the Debug Profile Editor in one of the following ways:
    • Click the Create CICS Profile icon (Create CICS Profile icon) in the view toolbar.
    • Right-click in the view and select Create CICS Profile from the menu.
  3. Specify appropriate values.
    Show/Hide Hints
    Click this link to show or hide descriptions for sections.
    Profile name
    Specify a profile name. A name is automatically generated when you create a new profile. You can use this name or specify a different one, but the name must be unique.
    Optional: Description
    Specify a description for the profile. The description is stored locally and visible in the z/OS Debugger Profiles view to help you identify a profile.
    Connection
    Select the Remote System Explorer z/OS® connection where the profile is active. If no connection is available, click New to create a new z/OS connection.
    Region
    Select a region from the list.
    If your z/OS connection does not support the Debug Profile Service API, a Port list is displayed instead. Obtain the DTCN port for the region from the system programmer and add it in this field. The port numbers are remembered for future use.
    CICS Filters
    Specify at least one of the filters. Some fields might be mandatory if the system programmer defined the DTCNFORCExxxx settings to make these fields mandatory. If any mandatory field is not specified, the activation fails and returns an error message that indicates the missing filter.
    Transaction
    Specify the CICS transaction that you want to debug.
    User ID
    Specify the user ID associated with the CICS resource that you want to debug.
    CICS SYSID
    Specify the system ID for a CICSplex connection to trigger a debug session.
    Load Module/Compile Unit
    Specify up to eight load module and compile unit pairs to tell the debugger which resources you want to debug.
    Note: Avoid using the wildcard (*) for both load module and compile unit in the same pair unless you want to debug all applications in the CICS region.
    Additional Filters: Net name
    Specify the name of a CICS terminal or CICS system to trigger a debug session.
    Additional Filters: IP
    Specify the client IP name or address to trigger a debug session.
    Additional Filters: Terminal ID
    Specify a terminal ID to trigger a debug session.
    Optional: Advanced Program Interruption Filters
    Specify either the Container filters or the Communication Area filters. You cannot specify both at the same time.
    Container
    Name
    Specify the name of a container within the current channel that is passed to a program on invocation.
    Offset
    Specify the offset of data in the named container that is passed to a program on invocation. The offset can be given in character format (such as 12) or in hexadecimal (such as X'C').
    Data
    Specify a data pattern to be matched against a container within the current channel that is passed to a program on invocation. The data pattern can be given in character format (such as ABC) or in hexadecimal (such as X'C1C2C3') with an even number of digits.
    Communication Area (COMMAREA)
    Offset
    Specify an optional communication area data offset.
    Data
    Specify options communication area data.
    Application
    Specify application filters to trigger a debug session.
    Platform Name
    Specify one or more regions that might execute an application.
    Application Name
    Specify the name of the CICS application to trigger the debug session.
    Operation Name
    Specify the name of the application operation to trigger the debug session.
    Application Version
    Specify a version for the application to trigger the debugger.
    Debug user-replaceable modules (URM)
    Select this option to enable debugging user-replaceable modules (URM).
    Optional: Debugger Options
    Test level
    Select TEST or NOTEST from the list of TEST runtime options.
    TEST
    Use this option to give z/OS Debugger control according to the specified options.
    • If z/OS Debugger is started with CEETEST, PLITEST, or __ctest(), the options in the debug profile are used.
    • If z/OS Debugger is started by using CALL CEETEST or an equivalent entry, you cannot debug higher-level non-Language Environment® programs or intercept non-Language Environment events that occur in higher-level programs after you return from the program that started z/OS Debugger.
    NOTEST
    Use this option so that z/OS Debugger is not started at program initialization. However, you can still start z/OS Debugger with CEETEST, PLITEST, or the __ctest() function. In this case, the suboptions specified with NOTEST are used when z/OS Debugger is started.
    Error level
    Select ALL, ERROR or NONE from the list of TEST runtime suboptions.
    ALL
    Specifies that the following occurrences cause z/OS Debugger to gain control, regardless of whether a breakpoint is defined for that condition.
    • An attention interrupt
    • An ABEND of a program
    • Any program or Language Environment condition of Severity 1 and above
    ERROR
    Specifies that only the following conditions cause z/OS Debugger to gain control without a user-defined breakpoint:
    • For C and C++: an attention interrupt, program termination, a predefined Language Environment condition of Severity 2 or above, any C and C++ condition other than SIGUSR1, SIGUSR2, SIGINT, or SIGTERM.
    • For COBOL: an attention interrupt, program termination, a predefined Language Environment condition of Severity 2 or above.
    • For PL/I: an attention interrupt, program termination, a predefined Language Environment condition of Severity 2 or above.
    NONE
    Specifies that z/OS Debugger gains control from a condition only when a breakpoint is defined for that condition.
    Prompt level
    Select PROMPT or NOPROMPT from the list of TEST runtime suboptions.
    PROMPT
    Indicates that you want z/OS Debugger to start immediately after Language Environment initialization. Commands are read from the preferences file and then any designated primary commands file. If neither file exists, commands are read from your terminal or workstation.
    NOPROMPT
    Indicates that you do not want z/OS Debugger to start immediately after Language Environment initialization. Instead, your application begins running.
    If you specify the NOPROMPT suboption, you cannot debug higher-level non-Language Environment programs or intercept non-Language Environment events that occur in higher-level programs after you return from the program that started z/OS Debugger.
    When z/OS Debugger is running without the Language Environment runtime started by using EQANMDBG, the NOPROMPT option is ignored; PROMPT is always in effect.
    Commands data set
    Specify a valid fully qualified data set name that contains the initial debugger commands to run when the debug session starts, or click Browse to select a data set.
    Note: Not all commands are permitted in remote debug sessions. You might see errors in the Debug Console view if such commands are included in the commands data set.
    Preferences data set
    Specify a valid fully qualified data set name that contains debugger commands that customize your debug session, or click Browse to select a data set.
    Note: Not all commands are permitted in remote debug sessions. You might see errors in the Debug Console view if such commands are included in the preferences data set.
    EQAOPTS file
    Specify the name of the data set containing the EQAOPTS commands for your debug session, or click Browse to select a file.
    Language Environment options
    Specify any additional Language Environment (LE) options that your program might need. You can change any Language Environment option that your site allows you to override except the STACK option.
    Optional: Advanced Connection Options
    Specify these options to connect to a client other than the current one, such as for headless code coverage or to send a debug session to another user’s client.
    Connection with specific client information
    Select this option to force the debug profile to use connection information that you specify. Specify either an IP and port, or a user ID.
    IP
    Specify the IP name or address to connect with when the debug or code coverage session is triggered.
    Port
    Specify the TCP/IP port that the debug daemon or headless code coverage collector is listening for incoming sessions.
    User ID
    Use this option when Debug Manager is running, and you want to send a debug session to another user’s client. That user must be signed into Remote System Explorer.
  4. Click the Save and Activate for Debug icon (Save and Activate for Debug icon) or the Save and Activate for Code Coverage icon (Save and Activate for Code Coverage icon) in the editor toolbar to save and activate the profile on the remote connection.
    Optionally, press M1+Sa or M1+Da to save and activate for debug, or press M1+M2+Ca to save and activate for code coverage.
    1. M1 is the COMMAND key on macOS, and the CTRL key on most other platforms. M2 is the SHIFT key.