Rational Developer for System z, Version 7.6

Updating your processes so you can debug programs with Debug Tool

After you have completed the tasks in Planning your debug session, you can use the information you have collected to update the following processes:

For more information about how to update these processes, see the following topics:

Update your compilation, assembly, and linking process

This topic describes the changes you must make to your compilation, assembly, and linking process to implement the choices you made in Planning your debug session. If you are familiar with managing JCL and with your site's compilation or assembly process, see Compiling your program without using Debug Tool Utilities for instructions on the specific changes you need to make. If your site uses Debug Tool Utilities to manage these processes, see Compiling your program by using Debug Tool Utilities for instructions on how to use the Program Preparation option to update these processes.

Compiling your program without using Debug Tool Utilities

Create or modify JCL so that it includes all the statements you need to compile or assemble your programs, then properly link any libraries. The following list describes the changes you need to make:

Table 11. Files that you need to save when compiling with a particular compiler option or suboption
Programming language Compiler suboption or assembler option File you need to save
COBOL
SEPARATE separate debug file
any other listing file
NOTEST listing file containing pseudo-assembler code
non-Language Environment COBOL

Compiling your OS/VS COBOL program

Compiling your VS COBOL II program

EQALANGX
any other listing file containing pseudo-assembler code
PL/I
SEPARATE separate debug file
any other (pre-Enterprise PL/I) listing file
any other (Enterprise PL/I) source file that was used as input to the compiler
NOTEST listing file containing pseudo-assembler code
C/C++
DEBUG(DWARF) file created by this compiler option and source file
TEST source file that was used as input to the compiler
NOTEST listing file containing pseudo-assembler code
assembler
ADATA EQALANGX
no debug information saved listing file containing pseudo-assembler code

After you complete this task, see Update your library and promotion process.

Compiling your program by using Debug Tool Utilities

Debug Tool Utilities provides several utilities than can help you compile your programs and start Debug Tool. The steps described in this topic apply to the following category of compilers and assemblers:

If you are using Debug Tool Utilities to prepare your program and start Debug Tool, read Appendix C. Examples: Preparing programs and modifying setup files with Debug Tool Utilities, which describes how to prepare a sample program and start Debug Tool by using Debug Tool Utilities. After you read the sample and understand how to use Debug Tool Utilities, do the following steps:

  1. Start Debug Tool Utilities.
  2. Type in "1" to select Program Preparation, then press Enter.
  3. Type in the number that corresponds to the compiler you want to use, then press Enter.
  4. Type in the information about the program you are compiling and select the appropriate options for the CICS® and DB2/SQL fields.

    If the program source is a sequential data set and the DB2 precompiler is selected, make sure the DBRMLIB data set field in panel EQAPPC1B, EQAPPC2B, EQAPPC3B, EQAPPC4B, or EQAPPC5B is a partitioned data set with a member name. For example, DEBUG.TEST.DBRMLIB(PROG1).

    Type in the backslash character ("/") in the Enter / to edit options and data set name patterns field, then press Enter.

  5. Using the information you collected in Table 5, fill out the fields with the appropriate values. After you have made all the changes you want to make, press PF3 to save this information and return to the previous panel.
  6. Review the choices you made. Press Enter.
  7. Verify your selections, then press Enter.
  8. After the compilation is done, a panel is displayed. If there were errors in the compilation, review the messages and make any changes. Return to step 1 to repeat the compilation.
  9. Press PF3 until you return to the Program Preparation panel.
  10. In the Program Preparation panel, type in "L", then press Enter.
  11. In the Link Edit panel, specify whether you want the link edit to run in the foreground or background. Specify the name of other libraries you need to link to your program. After you are done making all your changes, press Enter.
  12. Verify any selections, then press Enter.
  13. After the link edit is done, if there were errors in the link edit, review the messages and make any changes. Return to step 1 to repeat the process.
  14. Press PF3 until you return to the main Debug Tool Utilities panel.

After you complete this task, see Update your library and promotion process.

Compiling a Enterprise PL/I program on an HFS file system

If you are compiling and launching Enterprise PL/I programs on an HFS file system, you must do one of the following:

By default, the Enterprise PL/I compiler stores the relative path and file names in the object file. When you start a debug session, if the source is not in the same location as where the program is launched, Debug Tool does not locate the source. To avoid this problem, specify the full path name for the source when you compile the program. For example, if you execute the following series of commands, Debug Tool does not find the source because it is located in another directory (/u/myid/mypgm):

  1. Change to the directory where your program resides and compile the program.
    cd /u/myid/mypgm
    pli -g "//TEST.LOAD(HELLO)" hello.pli
  2. Exit UNIX® System Services and return to the TSO READY prompt.
  3. Launch the program with the TEST run-time option.
    call TEST.LOAD(HELLO) 'test/'

Debug Tool does find the source if you change the compile command to:

pli -g "//TEST.LOAD(HELLO)" /u/myid/mypgm/hello.pli

The same restriction applies to programs that you compile to run in a CICS environment.

Compiling your C program with c89 or c++

