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:
- You can mix them with other Language Environment run-time options in any order.
- Separate them with either blanks or commas.
- Separate all run-time 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 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:
- You must specify the name of the program to be debugged as the
first parameter; this is a positional parameter.
- Specify the run-time options in any order following the name of
the program to be debugged.
- Separate all options with commas.
- Separate the run-time options from user-program options with a
slash ('/'). If you do not specify any run-time 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 run-time 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 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:
- 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:
- 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:
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, 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:
- 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 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:
- 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 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:
- Compiled Language Debugger component of Rational Developer for System z
- Compiled Language Debugger component of WebSphere Developer for zSeries
- Compiled Language Debugger component of WebSphere Developer for System z
- WebSphere Developer Debugger for zSeries
- WebSphere Developer Debugger 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:
- Compiled Language Debugger component of Rational Developer for System z
- Compiled Language Debugger component of WebSphere Developer for zSeries
- Compiled Language Debugger component of WebSphere Developer for System z
- WebSphere Developer Debugger for zSeries
- WebSphere Developer Debugger 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 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
- 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 run-time 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.
|
This information center is powered by Eclipse technology. (http://www.eclipse.org)