The instructions in this section apply to programs that run in Language Environment. For programs that do not run in Language Environment, refer to the instructions in Starting Debug Tool for programs that start outside of Language Environment.
This topic describes some of the factors you should consider when you use the TEST runtime option, provides examples, and describes other runtime options you might need to specify. The syntax of the TEST runtime option is described in the topic TEST run-time option in Debug Tool Reference and Messages.
To specify how Debug Tool gains control of your application and begins a debug session, you use the TEST run-time option. The simplest form of the TEST option is TEST with no suboptions specified; however, suboptions provide you with more flexibility. There are four types of suboptions available, summarized below.
When you use the TEST run-time option, there are several implications to consider, which are described in this section.
In C, C++ or PL/I, you can define TEST with suboptions using a #pragma runopts or PLIXOPT string, then specify TEST with no suboptions at run time. This causes the suboptions specified in the #pragma runopts or PLIXOPT string to take effect.
You can change the TEST/NOTEST run-time options at any time with the SET TEST command.
Some suboptions are disabled with NOTEST, but are still allowed. This means you can start your program using the NOTEST option and specify suboptions you might want to take effect later in your debug session. The program begins to run without Debug Tool taking control.
To enable the suboptions you specified with NOTEST, start Debug Tool during your program’s run time by using a library service call such as CEETEST, PLITEST, or the __ctest() function.
If the test level in effect causes Debug Tool to gain control at a condition or at a particular program location, an implicit breakpoint with no associated action is assumed. This occurs even though you have not previously defined a breakpoint for that condition or location using an initial command string or a primary commands file. Control is given to your terminal or to your primary commands file.
The primary commands file acts as a surrogate terminal. After it is accessed as a source of commands, it continues to act in this capacity until all commands have been run or the application has ended. This differs from the USE file in that, if a USE file contains a command that returns control to the program (such as STEP or GO), all subsequent commands are discarded. However, USE files started from within a primary commands file take on the characteristics of the primary commands file and can be run until complete.
The initial command list, whether it consists of a command string included in the run-time options or a primary commands file, can contain a USE command to get commands from a secondary file. If started from the primary commands file, a USE file takes on the characteristics of the primary commands file.
In batch mode, when the end of your commands file is reached, a GO command is run at each request for a command until the program terminates. If another command is requested after program termination, a QUIT command is forced.
If Debug Tool is started during program initialization, it is started before all the instructions in the main prolog are run. At that time, no program blocks are active and references to variables in the main procedure cannot be made, compile units cannot be called, and the GOTO command cannot be used. However, references to static variables can be made.
If you enter the STEP command at this point, before entering any other commands, both program and Language Environment initialization are completed and you are given access to all variables. You can also enter all valid commands.
If Debug Tool is started while your program is running (for example, by using a CEETEST call), it might not be able to find all compile units associated with your application. Compile units located in load modules that are not currently active are not known to Debug Tool, even if they were run prior to Debug Tool’s initialization.
For example, suppose load module mod1 contains compile units cu1 and cu2, both compiled with the TEST option. The compile unit cu1 calls cux, contained in load module mod2, which returns after it completes processing. The compile unit cu2 contains a call to the CEETEST library service. When the call to CEETEST initializes Debug Tool, only cu1 and cu2 are known to Debug Tool. Debug Tool does not recognize cux.
The initial command string is run only once, when Debug Tool is first initialized in the process.
Commands in the preferences file are run only once, when Debug Tool is first initialized in the process.
The session log stores the commands entered and the results of the execution of those commands. The session log saves the results of the execution of the commands as comments. This allows you to use the session log as a commands file.
Refer to the following topics for more information related to the material discussed in this topic.
The Language Environment run-time options have the following order of precedence (from highest to lowest):
If the object module for the source program is input to the linkage editor before the CEEUOPT object module, then these options override CEEUOPT defaults. You can force the order in which objects modules are input by using linkage editor control statements.
Suboptions are processed in the following order:
Refer to the following topics for more information related to the material discussed in this topic.
The following examples of using the TEST run-time option are provided to illustrate run-time options available for your programs. They do not illustrate complete commands. The complete syntax of the TEST run-time option can be found in the Debug Tool Reference and Messages.
If you specify NOTEST and control has returned from the program in which Debug Tool first became active, you can no longer debug non-Language Environment programs or detect non-Language Environment events.
If no other definitions for the suboptions exist, the IBM-supplied default suboptions are (ALL, *, PROMPT, INSPREF).
TEST(,,,TCPIP&machine.somewhere.something.com%8001:*) TEST(,,,TCPIP&9.24.104.79%8001:*) NOTEST(,,,TCPIP&9.24.111.55%8001:*)
Refer to the following topics for more information related to the material discussed in this topic.
There are two additional run-time options that you might need to specify to debug COBOL and PL/I programs: STORAGE and TRAP(ON).
The STORAGE run-time option controls the initial content of storage when allocated and freed, and the amount of storage that is reserved for the "out-of-storage" condition. When you specify one of the parameters in the STORAGE run-time option, all allocated storage processed by the parameter is initialized to that value. If your program does not have self-initialized variables, you must specify the STORAGE run-time option.
The TRAP(ON) run-time option is used to fully enable the Language Environment condition handler that passes exceptions to the Debug Tool. Along with the TEST option, it must be used if you want the Debug Tool to take control automatically when an exception occurs. You must also use the TRAP(ON) run-time option if you want to use the GO BYPASS command and to debug handlers you have written. Using TRAP(OFF) with the Debug Tool causes unpredictable results to occur, including the operating system cancelling your application and Debug Tool when a condition, abend, or interrupt is encountered.
The TEST run-time option can be specified either when you start your program, or directly in your source by using this #pragma:
#pragma runopts (test(suboption,suboption...))
This #pragma must appear before the first statement in your source file. For example, if you specified the following in the source:
#pragma runopts (notest(all,*,prompt))
then entered TEST on the command line, the result would be
TEST(ALL,*,PROMPT).
TEST overrides the NOTEST option specified in the #pragma and, because TEST does not contain any suboptions of its own, the suboptions ALL, *, and PROMPT remain in effect.
If you link together two or more compile units with differing #pragmas, the options specified with the first compile are honored. With multiple enclaves, the options specified with the first enclave (or compile unit) started in each new process are honored.
If you specify options on the command line and in a #pragma, any options entered on the command line override those specified in the #pragma unless you specify NOEXECOPS. Specifying NOEXECOPS, either in a #pragma or with the EXECOPS compiler option, prevents any command line options from taking effect.
Refer to the following topics for more information related to the material discussed in this topic.