Product features

Code Debug TSO are debugging and testing tools for COBOL, Assembler, PL/I, and C programs. Code Debug automates the tasks of identifying problems, applying solutions, analyzing the impact of changes, and testing the fixes.

Compiling and assembling your programs, test session setup procedures, and Code Debug commands are compatible across languages, with some differences.

When you have COBOL, Assembler, PL/I, and/or C language versions installed at your site, Code Debug TSO allows you to debug mixed applications in the same test session.

Code Debug TSO  and Code Debug IMSare debugging and testing tools for COBOL, Assembler, PL/I, and C programs. Code Debug automates the tasks of identifying problems, applying solutions, analyzing the impact of changes, and testing the fixes.

Compiling and assembling your programs, test session setup procedures, and Code Debug commands are compatible across languages, with some differences.

When you have COBOL, Assembler, PL/I, and/or C language versions installed at your site, Code Debug TSO allows you to debug mixed applications in the same test session.

Modes of operation

There are two modes in which you can invoke a Code Debug TSO debugging session:

• Interactive mode
• Batch mode

Interactive mode

In this mode, you can interactively allocate the necessary files and databases required for the program to execute, set up the test session environment options, and optionally override any Code Debug defaults. As you watch your program execute, you can use interactive source-level debugging functions such as stepping through the source, setting breakpoints, displaying and modifying variables, etc.

Interactive mode is preferable when you have a specific problem for which you want to dynamically try out a solution.

Batch mode

There are two ways to invoke a Code Debug TSO debugging session in batch mode:

• Batch menu. Access the Batch menu by selecting option 3 (BATCH) on the Primary Menu. From the Batch menu, you can utilize the following facilities:
  • Batch Connect facility.
    Through the Batch Connect facility, your execution JCL is automatically submitted to MVS and you can connect directly to the job as it executes in its native environment—the MVS batch initiator.
    The Batch Connect facility automates the setup and file allocations, displays the job steps in the specified JCL, and lets you select the steps to which you want to interactively connect and those that you want to run in unattended batch. The Batch Connect JCL scanner automatically expands the JCL and inserts the necessary statements to run each step according to how you want it to be processed.
    With the Batch Connect facility, you get the benefit of submitting the job in batch, which uses less processor resources, and you can test programs with multiple steps, programs that require tape files and many I/O operations in background, and long running programs.
  • Multi-Batch Facility.
    The Multi-Batch Facility (MBF) also enables you to connect to a submitted batch job, see the source, and manipulate data as it executes in its native environment. You create one or more Multi-Batch entries for interactive or unattended debugging in which you specify the jobname, stepname, program, and (optionally) an initial script. When you submit your existing test or production JCL, Code Debug will automatically intercept matching programs and begin a debugging session.
• Manually changing your execution JCL.
  Although the Batch Connect facility is the preferred method for running a job in batch, you can manually access your execution JCL and make changes to convert the JCL to run with Code Debug TSO in unattended or interactive (Batch Connect) modes.

Interactive debugging and testing features

When your program is executed under interactive Code Debug TSO, the source is displayed in a fully scrollable window where you can view the inner workings of the program as each statement is executed. For instance, you can see the execution arrow moving from a branch instruction to the label specified in another section of the code.

The following figure shows the Source Display screen under Code Debug TSO. All debugging and testing functions are accessible from this screen without having to exit to a separate screen.

Code Debug TSO does not require any source code or load module changes; however, you need to create a “symbolic” information data set called the source listing file to debug at the source level. The source listing is created by compiling your programs with the Common Shared Services Assembler language processor (LP). Code Debug TSO displays and processes the source listing records during the test session.

Assembler Program in the Source Display Screen

The capabilities of Code Debug TSO are extensive enough to assist the experienced programmers’ needs, and yet, the implementation is simple enough and efficient enough to curtail the learning curve that novice programmers generally experience. The following list summarizes Code Debug TSO’s major features:

• Intercept program abends.
  Code Debug TSO detects application abends and displays a diagnostic message. You can request an Abend-AID formatted report if you have Abend-AID. You can also view the session log for more information. If the problem is a recoverable error, you can fix the error dynamically and resume execution.
• Start or stop execution at any point.
  You can set conditional or unconditional breakpoints, so you can stop program execution at any point and figure out what the program has processed so far, and what the consequences of any changes could be. You can also step through code, line by line, to understand how each statement affects the program.
• Display and modify variable, register, and storage contents.
  You can view the values of any variable as your program executes, and if you want, alter the values as if the program had actually moved in the value you requested. Tables can be displayed by dimension, and you can browse through each entry by incrementing and decrementing the subscript. You can also display general-purpose registers and memory to analyze the problem at the lower level.
• Trace logic flow.
  Statements can be highlighted to identify the execution path as Code Debug TSO traces through the program. You can control the speed of the execution so that you can follow the logic interactively at a speed that best suits you.
• Monitor execution coverage.
  You can set counters on statements to test execution coverage or to monitor loops and procedure calls for optimization.
• Alter logic.
  You can dynamically change the control flow by modifying the data values or by forcing a branch to test an alternate path.
• Bypass unwanted code.
  You can skip a range of statements or programs.
• Temporarily insert Code Debug TSO debugging statements.
  You can insert Code Debug TSO commands to control debugging conditions that occur at a certain location and to force data and logic changes. This feature lets you prototype some Assembler-like constructs. If you have Code Debug Db2 Extension and File-AID for Db2, you can also insert SQL statements.
• Display file status and DCBs.
  VSAM file status and last I/O operation can be retrieved through Code Debug TSO. DCB information can also be checked in the case of I/O error. When a DD statement is not preallocated, Code Debug TSO intercepts execution and gives you an opportunity to allocate the missing files before resuming execution.
• Test and debug programs that do not have the source available.
• Test multiple CSECT programs.
• Test programs with labels exceeding 8 characters.
• Test Assembler programs that are AMODE=31, RMODE=ANY.
• Display PSW and control blocks.
• Select the display format of the line command area from absolute address, offset, or statement number.
• Display called module stacking.
  The called module configuration such as the load address, entry point, size, attribute, AMODE, RMODE, and language can be retrieved.
• Maintain multiple profiles.

