TEST

TEST option syntax

Default is: NOTEST(NODWARF, NOSOURCE, NOSEPARATE)

Abbreviations are: None

Suboption abbreviation are:

• NOSO | SO for SOURCE | NOSOURCE
• NOSEP | SEP for SEPARATE | NOSEPARATE

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).

SEPARATE[(DSNAME|NODSNAME)] | NOSEPARATE

The default is SEPARATE(NODSNAME) when SEPARATE is specified with no suboptions.

Specify SEPARATE or SEPARATE(NODSNAME) 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.

If 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

Specify NOSEPARATE to include generated DWARF debugging information in the object program.

Controlling module size while retaining debugging capability:

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.

If 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.

When 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.

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, and NOTEST with DWARF, 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 (if DWARF is in effect)

With DWARF, the dump will have program variables and the line number of the failing statement. With NODWARF, 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.

LLA/VLF managed programs where DWARF diagnostic information is included:

When DWARF diagnostic information is included in the object program because of the TEST(NOSEPARATE) or other equivalent options and the program is staged to VLF, the information cannot be extracted from the program. The execution JCL requires the use of the IGZLOAD DD, the STEPLIB DD, or both to specify the location of any LLA/VLF managed libraries from which the application will load programs that have been staged to VLF. Otherwise, the COBOL variable information and the statement numbers in the traceback will be missing in the CEEDUMP and a diagnostic message will appear in the CEEDUMP. For more information, see Diagnostic messages in CEEDUMPs for IBM Enterprise COBOL for z/OS.

For each program staged to VLF, the following steps are taken to extract the DWARF diagnostic information:

1. The COBOL Runtime checks for the allocation of the IGZLOAD DD. It then checks if the library is associated with the IGZLOAD DD contains a member, for example, a COBOL program, whose name matches the program staged to VLF.
2. If the previous step was unsuccessful because the IGZLOAD DD was not allocated or the member was not found, the same process is attempted using the STEPLIB DD.

3. If the member is found, and the checksum that is stored with the DWARF diagnostic information retrieved from the member matches the checksum of the compile unit in the executing program, the information is extracted from the member.

   Note that if duplicate members exist in the IGZLOAD DD concatenation or in the STEPLIB DD concatenation respectively, the first occurrence in the DD concatenation is used to obtain the checksum.

   A mismatch can occur if a revised copy of the program is placed into a LLA/VLF managed library, but the environment-appropriate refresh for the staged LLA/VLF program has not been completed.

//GO1        EXEC  PGM=PGM1,                         * CALLED FROM LNKLST
//STEPLIB    DD    DSN=CEE1.SCEERUN,DISP=SHR
//IGZLOAD    DD    DSN=USER.COBOL.LOADLIB,DISP=SHR   * CONTAINS PGM1

If a program is LLA/VLF managed and staged to VLF, and is executed from one of the data sets in LNKLST, there is a need to allocate the IGZLOAD DD. However, if the program resides in one of the data sets in the STEPLIB DD, there is no need to allocate the IGZLOAD DD.