Debugging programs with special conditions for C

Checkpoint/step restart

Code Debug TSO supports Checkpoint/Step Restart using the RESTART JCL card under certain circumstances. Consider the following scenarios.

Scenario one

There is an ABEND in a multiple step job stream and the ABEND occurred in a step other than the step currently being tested. Under this scenario, both Step and Checkpoint Restarts are supported.

To use Step or Checkpoint Restarts, the session log, script, and document data sets need to be retained. Because it is not possible to know beforehand that a program will ABEND, it is your responsibility to specify retention for these data sets if you want the ability to do a Step or Checkpoint Restart. See Log, Script, and Document Data set Screens for how to do this.

Scenario two

An ABEND has occurred in a job stream without Code Debug TSO and the user wants to use Code Debug TSO to resolve the problem. Under this scenario, Step Restart is supported if the CONVERT JCL expansion option is used. Checkpoint Restart is not supported.

To use Step Restart, the RESTART JCL card must specify a STEPNAME. The XPEDITER allocation step is then inserted into the JCL just before the step specified on the RESTART JCL card, and the RESTART JCL card is modified to point to that XPEDITER allocation STEPNAME. If the RESTART JCL card does not specify a STEPNAME, no special processing is performed (the JCL is converted as usual).

If you want to be able to use Step Restart after testing with Code Debug TSO, retain the session log, script and document data sets as described in Scenario One.

31-bit support

Code Debug TSO runs as an ISPF dialog box in the TSO region under the MVS operating system. Code Debug TSO modules reside above the 16 MB line, except for the I/O modules. You can execute any programs that are AMODE(31) or RMODE(ANY) with Code Debug TSO.

Code generator support

Source code that has been generated with a code generator can be compiled with the language processor and debugged with Code Debug TSO at the generated C Language level. Code generators that product object modules are executed with Code Debug TSO; however, you might not be able to do any symbolic debugging, such as setting breakpoints and displaying variable contents.

Optimized code support

C programs that are optimized using the OPTIMIZE compiler option or the INLINE option can be debugged symbolically under Code Debug TSO without altering the load module. However, depending on the optimizing algorithm applied to the code, execution trace and stepping through code in Code Debug TSO can appear to be incorrect. The logic optimization can also impact the data flow in the program. Data values displayed with the KEEP and PEEK commands cannot be updated correctly, and the GOTO command is not allowed for a function name or line number that was streamlined by the optimizer.

OPT is displayed in the upper right corner of the Code Debug Source screen if the program has been compiled as OPTIMIZED or INLINE, as shown in the following figure.

OPT Indicator on Code Debug Source Screen

The side effects of optimization can be verified by comparing the test results against code that has not been optimized, or by analyzing the LIST information generated at compile time.

Mixed language support

You can debug mixed COBOL, PL/I, C, and/or Assembly language applications under the same debugging session if you are licensed for the languages comprising the application. If you are not licensed, you cannot create the necessary source listing records.

If you are licensed, Code Debug TSO automatically enables the appropriate language commands and run-time environment for the qualified program. The source is displayed if you created the source listing member for the program; the language dependencies are transparent to the user. Otherwise, the module for the language that is not licensed is treated as an executable module without source. You are not allowed to perform any symbolic debugging tasks; however, you can execute through the module.

Database support

There are three types of databases that Code Debug TSO supports. The first category is third-party software in general, the second is IMS/DB, and the last is Db2.

IDMS/DB, ADABAS, SUPRA, DATACOM/DB, System 2000

You can debug batch programs that issue calls to IDMS/DB, ADABAS, SUPRA (TIS/TOTAL), DATACOM/DB, and System 2000 under the Standard environment (option 1 on the Code Debug TSO Environments Menu). The databases are treated as if the programs are issuing I/O operations to the VSAM files. You must pre-allocate the databases using the File Allocation Utility. There are no special parameters that you must set in order to debug ADABAS and SUPRA programs; however, you must SET STATIC OFF to access IDMS database programs. If you are performing a Code Coverage test of a DATACOM application, you must enter the EXIT command at the end of the test in order to record Code Coverage statistics. This is because the DATACOM driver program does not follow prevalent return linkage conventions. See the Command-and-syntax-reference space for information about the SET commands.

IMS/DB

Batch programs that make database calls using invocations of CTDLI are debugged in the IMS/DB environment (option 3 on the Code Debug TSO Environments Menu). Verify that the IMS-related libraries such as RESLIB, PSB, and DBD, and the parameters information are correctly defined in the Setup Options screens as well as on the IMS test screen.

