Example: TEST runtime options

The following examples of using the TEST runtime option are provided to illustrate runtime options available for your programs. These commands do not illustrate complete commands. The complete syntax of the TEST runtime option can be found in Syntax of the TEST run-time option.

Remote debugging
If you are working in remote debug mode, that is, you are debugging your host application from your workstation, the following examples apply:
Table 1. TEST runtime option examples for remote debugging
Scenario TEST runtime option usage
Eclipse IDE using Debug Manager TEST(,,,DBMDT:*)

Indicates that you want to start a debug session in Debug Tool compatibility mode for an Eclipse debug client. The address of the client is automatically determined by Debug Manager for the current user ID.
Eclipse IDE using workstation IP address TEST(,,,TCPIP&abc.example.com%8001:*)

Indicates that you want to start a debug session in Debug Tool compatibility mode for an Eclipse debug client. In this example, the TCP/IP address of the client is manually specified as abc.example.com and the debug daemon is listening on port 8001.
IBM Z® Open Debug TEST(,,,RDS:*)

Indicates that you want to start a debug session using Remote Debug Service for Wazi for VS Code or Wazi for Dev Spaces. In this scenario, Remote Debug Service must be running and configured.


TEST(,,,TCPIP&127.0.0.1%8001:*)

Indicates that you want to start a debug session using Remote Debug Service for Wazi for VS Code or Wazi for Dev Spaces. In this scenario, Remote Debug Service is running on the local z/OS machine using the TCP/IP address of 127.0.0.1 and it is listening on port 8001 for internal z/OS® Debugger connections.

When Debug Profile Service is active, optionally you can use TEST with no suboptions specified to enable delay debug mode. For more information, see Simple TEST option.

Code coverage
If you want to start code coverage sessions, the following examples apply:
Table 2. TEST runtime option examples for code coverage
Scenario TEST runtime option usage
Code coverage with Eclipse IDE using Debug Manager TEST(,,,DBMDT:*)

Indicates that you want to start a code coverage session in Debug Tool compatibility mode for an Eclipse IDE. The address of the client is automatically determined by Debug Manager for the current user ID.
Code coverage with Eclipse IDE using workstation IP address TEST(,,,TCPIP&abc.example.com%8001:*)

Indicates that you want to start a code coverage session in Debug Tool compatibility mode for an Eclipse IDE. In this example, the TCP/IP address of the client is manually specified as abc.example.com and the debug daemon is listening on port 8001.
Headless code coverage using Remote Debug Service TEST(,,,RDS:*)

Indicates that you want to run a code coverage session and connect to Remote Debug Service. In this scenario, Remote Debug Service must be running and configured to collect code coverage.
Headless code coverage on z/OS TEST(,,,TCPIP&127.0.0.1%8001:*)

Indicates that you want to run a code coverage session using headless code coverage. In this scenario, headless code coverage is running on the local z/OS machine using the TCP/IP address of 127.0.0.1 and it is listening on port 8001 for z/OS Debugger connections.
Headless code coverage with a Windows or Linux client TEST(,,,TCPIP&cde.example.com%8001:*)

Indicates that you want to start a code coverage session using headless code coverage. In this scenario, the headless code coverage daemon is running on a Windows or Linux machine using the TCP/IP address of cde.example.com and it is listening on port 8001 for z/OS Debugger connections.
Notes:
Full-screen debugging
If you want to use full-screen debugging, the following examples apply:
Table 3. TEST runtime options for full-screen debugging
Scenario TEST runtime option usage
CICS full screen mode TEST(ALL,,,MFI%F000:)

When running under CICS®, z/OS Debugger displays its screens on terminal ID F000.
Full-screen mode with a dedicated terminal TEST(ALL,,,MFI%TRMLU001:)

For use with full-screen mode using a dedicated terminal without Terminal Interface Manager. The VTAM LU TRMLU001 is used for display. This terminal must be known to VTAM and not in session when z/OS Debugger is started.


TEST(ALL,,,MFI%SYSTEM01.TRMLU001:)
For use in the following situations:
  • You are using full-screen mode using a dedicated terminal without Terminal Interface Manager.
  • You must specify a network identifier.
The VTAM LU TRMLU001 on network node SYSTEM01 is used for display. This terminal must be known to VTAM and not in session when z/OS Debugger is started.
Full-screen mode using Terminal Interface Manager TEST(ALL,,,VTAM%USERABCD:)

For use with full-screen mode using the Terminal Interface Manager. The user accessed the z/OS Debugger Terminal Interface Manager with user id USERABCD.
TSO full-screen mode TEST(,,,MFI:*)

Indicates that you want the debugger to start a debug session in TSO full-screen mode.
Note: Full-screen debugging is supported only in IBM Developer for z/OS Enterprise Edition and IBM Debug for z/OS.
NOTEST
z/OS Debugger is not started at program initialization. Note that a call to CEETEST, PLITEST, or __ctest() causes z/OS Debugger to be started during the program's execution.
NOTEST(ALL,MYCMDS,*,*)
z/OS Debugger is not started at program initialization. Note that a call to CEETEST, PLITEST, or __ctest() causes z/OS Debugger to be started during the program's execution. After z/OS Debugger is started, the suboptions specified become effective and the commands in the file allocated to DD name of MYCMDS are processed.

If you specify NOTEST and control has returned from the program in which z/OS Debugger first became active, you can no longer debug non-Language Environment® programs or detect non-Language Environment events.

TEST
Specifying TEST with no suboptions causes a check for other possible definitions of the suboption. For example, C and C++ allow default suboptions to be selected at compile time using #pragma runopts. Similarly, PL/I offers the PLIXOPT string. Language Environment provides the macro CEEXOPT. Using this macro, you can specify installation and program-specific defaults.

If no other definitions for the suboptions exist, the IBM-supplied default suboptions (ALL,*,PROMPT,INSPPREF) are in effect. In an environment that is not a foreground TSO task, z/OS Debugger operates in delay debug mode when the Debug Profile Service API is active.

TEST(ALL,*,*,*)
z/OS Debugger is not started initially; however, any condition or an attention in your program causes z/OS Debugger to be started, as does a call to CEETEST, PLITEST, or __ctest(). Neither a primary commands file nor preferences file is used.
TEST(NONE,,*,*)
z/OS Debugger is not started initially and begins by running in a "production mode", that is, with minimal effect on the processing of the program. However, z/OS Debugger can be started using CEETEST, PLITEST, or __ctest().
TEST(ALL,test.scenario,PROMPT,prefer)
z/OS Debugger is started at the end of environment initialization, but before the main program prolog has completed. The ddname prefer is processed as the preferences file, and subsequent commands are found in data set test.scenario. If all commands in the commands file are processed and you issue a STEP command when prompted, or a STEP command is run in the commands file, the main block completes initialization (that is, its AUTOMATIC storage is obtained and initial values are set). If z/OS Debugger is reentered later for any reason, it continues to obtain commands from test.scenario repeating this process until end-of-file is reached. At this point, commands are obtained from your terminal.

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

  • Related references
  • z/OS Language Environment Programming Guide