Code Debug TSO’s Profile Handling facility provides a flexible and easy-to-use method for using and maintaining multiple profiles. Multiple profiles are used because some of the data you see during a Code Debug TSO debugging session depends on the current profile. This includes installation defaults established by your system programming staff, and most importantly, environment parameters and setup options for the debugging session.

Code Debug TSO input and output

The primary input to Code Debug TSO is the following:

1. DDIO libraries containing the source listing members.

2. Load libraries containing the programs to be tested and debugged.

   Important

   The source listing data set and your load libraries are the output of the compile and link process.

3. JCL, file list, or CLIST that can be processed to allocate the input files and databases needed by your program.
4. Optionally, a test script library.

The primary output of the debugging session is the following:

1. Data files generated by the execution of the program.
2. Session log.
   Code Debug TSO automatically records (to the session log file) the commands entered and the responses made to each command during a debugging session. The session log data set can have an LRECL of 133 or 80. The session log does not contain the interactive manipulation commands (e.g., LEFT, RIGHT, UP, DOWN) nor does it contain the actual program displays.
   In unattended batch mode, the session log file shows the output of a batch test and is available after the completion of the debugging session. In interactive mode, it is available at all times.
   The session log file can be kept as part of the documentation, to be referenced whenever maintenance is performed on the program. It can be viewed for further information in determining the cause and possible resolution of an abend. Handling Run-Time Errors contains a discussion of the session log display.
3. Test script containing the commands that were entered during the test session.
   After the session is terminated, you can save, copy, or move the generated script to a member of a script library (INCLUDE data set), which can then be used as input to another debugging session.

Types of programs supported

Code Debug TSO supports the following types of programs:

• Standard batch applications
• ISPF dialog box applications
• Batch applications that issue database calls (IDMS, IMS/DB, Db2, IDMS/DB, ADABAS, and SUPRA)
• IMS/DC programs using BTS
• Hogan applications (BATCHPEM, DLIPEM, BMPPEM, and IMSPEM)

Code Debug IMS supports the following types of programs:

• IMS/DC programs executing in the IMS message, BMP, or Fast Path region
• Hogan applications executing in the IMS message region

LOGON region size requirements

Debugging with Code Debug TSO may require an increase to the default TSO LOGON region size. This provides protection against abends caused by insufficient space.

See Displaying Available Memory (REGION SIZE) for region recommendations.

It has been our experience that 2048K to 4096K (2M to 4M) is sufficient size for debugging most applications.

Restrictions and warnings

The following list explains some of the technical restrictions and questions related to the functioning of Code Debug TSO:

Compiler options:

Code Debug  requires specific compile options which may vary depending on the language type and actual version being used. A user should always see the appropriate Common Shared Services User/Reference Guide for information related to any required compiler options. Examples are as follows: (1) Options NOTEST and NONUMBER are required for COBOL; (2) Option NOTEST is required for PL/I; and (3) Options ESD and LIST are required for Assembler. The Guide is required to assist users in manually converting Compile and Link JCL to execute the CSS Language Processor. The Guide also gives most users information on how to set up the Language Processor parameters to write a matching source listing to a DDIO file.

Postprocessed listing support:

When the postprocessed listing contains a PRINT NOGEN statement, the Code Debug TSO commands FIND, PEEK, and KEEP will not work correctly.

The postprocessed source listing must be compiled with the compile options required by Code Debug TSO; otherwise, unpredictable results can occur.

Attention (User interrupt—PA1 key) processing:

The use of the PA1 key (user interrupt) from within Code Debug TSO can sometimes cause a recursive abend.

Split screen:

When running Code Debug with the LE/370 run-time libraries with TRAP ON, do not split the screen and run another application that uses the LE/370 libraries. An abend may occur.

Multitasking support:

BMC does not support multitasking applications within Code Debug TSO, except in the dialog box environment, where single task testing is supported within a multitasking environment.

Self-modifying programs:

Code Debug’s ability to debug an application program is based on its inherent knowledge of the object module. Self-modifying code that changes opcodes, displacements, or operands is not supported for testing under Code Debug.

Optimized code:

Code Debug TSO displays the source for optimized code as it was originally written, but executes the code generated by the optimizer. As a result, depending on the optimizing algorithm applied to the code, the following can occur:

• Highlighting during execution of the trace of the optimized code can be misleading.
• Values displayed by the KEEP and PEEK commands may not be updated according to the program logic.
• Abends can occur when you use Code Debug TSO commands such as GOTO and SKIP that alter the program execution paths. These abends occur when the altered execution paths are in conflict with path dependencies generated by the optimizer.

IMS testing:

• When an application program is scheduled into an IMS MPP or BTS simulated MPP region, none of the breakpoints are retained from a previous test. Once the application program is scheduled, the breakpoints are retained until the application program returns to the IMS program controller, unless RETAIN IMS BREAKPOINTS was specified for the test.
• If you are not using the IMS User ID support, transactions specified on the test MPP screen are queued to run in the Code Debug TSO region regardless of where the transactions were initiated. Code Debug TSO assigns a unique class to each of the specified transaction codes and forces them to run only in your Code Debug TSO region. The transaction codes are not reassigned to their original class until you have completely finished testing in the MPP region.
• If a DLI program uses the XRST facility, the first DLI call must be the XRST call. Otherwise, you can cause an abend 04E with reason code 00D44054.
• Within a BTS/DLI setup, recovery of Db2 tables and IMS databases are uncoordinated. An SQL COMMIT/ROLLBACK call commits or rolls back changes made to Db2 tables only, not your IMS databases.
• Code Debug TSO forces on the PARDLI parameter in the BMP environment.
• When using the PWFI option, the testing dynamics are different than a non-PWFI test. In a non-PWFI test, a return code is returned after the GU from the message queue when there are no more messages. The PWFI test will wait for input at the GU to the message queue.

MVS/ESA support:

All nonprivileged ESA instructions are supported except when executing in the access register mode. Code Debug should not be invoked in access register mode.

High level assembler support:

Reassembling Assembler F and H programs with High Level Assembler is supported. Code Debug TSO does not support the new High Level Assembler features.

Naming convention:

Program names should not begin with IBM reserved prefixes such as IHO, ILBO, IGZ, and so on.

Memory allocations:

User programs and other vendor packages that perform FREEMAINs on subpool=0 or subpool=3 are not supported.

