Rational Developer for System z, Version 7.6

Debug Tool run-time options

This topic describes the run-time 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 run-time 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 run-time options for a Language Environment program, they are handled by Language Environment and the following rules apply:

When you specify run-time 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 run-time 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 run-time option
country_code
A valid country code, one of:
US
United States of America
JP
Japan

NATLANG run-time 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 run-time 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 run-time option

The TEST run-time option gives control of your program to Debug Tool.

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

Syntax of the TEST run-time option

You can combine any of the suboptions for the TEST run-time 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 run-time 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, your system administrator can prevent Debug Tool from stopping at this condition by specifying the THREADTERMCOND option in the EQAOPTS option file. Contact your system administrator to determine if this option was specified.

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 no commands file is supplied. The terminal, if available, is used as the source of Debug Tool commands.
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 through a VTAM 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 through a VTAM terminal only)
Specifies up to an eight-character VTAM® logical unit (LU) identifier for a terminal used in full-screen mode through a VTAM 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 through a VTAM terminal using the Debug Tool Terminal Interface Manager only)
Specifies Debug Tool should be started in full-screen mode through a VTAM 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 through a VTAM 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)
Debug Tool-supplied default preferences file DD name. Any preferences file that is specified to Debug Tool becomes the first source of Debug Tool commands after Debug Tool is started. It is often used to set up the Debug Tool environment.
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 no preferences file is supplied.

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 run-time 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 run-time 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 run-time 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.

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)