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 theOPT(STD)
orOPT(FULL)
compiler option, you must also specify theEJPD
suboption of theTEST
compiler option to be able to do the following tasks:- Use the
GOTO
orJUMPTO
commands. - Modify variables with predictable results.
EJPD
suboption, you might lose some optimization.If you are using other Application Delivery Foundation for z/OS tools, review the information in IBM® Application Delivery Foundation for z/OS 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 Application Delivery Foundation for z/OS tools.
- Use the
- 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 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)
If you are using other Application Delivery Foundation for z/OS tools, review the information in IBM Application Delivery Foundation for z/OS 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 Application Delivery Foundation for z/OS 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 Application Delivery Foundation for z/OS tools, review the information in IBM Application Delivery Foundation for z/OS 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 Application Delivery Foundation for z/OS 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 Application Delivery Foundation for z/OS tools, review the topic in IBM Application Delivery Foundation for z/OS 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 Application Delivery Foundation for z/OS 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 Application Delivery Foundation for z/OS tools, review the topic in IBM Application Delivery Foundation for z/OS 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 Application Delivery Foundation for z/OS 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 theTEST(SOURCE)
compiler option, the debug data is saved in the program object in aNOLOAD
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.Note: Do not use the binder PAGE statement when you link-edit a load module that contains more than one Enterprise COBOL for z/OS Version 5 or later program that is compiled with aTEST
compiler option where the debug data is saved in the program object in aNOLOAD
debug segment. - Scenario H: If you are compiling with Enterprise COBOL for z/OS Version 6 Release 2 or later, you can get the most z/OS Debugger functionality by using
TEST(SOURCE)
orTEST(SEPARATE,SOURCE)
. For Enterprise COBOL for z/OS Version 6 Release 2 with APAR PH04485 installed or later, you can specifyTEST(SEPARATE(DSNAME),SOURCE)
to store the separate debug file name, which is theSYSDEBUG 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 aNOLOAD
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.Note: Do not use the binder PAGE statement when you link-edit a load module that contains more than one Enterprise COBOL for z/OS Version 5 or later program that is compiled with aTEST
compiler option where the debug data is saved in the program object in aNOLOAD
debug segment. - With the
TEST(SEPARATE,SOURCE)
compiler option, the debug data is saved in a separate debug file. The compiler uses theSYSDEBUG DD
statement to specify the separate debug file.- For Enterprise COBOL for z/OS Version 6 Release 2 with
APAR PH04485 installed or later, 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
nameEQA_DBG_SYSDEBUG
environment variable
If you use an
EQAUEDAT
user exit, SET DEFAULT LISTINGS command,EQADEBUG DD
name, orEQA_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, orEQA_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 Enterprise COBOL for z/OS Version 6 Release 2 with
APAR PH04485 installed or later, you can specify
- With the
- 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
- 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:
- 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.
- After you start z/OS Debugger, verify that you
have not deactivated the Dynamic Debug facility by
entering the
QUERY DYNDEBUG
command. - 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
withTEST
, make sure the sequence fields in your source code all contain numeric characters. - You need to
specify the
SYM
suboption of theTEST
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
orDESCRIBE
. - To use the
DATA
suboption of thePLAYBACK ENABLE
command.
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
- To specify labels (paragraph or section names) as targets of the
- The
TEST
compiler option and theDEBUG
runtime option are mutually exclusive, withDEBUG
taking precedence. If you specify both theWITH DEBUGGING MODE
clause in yourSOURCE-COMPUTER
paragraph and theUSE FOR DEBUGGING
statement in your code,TEST
is deactivated. TheTEST
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 locationuserid.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 IICOB2LIB
library. - the
- If you specify
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:
Name of compiler option or suboption | Description of the effect |
---|---|
NOTEST |
|
NONE and NOHOOK |
|
EJPD |
You can modify variables in an optimized program that was compiled with one the following
compilers:
EJPD suboption of the
TEST compiler option. However, variables that are declared with the VALUE clause to
initialize them cannot be modified.
|
NOSYM |
If you are compiling with Enterprise COBOL for z/OS,
Version 4, the compiler ignores This option is not available with Enterprise COBOL for z/OS Version 5. |
STMT |
If you are compiling with Enterprise COBOL for z/OS,
Version 4, the compiler treats the This option is not available with Enterprise COBOL for z/OS Version 5. |
PATH |
If you are compiling with Enterprise COBOL for z/OS,
Version 4, the compiler treats the This option is not available with Enterprise COBOL for z/OS Version 5. |
BLOCK |
If you are compiling with Enterprise COBOL for z/OS,
Version 4, the compiler treats the This option is not available with Enterprise COBOL for z/OS Version 5. |
ALL |
If you are compiling with Enterprise COBOL for z/OS,
Version 4, the compiler treats the 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. |