Link options:

Code Debug TSO does not support the NE or OVLY linkage editor parameters.

Abend intercepts:

Code Debug TSO does not support programs that issue (E)STAE or (E)SPIE macros.

Additional Assembler restrictions:

The following capabilities are not available with Assembler:

• Debugging authorized programs.
• Tracing backwards in a review mode.
• Enhanced FIND (search data flow and program structure).
• Structure sensitive breakpoints.
• Intercepting unallocated files.
• Displaying file attributes.

Non-supported Code Debug restrictions:

Self-Modifying Programs

Self-modifying Assembler programs are not supported.

XCTL (Transfer Control Macro) or SVC 7

Code Debug TSO provides limited support for the Transfer Control Supervisor Call. The first program intercepted cannot issue an SVC 7. Subsequent programs that are intercepted may issue an SVC 7.

Code Debug TSO and Code Debug IMS are debugging and testing tools for COBOL, Assembler, PL/I, and C programs. Code Debug automates the tasks of identifying problems, applying solutions, analyzing the impact of changes, and testing the fixes. Compiling and assembling your programs, test session setup procedures, and Code Debug commands are compatible across languages, with some differences.

When you have COBOL, Assembler, PL/I, and/or C Language versions installed at your site, Code Debug TSO allows you to debug mixed applications in the same test session.

Modes of operation for C

There are two modes in which you can invoke a Code Debug TSO debugging session:

• Interactive mode
• Batch mode.

Interactive mode

In this mode, you can interactively allocate the necessary files and databases required for the program to execute, set up the test session environment options, and optionally override any Code Debug  defaults. As you watch your program execute, you can use interactive source-level debugging functions such as stepping through the source, setting breakpoints, displaying and modifying variables, etc.

Interactive mode is preferable when you have a specific problem for which you want to dynamically try out a solution.

Batch mode

There are two ways to invoke a Code Debug TSO debugging session in batch mode:

• Batch menu. Access the Batch menu by selecting option 3 (BATCH) on the Primary Menu. From the Batch menu, you can utilize the following facilities:
  • Batch Connect facility.

Through the Batch Connect facility, your execution JCL is automatically submitted to MVS and you can connect directly to the job as it executes in its native environment—the MVS batch initiator.

The Batch Connect facility automates the setup and file allocations, displays the job steps in the specified JCL, and lets you select the steps to which you want to interactively connect and those that you want to run in unattended batch. The Batch Connect JCL scanner automatically expands the JCL and inserts the necessary statements to run each step according to how you want it to be processed.

With the Batch Connect facility, you get the benefit of submitting the job in batch, which uses less processor resources, and you can test programs with multiple steps, programs that require tape files and many I/O operations in background, and long running programs.

• Multi-Batch Facility.

The Multi-Batch Facility (MBF) also enables you to connect to a submitted batch job, see the source, and manipulate data as it executes in its native environment. You create one or more Multi-Batch entries for interactive or unattended debugging in which you specify the jobname, stepname, program, and (optionally) an initial script. When you submit your existing test or production JCL,  Code Debug will automatically intercept matching programs and begin a debugging session.

• Manually changing your execution JCL.

Although the Batch Connect facility is the preferred method for running a job in batch, you can manually access your execution JCL and make changes to convert the JCL to run with Code Debug TSO in unattended or interactive (Batch Connect) modes.

Interactive debugging and testing features

When your program is executed under interactive Code Debug TSO, the source is displayed in a fully scrollable window where you can view the inner workings of the program as each program is executed. For instance, you can see the execution arrow moving from a function invocation to the actual function, or you can see a variable changing its value as the ASSIGN takes place.

The following figure shows the Source display screen under Code Debug TSO. All debugging and testing functions are accessible from this screen without having to exit to a separate screen.

Code Debug TSO does not require any source code or load module changes; however, you need to create a “symbolic” information data set called the source listing file to debug at the source level. The source listing is created by compiling your programs with the BMC AMI Common Shared Services C language processor. Code Debug TSO displays and processes the source listing records during the test session.

C Program in the Source Display Screen

The capabilities of Code Debug TSO are extensive enough to assist the experienced programmers’ needs, and yet, the implementation is simple enough and efficient enough to curtail the learning curve that novice programmers generally experience. The following list summarizes Code Debug TSO’s major features:

• Intercept program abends.
  Code Debug TSO detects application abends and displays a diagnostic message. You can request an Abend-AID formatted report if you have Abend-AID. You can also view the session log for more information. If the problem is a recoverable error, you can fix the error dynamically and resume execution.

• Start or stop execution at any point.
  You can set conditional or unconditional breakpoints, so you can stop program execution at any point and figure out what the program has processed so far, and what the consequences of any changes could be. You can also step through code, line by line, to understand how each statement affects the program.

• Display and modify variable, register, and storage contents.
  You can view the values of any variable as your program executes, and if you want, alter the values as if the program had actually moved in the value you requested. Arrays can be displayed by dimension, and you can browse through each entry by incrementing and decrementing the subscript. You can also display general-purpose registers and memory to analyze the problem at the lower level.

• Trace logic flow.
  Statements can be highlighted to identify the execution path as Code Debug TSO traces through the program. You can control the speed of the execution so that you can follow the logic interactively at a speed that best suits you.

• Monitor execution coverage.
  You can set counters on statements to test execution coverage or to monitor loops and procedure calls for optimization.

• Alter logic.
  You can dynamically change the control flow by modifying the data values or by forcing a branch to test an alternate path.

• Bypass unwanted code.
  You can skip a range of statements or programs.

• Temporarily insert Code Debug TSO debugging statements.
  You can insert Code Debug TSO commands to control debugging conditions that occur at a certain location and to force data and logic changes. This feature lets you prototype some COBOL-like constructs.

• Test and debug programs that do not have the source available.
• Display called module stacking.
  The called module configuration such as the load address, entry point, size, attribute, AMODE, RMODE, and language can be retrieved.
• Maintain multiple profiles.
  Code Debug TSO’s Profile Handling facility provides a flexible and easy-to-use method for using and maintaining multiple profiles. Multiple profiles are used because some of the data you see during a Code Debug TSO debugging session depends on the current profile. This includes installation defaults established by your system programming staff, and most importantly, environment parameters and setup options for the debugging session.

