Syntax of the TEST runtime option

For examples of using the TEST runtime option to illustrate runtime options available for your programs, see Example: TEST runtime options.

You can combine any of the suboptions for the TEST runtime option but only in the order specified by the TEST syntax. Any option or suboption referred to as "default" is the IBM-supplied default, and might have been changed by your system administrator during installation.

The syntax for this option is:
Read syntax diagramSkip visual syntax diagramNOTESTTEST(test_level,commands_file,prompt_level,preferences_file)
test_level
Read syntax diagramSkip visual syntax diagramALLERRORNONE
commands_file
Read syntax diagramSkip visual syntax diagram*NULLFILEcommands_file_designatorVADSCP nnnnn
prompt_level
Read syntax diagramSkip visual syntax diagramPROMPTNOPROMPT;*";command"
preferences_file
Read syntax diagramSkip visual syntax diagramMFI% terminal_id%network_identifier. VTAM_LU_id:VTAM% user_id:DIRECT&TCPIP&1VADTCPIP&1tcpip_id%8001%port_id:DBMDBMDT%user_id:INSPPREFNULLFILEpreferences_file_designator*
Notes:
  • 1 Specifies remote debug mode.

The following list explains what actions are taken by each option and suboption.

NOTEST
Specifies that z/OS® Debugger is not started at program initialization. However, Starting z/OS Debugger is still possible through the use of CEETEST, PLITEST, or the __ctest() function. In such a case, the suboptions specified with NOTEST are used when z/OS Debugger is started.
TEST
Specifies that z/OS Debugger is given control according to the specified suboptions. The TEST suboptions supplied are used if z/OS Debugger is started with CEETEST, PLITEST, or __ctest().

If z/OS Debugger is started by using CALL CEETEST (or an equivalent entry), you cannot debug higher-level non-Language Environment® programs or intercept non-Language Environment events that occur in higher-level programs after you return from the program that started z/OS Debugger.

test_level:

ALL (or blank)
Specifies that the occurrence of an attention interrupt, ABEND of a program, or any program or Language Environment condition of Severity 1 and above causes z/OS Debugger to gain control, regardless of whether a breakpoint is defined for that condition.

When a FINISH, CEE066 or CEE067 thread termination condition is raised by Language Environment, z/OS Debugger can be prevented from stopping at this condition by specifying the EQAOPTS THREADTERMCOND command. You or your system administrator can specify this command by creating an EQAOPTS load module or providing the command at run time.

If a condition occurs and a breakpoint exists for the condition, the commands specified in the breakpoint are executed. If a condition occurs and a breakpoint does not exist for that condition, or if an attention interrupt occurs, z/OS Debugger does the following:

  • In full-screen mode, z/OS Debugger reads commands from a commands file (if it exists and is available) or prompts you for commands.
  • In batch mode, z/OS Debugger reads commands from the commands file. If none is available, the program runs uninterrupted.
ERROR
Specifies that only the following conditions cause z/OS Debugger to gain control without a user-defined breakpoint.
  • For C and C++:
    • An attention interrupt
    • Program termination
    • A predefined Language Environment condition of Severity 2 or above
    • Any C and C++ condition other than SIGUSR1, SIGUSR2, SIGINT or SIGTERM.
  • For COBOL:
    • An attention interrupt
    • Program termination
    • A predefined Language Environment condition of Severity 2 or above.
  • For PL/I:
    • An attention interrupt
    • Program termination
    • A predefined Language Environment condition of Severity 2 or above.
If a breakpoint exists for one of the above conditions, commands specified in the breakpoint are executed. If no commands are specified, z/OS Debugger reads commands from a commands file or prompts you for them in interactive mode.
NONE
Specifies that z/OS Debugger gains control from a condition only if a breakpoint is defined for that condition. If a breakpoint exists for the condition, the commands specified in the breakpoint are executed. An attention interrupt does not cause z/OS Debugger to gain control unless z/OS Debugger was started. To change the TEST level after you start your debug session, use the SET TEST command.

commands_file:

* (or blank)
Indicates that you did not supply a commands file.
In the following situation, z/OS Debugger reads commands from a default user commands file:
  • You or your site specify a default naming pattern, through the EQAOPTS COMMANDSDSN command, identifying a user commands file.
  • The user commands file exists.
  • The user commands file contains a member with a name that matches the initial load module name of the first enclave.
If you or your site do not specify the name of a default user commands file or that file does not exist, and you are debugging in line mode, z/OS Debugger reads commands from the terminal.

To learn how to supply the EQAOPTS COMMANDSDSN command, see EQAOPTS commands.

