COBOL TEST Compiler Option: Debug Builds on z/OS

A COBOL abend in test is much easier to fix when the debugger can show the failing statement and variable names. The TEST compiler option tells Enterprise COBOL to create debug information for tools such as IBM z/OS Debugger. NOTEST is the normal choice when a release build does not need that debug data.

Build with debug data.

What is the COBOL TEST compiler option?

TEST controls the debug information produced by the COBOL compiler. IBM describes it as the option used to create the information needed to debug a program, including where that information is placed.

The exact suboptions depend on the compiler level. Enterprise COBOL 6.2 and later support modern combinations such as TEST(SEPARATE,SOURCE,EJPD) and NOTEST(DWARF,SOURCE). Older compilers used other forms, so always check the compile listing for the actual options in effect.

TEST vs NOTEST

Option	Meaning	Typical use
TEST	Produces debug data for source-level debugging.	Unit test, system test, problem recreation, and controlled support builds.
NOTEST	Does not request full source-level debug support.	Normal production builds when source debugging is not required.

Common TEST suboptions

SOURCE and NOSOURCE

SOURCE keeps source information available for the debugger. Use it when a developer needs to step through COBOL statements rather than only inspect offsets or dumps.

SEPARATE and NOSEPARATE

SEPARATE can place debug information outside the main program object for supported compiler levels. That can reduce object size while keeping source-level debugging available, but the separate debug file must be cataloged and available during the debug session.

DWARF and NODWARF

Modern Enterprise COBOL can use DWARF debug information. IBM notes that newer NOTEST combinations can still include DWARF data for tools that use it, depending on the compiler level and selected suboptions.

EJPD and NOEJPD

EJPD supports some debugger actions such as predictable variable changes and certain jump commands when used with selected optimization options. It can affect generated code, so use it only when the debug scenario needs it.

Example compile options

This example shows the intent, not a site standard. Your compile PROC might pass options through a symbolic parameter such as PARM.COBOL.

//COBOL  EXEC PGM=IGYCRCTL,
//             PARM='TEST(SEPARATE,SOURCE,EJPD),LIST,MAP,XREF'
//SYSIN  DD  DSN=DEV.COBOL.SOURCE(ACCT001),DISP=SHR
//SYSLIN DD  DSN=&&OBJ,DISP=(MOD,PASS),UNIT=SYSDA,
//             SPACE=(CYL,(1,1))

For a normal release build, the same site might use NOTEST with the other production compiler options approved by the build team.

When to use TEST

• Use TEST when a developer must debug statement-by-statement in a controlled test environment.
• Use it when a recurring abend needs source lines and variable names to shorten the investigation.
• Use it for support builds only when the debug data is stored and secured according to site rules.
• Use NOTEST when the program is being built for a normal production release and debug data is not required.

Production checks

Do not move a debug build to production just because it passed a test cycle. Check the compile listing, binder listing, load library, and deployment package. If your release process stores debug files separately, confirm they are not lost before a support team needs them.

For online programs, confirm the runtime and debugger setup with the CICS, IMS, or batch support team. A compile option alone does not make every runtime debugging scenario available.

Common mistakes

Assuming TEST is active from the PROC name

A PROC named COBTEST can still pass NOTEST after symbolic substitution. Read the compiler listing to see the final option set.

Losing the separate debug file

If the build uses a separate debug file, keep it cataloged, backed up, and tied to the exact program object. A mismatched debug file can waste hours during an abend call.

Mixing old and new compiler guidance

Enterprise COBOL V3, V4, V5, and V6 do not all use the same TEST suboption rules. Use the documentation for the compiler level shown in the compile listing.

Review checklist

• Confirm the compiler version and maintenance level.
• Check whether the build uses TEST or NOTEST.
• Check whether SOURCE, SEPARATE, DWARF, or EJPD is needed.
• Confirm the debug file location when SEPARATE is used.
• Keep debug data under the same access controls as source and load modules.
• Rebuild after changing compiler options; do not rely on an old load module.

Related Mainframe Forum guides

For nearby topics, read COBOL program compilation process, COBOL SSRANGE compiler option, COBOL RENT compiler option, COBOL ARITH compiler option, COBOL DYNAM compiler option, and COBOL file status.

External references

IBM documents choosing TEST and NOTEST suboptions, compiling with Enterprise COBOL, and compiler option changes in Enterprise COBOL 5 and 6.

FAQ

What does TEST do in COBOL?

TEST tells the compiler to produce debug information that can be used by source-level debugging tools.

Should TEST be used in production?

Usually no. Use production compiler options approved by your build team. Keep TEST for controlled debug and support builds unless your site standard says otherwise.

What is TEST(SEPARATE)?

TEST(SEPARATE) stores supported debug information separately from the main program object, depending on the compiler level and selected suboptions.

What should I check first when debugging does not work?

Read the compile listing. Confirm the compiler version, final TEST or NOTEST option, source suboption, and debug file location.

COBOL Run-Time Performance Options: TEST, TRAP, and VCTRSAVE

A batch job can run the same COBOL load module with different Language Environment options. One run may produce a clean dump for support. Another may start a debugger. A third may save vector registers for a condition handler that almost no program in the shop uses. Those choices affect support, diagnostics, and sometimes elapsed time.

Check options before tuning.

What this COBOL run-time performance post covers

This page covers three options from the old post: TEST, TRAP, and VCTRSAVE. The goal is not to switch every option to the fastest-looking value. The goal is to know what each option does, where it is set, and what to check before changing a production job.

