Choosing TEST or NOTEST compiler suboptions for COBOL programs

This topic describes the combination of TEST compiler option and suboptions you need to specify to obtain the wanted debugging scenario. This topic assumes you are compiling your COBOL program with Enterprise COBOL for z/OS®, Version 3.4, or later; however, the topics provide information about alternatives to use for older versions of the COBOL compiler.

The COBOL compiler provides the TEST compiler option and its suboptions to control the following actions:

The generation and placement of hooks and symbol tables.
The placement of debug information into the object file or a separate debug file.

The following instructions help you choose the combination of TEST compiler suboptions that provide the functionality you need to debug your program:

Choose a debugging scenario, keeping in mind your site's resources, from the following list:
- Scenario A: If you are compiling with Enterprise COBOL for z/OS, Version 4, you can get the most z/OS Debugger functionality and a small program size by using TEST(NOHOOK,SEPARATE). If you need to debug programs that are loaded into protected storage, verify that your site installed the Authorized Debug Facility.
  If you want to compile your program with the OPT(STD) or OPT(FULL) compiler option, you must also specify the EJPD suboption of the TEST compiler option to be able to do the following tasks:
  - Use the GOTO or JUMPTO commands.
  - Modify variables with predictable results.
  When you use the EJPD suboption, you might lose some optimization.
  If you are using other other IBM® Application Delivery Foundation for z Systems™ tools, review the information in IBM Application Delivery Foundation for z Systems Common Components Customization Guide and User Guide to make sure you specify all the compiler options you need to create the files needed by all the IBM Application Delivery Foundation for z Systems tools.
- Scenario B: If you are compiling with any of the following compilers, you can get the most z/OS Debugger functionality and a small program size by using TEST(NONE,SYM,SEPARATE):
  - Enterprise COBOL for z/OS and OS/390®, Version 3 Release 2 or later
  - Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR PQ63235
  - COBOL for OS/390 & VM, Version 2 Release 2
  - COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ63234.
  If you need to debug programs that are loaded into protected storage, verify that your site installed the Authorized Debug Facility.
  If you want to compile your program with optimization and be able to get the most z/OS Debugger functionality, you must compile it with one of the following combination of compiler options:
  - OPT(STD) TEST(NONE,SYM)
  - OPT(STD) TEST(NONE,SYM,SEPARATE)
  - OPT(FULL) TEST(NONE,SYM)
  - OPT(FULL) TEST(NONE,SYM,SEPARATE)
  For these types of programs, you can modify variables, but the results might be unpredictable.
  If you are using other IBM Application Delivery Foundation for z Systems tools, review the information in IBM Application Delivery Foundation for z Systems Common Components Customization Guide and User Guide to make sure you specify all the compiler options you need to create the files needed by all the IBM Application Delivery Foundation for z Systems tools.
- Scenario C: To get all z/OS Debugger functionality but have a larger program size and do not want debug information in a separate debug file, compile with one of the following compiler options for the compilers specified:
  - TEST(HOOK,NOSEPARATE) with Enterprise COBOL for z/OS, Version 4.
  - TEST(ALL,SYM,NOSEPARATE) with any of the following compilers:
    - Enterprise COBOL for z/OS and OS/390, Version 3 Release 2 or later
    - Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR PQ63235
    - COBOL for OS/390 & VM, Version 2 Release 2
    - COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ40298
  If you are using other IBM Application Delivery Foundation for z Systems tools, review the information in IBM Application Delivery Foundation for z Systems Common Components Customization Guide and User Guide to make sure that you specify all the compiler options that you need to create the files needed by all the IBM Application Delivery Foundation for z Systems tools.
- Scenario D: If you are using COBOL for OS/390 & VM, Version 2 Release 1, or earlier, and you want to get all z/OS Debugger functionality, use TEST(ALL,SYM).
  If you are using other IBM Application Delivery Foundation for z Systems tools, review the topic in IBM Application Delivery Foundation for z Systems Common Components Customization Guide and User Guide that corresponds to the compiler that you are using from the following list to make sure that you specify all the compiler options that you need to create the files needed by all the IBM Application Delivery Foundation for z Systems tools:
  - Enterprise COBOL for z/OS Version 3 and COBOL for OS/390 and VM programs
  - COBOL for MVS(tm) and VM programs
  - VS COBOL II programs
  - OS/VS COBOL programs