Code Debug TSO input and output

The primary input to Code Debug TSO is the following:

1. DDIO libraries containing the source listing members.

2. Load libraries containing the programs to be tested and debugged.

   Important

   The source listing data set and your load libraries are the output of the compile and link process.

3. JCL, file list, or CLIST that can be processed to allocate the input files and databases needed by your program
4. Optionally, a test script library.

The primary output of the debugging session is the following:

1. Data files generated by the execution of the program.
2. Session log.
   Code Debug TSO automatically records (to the session log file) the commands entered and the responses made to each command during a debugging session. The session log data set can have an LRECL of 133 or 80. The session log does not contain the interactive manipulation commands (e.g., LEFT, RIGHT, UP, DOWN) nor does it contain the actual program displays.
   In unattended batch mode, the session log file shows the output of a batch test and is available after the completion of the debugging session. In interactive mode, it is available at all times.
   The session log file can be kept as part of the documentation, to be referenced whenever maintenance is performed on the program. It can be viewed for further information in determining the cause and possible resolution of an abend. For additional information about the session log file, see the Handling Run-Time Errors for a discussion of the session log display.
3. Test script containing the commands that were entered during the test session.
   After the session is terminated, you can save, copy, or move the generated script to a member of a script library (INCLUDE data set), which can then be used as input to another debugging session.

Types of programs supported

Code Debug TSO supports the following types of programs:

• Standard batch applications
• ISPF dialog box applications
• Batch applications that issue database calls (IDMS, IMS/DB, Db2, IDMS/DB, ADABAS, and SUPRA)
• IMS/DC programs using BTS

Code Debug IMS supports the following types of programs:

• IMS/DC programs executing in the IMS message, BMP, or Fast Path region

LOGON region size requirements for C

Debugging with Code Debug TSO may require an increase to the default TSO LOGON region size. This provides protection against abends caused by insufficient space.

See Displaying Available Memory (REGION SIZE) for region recommendations.

It has been our experience that 2048K to 4096K (2M to 4M) is sufficient size for debugging most applications.

Restrictions and warnings for C

The following list explains some of the technical restrictions and questions related to the functioning of Code Debug TSO:

Postprocessed Listing Support:

The postprocessed source listing must be compiled with the same compile options required by Code Debug TSO for preprocessing; otherwise, post-processing will fail.

Attention (User Interrupt—PA1 Key) Processing:

The use of the PA1 key (user interrupt) from within Code Debug TSO can sometimes cause a recursive abend.

Split Screen:

When running Code Debug with the LE/370 run-time libraries with TRAP ON, do not split the screen and run another application that uses the LE/370 libraries. An abend may occur.

Multitasking Support:

Multitasking applications are not supported within Code Debug TSO, except in the dialog box environment, where single task testing is supported within a multitasking environment.

Self-Modifying Programs:

Code Debug’s ability to debug an application program is based on its inherent knowledge of the object module. Self-modifying code that changes opcodes, displacements, or operands is not supported for testing under Code Debug.

Optimized Code:

Code Debug TSO displays the source for optimized code as it was originally written, but executes the code generated by the optimizer. As a result, depending on the optimizing algorithm applied to the code, the following can occur:

• Highlighting during execution of the trace of the optimized code can be misleading.
• Values displayed by the KEEP and PEEK commands may not be updated according to the program logic.
• Abends can occur when you use Code Debug TSO commands such as GOTO and SKIP that alter the program execution paths. These abends occur when the altered execution paths are in conflict with path dependencies generated 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.

IMS Testing:

• When an application program is scheduled into an IMS MPP or BTS simulated MPP region, none of the breakpoints are retained from a previous test, unless RETAIN IMS BREAKPOINTS was specified for the test. Once the application program is scheduled, the breakpoints are retained until the application program returns to the IMS program controller.
• If you are not using the IMS User ID support, transactions specified on the test MPP screen are queued to run in the Code Debug TSO region regardless of where the transactions were initiated. Code Debug TSO assigns a unique class to each of the specified transaction codes and forces them to run only in your Code Debug TSO region. The transaction codes are not reassigned to their original class until you have completely finished testing in the MPP region.
• If a DLI program uses the XRST facility, the first DLI call must be the XRST call. Otherwise, you can cause an abend 04E with reason code 00D44054.
• Within a BTS/DLI setup, recovery of Db2 tables and IMS databases are uncoordinated. An SQL COMMIT/ROLLBACK call commits or rolls back changes made to Db2 tables only, not your IMS databases.
• Code Debug TSO forces on the PARDLI parameter in the BMP environment.
• If you are experiencing system abends while using the BTS TRACE to monitor Db2 activity, check with IBM for fixes available for the BTS program product. Problems have occurred in MVS/XA IMS 1.3 and BTS 1.3, as well as MVS/ESA IMS 3.1 and BTS 3.1.
• When using the PWFI option, the testing dynamics are different than a non-PWFI test. In a non-PWFI test, a return code is returned after the GU from the message queue when there are no more messages. The PWFI test will wait for input at the GU to the message queue.

Naming Convention:

Program names should not begin with IBM reserved prefixes such as IHO, ILBO, IGZ, and so on.

Memory Allocations:

User programs and other vendor packages that perform FREEMAINs on subpool=0 or subpool=3 are not supported.

Link Options:

Code Debug TSO does not support the NE or OVLY linkage editor parameters.

Abend Intercepts:

Code Debug TSO does not support programs that issue (E)STAE or (E)SPIE macros.

SP C:

User Programs utilizing the System Programming C Facility are not supported

Optimizing With IPA:

User programs requesting Interprocedural Analysis are not supported.

Code Debug TSO and Code Debug IMSare debugging and testing tools for COBOL, PL/I, Assembler, and C language programs. Code Debug automates the tasks of identifying problems, applying solutions, analyzing the impact of changes, and testing the fixes.

Compiling and assembling your programs, test session setup procedures, and Code Debug commands are compatible across languages, with some differences.

When you have COBOL, Assembler, PL/I, and/or C language versions installed at your site, Code Debug TSO allows you to debug mixed applications in the same test session.

Modes of Operation

There are two modes in which you can invoke a Code Debug TSO debugging session:

• Interactive mode
• Batch mode.

Interactive Mode

