TEST

Use TEST to produce object code that enables debugging with problem determination tools such as IBM® z/OS® Debugger and Fault Analyzer. With TEST, you can also enable the inclusion of symbolic variables in the formatted dumps that are produced by Language Environment®.

TEST option syntax

Read syntax diagramSkip visual syntax diagramNOTESTTEST(,DWARFNODWARFEJPDNOEJPDSEPARATE(DSNAMENODSNAME)NOSEPARATESOURCENOSOURCE)

Default is: Start of changeNOTEST(NODWARF, NOSOURCE, NOSEPARATE)End of change

Suboption defaults are:
  • Start of changeNODWARF, NOSOURCE, NOSEPARATEEnd of change when NOTEST is specified with no suboptions
  • Start of changeNOEJPD, DWARF, SOURCE, NOSEPARATEEnd of change when TEST is specified with no suboptions

Abbreviations are: None

Suboption abbreviation are: Start of change
  • NOSO | SO for SOURCE | NOSOURCE
  • NOSEP | SEP for SEPARATE | NOSEPARATE
End of change

Start of change
DWARF | NODWARF
If TEST(DWARF) is in effect, complete DWARF diagnostic information is included in the object program, or a separate debug file when the SEPARATE suboption is in effect. This option enables the best usability for application failure analysis tools, such as CEEDUMP and IBM Fault Analyzer.
When NOTEST(DWARF) is in effect, the debugging information is a subset of the DWARF information that is available with TEST(DWARF). The DWARF diagnostic information that is produced when NOTEST(DWARF) is in effect cannot be used with IBM z/OS Debugger. Consider using NOTEST(DWARF) when use of the debugger is not needed and you want to avoid the performance implications of the TEST option while having improved usability for application failure analysis tools, such as CEEDUMP and IBM Fault Analyzer.
Debugging information generated by the compiler is in the industry-standard DWARF format. For more information about DWARF, see About Common Debug Architecture in the DWARF/ELF Extensions Library Reference.
If NODWARF is in effect, DWARF diagnostic information is not included in the object program, or written to a separate debug file.
Notes:
  • SOURCE and SEPARATE are not allowed with NODWARF.
  • If you specify the DWARF suboption of TEST or NOTEST, you must set the CODEPAGE option to the CCSID that is used for the COBOL source program. Programs that use Japanese characters in DBCS literals or DBCS user-defined words must be compiled with the CODEPAGE option set to a Japanese codepage CCSID. For more information, see CODEPAGE.
EJPD | NOEJPD
EJPD and NOEJPD control enablement of the IBM z/OS Debugger commands JUMPTO and GOTO in production debugging sessions. EJPD and NOEJPD only take effect if you specify the TEST option and a non-zero OPTIMIZE level (OPTIMIZE(1) or OPTIMIZE(2)).
If you specify TEST(EJPD) and a non-zero OPTIMIZE level:
  • 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.
If you specify TEST(NOEJPD) and a non-zero OPTIMIZE level:
  • The JUMPTO and GOTO commands are not enabled, but you can use JUMPTO and GOTO if you use the SET WARNING OFF IBM z/OS Debugger command. In this scenario, JUMPTO and GOTO will have unpredictable results.
  • The normal amount of program optimization is done.
Note: EJPD is not allowed with NOTEST.
SOURCE | NOSOURCE
If you specify SOURCE, the DWARF debugging information generated by the compiler includes the expanded source code.
Note: SOURCE is not allowed if NODWARF is specified.
If you specify NOSOURCE, the generated DWARF debugging information does not include the expanded source code. You will not be able to debug using the IBM z/OS Debugger with TEST(NOSOURCE).
Start of changeSEPARATE[(DSNAME|NODSNAME)]End of change | NOSEPARATE
Start of changeThe default is SEPARATE(NODSNAME) when SEPARATE is specified with no suboptions.End of change
Specify SEPARATE or Start of changeSEPARATE(NODSNAME)End of change to control program object size on disk (NOSEPARATE does not affect the size of the loaded program object) while retaining debugging capability. Generated DWARF debugging information is written to the SYSDEBUG data set instead of to the object program. See the section below about controlling module size while retaining debugging capability.
Start of changeIf SEPARATE(DSNAME) is in effect, the SYSDEBUG dataset name used during compilation is stored in the object program. This name will be used as the default at run time when DWARF information is required. The dataset name can be overridden by using the SYSDEBUG COBOL debug file user exit, IGZIUXB. Note that when NODSNAME is in effect, the IGZIUXB user exit provides the only mechanism of locating the DWARF debugging information for the program.
Notes:
  • SEPARATE is not allowed if NODWARF is specified.
  • Support for debugging DWARF debugging information in the SYSDEBUG data set with the IBM debugger requires any of the tools at the following levels:
    • IBM Debug for z Systems® V14.1 (5655-Q50) (formerly IBM Debug Tool for z/OS) or later
    • IBM Developer for z Systems V14.1 (5724-T07) or later
    • IBM Application Delivery Foundation for z Systems V3.1 (5655-AC6) or later