- Scenario E: You can get most of z/OS Debugger's functionality by compiling with the NOTEST compiler option and generating an EQALANGX file. This requires that you debug your program in LangX COBOL mode.
- Scenario F: You can get some z/OS Debugger's functionality by compiling with the NOTEST compiler option. This requires that you debug your program in disassembly mode.
  If you are using other IBM Application Delivery Foundation for z Systems tools, review the topic in IBM Application Delivery Foundation for z Systems Common Components Customization Guide and User Guide that corresponds to the compiler that you are using from the following list to make sure you specify all the compiler options that you need to create the files needed by all the IBM Application Delivery Foundation for z Systems tools:
  - Enterprise COBOL for z/OS Version 4 programs
  - Enterprise COBOL for z/OS Version 3 and COBOL for OS/390 and VM programs
  - COBOL for MVS(tm) and VM programs
  - VS COBOL II programs
  - OS/VS COBOL programs
- Scenario G: If you are compiling with Enterprise COBOL for z/OS Version 5 or Version 6 Release 1, you can get the most z/OS Debugger functionality by using TEST(SOURCE). If you need to debug programs that are loaded into protected storage, you must verify that your site installed the Authorized Debug Facility. With the TEST(SOURCE) compiler option, the debug data is saved in the program object in a NOLOAD debug segment. The debug data does not increase the size of the loaded program. The debug data always matches the executable and is always available, so there is no need to search the lists of data sets. The size of the program object increases but not the footprint in memory, unless it is required to load the debug data while you are debugging a program.
- Scenario H: If you are compiling with Enterprise COBOL for z/OS Version 6 Release 2, you can get the most z/OS Debugger functionality by using TEST(SOURCE) or TEST(SEPARATE,SOURCE). For Enterprise COBOL for z/OS Version 6 Release 2 with APAR PH04485 installed, you can specify TEST(SEPARATE(DSNAME),SOURCE) to store the separate debug file name, which is the SYSDEBUG DD data set name, in the object program. If you need to debug programs that are loaded into protected storage, you must verify that your site installed the Authorized Debug Facility.
  - With the TEST(SOURCE) compiler option, the debug data is saved in the program object in a NOLOAD debug segment. The debug data does not increase the size of the loaded program. The debug data always matches the executable and is always available, so there is no need to search the lists of data sets. The size of the program object increases but not the footprint in memory, unless it is required to load the debug data when you are debugging a program.
  - With the TEST(SEPARATE,SOURCE) compiler option, the debug data is saved in a separate debug file. The compiler uses the SYSDEBUG DD statement to specify the separate debug file.
    - For Enterprise COBOL for z/OS Version 6 Release 2 with APAR PH04485 installed, you can specify SEPARATE(DSNAME) to store the name of the separate debug file in the program object.
    - If you do not specify SEPARATE(DSNAME) or the location of the separate debug file has changed since the compilation, specify the separate debug file location with one of the following methods. z/OS Debugger looks for the separate debug file in the following order:
      - SET SOURCE command to specify the exact location of the separate debug file
      - EQAUEDAT user exit
      - SET DEFAULT LISTINGS command
      - EQADEBUG DD name
      - EQA_DBG_SYSDEBUG environment variable
      If you use an EQAUEDAT user exit, SET DEFAULT LISTINGS command, EQADEBUG DD name, or EQA_DBG_SYSDEBUG environment variable, specify a PDS data set or z/OS UNIX System Services directory as the separate debug file location.
      
      If you use a SET DEFAULT LISTINGS command, EQADEBUG DD name, or EQA_DBG_SYSDEBUG environment variable, and if the separate debug file is not found because the file name does not match the CU name, z/OS Debugger will do an exhaustive search of the data sets specified by the same method to locate the matching debug file. The exhaustive search might be slow.
