Debug Tool runtime options

This topic describes the runtime options that you can use to control the operation of Debug Tool.

"Table 10" in Debug Tool User’s Guide describes most of the methods you can use to specify the TEST runtime options. Use that table with the information in the topic "Planning your debug session" in Debug Tool User’s Guide to select the method that works best for your site.

Some methods use the standard Language Environment runtime options. Other methods use Debug Tool keyword options with the same syntax and semantics as the corresponding Language Environment option. In all cases, you can omit these options if the default values are acceptable.

When you specify runtime options for a Language Environment program, they are handled by Language Environment and the following rules apply:

When you specify runtime options for a non-Language Environment program by using EQANMDBG under z/OS® batch or TSO, Debug Tool processes the options and the following rules apply:

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

Non-Language Environment positional parameter

If you use EQANMDBG to start Debug Tool to debug MVS™ batch or TSO programs that do not run in Language Environment, the first positional parameter must be the name of the program you want to debug. This name must be immediately followed by one of the following options:

If no user-program parameters are required, the slash is optional.

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

COUNTRY runtime option

Use the COUNTRY option to specify the country code to be used by Debug Tool. The default is always US.

The syntax for this option is:

Syntax diagram for the COUNTRY runtime option
country_code
A valid country code, one of:
US
United States of America
JP
Japan

NATLANG runtime option

Use the NATLANG option to specify the desired national language for Debug Tool. This determines the language that is used to display Debug Tool output, such as messages. If you do not specify NATLANG, the installation default is used.

The syntax for this option is:

Syntax diagram for the NATLANG runtime option
language_Id
A valid national language identifier, one of:
ENU
English
UEN
Upper-case English
JPN
Japanese
KOR
Korean

If you set NATLANG to JPN or KOR and you are using full-screen mode, enter the SET DBCS ON command so that Debug Tool displays messages in the correct format.

TEST runtime option

The TEST runtime option gives control of your program to Debug Tool.

This topic describes the TEST runtime option and its suboptions. The suboptions of the TEST runtime option control how, when, and where Debug Tool gains control of your program. For a description of how to specify the TEST runtime option, refer to the "Planning your debug session" in Debug Tool User’s Guide.

Syntax of the TEST runtime option

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:

Syntax diagram for the TEST runtime option
Notes:
  1. Specifies remote debug mode.

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

NOTEST
Specifies that Debug Tool is not started at program initialization. However, Starting Debug Tool 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 Debug Tool is started.
TEST
Specifies that Debug Tool is given control according to the specified suboptions. The TEST suboptions supplied are used if Debug Tool is started with CEETEST, PLITEST, or __ctest().

If Debug Tool 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 Debug Tool.

test_level:

ALL (or blank)
Specifies that the occurrence of an attention interrupt, termination of your program (either normally or through an ABEND), or any program or Language Environment condition of Severity 1 and above causes Debug Tool to gain control, regardless of whether a breakpoint is defined for that type of condition.

When a FINISH, CEE066 or CEE067 thread termination condition is raised by Language Environment, Debug Tool 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, Debug Tool does the following:

ERROR
Specifies that only the following conditions cause Debug Tool to gain control without a user-defined breakpoint. If a breakpoint exists for one of the above conditions, commands specified in the breakpoint are executed. If no commands are specified, Debug Tool reads commands from a commands file or prompts you for them in interactive mode.
NONE
Specifies that Debug Tool 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 Debug Tool to gain control unless Debug Tool 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, Debug Tool reads commands from a default user commands file:

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, Debug Tool 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 Debug Tool ignores any specification of the EQAOPTS COMMANDSDSN command. If you are debugging in line mode, Debug Tool 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.

The designation can be either a DD name or a data set name. Debug Tool uses the following procedure to determine if the designation is a DD name or data set name:

  • If the designation does not contain periods (.), Debug Tool considers it a DD name.
  • Otherwise, if you are running under CICS®, Debug Tool considers it a fully-qualified data set name.
  • Otherwise, Debug Tool 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 Debug Tool to interpret the data set name as a fully-qualified name, put a minus sign (-) in front of the name. In this case, Debug Tool will 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, Debug Tool 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. Debug Tool 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 Debug Tool session as the commands file for a subsequent Debug Tool 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 Debug Tool default code page (037). Consult with your system programmer to determine if he implemented the CODEPAGE option to specify a code page of 1047. If not, check the code page specified when you compiled your source. The C/C++ compiler uses a default code page of 1047 if you do not explicitly specify one. 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.

The following examples show how to use VADSCPnnnnn:

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

If neither the CODEPAGE option 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 Debug Tool 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 Debug Tool started immediately after Language Environment initialization. Instead, your application begins running. When Debug Tool 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 Debug Tool.

command
One or more valid Debug Tool commands. Debug Tool 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 Debug Tool 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 Debug Tool screen output during dual terminal session. The corresponding terminal should be in service and acquired, ready to receive Debug Tool-related I/O.
network_identifier (full-screen mode using a dedicated terminal 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 only)
Specifies up to an eight-character VTAM® logical unit (LU) identifier for a terminal used in full-screen mode using a dedicated terminal. 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. See Debug Tool User’s Guide for information about how to use this terminal.
VTAM (full-screen mode using a dedicated terminal using the Debug Tool Terminal Interface Manager only)
Specifies Debug Tool should be started in full-screen mode using a dedicated terminal for your debug sessions and that you have used the Debug Tool Terminal Interface Manager to assign a user ID to the terminal.
user_id (full-screen mode using a dedicated terminal using the Debug Tool Terminal Interface Manager only)
Specifies the user ID that you used to log on to the Debug Tool Terminal Interface Manager. See the entry for VTAM_LU_id for more information.
INSPPREF (or blank)
The default DD name, supplied by Debug Tool, for the preferences file.

In the following situation, Debug Tool reads commands from a default user preferences file:

Any preferences file you or your site specifies to Debug Tool becomes the first source of Debug Tool commands after Debug Tool is started. Use preferences files to set up the Debug Tool 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 Debug Tool is started and must contain a sequence of Debug Tool commands to be executed.

The designation can be either a DD name or a data set name. Debug Tool uses the following procedure to determine if the designation is a DD name or data set name:

  • If the designation does not contain periods (.), Debug Tool considers it a DD name.
  • Otherwise, if you are running under CICS, Debug Tool considers it a fully-qualified data set name.
  • Otherwise, Debug Tool 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 Debug Tool to interpret the data set name as a fully-qualified name, put a minus sign (-) in front of the name. In this case, Debug Tool will 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, Debug Tool 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, Debug Tool 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 Debug Tool ignores any specification of the EQAOPTS PREFERENCESDSN command.

The following TEST suboptions are for use only in remote debug mode:

TCPIP& or VADTCPIP& (remote debug mode only)
Specifies that Debug Tool start in remote debug mode and connect with one of the following remote debuggers:
tcpip_workstation_id (remote debug mode only)
TCP/IP name or address of the workstation 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 (remote debug mode only)
Specifies a unique TCP/IP port on your workstation that is used by the remote debug daemon. The default port number is 8001. The following remote debuggers use 8001 as the default TCP/IP port ID: If you changed the default TCP/IP port settings used by these remote debuggers, 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:').

Usage notes

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

TRAP runtime option

Use the TRAP option to specify how Debug Tool handles ABENDs and program interrupts.

The syntax for this option is:

Syntax diagram for the TRAP runtime option

ON
Enable Debug Tool to trap ABENDs.
OFF
Prevent Debug Tool from trapping ABENDs; an ABEND causes abnormal termination of both Debug Tool and the program under test.