Debugging programs with special conditions of COBOL

This topic discusses how programs with special conditions can be debugged using Code Debug TSO.

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 such as INTERSOLV APS, IBM Cross System Product Application Development (CSP/AD), and CA-Telon, can be compiled with the language processor and debugged with Code Debug TSO at the generated COBOL level. Code generators that produce 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

COBOL programs that are optimized using CA-Optimizer or the OPTIMIZE compiler 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 procedure name or statement number that was streamlined by the optimizer.

An OPT indicator is displayed in the upper right corner of the Code Debug Source screen if the program has been optimized, as shown in the following figure. For COBOL 4.2 and below, OPT will be displayed for any program that was compiled with some level of optimization. For COBOL 6.1 and above, OPT(n,x) (where n is the level of optimization and x is Y if STGOPT was used) will be displayed for all programs, reflecting the optimization level of compiler option OPTIMIZE and the setting of compiler option STGOPT.

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 PMAP and LIST information generated at compile time. When processing the source listing member with the VS COBOL II compiler, the LIST option is required with the OPT option, although the OFFSET option is accepted with the NOOPT option. The CA-Optimizer II is not supported by Code Debug TSO. However, the CA-Optimizer III Releases 5.1 and 6.0 are supported by Code Debug TSO.

Using the TEST Compile Option in IBM Enterprise COBOL V6 and Higher

Two advances in the newest IBM COBOL Compiler, Enterprise COBOL V6, are:

• implementation of modern code optimization
• exploitation of new machine facilities in the newest IBM mainframe processors.

Optimization can improve the performance characteristics of a COBOL program and help reduce its four-hour rolling average (4HRA) usage.

Unfortunately, it’s a well-documented fact that optimization makes debugging more difficult. When using IBM Enterprise COBOL V6 and higher, the optimization process can drastically change the sequential stream of machine instructions generated for each COBOL statement. The result is that, during the optimization process, machine instructions generated for one statement are moved a few COBOL statements before or after the current statement. This optimization process causes seemingly abnormal COBOL statement “jumping” when stepping through COBOL optimized code. This “jumping” effect—although technically correct—is not desirable when using a debugger to step though a program.

TEST Compile Option

Code Debug and CSS have implemented a method of minimizing this “jumping” effect. To use this feature, IBM Enterprise COBOL V6.1 users must specify the COBOL Compile Time option TEST as follows:

The TEST option is required to enable this feature, but BMC’s research has shown that both the EJPD and SOURCE sub-options are not needed and should be turned off by specifying NOEJPD and NOSOURCE as shown above. Sub-options EJPD and SOURCE can be enabled if necessary, but their use is not recommended because they incur additional CPU, memory, and/or disk space overhead beyond what TEST itself adds.

DWARF/NODWARF Compile Sub-Options

IBM Enterprise COBOL V6.2 introduced the DWARF/NODWARF sub-option of the COBOL Compile Time option TEST. Like EJPD and SOURCE, the DWARF sub-option is not desired or utilized. To minimize the “jumping” effect when stepping through optimized COBOL code, it should be disabled as follows:

Specifying all three of these TEST sub-options under COBOL V6 and higher will result in the most optimal CPU, memory, and disk space usage.

For more information on optimization and the use of TEST, see the BMC AMI Enterprise Common Components (ECC) document Getting the Most Out of Your BMC AMI Products – Best Practices Guide for Implementing Source Support.

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.

Subroutine Testing Support

You can debug COBOL subroutines in the unit testing mode or in the integration testing mode. When debugging a COBOL subroutine stand-alone, specify the subroutine name on the test screen. If the subroutine name differs from the load module name, also specify the load module name.

When the source is displayed, you must initialize the Linkage Section by moving in parameters, as if the call had just been made by the driver program. You can facilitate this process and create the source listing member only for the subroutine that you are debugging. Specify the driver program name on the test screen even though there is no source listing available for the driver.

When the debugging session starts, the session log file is displayed, however, the execution status indicates that the program is at the beginning of the driver. Enter a before module breakpoint on the submodule, then resume execution. Code Debug TSO executes the driver, the driver calls the submodule, and the source is displayed as soon as the breakpoint is encountered.

The inserted ACCEPT command can be very useful when you want to initialize Linkage Section values. For information on the ACCEPT command, see the Command-and-syntax-reference.

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 for information about the SET commands.