If you build your application using the c89 or c++, do the following steps:

  1. Compile your source code as usual, but specify the -g option to generate debugging information. The -g option is equivalent to the TEST compiler option under TSO or MVS batch. For example, to compile the C source file fred.c from the u/mike/app directory, specify:
    cd /u/mike/app
    c89 -g -o "//PROJ.LOAD(FRED)" fred.c
    Note:
    The quotation marks (") in the command line above are required.
  2. Set up your TSO environment, as described above.
  3. Debug the program under TSO by entering the following:
    FRED TEST ENVAR('PWD=/u/mike/app') / asis
    Note:
    The apostrophes (') in the command line above are required. ENVAR('PWD=/u/mike/app') sets the environment variable PWD to the path from where the source files were compiled. Debug Tool uses this information to determine from where it should read the source files.

Compiling a C program on an HFS file system

If you are compiling and launching programs on an HFS file system, you must do one of the following:

By default, the C compiler stores the relative path and file names of the source files in the object file. When you start a debug session, if the source is not in the same location as where the program is launched, Debug Tool does not find the source. To avoid this problem, specify the full path name of the source when you compile the program. For example, if you execute the following series of commands, Debug Tool does not find the source because it is located in another directory (/u/myid/mypgm):

  1. Change to the directory where your program resides and compile the program.
    cd /u/myid/mypgm
    c89 -g -o "//TEST.LOAD(HELLO)" hello.c
  2. Exit UNIX System Services and return to the TSO READY prompt.
  3. Launch the program with the TEST run-time option.
    call TEST.LOAD(HELLO) 'test/'

Debug Tool finds the source if you change the compile command to:

c89 -g -o "//TEST.LOAD(HELLO)" /u/myid/mypgm/hello.c

The same restriction applies to programs that you compile to run in a CICS environment.

Compiling a C++ program on an HFS file system

If you are compiling and launching programs on an HFS file system, you must do one of the following:

By default, the C++ compiler stores the relative path and file names of the source files in the object file. When you start a debug session, if the source is not in the same location as where the program is launched, Debug Tool does not locate the source. To avoid this problem, specify the full path name of the source when you compile the program. For example, if you execute the following series of commands, Debug Tool does not find the source because it is located in another directory (/u/myid/mypgm):

  1. Change to the directory where your program resides and compile the program.
    cd /u/myid/mypgm
    c++ -g -o "//TEST.LOAD(HELLO)" hello.cpp
  2. Exit UNIX System Services and return to the TSO READY prompt.
  3. Launch the program with the TEST run-time option.
    call TEST.LOAD(HELLO) 'test/'

Debug Tool finds the source if you change the compile command to:

c++ -g -o "//TEST.LOAD(HELLO)" /u/myid/mypgm/hello.cpp

The same restriction applies to programs that you compile to run in a CICS environment.

Update your library and promotion process

If you use a library to maintain your program and a promotion process to move programs through levels of quality and testing, you might have to update these processes to ensure that Debug Tool can find the files it needs to obtain information about your programs. For example, if your final production level does not have access to the same libraries as your development level, and you want to be able to debug programs that are in the final product level, you might need to update the environment in your final production level so that it can access to the following resources:

If your source code is being managed by a library system that requires the SUBSYS=ssss parameter when the data set is allocated, you need a custom version of the EQAOPTS options module that specifies the SUBSYS=ssss allocation parameter. This is required for the following types of programs:

This support is not available for CICS programs. See the Debug Tool Customization Guide for details.

Make the modifications necessary to implement your preferred method of starting Debug Tool

In this topic, you will use the information you gathered after completing 2 and Choosing a method or methods for starting Debug Tool to write the TEST runtime options string, then save that string in the appropriate location.

You might have to write several different TEST runtime options strings. For example, the TEST runtime options string that you write for your CICS programs might not be the same TEST runtime options string you can use for your IMS™ programs. For this situation, you might want to use Table 12 to record the string you want to use for each type of program you are debugging.

Table 12. Record the TEST runtime options strings you need for your site
Test runtime options string (for example, TEST(ALL,,,MFI%SYSTEM01.TRMLU001:))
TSO

JES batch

UNIX System Services

CICS

DB2

DB2 stored procedures (PROGRAM TYPE=MAIN)

DB2 stored procedures (PROGRAM TYPE=SUB)

IMS TM

IMS batch

IMS BTS

If you are not familiar with the format of the TEST runtime option string, see the following topics:

After you have written the TEST runtime option strings, you need to save them in the appropriate location. Using the information you recorded in Table 10, review the following list, which directs you to the instructions on where and how to save the TEST runtime options strings:

Through the EQADBCXT, EQADICXT, or EQADDCXT user exit routines
See Specifying the TEST runtime options through the Language Environment user exit.
Through the DFSBXITA user exit routine
See Setting up the DFSBXITA user exit routine.
Using the CADP transaction
See Creating and storing debugging profiles with CADP.
Using the DTCN transaction
See Creating and storing a DTCN profile.
Using the DB2 catalog
See Preparing a DB2 stored procedures program.
By coding a call to CEETEST, __ctest(), or PLITEST
See one of the following topics:
Through CEEUOPT or CEEROPT
See one of the following topics:
Using the CEEOPTS DD statement in JCL or CEEOPTS allocation in TSO
Use the JCL for Batch Debugging option in Debug Tool Utilities.
Using the parms on the EXEC statement when you start your program
When you specify the EXEC statement, include the TEST runtime option as a parameter.
Use the parms on the RUN statement when you start your program
When you specify the RUN statement, include the TEST runtime option as a parameter.
Using the parms on the CALL statement when you start your program
See the example in Starting Debug Tool.
Through the EQASET transaction
See Running the EQASET transaction for non-Language Environment IMS MPPs.
Through the EQANMDBG program
See Starting Debug Tool for programs that start outside of Language Environment.

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)