During the debugging session, you can dynamically issue DLI function calls on behalf of your program and access the IMS databases through the use of the DLI command.

IOPCB and return codes can be kept in the Keep window to monitor the DLI calls that are issued.

The last function code and its return code can be retrieved to monitor the DLI activities through the use of the SHOW IMSFUNC command. Using HELP IMSCODE shows the common IMS abend codes.

DBT HSSR

DBT HSSR is the abbreviation for the IBM IMS/VS Data Base Tool High Speed Sequential Retrieval utility. Code Debug can be used to test both DBT HSSR application programs and user exits.

These programs are debugged using the IMS/DB environment option (option 3 on the Code Debug TSO Environments Menu). To support HSSR, you must add one or more PARMs on the Code Debug TSO IMS Parameter Lists screen. For example:

The PARM must follow HSSR standards. To get the proper parameter values, see the working batch JCL or to the IBM IMS/VS DBT HSSR User’s space

Begin the PARM with the name of the control program, normally DFSRRC00, followed by a slash (/), followed by the environment type.

The subparameters following the first and second commas (that is, MODULE and either PSB or DBD) are dummy values that are replaced at execution time by values from the IMS test screen.

On the IMS test screen, specify the program type that matches the HSSR PARM you want; i.e., HSD, HSB, or HSU.

In the PROGRAM field on the IMS test screen, specify the highest level HSSR application program. This is the program name that is normally specified as the MBR keyword in the JCL PARM. For testing HSSR user exits, the name is either FABHFSU or FABHURG1.

Code Debug uses the value in the PSB field internally to replace the data string between the second and third commas. This can be either a PSB or a DBD, depending on the HSSR function to be performed.

Since the Code Debug TSO IMS Setup Menu has screens only for IMS-related data sets, allocate the HSSR data sets in your file allocation list.

When you press the Enter key from the Code Debug TSO IMS test screen, the presence of the slash (/) in the specified PARM causes Code Debug to automatically invoke the HSSR driver program, FABHX034. Before and after module breakpoints are set automatically in the program specified on the test screen. If no source listing member exists for this program, the Code Debug session log is displayed. From the session log, you can set additional breakpoints and then enter the GO command.

Db2

Batch programs that make EXEC SQL calls without IMS/DB are debugged in the Standard environment (Option 1 on the Code Debug TSO Environments Menu). The DSNLOAD libraries and the associated Db2 subsystem name must be identified on the Setup screen. Enter YES in the Is this a DB2 Test? field. In this case, Code Debug TSO issues a DSN RUN command to establish the Db2 environment. The plan name and the system name must be supplied in order to successfully execute the DSN RUN.

ISPF dialog box applications that have programs that make EXEC SQL calls are debugged in the Dialog Box environment (Option 2).

Batch programs that make Db2 calls as well as IMS/DB calls must be debugged in the IMS/DB environment (Option 3).

IMS/DC programs that make Db2 calls are debugged with BTS in the BTS environment (Option 4) or by using Code Debug IMS option 8 or 9. In an IMS/DC test session with Db2, split screen cannot be used with any product that causes another attach to Db2. This is an IMS restriction.

Use HELP SQLCODE to show the common SQL return codes.

Shared DL/I Database (DFHDRP) support

Programs that access DL/I databases shared between the CICS region and TSO can be debugged through Code Debug TSO by executing a CLIST through TSO or by executing a CLIST as a USEREXIT.

The Code Debug TSO support for DFHDRP is provided for users who have already installed DFHDRP (Shared DL/I Database) at their sites. See the CICS/OS/VS Installation and Operations space order number SC33-0071, “Running a Batch Region for DL/I Shared Databases” for details of this IBM feature.

There are two methods of installing Code Debug TSO DFHDRP support:

To install this support, see the Code Debug TSO and Code Debug IMS Advanced Configuration space

After the CLIST is executed, the program source appears. At this point, normal Code Debug TSO commands are in effect.

PANEXEC support

PANEXEC programs can be debugged using Code Debug TSO. The installer must specify Y for the PANEXEC_LOAD_MODULE_SUPPORT keyword in the CMSC PARMLIB. This allows the PANEXEC Load Libraries screen to appear during installation.

On the PANEXEC Load Libraries screen, the data set name allocated to ddname PANESRL must be entered in the PANEXEC Load Library DSNAMES field and the ddname associated with your PANEXEC control cards must be entered in the PANEXEC Control Card File DSNAMES field.

Language environment support

Code Debug TSO provides the following support for Language Environment (LE):