Runtime options versus compiler options

Compiler options are chosen when the program is compiled. Runtime options are chosen when the program runs under Language Environment. A production issue can involve both. For example, the TEST compiler option controls debug data in the program object or separate debug files, while the Language Environment TEST runtime option controls when a debugging tool takes control.

If you need the deeper compiler discussion, see COBOL TEST compiler option. This page stays with the run-time side and the production support tradeoffs.

Quick reference

Option	What it controls	Production note
TEST	When a debug tool can take control of the application.	Use only when the job or region is meant to be debugged.
TRAP	How Language Environment handles abends and program checks.	IBM guidance generally favors TRAP(ON) for normal application runs.
VCTRSAVE	Whether vector state is saved for user condition handlers.	Keep it off unless a real condition handler needs vector state.

TEST runtime option

The Language Environment TEST runtime option controls the conditions under which a debugging tool can take control. It belongs in a controlled test or debug setup, not as a casual setting in a high-volume production batch stream.

Debug readiness can add cost in two places. The program may be compiled with debug data, and the run may include runtime options that let a debugger start. When the job is performance-sensitive, confirm both the compile listing and the runtime options report before blaming COBOL logic.

What to check

• Does the compile listing show TEST or NOTEST?
• Does the runtime options report show a Language Environment TEST setting?
• Is this a production job, a QA run, or a one-time debug run?
• Is the program also compiled with OPT, TEST, EJPD, or related debug suboptions?

TRAP runtime option

TRAP controls whether Language Environment intercepts abends and program interrupts. With TRAP(ON), Language Environment can handle conditions, produce useful diagnostic output, and close resources in a controlled way. IBM warns that TRAP(OFF) can lead to unexpected results.

This is a supportability setting as much as a performance setting. Switching it off to chase a small timing gain can make the next S0C7, S0C4, or arithmetic overflow harder to diagnose. In many shops, TRAP(ON) is the normal setting unless the systems programming team has a specific reason to do otherwise.

Safe production rule

Do not change TRAP alone because one job ran slowly. Capture the current options, look at CPU and elapsed time, check the abend and dump requirements, and involve the team that owns the Language Environment defaults.

VCTRSAVE runtime option

VCTRSAVE controls whether vector state is saved and restored when user condition handlers are called. If the application does not use that function, saving extra state can add needless work around condition handling.

IBM-supplied defaults commonly show VCTRSAVE(OFF). That is a sensible setting for many ordinary COBOL batch programs. Turn it on only when the application, a called routine, or a user-written condition handler really needs the vector environment preserved.

How to see the options used by a job

Do not rely only on a standard sheet from ten years ago. Check what the current job actually used. Language Environment can report runtime options with RPTOPTS(ON), and COBOL runtime-specific options can also be reported depending on the COBOL level and site setup.

//STEP1    EXEC PGM=PAYMAIN,
//             PARM='RPTOPTS(ON),TRAP(ON)'
//STEPLIB  DD  DSN=PAYROLL.LOADLIB,DISP=SHR
//SYSOUT   DD  SYSOUT=*
//CEEDUMP  DD  SYSOUT=*

Your site may set options through PARM=, CEEOPTS, IGZOPTS, runtime option modules, or region defaults. If two places set the same option, the final report is the evidence to use.

When performance tuning is the wrong first move

These options can matter, but a slow job is often slow for a simpler reason: too many file reads, bad sort placement, missing Db2 statistics, repeated dynamic calls, or avoidable table scans. Runtime options should be checked after you know where the time is going.

For related COBOL tuning topics, read COBOL performance tuning tips, COBOL DYNAM compiler option, and COBOL RENT compiler option.

Production checklist

• Capture elapsed time and CPU time before any option change.
• Save the compile listing for the program being tested.
• Run with RPTOPTS(ON) in a controlled test job if allowed.
• Confirm whether TEST is needed for the current run.
• Keep TRAP(ON) unless your site has a documented exception.
• Keep VCTRSAVE(OFF) unless vector state must be saved for condition handlers.
• Record the final setting in the job documentation or change ticket.

Common mistakes

Confusing compile TEST with runtime TEST

A program can be compiled one way and run another way. Check both sides before deciding why debug behavior or timing changed.

Turning off TRAP without a dump plan

The next abend may lose the diagnostic path that support depends on. Do not trade away problem determination unless the site standard clearly permits it.

Changing options without a baseline

If you do not have CPU, elapsed time, input volume, and the current options report, you cannot tell whether the change helped.

Related COBOL posts

• COBOL Run-Time Performance Part 1
• COBOL TEST Compiler Option
• COBOL DYNAM Compiler Option
• COBOL RENT Compiler Option
• COBOL SSRANGE Compiler Option
• COBOL ARITH Compiler Option

FAQ

Should TEST be used in production COBOL jobs?

Use it only when the run is meant for debugging or when your site standard requires specific debug data. For normal high-volume production work, confirm that debug settings are intentional.

Is TRAP(ON) slower?

For many applications, TRAP(ON) is kept because the diagnostic value matters. Do not switch to TRAP(OFF) without testing and a clear dump-handling reason.

When is VCTRSAVE(ON) needed?

It is needed when user condition handlers depend on the vector environment. Ordinary COBOL batch programs often do not need it.

How do I confirm the active runtime options?

Use a controlled run with option reporting such as RPTOPTS(ON), if your site allows it, and review the Language Environment options report in the job output.

References

• IBM: Using Language Environment runtime options
• IBM: Language Environment runtime options
• IBM: Specifying COBOL runtime options