TEST

TEST option syntax

Option default is: NOTEST(NODWARF)

Abbreviations are: None

Suboption abbreviation is: NOS | S

TEST suboptions

When the TEST option is specified, DWARF debugging information is included in the application module.

The EJPD and NOEJPD suboptions control enablement of the Debug Tool commands JUMPTO and GOTO in production debugging sessions. These suboptions take effect only if you specify the TEST option and a non-zero OPTIMIZE level (OPTIMIZE(1) or OPTIMIZE(2)).

EJPD

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.

NOEJPD

If you specify TEST(NOEJPD) and a non-zero OPTIMIZE level:

• The JUMPTO and GOTO commands are not enabled. However, you can still use JUMPTO and GOTO if you use the SET WARNING OFF Debug Tool command. In this scenario, JUMPTO and GOTO will have unpredictable results.
• The normal amount of program optimization is done.

SOURCE

If you specify TEST(SOURCE), the generated DWARF debug information generated by the compiler includes the expanded source code, and the compiler listing is not needed by IBM Debug Tool.

NOSOURCE

If you specify TEST(NOSOURCE), the generated DWARF debugging information does not include the expanded source code, and you will not be able to use IBM Debug Tool.

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 a non-zero OPTIMIZE level, STGOPT and TEST(NOEJPD).
  • The Debug Tool commands JUMPTO and GOTO are not supported. However, you can still use JUMPTO and GOTO if you use the SET WARNING OFF Debug Tool command. In this scenario, JUMPTO and GOTO will have unpredictable results.
  • Except for the DESCRIBE ATTRIBUTES command, Debug Tool commands cannot refer to any data item that was discarded from a program by the STGOPT 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 predictable behavior for the Debug Tool 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 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(DWARF), the dump will have program variables and the line number of the failing statement. With NOTEST(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.