For COBOL programs using IMS, include the IMS interface module DFSLI000 from the IMS RESLIB library.
For scenarios A, B and E, do the following steps:
1. If you use the Dynamic Debug facility to place hooks into programs that reside in read-only storage, verify with your system administrator that the Authorized Debug facility has been installed and that you are authorized to use it.
2. After you start z/OS Debugger, verify that you have not deactivated the Dynamic Debug facility by entering the QUERY DYNDEBUG command.
3. Verify that the separate debug file is a non-temporary file and is available during the debug session. The listing does not need to be saved.
Verify whether you need to do any of the following tasks:
- If you specify NUMBER with TEST, make sure the sequence fields in your source code all contain numeric characters.
- You need to specify the SYM suboption of the TEST compiler option to do the following actions:
  - To specify labels (paragraph or section names) as targets of the GOTO command.
  - To reference program variables by name.
  - To access a variable or expression through commands like LIST or DESCRIBE.
  - To use the DATA suboption of the PLAYBACK ENABLE command.
  You need to specify the SYM suboption to do these actions only if you are compiling with any of the following compilers:
  - Any release of Enterprise COBOL for z/OS and OS/390, Version 3
  - Any release of COBOL for OS/390 & VM, Version 2
- The TEST compiler option and the DEBUG runtime option are mutually exclusive, with DEBUG taking precedence. If you specify both the WITH DEBUGGING MODE clause in your SOURCE-COMPUTER paragraph and the USE FOR DEBUGGING statement in your code, TEST is deactivated. The TEST compiler option appears in the list of options, but a diagnostic message is issued telling you that because of the conflict, TEST is not in effect.
- For VS COBOL II programs, if you use the TEST compiler option, you must specify:
  - the SOURCE compiler option. This option is required to generate a listing file and save it at location userid.pgmname.list.
  - the RESIDENT compiler option. This option is required by Language Environment® to ensure that the necessary z/OS Debugger routines are loaded dynamically at run time.
  In addition, you must link your program with the Language Environment SCEELKED library and not the VS COBOL II COB2LIB library.

After you have chosen the compiler options and suboptions, see Planning your debug session to determine the next task you must complete.

Refer to the following topics for more information related to the material discussed in this topic.

Related references
Description of the TEST compiler option in Enterprise COBOL for z/OS Programming Guide

The following table explains the effects of the NOTEST compiler option, the TEST compiler option, and some of the suboptions of the TEST compiler option on z/OS Debugger behavior or the availability of features, which are not described in Enterprise COBOL for z/OS Programming Guide:

