Use TEST to produce object code that enables Debug Tool to perform batch and interactive debugging.
With TEST, you can also enable the inclusion of symbolic variables in the formatted dumps produced by Language Environment.

TEST option syntax

Option default is: NOTEST

Suboption defaults are: HOOK, NOSEPARATE, NOEJPD

Abbreviations are: SEP|NOSEP

You can specify TEST suboptions in any order, and can specify any combination of suboptions (one, two, or all).
If you code a left parenthesis after TEST, however, you must code at least one suboption.

The amount of debugging support available depends on which TEST suboptions you use, as explained below.
Use NOTEST if you do not want to generate object code that has debugging information and do not require that formatted dumps include symbolic variables.

Hook suboptions (compiled-in versus dynamic hooks)

HOOK

Compiled-in hooks are generated at all statements, labels, and path points, and at all program entry and exit points (both in outermost and in contained programs).
In addition, if the DATEPROC option is in effect, hooks are generated at all date-processing statements.

A path point is any location in a program where the logic flow is not necessarily sequential, or can change.
Some examples of path points are IF-THEN-ELSE constructs, PERFORM loops, ON SIZE ERROR phrases, and CALL statements.

NOHOOK

No compiled-in hooks are generated.
With TEST(NOHOOK), you can use the Dynamic Debug facility of Debug Tool (SET DYNDEBUG ON) to interactively debug your program.

Symbolic debugging information suboptions

Information needed to enable symbolic debugging is always generated if the TEST option is in effect.

SEPARATE

Specify the SEPARATE suboption to control module size while retaining debugging capability.
Symbolic information is written to the SYSDEBUG data set instead of to the object module.
See the section below about controlling module size while retaining debugging capability.

NOSEPARATE

Specify the NOSEPARATE suboption to include symbolic debugging information in the object module.

JUMPTO and GOTO enablement suboptions

The EJPD and NOEJPD suboptions control enablement of the Debug Tool commands JUMPTO and GOTO in production debugging sessions.
These suboptions have an effect only if the TEST(NOHOOK) and OPTIMIZE compiler options are specified.

EJPD

When TEST(NOHOOK,. . .,EJPD) and OPTIMIZE are specified:

• The JUMPTO and GOTO commands are enabled.
• The amount of program optimization is reduced.
  Optimization is done within statements, but most optimizations do not cross statement boundaries.

NOEJPD

When TEST(NOHOOK,. . .,NOEJPD) and OPTIMIZE are specified:

• The JUMPTO and GOTO commands are not enabled.
• The normal amount of program optimization is done.

Controlling module size while retaining debugging capability:

The TEST option causes the compiler to generate debug information tables that Debug Tool uses to resolve data-names, paragraph-names, and the like.
This information can take a lot of storage.
You can choose either to compile this information into the object program or to write it to the separate SYSDEBUG data set:

• For smaller load modules, use the SEPARATE suboption and keep the separate debugging files for use during Debug Tool sessions.
• To avoid having to manage separate debugging files, compile with the NOSEPARATE suboption; note though that this suboption results in larger load modules.

If you invoke the COBOL compiler from JCL or TSO and you specify TEST(. . .,SEPARATE,. . .), the symbolic debug information tables are written to the data set that you specify in the SYSDEBUG DD statement.
For details about coding that statement and about the SYSDEBUG data set, see the related information below about defining the debug data set and about logical record length and block size.

When you invoke the COBOL compiler from the z/OS UNIX shell and you specify TEST(. . .,SEPARATE,. . .), the symbolic debug information tables are written to file.dbg in the current directory, where file is the name of the COBOL source file.

Performance versus debugging capability:

You can control the amount of debugging capability that you get and so also the program performance, as follows:

• For the best performance, but with some restrictions on debugging, compile using OPTIMIZE and TEST(NOHOOK,. . .,NOEJPD).

  When you use the Dynamic Debug facility of Debug Tool (SET DYNDEBUG ON), you can interactively debug your program even if the program has no compiled-in debug hooks.

  With TEST(NOHOOK,. . .,NOEJPD), you can also compile using OPTIMIZE (either OPT(STD) or OPT(FULL)) for a more efficient program, but with some restrictions on debugging:

  • The Debug Tool commands JUMPTO and GOTO are not supported.
  • Except for the DESCRIBE ATTRIBUTES command, Debug Tool commands cannot refer to any data item that was discarded from a program by the OPT(FULL) option.
  • The Debug Tool command AT CALL entry-name is not supported.
• For some reduction in program performance from the production-debugging scenario above, but to enable the Debug Tool commands JUMPTO and GOTO, specify OPTIMIZE and TEST(NOHOOK,. . .,EJPD).

  The restrictions above about referring to items discarded by OPT(FULL) and about the AT CALL command also apply when you use this combination of options.

• For medium performance but fewer restrictions on debugging, specify NOOPT and TEST(NOHOOK).

  This combination does not run as fast as optimized code, but it provides increased debugging capability.
  All Debug Tool commands are supported except AT CALL entry-name.

• For slowest performance but maximum debugging capability, specify NOOPT and TEST(HOOK).

  TEST(HOOK) causes the compiler to put compiled-in hooks at every statement, resulting in slower code, but all Debug Tool commands are supported.

Language Environment:

The TEST option specified with any of its suboptions can improve your formatted dumps from Language Environment by adding these two features to the dumps:

• A line number that indicates the failing statement, rather than just an offset
• The values of the program variables

With NOTEST, the dump will not have program variables nor the line number of the failing statement.

Enterprise COBOL uses the Language Environment-provided dump services to produce dumps that are consistent in content and format with those that are produced by other Language Environment-conforming member languages.

Whether Language Environment produces a dump for unhandled conditions depends on the setting of the runtime option TERMTHDACT.
If you specify TERMTHDACT(DUMP), a dump is generated when a condition of severity 2 or greater goes unhandled.

SEPARATE suboption and Language Environment:

For programs that are compiled using TEST(. . .,SEPARATE,. . .), Language Environment gets the name of the separate debug data set (which is written to ddname SYSDEBUG) from the object program.
To change the name of the separate debug data set, use the Language Environment COBOL debug file exit.