In this mode, you can interactively allocate the necessary files and databases required for the program to execute, set up the test session environment options, and optionally override any Code Debug defaults. As you watch your program execute, you can use interactive source-level debugging functions such as stepping through the source, setting breakpoints, displaying and modifying variables, etc.

Interactive mode is preferable when you have a specific problem for which you want to dynamically try out a solution.

Batch Mode

There are two ways to invoke a Code Debug TSO debugging session in batch mode:

• Batch menu. Access the Batch menu by selecting option 3 (BATCH) on the Primary Menu. From the Batch menu, you can utilize the following facilities:

  • Batch Connect facility.

    Through the Batch Connect facility, your execution JCL is automatically submitted to MVS and you can connect directly to the job as it executes in its native environment—the MVS batch initiator.

    The Batch Connect facility automates the setup and file allocations, displays the job steps in the specified JCL, and lets you select the steps to which you want to interactively connect and those that you want to run in unattended batch. The Batch Connect JCL scanner automatically expands the JCL and inserts the necessary statements to run each step according to how you want it to be processed.

    With the Batch Connect facility, you get the benefit of submitting the job in batch, which uses less processor resources, and you can test programs with multiple steps, programs that require tape files and many I/O operations in background, and long running programs.

  • Multi-Batch Facility.

    The Multi-Batch Facility (MBF) also enables you to connect to a submitted batch job, see the source, and manipulate data as it executes in its native environment. You create one or more Multi-Batch entries for interactive or unattended debugging in which you specify the jobname, stepname, program, and (optionally) an initial script. When you submit your existing test or production JCL, Code Debug will automatically intercept matching programs and begin a debugging session.

• Manually changing your execution JCL.

  Although the Batch Connect facility is the preferred method for running a job in batch, you can manually access your execution JCL and make changes to convert the JCL to run with Code Debug TSO in unattended or interactive (Batch Connect) modes.

Interactive Debugging and Testing Features

When your program is executed under interactive Code Debug TSO, the source is displayed in a fully scrollable window where you can view the inner workings of the program as each statement is executed. For example, you can see the execution arrow moving from a PERFORM statement to the actual out-of-line perform paragraph, or you can see a data identifier changing its value as the MOVE, INITIALIZE, STRING, or COMPUTE statements are executed.

The following figure shows the Source display screen under Code Debug TSO. All debugging and testing functions are accessible from this screen without having to exit to a separate screen.

Code Debug TSO does not require any source code or load module changes; however, you need to create a “symbolic” information data set called the source listing file to debug at the source level. The source listing is created by compiling your programs with the BMC AMI Common Shared Services COBOL language processor. Code Debug TSO displays and processes the source listing records during the test session.

COBOL Program in the Source Display Screen

The capabilities of Code Debug TSO are extensive enough to assist the experienced programmers’ needs, and yet, the implementation is simple enough and efficient enough to curtail the learning curve that novice programmers generally experience. The following list summarizes Code Debug TSO’s major features:

• Intercept program abends.

  Code Debug TSO detects application abends and displays a diagnostic message. You can request an Abend-AID formatted report if you have Abend-AID. You can also view the session log for more information. If the problem is a recoverable error, you can fix the error dynamically and resume execution.

• Start or stop execution at any point.

  You can set conditional or unconditional breakpoints, so you can stop program execution at any point and figure out what the program has processed so far, and what the consequences of any changes could be. You can also step through code, line by line, to understand how each statement affects the program.

• Display and modify variable, register, and storage contents.

  You can view the values of any variable as your program executes, and if you want, alter the values as if the program had actually moved in the value you requested. Tables can be displayed by dimension, and you can browse through each entry by incrementing and decrementing the subscript. You can also display general-purpose registers and memory to analyze the problem at the lower level.

• Trace logic flow.

  Statements can be highlighted to identify the execution path as Code Debug TSO traces through the program. You can control the speed of the execution so that you can follow the logic interactively at a speed that best suits you.

• Logically review execution in the reverse direction.

  Code Debug TSO can display the execution history in the reverse direction so you can review the execution path with associated data values. The execution arrow moves backwards, and the data display shows the original values.

• Monitor execution coverage.

  You can set counters on statements to test execution coverage or to monitor loops and procedure calls for optimization.

• Alter logic.

  You can dynamically change the control flow by modifying the data values or by forcing a branch to test an alternate path.

• Bypass unwanted code.

  You can skip a range of statements or programs.

• Temporarily insert Code Debug TSO debugging statements.

  You can insert Code Debug TSO commands to control debugging conditions that occur at a certain location and to force data and logic changes. This feature lets you prototype some COBOL-like constructs. If you have Code Debug Db2 Extension and File-AID for Db2, you can also insert SQL statements.

• Analyze program structure and data flow.

  Code Debug TSO identifies certain program structures (conditionals, branches, I/Os, statements that alter data values, etc.) by highlighting the applicable statements when requested. Also, statements that make references (MODIFY or USE) to a particular data item can be identified.

• Display file status and DCBs.

  VSAM file status and last I/O operation can be retrieved through Code Debug TSO. DCB information can also be checked in the case of I/O error. When a DD statement is not preallocated, Code Debug TSO intercepts execution and gives you an opportunity to allocate the missing files before resuming execution.

• Test and debug programs that do not have the source available.

• Display called module stacking.

  The called module configuration such as the load address, entry point, size, attribute, AMODE, RMODE, and language can be retrieved.

• Maintain multiple profiles.

  Code Debug TSO’s Profile Handling facility provides a flexible and easy-to-use method for using and maintaining multiple profiles. Multiple profiles are used because some of the data you see during an Code Debug TSO debugging session depends on the current profile. This includes installation defaults established by your system programming staff, and most importantly, environment parameters and setup options for the debugging session.

Code Debug TSO Input and Output

The primary input to Code Debug TSO is the following:

1. DDIO libraries containing the source listing members.

2. Load libraries containing the programs to be tested and debugged.

   Important

   The source listing data set and your load libraries are the output of the compile and link process.

3. JCL, file list, or CLIST that can be processed to allocate the input files and databases needed by your program.
4. Optionally, a test script library.

The primary output of the debugging session is the following:

1. Data files generated by the execution of the program.

