Debugging IMS programs

This topic describes the following tasks:

Debugging IMS batch programs interactively by running BTS in TSO foreground

If you want to debug an IMS batch program interactively, you can use full-screen mode using a dedicated terminal or remote debug mode. This topic describes a third option, which is to run BTS in the TSO foreground, by doing the following steps:

  1. Define a dummy transaction code on the ./T command to initiate your program
  2. Include a dummy transaction in the BTS input stream
  3. Start BTS in the TSO foreground.

    FSS is the default option when BTS is started in the TSO foreground, and is available only when you are running BTS in the TSO foreground. FSS can only be turned off by specifying TSO=NO on the ./O command. When running in the TSO foreground, all call traces are displayed on your TSO terminal by default. This can be turned off by parameters on either the ./O or ./T commands.

Note:
If your source (C and C++) or listing (COBOL and PL/I) does not come up in Debug Tool when you launch it, check that the source or listing file name corresponds to the MVS™ library name, and that you have at least read access to that MVS library.

Debugging IMS batch programs in batch mode

You can use Debug Tool to debug IMS programs in batch mode. The debug commands must be predefined and included in one of the Debug Tool commands files, or in a command string. The command string can be specified as a parameter either in the TEST run-time option, or when CALL CEETEST or __ctest is used. Although batch mode consumes fewer resources, you must know beforehand exactly which debug commands you are going to issue. When you run BTS as a batch job, the batch mode of Debug Tool is the only mode available for use.

For example, you can allocate a data set, userid.CODE.BTSINPUT with individual members of test input data for IMS transactions under BTS.

Debugging non-Language Environment IMS MPPs

You can debug IMS message processing programs (MPPs) that do not run in Language Environment by doing the following tasks:

  1. Verify that your system is configured correctly and start a new region. See Verifying configuration and starting a region for non-Language Environment IMS MPPs for instructions.
  2. Choose a debugging interface. See Choosing an interface and gathering information for non-Language Environment IMS MPPs for instructions.
  3. Run the EQASET transaction, which identifies the debugging interface you chose and enables debugging. See Running the EQASET transaction for non-Language Environment IMS MPPs.
  4. Start the IMS transaction that is associated with the program you want to debug.

After you finish debugging your program, you can do one of the following:

Verifying configuration and starting a region for non-Language Environment IMS MPPs

Before you debug an IMS MPP that does not run in Language Environment, do the following steps:

  1. Consult with your system administrator and verify that your system has been configured to debug IMS programs that do not run in Language Environment. See the Debug Tool Customization Guide for instructions on how to include the APPLFE=EQANIAFE parameter string in the JCL that starts a region and EQANISET.
  2. Start an IMS message processing region (MPR) that runs the EQANIAFE application front-end routine whenever a message processing program (MPP) is scheduled.

After you complete these steps, choose a debugging interface as described in Choosing an interface and gathering information for non-Language Environment IMS MPPs.

Choosing an interface and gathering information for non-Language Environment IMS MPPs

Choose from one of the following debugging interfaces and gather the indicated information:

After you choose a debugging interface, run the EQASET transaction as described in Running the EQASET transaction for non-Language Environment IMS MPPs.

Running the EQASET transaction for non-Language Environment IMS MPPs

Running the EQASET transaction indicates to the EQANIAFE application front-end routine that you want to do one of the following functions:

To enable a debugging session, select one of the following options:

After you enter an EQASET command, on the same terminal, start the transaction that is associated with the application program that you want to debug.

To request information about your existing preferences, enter the command EQASET STATUS.

To disable a debugging session, enter the command EQASET OFF.

To re-enable a debugging session after using EQASET OFF, enter the command EQASET ON.

Syntax of the EQASET transaction for non-Language Environment MPPs

The following diagram displays the syntax of the EQASET transaction for non-Language Environment MPPs:

Read syntax diagramSkip visual syntax diagram>>-EQASET--+-MFI=--+------------------------------------------+-+-><
           |       '-+---------------------+-terminal_LU_name-' |
           |         '-network_identifier.-'                    |
           +-VTAM=--+---------+---------------------------------+
           |        '-user_ID-'                                 |
           +-TCP=--+----------------------------+---------------+
           |       '-IP_address--%--port_number-'               |
           +-VTCP=--+----------------------------+--------------+
           |        '-IP_address--%--port_number-'              |
           +-ON-------------------------------------------------+
           +-OFF------------------------------------------------+
           '-STATUS---------------------------------------------'
 

The EQASET transaction manages a separate debugging setting for each user that runs the transaction. Each setting is identified by the user ID that is used to log on to the terminal where the transaction is run. For any user ID, only the last debugging preference (MFI, TCP, VTCP, or VTAM) entered is saved. You can use the STATUS option to see the current debugging preference.

The following TEST runtime option string is constructed with the debugging preference:

TEST(ALL,INSPIN,,debuggingPreference:*)

You cannot customize the other runtime options.