• Debugging applications with TRAP ON or TRAP OFF. Applications can be debugged with TRAP ON as well as TRAP OFF. The SET LETRAP ON/OFF command lets you set the TRAP option. Multiple enclaves are not supported if LETRAP is ON.
• Debugging the new handlers language construct. Code Debug TSO lets you control execution and follow user handler invocation with the following restriction:
  • User handler for S0C1: Code Debug TSO will always get control of a S0C1 abend, preventing the user from effectively debugging handler routines that process S0C1 ABENDS.

Usage note

Even though your application runs successfully from the LINKLIST or (E) LPA, the application load library or libraries, including any C and/or LE runtime libraries that are required, are also required in the STEPLIB.

Global handling of special conditions

If special conditions can be handled by a command stream in an initial script, the @@SITE@@ member can be used to include these commands for the entire user community. This member will be executed prior to any initial script specified by the user. If placed in a site-wide script library (defined at installation), a special environment can be initiated for all users, even if no initial script is specified.

Using IBM MQ for z/OS with Code Debug TSO

In order to use IBM MQ for z/OS (formerly MQSeries and WebSphere MQ) with Code Debug TSO, you must allocate MQ LOADLIBs under DFSESL.

• If testing under IMS in batch, your JCL should already have a DFSESL DD card and can be used without modification.
• If performing an interactive IMS test (with or without Db2), do either of the following:
  • Indicate DB2 = YES with a subsystem name (on the test screen). The subsystem name points to an entry on the DSN LOADLIB screen in the SEtup.

On the DSN LOADLIB screen, more than one LOADLIB can be indicated under DSN LOAD DSNAME for any given NAME. For example, when you are using Db2:

NAME DSNLOAD DSNAME
D220 ’Valid.DB2.Subsystem’
D220 ’MQ.SERIES.LOADLIB’

In another example in which you are not using Db2, continue to specify DB2 = YES with a subsystem name:

NAME DSNLOAD DSNAME
D220 ’MQ.SERIES.LOADLIB’

or

Use the FAU (File Allocation Utility) to allocate the DFSESL DD and point to your MQ LOADLIBs. For more information, see Using the File Allocation Utility.

Using BMC’s AR/CTL with Code Debug TSO’s multi-batch (including Workbench for Eclipse)

BMC’s AR/CTL interface and BMC's Multi-Batch interface (used by Workbench for Eclipse) use similar methods to intercept jobs. These methods can prevent AR/CTL from making a connection to a Db2 subsystem in a non-IMS environment, or prevent Multi-Batch from intercepting the job for testing with Code Debug TSO. In order for the two interfaces to work cooperatively, perform the following steps:

1. The AR/CTL interface (usually BMCP and BMCBCSS) must be started before the Code Debug TSO Multi-Batch interface (job JCLACTMB). If the Multi-Batch interface was started first, run JCLACTMB with PARM=DEACTIVATE. Then run it again with PARM=ACTIVATE. (See the Code Debug TSO and Code Debug IMS Advanced Configuration space, Task 2.12 for more information on activation/deactivation of Multi-Batch.)
2. For all jobs that will use AR/CTL with IMS, this is all that is required.
3. For all jobs that will use AR/CTL for a non-IMS Db2 connection, the steps required depend on the method used to establish the connection. AR/CTL can connect using any of three methods. The method is selected when setting up the intercept for the non-IMS job. The three methods are:
   • DB2 Batch Attachment Facility Only = CAF
     • If this method is used, the program specified must be AESNBAF0. When Code Debug TSO gets control, either an Initial Script containing an INTERCEPT real-program-name, or typing the INTERCEPT command manually, will provide the source and initial breakpoints. Under Workbench for Eclipse, you can use the Initial Script or the OPEN DDIO tab to provide the source and initial breakpoints.
   • DB2 Batch Attachment Facility Only = RRS
     • If this method is used, the program specified must be AESNBAF0. When Code Debug TSO gets control, either an Initial Script containing an INTERCEPT real-program-name, or typing the INTERCEPT command manually, will provide the source and initial breakpoints. Under Workbench for Eclipse, you can use the Initial Script or the OPEN DDIO tab to provide the source and initial breakpoints.
   • DB2 Batch Attachment Facility Only = N
     • If this (native) method is used, the actual program should be specified and the user must add the following DD card to the step to be tested with Multi-Batch (Mainframe or Workbench for Eclipse):

//ARCTL$MB DD DUMMY

• This DD card will have no effect on the job if it is not being tested with Multi-Batch (meaning that the DD card does not prevent AR/CTL from working).