2. Session log.

   Code Debug TSO automatically records (to the session log file) the commands entered and the responses made to each command during a debugging session. The session log data set can have an LRECL of 133 or 80. The session log does not contain the interactive manipulation commands (e.g., LEFT, RIGHT, UP, DOWN) nor does it contain the actual program displays.

   In unattended batch mode, the session log file shows the output of a batch test and is available after the completion of the debugging session. In interactive mode, it is available at all times.

   The session log file can be kept as part of the documentation, to be referenced whenever maintenance is performed on the program. It can be viewed for further information in determining the cause and possible resolution of an abend. Handling Run-Time Errors contains a discussion of the session log display.

3. Test script containing the commands that were entered during the test session.

   After the session is terminated, you can save, copy, or move the generated script to a member of a script library (INCLUDE data set), which can then be used as input to another debugging session.

Types of Programs Supported

Code Debug TSO supports the following types of programs:

• Standard batch applications
• ISPF dialog box applications
• Batch applications that issue database calls (IDMS, IMS/DB, Db2, IDMS/DB, ADABAS, and SUPRA)
• IMS/DC programs using BTS
• Hogan applications (BATCHPEM, DLIPEM, BMPPEM, and IMSPEM)

Code Debug IMS supports the following types of programs:

• IMS/DC programs executing in the IMS message, BMP, or Fast Path region
• Hogan applications executing in the IMS message region

LOGON Region Size Requirements

Debugging with Code Debug TSO may require an increase to the default TSO LOGON region size. This provides protection against abends caused by insufficient space.

See Displaying Available Memory (REGION SIZE) for region recommendations.

It has been our experience that 2048K to 4096K (2M to 4M) is sufficient size for debugging most applications.

Restrictions and Warnings

The following list explains some of the technical restrictions and questions related to the functioning of Code Debug TSO:

Compiler Options:

Code Debug requires specific compile options which may vary depending on the language type and actual version being used. A user should always see  Common Shared Services User/Reference Guide for information related to any required compiler options. Examples are as follows: (1) Options NOTEST and NONUMBER are required for COBOL; (2) Option NOTEST is required for PL/I; and (3) Options ESD and LIST are required for Assembler. The Guide is required to assist users in manually converting Compile and Link JCL to execute the CSS Language Processor. The Guide also gives most users information on how to set up the Language Processor parameters to write a matching source listing to a DDIO file.

Postprocessed Listing Support:

When the postprocessed listing contains a COPY SUPPRESS statement, the Code Debug TSO commands FIND, PEEK, and KEEP will not work correctly.

The postprocessed source listing must have been compiled with the compile options required by Code Debug TSO; otherwise, unpredictable results can occur.

Attention (User Interrupt—PA1 Key) Processing:

The use of the PA1 key (user interrupt) from within Code Debug TSO can sometimes cause a recursive abend.

Split Screen:

When running Code Debug with the LE/370 run-time libraries with TRAP ON, do not split the screen and run another application that uses the LE/370 libraries. An abend may occur.

Multitasking Support:

BMC does not support multitasking applications within Code Debug TSO, except in the dialog box environment, where single task testing is supported within a multitasking environment.

Self-Modifying Programs:

Code Debug’s ability to debug an application program is based on its inherent knowledge of the object module. Self-modifying code that changes opcodes, displacements, or operands is not supported for testing under Code Debug.

Optimized Code:

Code Debug TSO displays the source for optimized code as it was originally written, but executes the code generated by the optimizer. As a result, depending on the optimizing algorithm applied to the code, the following can occur:

• Highlighting during execution of the trace of the optimized code can be misleading.
• Values displayed by the KEEP and PEEK commands may not be updated according to the program logic.
• Abends can occur when you use Code Debug TSO commands such as GOTO and SKIP that alter the program execution paths. These abends occur when the altered execution paths are in conflict with path dependencies generated by the optimizer.
• If you used Copy Suppress in the Procedure Division, you might not be able to set a breakpoint on the first statement following the copied code.

OPT is displayed in the upper right corner of the Code Debug Source screen if the program has been optimized.

IMS Testing:

• When an application program is scheduled into an IMS MPP or BTS simulated MPP region, none of the breakpoints are retained from a previous test, unless RETAIN IMS BREAKPOINTS was specified for the test. Once the application program is scheduled, the breakpoints are retained until the application program returns to the IMS program controller.
• If you are not using the IMS UserID support, transactions specified on the test MPP screen are queued to run in the Code Debug TSO region regardless of where the transactions were initiated. Code Debug TSO assigns a unique class to each of the specified transaction codes and forces them to run only in your Code Debug TSO region. The transaction codes are not reassigned to their original class until you have completely finished testing in the MPP region.
• If a DLI program uses the XRST facility, the first DLI call must be the XRST call. Otherwise, you can cause an abend 04E with reason code 00D44054.
• Within a BTS/DLI setup, recovery of Db2 tables and IMS databases are uncoordinated. An SQL COMMIT/ROLLBACK call commits or rolls back changes made to Db2 tables only, not your IMS databases.
• Code Debug TSO forces on the PARDLI parameter in the BMP environment.
• If you are experiencing system abends while using the BTS TRACE to monitor Db2 activity, check with IBM for fixes available for the BTS program product. Problems have occurred in MVS/XA IMS 1.3 and BTS 1.3, as well as MVS/ESA IMS 3.1 and BTS 3.1.
• When using the PWFI option, the testing dynamics are different than a non-PWFI test. In a non-PWFI test, a return code is returned after the GU from the message queue when there are no more messages. The PWFI test will wait for input at the GU to the message queue.

Naming Convention:

Program names should not begin with IBM reserved prefixes such as IHO, ILBO, IGZ, and so on.

COBOL Ready Trace:

Unpredictable results can occur in Code Debug TSO when the COBOL READY TRACE command is used.

Memory Allocations:

User programs and other vendor packages that perform FREEMAINs on subpool=0 or subpool=3 are not supported.

Link Options:

Code Debug TSO does not support the NE or OVLY linkage editor parameters.

Abend Intercepts:

Code Debug TSO does not support programs that issue (E)STAE or (E)SPIE macros.

