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:
- You can mix them with other Language Environment runtime options in any order.
- Separate them with either blanks or commas.
- Separate all runtime options from user-program options with a
slash ('/').
- The placement of these options (before or after the slash) depends
on the programming language of the MAIN routine.
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:
- You must specify the name of the program to be debugged as the
first parameter; this is a positional parameter.
- Specify the runtime options in any order following the name of
the program to be debugged.
- Separate all options with commas.
- Separate the runtime options from user-program options with a
slash ('/'). If you do not specify any runtime options, the
slash follows the name of the program.
- Specify any parameters to the user-program after the slash.
- If no user-program parameters are required, you can omit the slash.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- "Planning your debug session" in Debug Tool User’s Guide
- Related
references
- z/OS Language Environment Programming Reference
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:
- one or more of the Debug Tool keyword runtime options described in
the following sections of this chapter and then a slash ('/') and
any user-program parameters
- a slash ('/') and any user-program parameters
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.
- Related tasks
- "Planning your debug session" in Debug Tool User’s Guide
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:
- 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:
- 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:
Notes:
- 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:
- In full-screen mode, Debug Tool reads commands from a commands file
(if it exists and is available) or prompts you for commands.
- In batch mode, Debug Tool reads commands from the commands file.
If none is available, the program runs uninterrupted.
- ERROR
- Specifies that only the following conditions cause Debug Tool 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, 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:
- 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, 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:
- 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 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:
- 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 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:
- IBM Debug Tool plug-in for Eclipse
- compiled language debugger component of Rational Developer for System z
- 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:
- IBM Debug Tool plug-in for Eclipse
- compiled language debugger component of Rational Developer for System z
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
- 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
- Debug Tool User’s Guide
TRAP runtime option
Use the TRAP option to specify how Debug Tool handles ABENDs
and program interrupts.
The syntax for
this option is:
- 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.