MFI=
Use full-screen mode using a dedicated terminal without the Debug Tool Terminal Interface Manager. You must specify a dedicated terminal LU name for the debug session. If your site requires that you specify the VTAM network identifier, prefix the name of the VTAM network identifier to the terminal LU name. Without specifying the terminal LU name, debugging is turned off. No space is allowed after the equal sign (=). The preference implies debugging is turned on.
VTAM=
Use full-screen mode using a dedicated terminal with the Debug Tool Terminal Interface Manager. You must specify the user ID that was used to log on to the dedicated terminal designated for a debug session. Without specifying the user ID, debugging is turned off. No space is allowed after the equal sign (=). The preference implies debugging is turned on.
TCP= or VTCP=
Use remote debug mode. Specify the TCP/IP address and port number of the workstation where the remote debug daemon is running. Without specifying the IP address and port number, debugging is turned off. No space is allowed after the equal sign (=). The preference implies debugging is turned on. You can specify the TCP/IP address in one of the following formats:
IPv4
You can specify the address as a symbolic address, such as some.name.com, or a numeric address, such as 9.112.26.333.
IPv6
You must specify the address as a numeric address, such as 1080:0:FF::0970:1A21. If you use IPv6 format, you must use the TCP= option; you cannot use the VTCP= option.
ON
Turn on debugging. This is valid only when a debugging preference (MFI, TCP, VTCP, or VTAM) has been set.
OFF
Turn off debugging.
STATUS
Display the current debugging preference. The EQASET transaction displays only the first 25 characters of the IP address.

Debugging Language Environment IMS MPPs without issuing /SIGN ON

The Language Environment user exit for IMS (EQADICXT) constructs the name of an MVS data set that contains the Language Environment runtime options, including the TEST runtime option. EQADICXT constructs the name of the MVS data set by assigning values to tokens that represent each qualifier in a data set name; it assigns the IMS user ID as the value for the &USERID token. However, if you do not sign on to IMS (by using /SIGN ON), the IMS user ID is either the same as the IMS LTERM ID or it is not defined. In either case, EQADICXT cannot locate the MVS data set. To specify that EQADICXT assigns a TSO user ID as the value for the &USERID token, run the EQASET transaction specifying the TSOID option. For a description of the EQASET transaction with the TSOID option, see Syntax of the EQASET transaction for Language Environment MPPs.

Syntax of the EQASET transaction for Language Environment MPPs

The following diagram displays the syntax of the EQASET transaction for Language Environment MPPs:

Read syntax diagramSkip visual syntax diagram>>-EQASET--+-TSOID=--+-------------+-+-------------------------><
           |         '-tso_user_ID-' |
           '-STATUS------------------'
 

When you use the EQASET transaction for Language Environment MPPs, it associates the current IMS LTERM ID with the specified TSO user ID. EQADICXT can construct a valid name for the MVS data set using the TSO user ID for the &USERID token.

TSOID=
Identify a TSO user ID to use in place of the &USERID token in the Language Environment® user exit. The TSO user ID must match the user ID used to create the data set name, as described in Creating and managing the TEST runtime options data set.
STATUS
Display the current value for TSOID.

This option might also display information about debugging preferences for non-Language Environment MPPs.

Creating setup file for your IMS program by using Debug Tool Utilities

You can create setup files for your IMS Batch Messaging Process (BMP) program which describe how to create a custom region and defines the STEPLIB concatenation statements that reference the data sets for your IMS program's load module and the Debug Tool load module. You can also create and customize a setup file to create a private message region that you can use to test your IMS message processing program (MPP). Creating a private message region with class X allows you to test your IMS program run by transaction X and reduce the risk of interfering with other regions being used by other IMS programs.

To create a setup file for your IMS program by using Debug Tool Utilities, do the following steps:

  1. Start Debug Tool Utilities. If you do not know how to start Debug Tool Utilities, see Starting Debug Tool Utilities.
  2. In the Debug Tool Utilities panel (EQA@PRIM), type 4 in the Option line and press Enter.
  3. In the Manage IMS Programs panel (EQAPRIS), type 2 in the Option line and press Enter.
  4. In the Create Private Message Regions - Edit Setup File panel (EQAPFORA), type in the information to create a new setup file or edit an existing setup file. Press Enter.

    Create a private message region to customize your application or Debug Tool libraries while you debug your application so that you do not impact other user's activities. Consult your system administrator for authorization and rules regarding the creation of private message regions.

    After you specify the setup information required to run your IMS program, you can specify the information needed to create a private message region you can use to test your IMS program or specify how to run a BMP program. To specify this setup information, do the following steps:

  5. In the Edit Setup File panel (EQAPFORI), type in the information to start IMS batch processor. Type a forward slash (/) in the field Enter / to modify parameters, then press Enter to modify parameters for the batch processor.
  6. In the Parameters for IMS Procedures panel (EQAPRIPM), use one of the following values in the TYPE field to indicate which action you want done:

    Enter other parameters as needed. Press PF1 for information about the parameters.

  7. After you type in the specifications, you can submit your job for processing by pressing PF10.

Placing breakpoints in IMS applications to avoid the appearance of Debug Tool becoming unresponsive

When you debug an IMS application program, the way IMS manages resources might occasionally make Debug Tool appear unresponsive. To avoid this situation, set breakpoints as close as possible to the location that you need to debug or at the GetUnique (GU) call statement. The information in this topic helps you understand how IMS’s management of resources might appear to make Debug Tool unresponsive and helps you determine the approximate location to set a breakpoint to avoid this situation.

After you start an IMS transaction, IMS loads and runs the application program associated with that transaction. IMS manages all the messages requested by and returned to that application program, along with all the messages requested by and returned to other application programs running at the same time. IMS uses the processing limit count (PLCT) and other tools to ensure that application programs get the appropriate share of resources. As long as your IMS application program does not exceed the PLCT8, it continues running and processing messages or waiting for the next message. However, if you are trying to debug the application program, the continued message processing or waiting for messages might make Debug Tool appear unresponsive. To avoid this situation, try one of the following options at the beginning of your debug session, before you begin running the application program (for example, by entering the GO command):

Related references


8.
IMS Quick reschedule allows application programs to process more than the PLCT for each physical schedule. Quick reschedule helps eliminate processing overhead caused by unnecessary rescheduling and reloading of application programs.