Code Debug TSO are debugging and testing tools for COBOL, Assembler, PL/I, and C programs. Code Debug automates the tasks of identifying problems, applying solutions, analyzing the impact of changes, and testing the fixes. Compiling and assembling your programs, test session setup procedures, and Code Debug commands are compatible across languages, with some differences. When you have COBOL, Assembler, PL/I, and/or C language versions installed at your site, Code Debug TSO  allows you to debug mixed applications in the same test session.

Modes of operation

There are two modes in which you can invoke a Code Debug TSO debugging session:

• Interactive mode
• Batch mode.

Interactive mode

In this mode, you can interactively allocate the necessary files and databases required for the program to execute, set up the test session environment options, and optionally override any Code Debug defaults. As you watch your program execute, you can use interactive source-level debugging functions such as stepping through the source, setting breakpoints, displaying and modifying variables, etc.

Interactive mode is preferable when you have a specific problem for which you want to dynamically try out a solution.

Batch mode

There are two ways to invoke a Code Debug TSO debugging session in batch mode:

• Batch menu. Access the Batch menu by selecting option 3 (BATCH) on the Primary Menu. From the Batch menu, you can utilize the following facilities:
  • Batch Connect facility.

Through the Batch Connect facility, your execution JCL is automatically submitted to MVS and you can connect directly to the job as it executes in its native environment—the MVS batch initiator.

The Batch Connect facility automates the setup and file allocations, displays the job steps in the specified JCL, and lets you select the steps to which you want to interactively connect and those that you want to run in unattended batch. The Batch Connect JCL scanner automatically expands the JCL and inserts the necessary statements to run each step according to how you want it to be processed.

With the Batch Connect facility, you get the benefit of submitting the job in batch, which uses less processor resources, and you can test programs with multiple steps, programs that require tape files and many I/O operations in background, and long running programs.

• 
  
  • Multi-Batch Facility.

The Multi-Batch Facility (MBF) also enables you to connect to a submitted batch job, see the source, and manipulate data as it executes in its native environment. You create one or more Multi-Batch entries for interactive or unattended debugging in which you specify the jobname, stepname, program, and (optionally) an initial script. When you submit your existing test or production JCL, Code Debug will automatically intercept matching programs and begin a debugging session.

• Manually changing your execution JCL.

Although the Batch Connect facility is the preferred method for running a job in batch, you can manually access your execution JCL and make changes to convert the JCL to run with Code Debug TSO in unattended or interactive (Batch Connect) modes.

Interactive debugging and testing features

When your program is executed under interactive Code Debug TSO, the source is displayed in a fully scrollable window where you can view the inner workings of the program as each statement is executed. For instance, you can see the execution arrow moving from a CALL statement to the actual procedure, or you can see a variable changing its value as the ASSIGN takes place.

The following figure shows the Source display screen under Code Debug TSO. All debugging and testing functions are accessible from this screen without having to exit to a separate screen.

Code Debug TSO does not require any source code or load module changes; however, you need to create a “symbolic” information data set called the source listing file to debug at the source level. The source listing is created by compiling your programs with the BMC AMI Common Shared Services PL/I language processor. Code Debug TSO displays and processes the source listing records during the test session.

PL/I Program in the Source Display Screen

The capabilities of Code Debug TSO are extensive enough to assist the experienced programmers’ needs, and yet, the implementation is simple enough and efficient enough to curtail the learning curve that novice programmers generally experience. The following list summarizes Code Debug TSO’s major features:

• Intercept program abends.

Code Debug TSO detects application abends and displays a diagnostic message. You can request an Abend-AID formatted report if you have Abend-AID. You can also view the session log for more information. If the problem is a recoverable error, you can fix the error dynamically and resume execution.

• Start or stop execution at any point.

You can set conditional or unconditional breakpoints, so you can stop program execution at any point and figure out what the program has processed so far, and what the consequences of any changes could be. You can also step through code, line by line, to understand how each statement affects the program.

• Display and modify variable, register, and storage contents.

You can view the values of any variable as your program executes, and if you want, alter the values as if the program had actually moved in the value you requested. Arrays can be displayed by dimension, and you can browse through each entry by incrementing and decrementing the subscript. You can also display general-purpose registers and memory to analyze the problem at the lower level.

• Trace logic flow.

Statements can be highlighted to identify the execution path as Code Debug TSO traces through the program. You can control the speed of the execution so that you can follow the logic interactively at a speed that best suits you.

• Monitor execution coverage.

You can set counters on statements to test execution coverage or to monitor loops and procedure calls for optimization.

• Alter logic.

You can dynamically change the control flow by modifying the data values or by forcing a branch to test an alternate path.

• Bypass unwanted code.

You can skip a range of statements or programs.

• Temporarily insert Code Debug TSO debugging statements.

You can insert Code Debug TSO commands to control debugging conditions that occur at a certain location and to force data and logic changes. This feature lets you prototype some PL/I-like constructs. If you have Code Debug for Db2 Extension and File-AID for Db2, you can also insert SQL statements.

• Display file status and DCBs.

VSAM file status and last I/O operation can be retrieved through Code Debug TSO. DCB information can also be checked in the case of I/O error. When a DD statement is not preallocated, Code Debug TSO intercepts execution and gives you an opportunity to allocate the missing files before resuming execution.

• Test and debug programs that do not have the source available.
• Display called module stacking.

The called module configuration such as the load address, entry point, size, attribute, AMODE, RMODE, and language can be retrieved.

• Maintain multiple profiles.

Code Debug TSO’s Profile Handling facility provides a flexible and easy-to-use method for using and maintaining multiple profiles. Multiple profiles are used because some of the data you see during a Code Debug TSO debugging session depends on the current profile. This includes installation defaults established by your system programming staff, and most importantly, environment parameters and setup options for the debugging session.

Code Debug TSO input and output

The primary input to Code Debug TSO is the following:

1. DDIO libraries containing the source listing members.

2. Load libraries containing the programs to be tested and debugged.

   Important

   The source listing data set and your load libraries are the output of the compile and link process.

3. JCL, file list, or CLIST that can be processed to allocate the input files and databases needed by your program.
4. Optionally, a test script library.

The primary output of the debugging session is the following:

1. Data files generated by the execution of the program.
2. Session log.
   Code Debug TSO automatically records (to the session log file) some of the commands entered and the responses made to each command during a debugging session. The session log data set can have an LRECL of 133 or 80. The session log does not contain the interactive manipulation commands (e.g., LEFT, RIGHT, UP, DOWN) nor does it contain the actual program displays.
   
   In unattended batch mode, the session log file shows the output of a batch test and is available after the completion of the debugging session. In interactive mode, it is available at all times.
   
   The session log file can be kept as part of the documentation, to be referenced whenever maintenance is performed on the program. It can be viewed for further information in determining the cause and possible resolution of an abend. Handling Run-Time Errors contains a discussion of the session log display.
3. Test script containing the commands that were entered during the test session.
   After the session is terminated, you can save, copy, or move the generated script to a member of a script library (INCLUDE data set), which can then be used as input to another debugging session.

Types of programs supported

Code Debug TSO supports the following types of programs:

• Standard batch applications
• ISPF dialog box applications
• Batch applications that issue database calls (IDMS, IMS/DB, Db2, IDMS/DB, ADABAS, and SUPRA)
• IMS/DC programs using BTS
• Hogan applications (BATCHPEM, DLIPEM, BMPPEM, and IMSPEM).

Code Debug IMS supports the following types of programs:

• IMS/DC programs executing in the IMS message, BMP, or Fast Path region
• Hogan applications executing in the IMS message region.

LOGON region size requirements

Debugging with Code Debug TSO may require an increase to the default TSO LOGON region size. This provides protection against abends caused by insufficient space.

See Displaying Available Memory (REGION SIZE) for region recommendations.

It has been our experience that 2048K to 4096K (2M to 4M) is sufficient size for debugging most applications.

Restrictions and warnings

The following list explains some of the technical restrictions and questions related to the functioning of Code Debug TSO:

Compiler Options:

Code Debug requires specific compile options which may vary depending on the language type and actual version being used. A user should always see to the BMC AMI Common Shared Services User/Reference Guide for information related to any required compiler options. Examples are as follows: (1) Options NOTEST and NONUMBER are required for COBOL; (2) Option NOTEST is required for PL/I; and (3) Options ESD and LIST are required for Assembler. The Guide is required to assist users in manually converting Compile and Link JCL to execute the CSS Language Processor. The Guide also gives most users information on how to set up the Language Processor parameters to write a matching source listing to a DDIO file.

Postprocessed Listing Support:

When the postprocessed listing contains a COPY SUPPRESS statement, the Code Debug TSO commands FIND, PEEK, and KEEP will not work correctly.

The postprocessed source listing must have been compiled with the compile options required by Code Debug TSO; otherwise, unpredictable results can occur.

Attention (User Interrupt—PA1 Key) Processing:

The use of the PA1 key (user interrupt) from within Code Debug TSO can sometimes cause a recursive abend.

Split Screen:

When running Code Debug with the LE/370 run-time libraries with TRAP ON, do not split the screen and run another application that uses the LE/370 libraries. An abend may occur.

Multitasking Support:

BMC does not support multitasking applications within Code Debug TSO, except in the dialog box environment, where single task testing is supported within a multitasking environment.

Self-Modifying Programs:

Code Debug’s ability to debug an application program is based on its inherent knowledge of the object module. Self-modifying code that changes opcodes, displacements, or operands is not supported for testing under Code Debug.

Optimized Code:

Code Debug TSO displays the source for optimized code as it was originally written, but executes the code generated by the optimizer. As a result, depending on the optimizing algorithm applied to the code, the following can occur:

• Highlighting during execution of the trace of the optimized code can be misleading.
• Values displayed by the KEEP and PEEK commands may not be updated according to the program logic.
• Abends can occur when you use Code Debug TSO commands such as GOTO and SKIP that alter the program execution paths. These abends occur when the altered execution paths are in conflict with path dependencies generated 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.

IMS Testing:

• When an application program is scheduled into an IMS MPP or BTS simulated MPP region, none of the breakpoints are retained from a previous test, unless RETAIN IMS BREAKPOINTS was specified for the test. Once the application program is scheduled, the breakpoints are retained until the application program returns to the IMS program controller.
• If you are not using the IMS User ID support, transactions specified on the test MPP screen are queued to run in the Code Debug TSO region regardless of where the transactions were initiated. Code Debug TSO assigns a unique class to each of the specified transaction codes and forces them to run only in your Code Debug TSO region. The transaction codes are not reassigned to their original class until you have completely finished testing in the MPP region.
• If a DLI program uses the XRST facility, the first DLI call must be the XRST call. Otherwise, you can cause an abend 04E with reason code 00D44054.
• Within a BTS/DLI setup, recovery of Db2 tables and IMS databases are uncoordinated. An SQL COMMIT/ROLLBACK call commits or rolls back changes made to Db2 tables only, not your IMS databases.
• Code Debug TSO forces on the PARDLI parameter in the BMP environment.
• If you are experiencing system abends while using the BTS TRACE to monitor Db2 activity, check with IBM for fixes available for the BTS program product. Problems have occurred in MVS/XA IMS 1.3 and BTS 1.3, as well as MVS/ESA IMS 3.1 and BTS 3.1.
• When using the PWFI option, the testing dynamics are different than a non-PWFI test. In a non-PWFI test, a return code is returned after the GU from the message queue when there are no more messages. The PWFI test will wait for input at the GU to the message queue.

Naming Convention:

Program names should not begin with IBM reserved prefixes such as IHO, ILBO, IGZ, and so on.

Memory Allocations:

User programs and other vendor packages that perform FREEMAINs on subpool=0 or subpool=3 are not supported.

Link Options:

Code Debug TSO does not support the NE or OVLY linkage editor parameters.

Abend Intercepts:

Code Debug TSO does not support programs that issue (E)STAE or (E)SPIE macros.

PL/I:

The compiler for PL/I is somewhat different in the way it handles certain aspects of the language. One such difference involves the method by which statements are identified. Historically, each PL/I statement was given a unique statement number for identification in the various elements of the compiler output. With a PL/I compilation, however, the identification is less finite, with only the file and line number being used to discern between language constructs.

Because this mechanism is somewhat awkward when using Code Debug, the BMC Language Processor instead associates each file and line number combination with a single sequential line number. It is this generated line number which is used by Code Debug with PL/I programs as the replacement notation for statement number.

As a result, references to the term “statement” in Code Debug documentation, messages, and panels actually refer to the line construct (which may contain multiple statements) in a PL/I environment.