IMS/DB

Batch programs that make database calls using CALL to CBLTDLI 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 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 Guide.

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 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 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.

When the source is displayed, you will notice that Code Debug TSO defaults to suppressing the Db2-translated statements, except for the initialization statements. The EXEC SQL statements can be optionally expanded to be debugged at the generated COBOL statement level instead of at the EXEC SQL level by using the GEN command. Also, if you are licensed for Code Debug Db2 Extension and File-AID for Db2, you can insert EXEC SQL statements to prototype Db2 calls in addition to browsing and editing Db2 tables while in Code Debug TSO.

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 Guide, 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:

1. USEREXIT CLIST

Invoked from within Code Debug TSO and is panel driven.

2. CLIST to execute DFHDRP

Invoked through TSO. Requires modification for each program to be tested under Code Debug TSO.

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.

Code Debug TSO can debug sort exits for DFSORT and SYNCSORT if you follow these steps:

1. For DFSORT, enter XPDSORT as the program name on the test screen instead of your sort exit program name. XPDSORT is a dummy program supplied by Code Debug TSO to create a link to SORT. You must specify the name of the Code Debug load library on the Load Module Libraries screen. This library contains XPDSORT.

   For SYNCSORT, enter SYNCSORT as the program name on the test screen instead of your sort exit program name. You must specify the name of the SYNCSORT load library on the Load Module Libraries screen. This library contains SYNCSORT.

   The Load Module Libraries screen can be accessed from the Test Setup Menu selected from the Standard test environment screen.

2. Enter the following, plus any parameters required by your specific sort, in the PARM string field of the test screen:

      NOSTIMER

   For DFSORT, specify:

     DEBUG NOESTAE

   using the DFSPARM, SYSIN, or SORTCNTL DD statement.

3. Create an initial test script member that contains the following commands:

   • SET DYNAMIC eeeeeeee

     where eeeeeeee is the name of your sort exit.

     Notes:

     1. Ensure that the specified sort exit exists in the user load library under SETUP.

     2. You must also modify your sort control statement, such as MODS Enn=(eeeeeeee,10,,C), to point to XTASKLIB.

   • SET DYNAMIC xxxxxxxx
     where xxxxxxxx is the name of any dynamically called load module to be debugged.

     Important

     Ensure that the specified load module exists in the user load library under SETUP.

   • BEFORE xxxxxxxx:
     where xxxxxxxx is the name of any module to be debugged, compiled by JCL calling Code Debug TSO.

     Important

     Remember to place a colon (:) at the end to specify that this is a compiled module.

   • AFTER xxxxxxxx:
     where xxxxxxxx is the name of any module to be debugged, compiled by JCL calling Code Debug TSO.

     Important

     Remember to place a colon (:) at the end to specify that this is a compiled module.

   • SET EXCLUDE zzzzzzzz
     where zzzzzzzz is the name of any COBOL module that does VCON modifications.

     Important

     If the sort exit being tested has a load module name different than the CSECT name, use the fully qualified BEFORE and AFTER commands. For example, use the following format:BEFORE load module::SORT_EXIT:

4. Verify that the file allocation list specified on the test screen contains all of your sort work files and sort control statements, either in-stream or in a data set allocated under one of the following DD statements—SYSIN, DFSPARM, SORTCNTL, or $ORTPARM (for SYNCSORT), in addition to the files your application programs are expecting. If you have specified a data set containing JCL, Code Debug TSO will not automatically select the required files. Instead, you will be presented with a list of the JCL. Select the required DDNAMEs from this list.

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 if your application programs would normally find any required Language dependent run-time subroutines (including LE), without being included in the JOBLIB/STEPLIB of the batch JCL (usually from the LINKLIST or (E)LPA), the libraries must still be specified as part of the test session setup. This will ensure that Code Debug’s Task Library will be properly configured. For Batch Connect, the preferred method is to include the run-time libraries in the STEPLIB DD statement concatenations of the JCL steps that are being intercepted.

Third-Party Package Support

Third-Party packages are often written in Assembler language using a non-standard linkage convention. Reset the static call tracing facility by using the SET STATIC OFF command in an initial script so that Code Debug TSO does not monitor the calls.

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).