Starting Code Debug IMS (C User Guide)

Code Debug IMS consists of menus and screens accessed through ISPF. Code Debug IMS screens are viewed on the TSO terminal; the IMS application format screens are viewed on the IMS terminal.

Before starting the session, prepare your programs (precompile, compile, and link edit) with the BMC AMI Common Shared Services C language processor. You can use the Code Debug TSO online facilities to prepare your programs. See the Preparing Your Programs for additional information. For more information about BMC AMI's Common Shared Services, See the Common Shared Services User/Reference space.

1. Once you have a valid load module and DDIO data set, log on to TSO and invoke Code Debug TSO. Use the procedures that are in effect at your site.

2. From the Code Debug TSO Primary Menu, select option 2 (TSO) to display the Environments Menu.

   Warning

   Important

   If the Environments Menu is not displayed, access it by entering SETUP on the command line of the test screen that is being displayed. On the Test Setup Menu, enter option 0 (ENVIRONMENT).

3. Specify the appropriate environment, 8 (MPP) or 9 (BMP/IFP) on the Environments Menu. The environment test screen for that environment is displayed.
4. On the environment test screen, enter the command SETUP to display the Setup Menu.
5. Specify A (All) to review all your setup selections.
   1. 
      
      • Load libraries—user program libraries allocated as STEPLIB. Verify that the order of concatenation is correct.
      • DDIO data set—library name should be the data set name specified on the CWPDDIO DD statement in your Code Debug compile step.
      • Test script libraries.
      • Test session log data set.
      • Test session script data set.
      • Db2 system names and DSNLOAD data sets.
      • PANEXEC defaults (if installed).
      • PSB and DBD libraries (GSAM only).
      • IMS preload list.
      • IMS authorized load libraries.
      • IMS region ID and PARM strings—PARM fields set up at install time can be changed.
6. If everything is correct, press PF3 from the Setup Menu to return to the environment test screen.

7. Complete the environment test screen as described in Debugging an MPP Program or Debugging a BMP/IFP Program.

   Warning

   Important

   Code Debug IMS environment test screens shown as examples in this section are fully described in Code Debug TSO Environment Test Screens.

8. Wait for the intercepts to be set, then log on to IMS and enter the transactions.
9. View the Code Debug IMS source display on the TSO terminal. Switch to the IMS terminal for all input and output operations.
10. At the end of each MPP transaction, enter GO to continue debugging or EXIT to terminate.
11. At the end of a Batch Message Processing (BMP) or Interactive Fast Path (IFP) program, you are returned to the BMP/IFP screen. Press Enter to go into the same debugging session again, or enter END to return to the Primary Menu.

Debugging an MPP program

Select option 8 from the Environments Menu to debug an MPP program. The MPP environment test program screen shown in the following figure is displayed. The MPP screen lets you set up environment parameters for debugging a program in an IMS Message Region. When you identify the transactions to be debugged and initiate the session, Code Debug IMS attaches the IMS message region within the TSO address space.

Enter END to terminate any display. HELP is also available from any screen.

MPP Environment Test Program Screen

The following commands are valid on the MPP Test screen:

SEtup

Displays the Setup Menu from which you can select screens for specifying load libraries, DDIO data sets, and so on.

Log

Browses the session log after you execute a program. The session log file contains a record of the commands that were entered during the debugging session and the responses to them.

INter

Displays the Intercepts screen showing you what IDs are logged on to Code Debug IMS, what programs are being used, and so on.

DOwn

Scrolls to a continuation MPP screen. From this screen, UP is available for returning to the first debugging screen.

PROFile

Displays the available Profile options in a file where you can select, delete, copy, rename, and use the Profile of your choice. It also lets you “merge” or “copy” another users profile into your own.

ALLOC

This command takes you to the File Allocation Utility (FAU) screens to create a file allocation list, which your program may require for the debugging session.

The fields on the MPP program screen are:

Program

Required if TRANCODE is not specified. Used to identify which programs are to be debugged by Code Debug IMS. You can enter the load module name in this field or the transaction code in the TRANCODE field, or supply values for both fields. If you enter only the program name, the program must be associated with only one transaction. If the program is associated with multiple transactions, then the transactions that are to be debugged must be entered in the TRANCODE field and the program name can be omitted from the PROGRAM field.

Three programs or transaction codes can be specified on the first MPP screen. If you fill the first screen and need more space, enter DOWN (PF8) and a second MPP Program (continuation) screen is displayed similar to the one shown in the following figure.

Once the second screen is full, you can scroll down to a third screen. Notice that on the second (and subsequent screens), the UP (PF7) command is available in addition to the DOWN command.

Second MPP Program Screen

TRANCODE

Used to identify which transactions are to be debugged by Code Debug IMS. You can enter the transaction code in this field or the load module name in the PROGRAM field, or enter values for both fields.

This field is required if PROGRAM is not specified or if multiple transactions are associated with the program.

INITSCR

The member name of the script in the INCLUDE library specified on the Setup panel. The INITSCR field can be typed over to specify a test script member which can be processed at the beginning of a debugging session.

When using Code Debug IMS, enter the member name of a test script if you want to execute a predefined command stream at the beginning of the debugging session. This member will be executed after the inclusion of the site-wide script member @@SITE@@, if defined.

POSTSCR

Enter the member name of a test script if you want to execute a predefined command stream at the end of the debugging session.

START

Enter up to four digits to specify the occurrence of the program invocation on which the intercept is to begin. By default, program intercept begins on the first occurrence. When the program is intercepted, the debugging session is initiated and the source is displayed.

MAX

Enter up to four digits to specify the maximum number of times the program intercept is to be processed. If this field is left blank, the value defaults to an infinite number. If you enter an EXIT command and there are still intercepts remaining, those intercepts are ignored.

DATA

Specify up to 30 bytes of data from the IMS transaction you want to debug.

The DATA field is only active if IMS User ID/Data Value Intercept Support is enabled. See Task 2.8 Configure the Code Debug IMS User ID Intercept Installation Utility in the Code Debug TSO and Code Debug IMS Advanced Configuration space for more details.

IMS USERID

Specify the ID of the IMS user issuing the IMS transaction you want to debug. If IMS User ID/Data Value Intercept Support is enabled, you can enter an asterisk (*) to specify a generic match on any user ID.

The IMS USERID field is only active if either IMS User ID Support or IMS User ID/Data Value Intercept Support is enabled. See ask 2.8 Configure the Code Debug IMS User ID Intercept Installation Utility in the Code Debug TSO and Code Debug IMS Advanced Configuration space for more details.

Retain Breakpoints?

If you want Code Debug to retain breakpoints from one iteration of an IMS program or transaction to the next, enter YES in this field. Before breakpoints, after breakpoints, onetime breakpoints, counts, skips, traces, and when conditions from the previous test iteration will be reapplied. Count values will accumulate across iterations, but maximum execution count limits are not preserved. Keeps and inserted lines are not retained.

The default is NO and will result in each iteration starting with only before and after breakpoints.

Code Coverage counters and breakpoints, where applicable, are unaffected by this feature.

NBA

Enter the Normal Buffer Allocation (NBA), up to four digits. The default value is 0.

OBA

Enter the Overflow Buffer Allocation (OBA), up to four digits. The default value is 0.

File List/JCL Member

Enter the data set name that contains the file list, CLIST, or JCL. The File Allocation Utility (FAU) preallocates files and databases that will be processed by the program upon entry to the debugging session.

If the member name of a PDS is omitted, a member list is displayed.

If the data set contains a CLIST, Code Debug IMS immediately executes it and begins the debugging session. If the data set contains a file list or JCL, the FAU is invoked to dynamically allocate the specified files before beginning the debugging session. See the Using the File Allocation Utility for detailed information about the FAU.