Table 1. Description of the effects that the COBOL NOTEST compiler option and some of the TEST compiler suboptions have on z/OS Debugger.
Name of compiler option or suboption	Description of the effect
NOTEST	You cannot step through program statements. You can suspend execution of the program only at the initialization of the main compile unit. You can include calls to `CEETEST` in your program to allow you to suspend program execution and issue z/OS Debugger commands. You cannot examine or use any program variables. You can list storage and registers. The source listing produced by the compiler cannot be used; therefore, no listing is available during a debug session. Using the `SET DEFAULT LISTINGS` command cannot make a listing available. Because a statement table is not available, you cannot set any statement breakpoints or use commands such as `GOTO` or `QUERY` location. However, you can still debug your program using the disassembly view. To learn how to use the disassembly view, see Debugging a disassembled program.
NONE and NOHOOK	If you use one of the following compilers, you can use the `GOTO` or the `JUMPTO` commands when you debug a non-optimized program: Enterprise COBOL for z/OS, Version 4 Any release of Enterprise COBOL for z/OS and OS/390, Version 3 Any release of COBOL for OS/390 & VM, Version 2 If you compile your program by using Enterprise COBOL for z/OS Version 4.1, you can use the `GOTO` or `JUMPTO` commands when you debug an optimized program. To enable the `GOTO` or `JUMPTO` commands, you must specify the `EJPD` suboption of the `TEST` option. When you specify the `EJPD` suboption, you might lose some optimization. You can use the `SET WARNING OFF` setting to obtain limited support for `GOTO` and `JUMPTO` when you compile with the `NOEJPD` suboption of the `TEST` compiler option. `GOTO` and `JUMPTO` are not enabled. A call to `CEETEST` can be used at any point to start z/OS Debugger. NONE and NOHOOK are not available with Enterprise COBOL for z/OS Version 5, but when you specify the TEST compile with this compiler, it creates an object similar to specifying NONE and NOHOOK with previous compilers.
EJPD	You can modify variables in an optimized program that was compiled with one the following compilers: Enterprise COBOL for z/OS, Version 5 Enterprise COBOL for z/OS, Version 4 Enterprise COBOL for z/OS and OS/390, Version 3 Release 2 or later Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR PQ63235 installed COBOL for OS/390 & VM, Version 2 Release 2 COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ63234 installed However, results might be unpredictable. To obtain more predictable results, compile your program with Enterprise COBOL for z/OS, Version 4 and 5, and specify the `EJPD` suboption of the `TEST` compiler option. However, variables that are declared with the VALUE clause to initialize them cannot be modified. LOUD The LOUD parameter is suggested, but optional. If you specify it, additional informational and statistical messages are displayed.
NOSYM	You cannot reference program variables by name. You cannot use commands such as `LIST` or `DESCRIBE` to access a variable or expression. You cannot use commands such as `CALL` variable to branch to another program, or `GOTO` to branch to another label (paragraph or section name). If you are compiling with Enterprise COBOL for z/OS, Version 4, the compiler ignores `SYM` or `NOSYM` and always creates a symbol table. This option is not available with Enterprise COBOL for z/OS Version 5.
STMT	The COBOL compiler generates compiled-in hooks for date processing statements only when the `DATEPROC` compiler option is specified. A date processing statement is any statement that references a date field, or any `EVALUATE` or `SEARCH` statement `WHEN` phrase that references a date field. You can set breakpoints at all statements and step through your program. z/OS Debugger cannot gain control at path points unless they are also at statement boundaries. Branching to all statements and labels using the z/OS Debugger command `GOTO` is allowed. If you are compiling with Enterprise COBOL for z/OS, Version 4, the compiler treats the `STMT` suboption as if it were the `HOOK` suboption, which is equivalent to the `ALL` suboption for any release of Enterprise COBOL for z/OS and OS/390, Version 3, or COBOL for OS/390 & VM, Version 2. This option is not available with Enterprise COBOL for z/OS Version 5.
PATH	z/OS Debugger can gain control only at path points and block entry and exit points. If you attempt to step through your program, z/OS Debugger gains control only at statements that coincide with path points, giving the appearance that not all statements are executed. A call to `CEETEST` can be used at any point to start z/OS Debugger. The z/OS Debugger command `GOTO` is valid for all statements and labels coinciding with path points. If you are compiling with Enterprise COBOL for z/OS, Version 4, the compiler treats the `PATH` suboption as if it were the `HOOK` suboption, which is equivalent to the `ALL` suboption for any release of Enterprise COBOL for z/OS and OS/390, Version 3, or COBOL for OS/390 & VM, Version 2. This option is not available with Enterprise COBOL for z/OS Version 5.
BLOCK	z/OS Debugger gains control at entry and exit of your program, methods, and nested programs. z/OS Debugger can be explicitly started at any point with a call to `CEETEST`. Issuing a command such as `STEP` causes your program to run until it reaches the next entry or exit point. `GOTO` can be used to branch to statements that coincide with block entry and exit points. If you are compiling with Enterprise COBOL for z/OS, Version 4, the compiler treats the `BLOCK` suboption as if it were the `HOOK` suboption, which is equivalent to the `ALL` suboption for any release of Enterprise COBOL for z/OS and OS/390, Version 3, or COBOL for OS/390 & VM, Version 2. This option is not available with Enterprise COBOL for z/OS Version 5.
ALL	You can set breakpoints at all statements and path points, and step through your program. z/OS Debugger can gain control of the program at all statements, path points, date processing statements, labels, and block entry and exit points, allowing you to enter z/OS Debugger commands. Branching to statements and labels using the z/OS Debugger command `GOTO` is allowed. If you are compiling with Enterprise COBOL for z/OS, Version 4, the compiler treats the `ALL` suboption as if it were the `HOOK` suboption, which is equivalent to the `ALL` suboption for any release of Enterprise COBOL for z/OS and OS/390, Version 3, or COBOL for OS/390 & VM, Version 2. This option is not available with Enterprise COBOL for z/OS Version 5, but when you specify the TEST compile with this compiler, it creates an object similar to specifying ALL with the exception that compiled-in hooks are not available.