End of change
Specify NOSEPARATE to include generated DWARF debugging information in the object program.
End of change

Start of change Controlling module size while retaining debugging capability:End of change

Start of change The DWARF suboption of TEST causes the compiler to generate debug information tables that IBM z/OS Debugger 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 executables, use the SEPARATE suboption and keep the separate debugging files for use during IBM z/OS Debugger sessions.
  • To avoid having to manage separate debugging files, compile with the NOSEPARATE suboption; note that this suboption results in larger object programs on DASD. The size when loaded into virtual storage is not increased by use of the NOSEPARATE option.
End of change

Start of changeIf you invoke the COBOL compiler from JCL or TSO and you specify NOTEST|TEST(...,SEPARATE,...), the DWARF debugging information is 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. End of change

Start of changeWhen you invoke the COBOL compiler from the z/OS UNIX shell and you specify NOTEST|TEST(...,SEPARATE,...), the DWARF debugging information is written to file.dbg in the current directory, where file is the name of the COBOL source file.End of change

Performance versus debugging capability:

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

  • For the best performance, but with some restrictions on debugging, compile using a non-zero OPTIMIZE level, STGOPT and TEST(NOEJPD).
    • The IBM z/OS Debugger commands JUMPTO and GOTO are not supported. However, you can still use JUMPTO and GOTO if you use the SET WARNING OFF IBM z/OS Debugger command. In this scenario, JUMPTO and GOTO will have unpredictable results.
    • Except for the DESCRIBE ATTRIBUTES command, IBM z/OS Debugger commands cannot refer to any data item that was discarded from a program by the STGOPT option.
    • The IBM z/OS Debugger command AT CALL entry-name is not supported.
  • For some reduction in program performance from the production-debugging scenario above, but to enable predictable behavior for the IBM z/OS Debugger commands JUMPTO and GOTO, specify a non-zero OPTIMIZE level and TEST(EJPD).

    The restrictions above about referring to items discarded by the STGOPT option, and about the AT CALL command also apply when you use a non-zero OPTIMIZE level and TEST(EJPD).

  • For slowest performance but maximum debugging capability, specify OPTIMIZE(0), NOSTGOPT and TEST.

    The OPTIMIZE(0) option causes the compiler to generate slower code, but all IBM z/OS Debugger commands are supported.

Language Environment:

The TEST option specified with any of its suboptions, Start of changeand NOTEST with DWARFEnd of change, 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 variablesStart of change (if DWARF is in effect)End of change

With Start of changeDWARFEnd of change, the dump will have program variables and the line number of the failing statement. With Start of changeNODWARFEnd of change, 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.

Note: IBM z/OS Debugger is a component of the following products:
  • IBM Developer for z Systems Enterprise Edition (included in IBM Application Delivery Foundation for z Systems)
  • IBM Debug for z Systems (formerly IBM Debug Tool for z/OS)
  • Start of changeIBM Developer for z SystemsEnd of change
To find out which IBM debug product best suits your needs, see https://www.ibm.com/support/knowledgecenter/SSQ2R2_14.0.0/com.ibm.debugtool.doc/common/dcompo.html.

related concepts
DWARF/ELF Extensions Library Reference (About Common Debug Architecture)

related tasks  
Defining the debug data set (SYSDEBUG)
  
Using the debugger  
Suppressing information in CEEDUMP processing  
Generating a Language Environment dump with TERMTHDACT (Language Environment Debugging Guide)
Special considerations while using the TEST runtime option (Debug Tool User's Guide)

related references  
Logical record length and block size
cob2 input and output files  
Conflicting compiler options  
OPTIMIZE  
TEST | NOTEST (Language Environment Programming Reference)