Unattended?

Enter YES to run in Unattended mode. The default value is NO. In unattended mode, after the Code Debug IMS Message Processing Region (MPR) is attached, Code Debug commands are only processed in the Initial Script, Post Script, and Abend Script. The TSO terminal remains locked, and Code Debug commands are not allowed from the terminal. When you are finished testing in the Code Debug IMS MPR, the MPR may be stopped and the TSO terminal unlocked by using either the Code Debug Stop Region transaction, XPST, or the Code Debug Stop Region BMP procedure XPSTOP. See the Stopping the Code Debug IMS Dependent Region.

Code Coverage Test?

Enter YES to collect statistics without Test Data Optimization information. Enter TDO to collect statistics and TDO information. The default value is NO.

System Flow?

Enter YES to collect Code Coverage System Flow data. The default value is NO.

Is This a DB2 Test?

Enter YES if the program executes EXEC SQL statements. The default value is NO.

System

Enter the Db2 subsystem name if the program executes EXEC SQL statements. The subsystem name depends on the release level of Db2 and is assigned at the time of installation.

When entries for the screen are complete and you press Enter, the screen clears. If the intercepts are set, the following messages appear on the screen:

The terminal is then locked. If an error is encountered, however, the intercepts are not set and you are returned to the test screen. A message indicating an error occurred is displayed on the message line. You can access the session log for more information.

If the intercepts are set successfully, go to the IMS terminal and start the transaction you want to debug by entering the transaction code that invokes your program. Note that you should invoke the program the way you would without Code Debug IMS; e.g., by going through a signon screen or another transaction. If a format screen is invoked, enter any data needed by the transaction.

When you press Enter, IMS schedules the transaction for execution and locks your terminal if it is in response mode. Return to the TSO terminal.

If you have a source listing member for the high-level program, your source will be displayed. See Debugging Interactively for information on how to interactively debug a program with source. All interactive Code Debug TSO commands are valid except USE and RETEST. If you do not have a source listing member for the high-level program, the session log is displayed with a message indicating that the program does not have a source listing member. See Debugging a Sourceless Program for information on how to interactively debug a program without a source listing member.

To enter or review data at any point in execution, go to the IMS terminal.

At the TEST COMPLETED message, you can enter GO to retest this transaction or test another one, or enter EXIT to return to the MPP screen. At the end of the debugging session, the session log is available for viewing. You can also save a script of the commands entered for future use.

IMS Conversational Transaction Considerations

To facilitate IMS user ID support, Code Debug IMS creates a clone of the original IMS transaction, which it then executes in an Code Debug MPR. Because cloned transactions each have a unique transaction code, multiple iterations of a transaction can coexist without lockout occurring. This cloning process takes place on the first execution of a transaction.

If you do not want Code Debug to intercept the first iteration of a conversational transaction, do the following:

• Initiate Code Debug before the transaction begins
• Specify a starting transaction number.

At the first iteration, Code Debug will create a clone of the transaction, but the actual debugging session will not start until the specified starting iteration.

After you enter the EXIT command to end your session, you must also enter /EXIT to end the original IMS transaction. This is because Code Debug has already torn down the MPR used for the transaction’s clone. If not ended manually, the transaction could hang because there is no longer an Code Debug MPR to process it.

Debugging a BMP/IFP program

After selecting option 9 from the Environments Menu to debug a BMP or Fast Path program, the BMP/IFP screen shown in the following figure is displayed. The BMP/IFP screen lets you set up the parameters to test and debug a program in an IMS, BMP, or Fast Path Region. When you identify the transactions to be debugged and initiate a session, Code Debug IMS attaches the IMS message region within the TSO address space.

The commands (except DOWN) described in Debugging an MPP Program can also be entered on this screen.

BMP/IFP Program Screen

The fields on the BMP/IFP program screen are:

Program

