Choosing TEST or NOTEST compiler suboptions for PL/I programs

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

The PL/I compiler provides the TEST compiler option and its suboptions to control the following actions:

  • The generation and placement of statements and symbol tables.
  • The placement of debug information into the program object or separate debug file.
  • The placement of source file contents into the program object or not.

z/OS Debugger does not support debugging optimized PL/I programs. Do not use compiler options other than NOOPTIMIZE,

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

  1. Choose a debugging scenario, keeping in mind your site's resources, from the following list:
    • Scenario A: If you are using Enterprise PL/I for z/OS, Version 6.1 or later with APAR PH50085, and you want to access the source without providing the source location, use TEST(NOSEPARATE,SOURCE) and GOFF. With TEST(NOSEPARATE,SOURCE), the source content captured in the GOFF object is controlled by the LISTVIEW option in the same way as the source contents captured in the debug side file when you compile with TEST(SEPERATE).
    • Scenario B: If you are using Enterprise PL/I for z/OS, Version 3.8 or later, and you want to get the most z/OS Debugger functionality and a small program size, use TEST(ALL,NOHOOK,SYM,SEPARATE) and the LISTVIEW(SOURCE) compiler option. If you need to debug programs that are loaded into protected storage, verify that your site installed the Authorized Debug Facility.
      Consider the following options:
      • If you are using Enterprise PL/I for z/OS, Version 4 or later, you can specify the GONUMBER(SEPARATE) compiler option, which can help make the program size smaller.
      • You can specify any of the LISTVIEW sub-options (SOURCE, AFTERALL, AFTERCICS, AFTERMACRO, or AFTERSQL), as described in Enterprise PL/I for z/OS Programming Guide, to display either the original source or the source after the specified preprocessor.
        Note: If a sub-option other than SOURCE is specified for LISTVIEW, then TEST(SEPERATE) also needs to be specified.
      • If you are debugging in full-screen mode and you want to debug programs with INCLUDE files that have executable code, specify the LISTVIEW(AFTERMACRO) compiler option and, if you do not specify the MACRO compiler option, specify the PP(MACRO(INCONLY)) compiler option.
      • If you are debugging in remote debug mode and you want to automonitor variables in INCLUDE files, specify the LISTVIEW(AFTERMACRO) compiler option and, if you do not specify the MACRO compiler option, specify the PP(MACRO(INCONLY)) compiler option.

      If you are using other Application Delivery Foundation for z/OS tools, see topic Enterprise PL/I Version 3.5 and Version 3.6 programs 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: If you are using Enterprise PL/I for z/OS, Version 3.7, and you want to get the most z/OS Debugger functionality and a small program size, use TEST(ALL,NOHOOK,SYM,SEPARATE,SOURCE). If you need to debug programs that are loaded into protected storage, verify that your site installed the Authorized Debug Facility.
      Consider the following options:
      • You can substitute SOURCE with AFTERALL, AFTERCICS, AFTERMACRO, or AFTERSQL, as described in Enterprise PL/I for z/OS Programming Guide.
      • If you are debugging in full-screen mode and you want to debug programs with INCLUDE files that have executable code, specify the TEST(ALL,NOHOOK,SYM,SEPARATE,AFTERMACRO) compiler options and, if you do not specify the MACRO compiler option, specify the PP(MACRO(INCONLY)) compiler option.
      • If you are debugging in remote debug mode and you want to automonitor variables in INCLUDE files, specify the TEST(ALL,NOHOOK,SYM,SEPARATE,AFTERMACRO) compiler options and, if you do not specify the MACRO compiler option, specify the PP(MACRO(INCONLY)) compiler option.

      If you are using other Application Delivery Foundation for z/OS tools, see topic Enterprise PL/I Version 3.5 and Version 3.6 programs 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 Enterprise PL/I for z/OS, Version 3.5 or 3.6, and you want to get most z/OS Debugger functionality and a small program size, use TEST(ALL,NOHOOK,SYM,SEPARATE). If you need to debug programs that are loaded into protected storage, verify that your site installed the Authorized Debug Facility.

      If you are using other Application Delivery Foundation for z/OS tools, see topic Enterprise PL/I Version 3.5 and Version 3.6 programs 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 E: If you are using Enterprise PL/I for z/OS, Version 3.4, and you want to debug your program without compiled-in hooks, use TEST(ALL,NOHOOK,SYM). If you need to debug programs that are loaded into protected storage, verify that your site installed the Authorized Debug Facility.

      If you are using other Application Delivery Foundation for z/OS tools, see topic Enterprise PL/I Version 3.4 and earlier programs 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 F: If you are using Enterprise PL/I for z/OS, Version 3.3 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, see topic Enterprise PL/I Version 3.4 and earlier programs or PL/I for MVS(tm) and VM and OS PL/I programs 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 G: You can get some z/OS Debugger 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 you need to create the files needed by all the Application Delivery Foundation for z/OS tools:
      • Enterprise PL/I Version 3.5 and Version 3.6 programs
      • Enterprise PL/I Version 3.4 and earlier programs
      • PL/I for MVS™(tm) and VM and OS PL/I programs
  2. For scenarios A, B, C, D, F, and G, 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.
  3. Verify whether you need to do any of the following tasks:

    • When you compile a program, do not associate SYSIN with an in-stream data set (for example //SYSIN DD *) because z/OS Debugger requires access to a permanent data set for the source of the program you are debugging.

    • If you are compiling a PL/I for MVS & VM or OS PL/I program and to be able to view your listing while debugging in full-screen mode, you must compile the program with the SOURCE compiler option. The SOURCE compiler option is required to generate a listing file. You must direct the listing to a non-temporary file that is available during the debug session. During a debug session, z/OS Debugger displays the first file it finds named userid.pgmname.list in the Source window. In addition, you must link your program with the Language Environment® SCEELKED library; do not use the OS PL/I PLIBASE or SIBMBASE library.

      If z/OS Debugger cannot find the listing at this location, see Changing which file appears in the Source window.

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

Table 1. Description of the effects that the PL/I NOTEST compiler option and the TEST compiler suboptions have on z/OS Debugger.
Name of compiler option or suboption Description of the effect
NOTEST

Some behaviors or features change when you debug a PL/I program compiled with the NOTEST compiler option. The following list describes these changes:

  • You can list storage and registers.
  • You can include calls to PLITEST or CEETEST in your program so you can suspend running your program and issue z/OS Debugger commands.
  • You cannot step through program statements. You can suspend running your program only at the initialization of the main compile unit.
  • You cannot examine or use any program variables.
  • Because hooks at the statement level are not inserted, you cannot set any statement breakpoints or use commands such as GOTO or QUERY LOCATION.
  • The source listing produced by the compiler cannot be used; therefore, no listing is available during a debug session.
However, you can still debug your program using the disassembly view. To learn how to use the disassembly view, see Debugging a disassembled program.
NOHOOK

Some behaviors or features change when you debug a PL/I program compiled with the NOHOOK suboption of the TEST compiler option. The following list describes these changes:

  • For z/OS Debugger to generate overlay hooks, one of the suboptions ALL, PATH, STMT or BLOCK must be in effect, but HOOK need not be specified, and NOHOOK would be recommended.
  • If NOHOOK is specified, ENTRY and EXIT breakpoints are the only PATH breakpoints at which z/OS Debugger stops.
NONE

When you compile a PL/I program with the NONE suboption of the TEST compiler option, you can start z/OS Debugger at any point in your program by writing a call to PLITEST or CEETEST in your program.
SYM

Some behaviors or features change when you debug a PL/I program compiled with the SYM suboption of the TEST compiler option. The following list describes these changes:

  • You can reference all program variables by name, which allows you to examine them or use them in expressions and use the DATA parameter of the PLAYBACK ENABLE command.
  • Enables support for the SET AUTOMONITOR ON command.
  • Enables the support for labels as GOTO targets.
NOSYM

Some behaviors or features change when you debug a PL/I program compiled with the NOSYM suboption of the TEST compiler option. The following list describes these changes:

  • 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 (procedure or block name).
BLOCK

Some behaviors or features change when you debug a PL/I program compiled with the BLOCK suboption of the TEST compiler option. The following list describes these changes:

  • Enables z/OS Debugger to gain control at block boundaries: block entry and block exit.
  • When Dynamic Debug is not active and you use the HOOK compiler option, you can gain control only at the entry and exit points of your program and all entry and exit points of internal program blocks. When you enter the STEP command, for example, your program runs until it reaches the next block entry or exit point.
  • When Dynamic Debug is active, you can set breakpoints at all statements and step through your program.
  • You cannot gain control at path points unless you also specify PATH.
  • A call to PLITEST or CEETEST can be used to start z/OS Debugger at any point in your program.
  • Hooks are not inserted into an empty ON-unit or an ON-unit consisting of a single GOTO statement.
STMT

Some behaviors or features change when you debug a PL/I program compiled with the STMT suboption of the TEST compiler option. The following list describes these changes:

  • 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, unless you also specify PATH.
  • Branching to all statements and labels using the z/OS Debugger command GOTO is allowed.
ALL

Some behaviors or features change when you debug a PL/I program compiled with the ALL suboption of the TEST compiler option. The following list describes these changes:

  • 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, labels, and block entry and exit points, allowing you to enter z/OS Debugger commands.
  • Enables branching to statements and labels using the z/OS Debugger command GOTO.

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 PL/I for z/OS Programming Guide.