NULLFILE
Indicates that you did not supply a commands file and z/OS Debugger ignores any specification of the EQAOPTS COMMANDSDSN command. If you are debugging in line mode, z/OS Debugger reads commands from the terminal.
commands_file_designator
Valid designation for the primary commands file. A commands file is used instead of the terminal as the initial source of commands, and only after the preferences file, if specified, is processed.
If the designation contains non-alphanumeric characters (for example, a parenthesis), the designation must be enclosed in either quotation marks (") or apostrophes ('). However, when a data set name is enclosed in quotation marks or apostrophes, z/OS Debugger still considers the data set name a partially-qualified data set name and prefixes the user ID to form the fully-qualified data set name.

The commands_file_designator has a maximum length of 80 characters.

If the specified DD name is longer than eight characters, it is automatically truncated. No error message is issued.

The primary commands file is required when you debug in batch mode. z/OS Debugger reads and executes commands listed in the commands file until the file runs out of commands or the program finishes running. You can use a log file from one z/OS Debugger session as the commands file for a subsequent z/OS Debugger session.

The primary commands file is shared across multiple enclaves.

VADSCPnnnnn
Specifies a CCSID (Coded Character Set Identifiers) to use when you are debugging programs in remote debug mode and the source or compiler use a code page other than 037.
If your C/C++ source contains square brackets or other special characters, you might need to specify the VADSCPnnnnn suboption to override the z/OS Debugger default code page (037). The C/C++ compiler uses a default code page of 1047 if you do not explicitly specify one. Check the code page specified when you compiled your source. If the code page used is 1047 or a code page other than 037, you need to specify the VADSCPnnnnn suboption specifying that code page.
Note: Your system programmer might implement the EQAOPTS CODEPAGE command to set a new code page. You can check that with the QUERY EQAOPTS command.

The following examples show how to use VADSCPnnnnn:

  • For Japanese EBCDIC CCSID 930 
    TEST(ALL,VADSCP930,,TCPIP&9.10.11.12%8001:*)
  • For Japanese EBCDIC CCSID 939 
    TEST(ALL,VADSCP939,,TCPIP&9.10.11.12%8001:*)
  • For German EBCDIC CCSID 1141 
    TEST(ALL,VADSCP1141,,TCPIP&9.10.11.12%8001:*)
  • For Korean EBCDIC CCSID 933 
    TEST(ALL,VADSCP933,,TCPIP&9.10.11.12%8001:*)

If a EQAOPTS CODEPAGE command exists, the code page specified in the EQAOPTS CODEPAGE command overrides the CCSID specified in VADSCPnnnnn.

If neither the EQAOPTS CODEPAGE command or the VADSCPnnnnn option are specified, the default code page is US code page (037).

prompt_level:

PROMPT (or ; or blank)
Indicates that you want z/OS Debugger started immediately after Language Environment initialization. Commands are read from the preferences file and then any designated primary commands file. If neither file exists, commands are read from your terminal or workstation.
NOPROMPT (or *)
Indicates that you do not want z/OS Debugger started immediately after Language Environment initialization. Instead, your application begins running. When z/OS Debugger is running without the Language Environment run time (started by using EQANMDBG), the NOPROMPT option is ignored; PROMPT is always in effect.

If you specify the NOPROMPT suboption, you cannot debug higher-level non-Language Environment programs or intercept non-Language Environment events that occur in higher-level programs after you return from the program that started z/OS Debugger.

command
One or more valid z/OS Debugger commands. z/OS Debugger is started immediately after program initialization, and then the command (or command string) is executed. The command string can have a maximum length of 250 characters, and must be enclosed in quotation marks ("). Multiple commands must be separated by a semicolon.

If you include a STEP command or GO command in your command string, none of the subsequent commands are processed.

The use of a command in prompt_level is not supported in remote debug mode.

preferences_file:

MFI (Main Frame Interface)
Specifies z/OS Debugger should be started in full-screen mode for your debug sessions.
terminal_id (CICS® only)
Specifies up to a four-character terminal id to receive z/OS Debugger screen output during dual terminal session. The corresponding terminal should be in service and acquired, ready to receive z/OS Debugger-related I/O.
network_identifier (full-screen mode using a dedicated terminal without Terminal Interface Manager only)
Specifies an optional 1-8 character network name that identifies the network in which the partner LU, identified by the VTAM_LU_Id parameter, resides.
VTAM_LU_id (full-screen mode using a dedicated terminal without Terminal Interface Manager only)
Specifies up to an eight-character VTAM® logical unit (LU) identifier for a terminal used in full-screen mode using a dedicated terminal without Terminal Interface Manager. The VTAM_LU_id parameter cannot be used to debug CICS applications. Contact your system programmer to determine how to access this type of terminal LU at your site.
VTAM (full-screen mode using the Terminal Interface Manager only)
Specifies z/OS Debugger should be started in full-screen mode using the Terminal Interface Manager for your debug sessions and that you have used the z/OS Debugger Terminal Interface Manager.
user_id (full-screen mode using the Terminal Interface Manager only)
Specifies the user ID that you used to log on to the z/OS Debugger Terminal Interface Manager. Contact your system programmer to determine how to access this type of terminal at your site.
INSPPREF (or blank)
The default DD name, supplied by z/OS Debugger, for the preferences file.
In the following situation, z/OS Debugger reads commands from a default user preferences file:
  • You specify INSPPREF or leave it blank, but do not allocate the DD name.
  • You or your site specify a default naming pattern, through the EQAOPTS PREFERENCESDSN command, identifying a user preferences file.
  • The user preferences file exists.
Any preferences file you or your site specifies to z/OS Debugger becomes the first source of z/OS Debugger commands after z/OS Debugger is started. Use preferences files to set up the z/OS Debugger environment; for example, PF key assignments or screen layout.
preferences_file_designator
A valid DD name or data set designation specifying the preferences file to use.

This file is read the first time z/OS Debugger is started and must contain a sequence of z/OS Debugger commands to be processed.

The designation can be either a DD name or a data set name. z/OS Debugger uses the following procedure to determine if the designation is a DD name or data set name:
  • If the designation does not contain periods (.), z/OS Debugger considers it a DD name.
  • Otherwise, if you are running under CICS, z/OS Debugger considers it a fully-qualified data set name.
  • Otherwise, z/OS Debugger considers it a partially-qualified data set name and prefixes it with the user ID to form the fully-qualified data set name. If you want z/OS Debugger to interpret the data set name as a fully-qualified name, put a minus sign (-) in front of the name. In this case, z/OS Debugger does not append the user ID to the data set name.
If the designation contains non-alphanumeric characters (for example, a parenthesis), the designation must be enclosed in either quotation marks (") or apostrophes ('). However, when a data set name is enclosed in quotation marks or apostrophes, z/OS Debugger still considers the data set name a partially-qualified data set name and prefixes the user ID to form the fully-qualified data set name.
*
Specifies that you did not supply a preferences file.

If you or your site specifies a naming pattern, through the EQAOPTS PREFERENCESDSN command, identifying a user preferences file, z/OS Debugger reads commands from that file.

To learn how to supply the EQAOPTS PREFERENCESDSN command, see EQAOPTS commands.

NULLFILE
Indicates that you did not supply a preferences file and z/OS Debugger ignores any specification of the EQAOPTS PREFERENCESDSN command.

The following TEST suboptions are for remote debug mode and code coverage:

DIRECT&, TCPIP&, or VADTCPIP&
Specifies that z/OS Debugger starts in remote debug mode with a client.
Use DIRECT& to start the debugger in standard mode. Use TCPIP& or VADTCPIP& to start the debugger in Debug Tool compatibility mode.
Notes:
  1. IBM® Wazi Developer for Red Hat® CodeReady Workspaces can only be used in Debug Tool compatibility mode.
  2. Standard mode does not support commands files or preferences files. If they are specified, they are ignored.
tcpip_id
TCP/IP name or address where the remote debug daemon is running, in one of the following formats:
IPv4
You can specify the address as a symbolic address, such as some.name.com, or a numeric address, such as 9.112.26.333.
IPv6
You must specify the address as a numeric address, such as 1080:0:FF::0970:1A21.
%port_id
Specifies a unique TCP/IP port on your workstation that is used by the remote debug daemon. The default port number is 8001.
If you changed the default TCP/IP port settings used by the remote debugger client, you must specify the new number as the port ID in your TEST runtime options string. For example, if you changed the default TCP/IP port to 8003, your TEST runtime options string would be TEST(ALL,'*',PROMPT,'TCPIP&9.112.26.333%8003:').
DBM and DBMDT
Specifies that z/OS Debugger uses the Debug Manager to automatically determine the client IP and port number to connect to when you start remote debug mode with one of the remote debuggers listed previously under DIRECT&, TCPIP& or VADTCPIP&.
Use DBM to start the debugger in standard mode. Use DBMDT to start the debugger in Debug Tool compatibility mode.
Notes:
  • DBM and DBMDT are only supported with Eclipse clients.
  • Standard mode does not support commands files or preferences files. If they are specified, they are ignored.
  • Standard mode is not supported in IBM Wazi Developer for Red Hat CodeReady Workspaces.
Before you start z/OS Debugger with DBM or DBMDT TEST runtime parameters, you must log on to the host via the Remote System Explorer (RSE) in IBM Explorer for z/OS.
You can start a debug session only when Debug Manager and RSE both run in secured mode or unsecured mode. To establish a secured connection between Debug Manager and RSE, they need to use the same certificates or different chained certificates of the same CA root. Otherwise, you need to import the certificates that are regarded as untrusted. For more information, see Encrypted communication with Debug Manager.
user_id
Optionally specifies a user ID for routing the debug session. By default the same user ID as the job launching or running the debug session is assumed.

Usage notes

  • If the code page is not specified correctly or the conversion images are not available in the system, the default code page (00037) is used for the debug session.
  • If the code page is specified correctly and the conversion images are available in the system, but the string conversion is not successful, default code page (00037) is used for this conversion.

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

  • Related references
  • z/OS Language Environment Debugging Guide
  • Related tasks
  • IBM z/OS Debugger User's Guide