Required. Used to identify which program is to be intercepted and debugged by Code Debug IMS. You must enter the load module name in this field or supply values for both this field and the TRAN CODE field. Code Debug inserts this value into the program subparameter for the parameter it passes to IMS.

PSB

Required. Enter the program specification block associated with the program you are debugging. Code Debug inserts the specified value into the BMP parameter passed to the IMS driver program.

TRAN CODE

Used with a BMP to provide the name of a message queue to be processed by the BMP. This field is not used with an IFP program.

Initial Script

The member name of the script in the INCLUDE library specified on the Setup panel. The INITSCR field can be typed over to specify a test script member which can be processed at the beginning of a debugging session.

Enter the member name of a test script if you want to execute a predefined command stream at the beginning of the debugging session. This member will be executed after the inclusion of the site-wide script member @@SITE@@, if defined.

Post Script

Enter the member name of a test script if you want to execute a predefined command stream at the end of the debugging session.

NBA

Enter the Normal Buffer Allocation (NBA), up to four digits.

OBA

Enter the Overflow Buffer Allocation (OBA), up to four digits.

File List/JCL Member

Enter the data set name that contains the file list, CLIST, or JCL. The File Allocation Utility (FAU) preallocates files and databases that will be processed by the program upon entry to the debugging session.

If the member name of a PDS is omitted, a member list is displayed. If the data set contains a CLIST, Code Debug IMS immediately executes it and begins the debugging session. If the data set contains a file list or JCL, the FAU is invoked to dynamically allocate the specified files before beginning the debugging session. See Using the File Allocation Utility for detailed information about the FAU.

Code Coverage Test?

Enter YES to collect Code Coverage execution statistics without Test Data Optimization information. Enter TDO to collect statistics and TDO information. The default value is NO.

System Flow?

Enter YES to collect Code Coverage System Flow data. The default value is NO.

Is This a DB2 Test?

Enter YES if the program executes EXEC SQL statements. The default value is NO.

System

Enter the Db2 subsystem name if the program executes EXEC SQL statements. The subsystem name depends on the release level of Db2 and is assigned at the time of installation.

After typing in all required values, press Enter to initiate the debugging session. The screen will be cleared and, if the intercepts are set, the following messages will be displayed:

The terminal is then locked until the screen changes. If an error is encountered, you are returned to the test screen. A message indicating an error occurred is displayed on the message line. You can access the session log for more information.

When the intercepts are set, go to the IMS terminal and begin the transaction you want to debug by entering the transaction code that invokes your program. Note that you should invoke the program in the usual way (without Code Debug IMS); e.g., going through a sign-on screen or other transaction if necessary. Once the format screen appears, you can enter any data needed by the transaction. IMS schedules the transaction for execution, then locks the IMS terminal if it is in response mode. Return to the TSO terminal.

If you have a source listing member for the high-level program, your source will be displayed. See Debugging Interactively for additional information on how to interactively debug a program with source. All interactive Code Debug TSO commands are valid except USE and RETEST.

If you do not have a source listing member for the high-level program, the session log is displayed with a message indicating that the program does not have a source listing member. See Debugging a Sourceless Program for information on how to interactively debug a program without a source listing member.

To enter or review data at any point in execution, go to the IMS terminal.

To end a BMP debugging session, type EXIT. To end an Interactive Fast Path (IFP) debugging session, the directions are different. You can type EXIT if you have a breakpoint. If the Interactive Fast Path (IFP) program is waiting for input from the terminal, the IFP region may be stopped and the TSO terminal unlocked by using either the Code Debug Stop Region transaction, XPST, or the Code Debug Stop Region BMP procedure XPSTOP. See Stopping the Code Debug IMS Dependent Region.

When the debugging session is terminated, you are returned to the BMP/IFP screen. At this point, session log and script data sets are available. You can press Enter to go into the same debugging session again, or type END to go back to the Environments Menu.