Debug Tool commands
Commands and keywords
can be abbreviated. The abbreviations shown with some commands are
the minimum abbreviations. However, you can use a minimum abbreviation
or any string from the minimum to completely spelling out the keyword;
all are valid. This is true of all keywords for commands.
If you are debugging in full-screen mode, you can get help with Debug Tool command
syntax by either pressing PF1 or entering a question mark (?)
on the command line. This lists all Debug Tool commands in the Log window.
To get a list of options for a command, enter a partial command
followed by a question mark.
The table below summarizes the Debug Tool commands.
| ? command |
Displays all Debug Tool commands in the Log window. |
| ALLOCATE command |
Allocates a file to an existing data set, a
concatenation of existing data sets, or a temporary data set. |
| ANALYZE command (PL/I) |
Displays the process of evaluating an expression
and the data attributes of any intermediate results. |
| Assignment command (assembler and disassembly) |
Assigns the value of an expression to a specified
storage location or register. |
| Assignment command (non-Language Environment COBOL) |
Assigns the value of an expression to a specified
reference. |
| Assignment command (PL/I) |
Assigns the value of an expression to a specified
reference. |
| AT command |
Defines a breakpoint (gives control of your program
to Debug Tool under the specified circumstances). |
| BEGIN command |
BEGIN and END delimit a sequence of one or more
commands to form one longer command. |
| block command (C and C++) |
Allows you to group any number of Debug Tool commands
into one command. |
| break command (C and C++) |
Allows you to terminate and exit a loop (that
is, do, for, and while) or switch command
from any point other than the logical end. |
| CALL command |
The CALL command calls either a procedure,
entry name, or program name, or it requests that a utility function
be run. |
| CLEAR command |
Removes the actions of previously issued Debug Tool commands
(such as breakpoints). |
| COMMENT command |
Used to insert commentary into the session log. |
| COMPUTE command (COBOL) |
Assigns the value of an arithmetic expression
to a specified reference. |
| CURSOR command (full-screen mode) |
Moves the cursor between the last saved position
on the Debug Tool session panel (excluding the header fields) and the
command line. |
| Declarations (assembler, disassembly, and non-Language Environment COBOL) |
Declares session variables that are effective
during a Debug Tool session. |
| Declarations (C and C++) |
Declares session variables and tags that are effective
during a Debug Tool session. |
| Declarations (COBOL) |
Declares session variables that are effective
during a Debug Tool session. |
| DECLARE command (PL/I) |
Declares session variables that are effective
during a Debug Tool session. |
| DESCRIBE command |
Displays the attributes of references, compile
units, and the execution environment. |
| DISABLE command |
Makes the AT breakpoint inoperative,
but does not clear it; you can ENABLE it later without
typing the entire command again. |
| do/while command (C and C++) |
Performs a command before evaluating the test
expression. |
| DO command (PL/I) |
Allows one or more commands to be collected into
a group which can (optionally) be run repeatedly. |
| ENABLE command |
Makes AT breakpoints operative after
they have been disabled by the DISABLE command. |
| EVALUATE command (COBOL) |
Provides a shorthand notation for a series of
nested IF statements. |
| Expression command (C and C++) |
Evaluates the given expression which can be used
to either assign a value to a variable or to call a function. |
| FIND command |
Provides full-screen and line mode searching of
source and listing files, and full-screen searching of Log and Monitor
windows. |
| for command (C and C++) |
Provides iterative looping. |
| FREE command |
Frees (deallocates) an allocated file. |
| GO command |
Causes Debug Tool to start or resume running your
program. |
| GOTO command |
Causes Debug Tool to resume program execution at the
specified statement id. |
| GOTO LABEL command |
Causes Debug Tool to resume running program at the
specified statement label. |
| %IF command (programming language neutral) |
Lets you conditionally perform a command; use
this syntax if you are constructing a command that might run in different
programming languages. |
| IF command (assembler, disassembly, and non-Language Environment COBOL) |
Lets you conditionally perform a command. |
| if command (C and C++) |
Lets you conditionally perform a command. |
| IF command (COBOL) |
Lets you conditionally perform a command. |
| IF command (PL/I) |
Lets you conditionally perform a command. |
| IMMEDIATE command (full-screen mode) |
Causes a command within a command list to be performed
immediately. For use with commands assigned to a PF key. |
| INPUT command (C, C++, and COBOL) |
Provides input for an intercepted read and is
valid only when there is a read pending for an intercepted file. |
| JUMPTO command |
Jumps to the specified statement and then stops
the program at that statement. |
| LIST command |
Displays information about your Debug Tool session. |
| LOAD command |
Specifies that the named module should be loaded
for debugging purposes. |
| LOADDEBUGDATA command |
Specifies that a compile unit (CU) as an assembler
CU and loads debug data. |
| MEMORY command |
Identifies an address in memory to display in
the Memory window. |
| MONITOR command |
Defines or redefines a command whose output is
displayed in the Monitor window (full-screen mode), terminal output
(line mode), or log file (batch mode). |
| MOVE command (COBOL) |
Transfers data from one area of storage to another. |
| NAMES command |
Specify names of load modules or compile units
to debug or ignore, and display the current setting of the NAMES command. |
| Null command |
A semicolon written where a command is expected. |
| ON command (PL/I) |
Establishes the actions to be executed when the
specified PL/I condition is raised. |
| PANEL command (full-screen mode) |
Displays special panels (for example, to customize
your full-screen session). |
| PERFORM command (COBOL) |
Identifies a series of commands to be run. The
series of commands can be run repeatedly, if you use the UNTIL keyword
of the command. |
| PLAYBACK commands |
Commands to start and stop recording application
execution states and replay the recorded execution states. |
| Prefix commands (full-screen mode) |
Apply only to source listing lines and are typed
into the Source window. |
| PROCEDURE command |
Allows the definition of a group of commands that
can be accessed using the CALL procedure command. |
| QUALIFY RESET command |
Resets qualification to the block of the suspended
program and scrolls the source window to display the current statement
line. |
| QUERY command |
Displays the current value of Debug Tool settings
(such as the current location in the suspended program). |
| QUIT command |
Ends a Debug Tool session (with a return code, if
specified). |
| QQUIT command |
Ends a Debug Tool session (without additional prompting) |
| RETRIEVE command (full-screen mode) |
Displays the last command entered on the command
line. |
| RESTORE command |
Enables explicit restoring of settings, breakpoints,
and monitor specifications. |
| RUN command |
Causes Debug Tool to start or resume running your
program. |
| RUNTO command |
Causes Debug Tool to run your program to a specific
point (without setting a breakpoint) |
| SCROLL command (full-screen mode) |
Provides horizontal and vertical scrolling in
full-screen mode. |
| SELECT command (PL/I) |
Chooses one of a set of alternate commands. |
| SET command |
Controls various Debug Tool settings. |
| SET command (COBOL) |
Assigns a value to a COBOL reference. |
| SHOW prefix command (full-screen mode) |
Specifies what relative statement (for C) or relative
verb (for COBOL) within the line is to have its frequency count temporarily
shown in the suffix area. |
| STEP command |
Causes Debug Tool to dynamically step through a program,
running one or more program statements. |
| STORAGE command |
Enables you to alter up to eight bytes of storage. |
| switch command (C and C++) |
Enables you to transfer control to different commands
within the switch body, depending on the value of the switch expression. |
| SYSTEM command (z/OS) |
Lets you issue TSO commands during a Debug Tool session. |
| TRIGGER command |
Raises the specified AT condition in Debug Tool,
or raises the specified programming language condition in your program. |
| TSO command (z/OS) |
Lets you issue TSO commands during a Debug Tool session
(this command is valid only in a TSO environment). |
| USE command |
Causes the Debug Tool commands in the specified file
or data set to be either performed or syntax checked. |
| while command (C and C++) |
Enables you to repeatedly perform the body of
a loop until the specified condition is no longer met or evaluates
to false |
| WINDOW command (full-screen mode) |
Opens, close, resizes, or expands to full screen
(zooms) the specified window on the Debug Tool session panel. |
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
? command
The ? command displays a list of Debug Tool commands in
the Log window.
Usage
note
In the following cases, Debug Tool does not display the syntax help
after you enter the ? command:
- The Debug Tool SYSTEM and TSO commands followed
by the ? command do not display the syntax help; instead
the ? is sent to the host as part of the system command.
- The COMMENT command followed by the ? command
does not display the syntax help.
- The SET PFx command accepts a ? as the "command" operand
and, in this case, does not display syntax help.
ALLOCATE command
The ALLOCATE command allocates a file to an existing
data set, a concatenation of existing data sets, or a temporary data
set.
- FILE ddname
- The DD name of the file.
- DSNAME dsn
- The name of an existing data set.
- DSNAME (dsn,dsn,...)
- The names of the existing data sets that need to be concatenated.
- TEMP
- A temporary data set is allocated.
- TRACKS (primspc,secspc,...)
- The number of tracks for the primary space (primspc)
and secondary space (secspc) to allocate for the temporary
data set.
- OLD
- Set the disposition of the data set to OLD.
- SHR
- Set the disposition of the data set to SHR.
- MOD
- Set the disposition of the data set to MOD.
Usage
note
This command is not available under CICS®.
Refer to the following topics for more information
related to the material discussed in this topic.
ANALYZE command (PL/I)
The ANALYZE command displays the process of evaluating
an expression and the data attributes of any intermediate results.
To display the results of the expression, use the LIST command.
- EXPRESSION
- Requests that the accompanying expression be evaluated
from the following points of view:
- What are the attributes of each element during the evaluation
of the expression?
- What are the dimensions and bounds of the elements of the expression,
if applicable?
- What are the attributes of any intermediate results that will
be created during the processing of the expression?
- expression
- A valid Debug Tool PL/I expression.
Usage notes
- If SET SCREEN ON is in effect, and you want to issue ANALYZE
EXPRESSION for an expression in your program, you can bring
the expression from the Source window up to the command line by typing
over any character in the line that contains the expression. Then,
edit the command line to form the desired ANALYZE EXPRESSION command.
- If SET WARNING ON is in effect, Debug Tool displays messages
about PL/I computational conditions that might be raised when evaluating
the expression.
- Although the PL/I compiler supports the concatenation of GRAPHIC strings, Debug Tool does
not.
- The ANALYZE command cannot be used to debug Enterprise PL/I programs.
- The ANALYZE command cannot be used while you replay
recorded statements by using the PLAYBACK commands.
- The ANALYZE command cannot be used while you debug
a disassembled program.
Example
This example is based on the following program segment:
DECLARE lo_point FIXED BINARY(31,5);
DECLARE hi_point FIXED BINARY(31,3);
DECLARE offset FIXED DECIMAL(12,2);
DECLARE percent CHARACTER(12);
lo_point = 5.4; hi_point = 28.13; offset = -6.77;
percent = '18';
The following is an example of the information prepared by issuing ANALYZE
EXPRESSION. Specifically, the following shows the effect that
mixed precisions and scales have on intermediate and final results
of an expression:
ANALYZE EXPRESSION ( (hi_point - lo_point) + offset / percent )
>>> Expression Analysis <<<
( HI_POINT - LO_POINT ) + OFFSET / PERCENT
| HI_POINT - LO_POINT
| | HI_POINT
| | FIXED BINARY(31,3) REAL
| | LO_POINT
| | FIXED BINARY(31,5) REAL
| FIXED BINARY(31,5) REAL
| OFFSET / PERCENT
| | OFFSET
| | FIXED DECIMAL(12,2) REAL
| | PERCENT
| | CHARACTER(12)
| FIXED DECIMAL(15,5) REAL
FIXED BINARY(31,17) REAL
Refer to the following topics for more information
related to the material discussed in this topic.
Assignment command (assembler and disassembly)
The Assignment command assigns the value of an expression
to a specified memory location or register.
- receiver
- A valid Debug Tool assembler reference or expression.
- receiverlen
- A valid Debug Tool assembler reference or expression enclosed in
opening and closing brackets (<, >). The
value of this reference is used as the length of the receiver.
- sourceexpr
- A valid Debug Tool assembler expression.
Assignment rules
An assembler assignment is an arithmetic assignment, a bit assignment,
or a character assignment.
- Arithmetic assignments are padded (usually with zeros) and truncated
on the left. If the source has a type of F or H, the arithmetic statement
is padded with sign bits.
- Bit assignments are padded (with zeros) and truncated on the right.
- Character assignments are padded (with blanks) and truncated on
the right.
The following table shows how the assignment type is determined
from the source and receiver data types. In this table, the following
definitions are used:
- ?
- Indicates an unknown type, for example, R1->+2.
- *
- Indicates any type or length.
- Arithmetic
- Indicates an arithmetic assignment. Padding is on left with
sign bits.
- Bit
- Indicates a string assignment padded with zeros.
- Character
- Indicates a string assignment padded with blanks.
- Hex Float
- Hexadecimal floating point assignment.
- String assignment
- The number of bytes that correspond to the Min(receiver
length, source length) are moved from the source to the receiver.
If the receiver length is larger, it is padded. If the source length
is larger, it is truncated. All padding and truncation is done on
the right.
- Move
- The number of bytes that correspond to the receiver length are
moved directly into the receiver location.
- Error
- Statement that is flagged as not valid.
Table 2. Assignment rules depending on the source and receiver type
| Receiver |
Source |
Assignment type |
Pad or Truncate |
| Type |
Length |
Type |
Length |
| * |
1 -
* |
? |
? |
Move |
None |
| F, H, A, Y |
1 - 4 |
F, H, A, Y, X, B, C |
1 - 4 |
Arithmetic |
Left |
| E, D, L |
4, 8, 16 |
Hex Float |
Right - 0 |
| P, Z |
1 - * |
Arithmetic |
|
| X, B, C |
>4 |
Error |
|
| Other |
Other |
Error |
|
| X |
1 - 4 |
F, H, A, Y |
1 - 4 |
Arithmetic |
Left |
| P, Z |
1 - * |
Arithmetic |
|
| 1 - * |
X, B |
1 - * |
Bit |
Right - 0 |
| C |
Bit |
Right - 0 |
| Other |
|
Error |
|
| C |
1 - 4 |
F, H, A, Y |
1 - 4 |
Arithmetic |
Left |
| P, Z |
1 - * |
Arithmetic |
|
| 1 - * |
X, B |
1 - * |
Bit |
Right - 0 |
| C |
Character |
Right - blank |
| Other |
|
Error |
|
| P, Z |
1 - * |
P, Z |
1 - * |
Packed |
|
| F, H, A, Y, X, B, C |
1 - 4 |
Packed |
|
| E, D, L |
4, 8, 16 |
Hex Float |
Right - 0 |
| E, D, L |
4, 8, 16 |
X |
= |
Move |
None |
| E, D, L |
4, 8, 16 |
Hex Float |
Right - 0 |
| F, H, A, Y |
1 - 4 |
Hex Float |
Right - 0 |
| P, Z |
1 - * |
Hex Float |
Right - 0 |
| ? |
1 - 4 |
F, H, A, Y |
1 - 4 |
Arithmetic |
Left |
| 1 - * |
X, B, C |
1 - * |
Bit |
Right - 0 |
| All others |
Error |
|
Usage notes
- When the receiver expression does not have an implicit length,
you must specify a length override and enclose it in angle brackets
(<>). For example %R1->+10 <4> = 20; requires
an explicit length expression because the receiver expression has
no implicit length. However, X=X+1; (where X is
defined as X DS F) would not normally have an explicit
length specification.
- The Assignment command cannot be used while you replay
recorded statements by using the PLAYBACK commands.
Examples
- Assign the value 6 to variable x.
x = 6 ;
- Increment the value of X by 5.
X = X + 5 ;
- Assign to R5 the address of name_table.
%R5 = addr'name_table ;
- Assign to the prg_name variable the value of the character
string 'MYPROG'.
prg_name = 'MYPROG' ;
- Assign the value of X to the 4 bytes at offset 8 from
the contents of R8.
%R8->+8 <l'x> = x;
- Move a string of 14 bytes pointed to by the contents of R8 (where
R8 was an equated register used in the program) to 6 bytes past the
location pointed to by R2.
%R2->+6 <14> = R8->+0;
- Set 32 bytes pointed to by R6 to zero.
%R6->+0 <X'20'> = X'00';
Refer to the following topics for more information
related to the material discussed in this topic.
Assignment command (non-Language Environment COBOL)
The Assignment command assigns the value of an expression
to a specified reference. It is the equivalent of the COBOL COMPUTE
statement.
- receiver
- A valid Debug Tool non-Language Environment COBOL reference enclosed
in apostrophes (').
- sourceexpr
- A valid Debug Tool non-Language Environment COBOL expression enclosed
in apostrophes (').
Usage notes
- When receiver is an arithmetic variable, then sourceexpr can
be a hexadecimal string of the same length as receiver. Debug Tool assumes
that the correct internal representation is used and the hexadecimal
value is moved directly into receiver.
- When receiver is a non-numeric string, then sourceexpr can
be a hexadecimal string of any length. If the length of sourceexpr is
less than the length of receiver, then receiver is
padded on the right with binary zeros.
- When receiver is a COBOL INDEX variable, then Debug Tool assumes
that sourceexpr is a subscript value and converts it to the
proper offset before storing the value into receiver.
- The Assignment command cannot be used while you replay recorded
statements by using the PLAYBACK commands.
Examples
- Assign the value 6 to variable x.
'x' = '6' ;
- Increment the value of X by 5.
'X' = 'X + 5' ;
Refer to the following topics for more information
related to the material discussed in this topic.
Assignment command (PL/I)
The Assignment command assigns the value of an expression
to a specified reference.
- reference
- A valid Debug Tool PL/I reference.
- expression
- A valid Debug Tool PL/I expression.
Usage notes
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
AT command
The AT command defines a breakpoint or a set of breakpoints.
By defining breakpoints, you can temporarily suspend program execution
and use Debug Tool to perform other tasks. By specifying an AT-condition
in the AT command, you instruct Debug Tool when to gain control.
You can also specify in the AT command what action Debug Tool should
take when the AT-condition occurs.
A breakpoint for the specified AT-condition remains
established until either another AT command establishes
a new action for the same AT-condition or a CLEAR command
removes the established breakpoint. An informational message is issued
when the first case occurs. Some breakpoints might become obsolete
during a debug session and will be cleared automatically by Debug Tool.
For MVS batch, TSO, and CICS programs,
the SET SAVE and SET RESTORE commands can be used to automatically
save and restore breakpoints between Debug Tool sessions. For all
other programs, the SET SAVE and RESTORE commands can be used to automatically
save and manually restore breakpoints between sessions.
For CICS only: If you do not use the SET SAVE and SET RESTORE commands
to control the saving and restoring of breakpoints or monitor specifications
and you use a DTCN profile to start a full-screen mode debugging session, Debug Tool preserves
the following breakpoints for that session until the DTCN profile
is deleted:
- APPEARANCE breakpoints
- CALL breakpoints
- DELETE breakpoints
- ENTRY breakpoints
- EXIT breakpoints
- GLOBAL APPEARANCE breakpoints
- GLOBALCALL breakpoints
- GLOBAL DELETE breakpoints
- GLOBAL ENTRY breakpoints
- GLOBAL EXIT breakpoints
- GLOBAL LABEL breakpoints
- GLOBAL LOAD breakpoints
- GLOBAL STATEMENT/LINE breakpoints
- LABEL breakpoints
- LOAD breakpoints
- OCCURRENCE breakpoints
- STATEMENT/LINE breakpoints
- TERMINATION breakpoint
If a deferred AT ENTRY breakpoint has not been encountered, it
is not saved nor restored.
For optimized COBOL programs: The order in
which breakpoints are encountered in optimized programs is generally
the same as in unoptimized programs. There might be differences due
to the effects of optimization.
The following table summarizes the forms of the AT command.
Usage notes
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
every_clause syntax
Most forms of the AT command contain an optional every_clause that
controls whether the specified action is taken based on the number
of times a situation has occurred. For example, you might want an
action to occur only every 10th time a breakpoint is reached.
The syntax for every_clause is:
- EVERY integer
- Specifies how frequently the breakpoint is taken. For example, EVERY 5
means that Debug Tool is started every fifth time the AT-condition
is met. The default is EVERY 1.
- FROM integer
- Specifies when Debug Tool invocations are to begin. For example, FROM
8 means that Debug Tool is not started until the eighth time the AT-condition
is met. If the FROM value is not specified, its value
is equal to the EVERY value.
- TO integer
- Specifies when Debug Tool invocations are to end. For example, TO
20 means that after the 20th time this AT-condition
is met, it should no longer start Debug Tool. If the TO value
is not specified, the every_clause continues indefinitely.
Usage notes
- FROM integer cannot exceed TO integer and
all integers must be >= 1.
- EVERY by itself is the same as EVERY 1 FROM 1.
- The EVERY, FROM, and TO clauses can be specified
in any order.
Examples
- Break every third time statement 50 is reached, beginning with
the 48th time and ending after the 59th time. The breakpoint action
is performed the 48th, 51st, 54th, and 57th time statement 50 is reached.
AT EVERY 3 FROM 48 TO 59 STATEMENT 50;
- At the fifth change of structure field member of the
structure named mystruct, print a message saying that it
has changed and list its new value. In addition, clear the CHANGE breakpoint.
The current programming language setting is C.
AT FROM 5 CHANGE mystruct.member {
LIST ("mystruct.member has changed.
It is now", mystruct.member);
CLEAR AT CHANGE mystruct.member;
}
AT ALLOCATE (PL/I) command
AT ALLOCATE gives Debug Tool control when storage for a
named controlled variable or aggregate is dynamically allocated by
PL/I. When the AT ALLOCATE breakpoint occurs, the allocated
storage has not yet been initialized; initialization, if any, occurs
when control is returned to the program.
- identifier
- The name of a PL/I controlled variable whose allocation causes
an invocation of Debug Tool. If the variable is the name of a structure,
only the major structure name can be specified.
- *
- Sets a breakpoint at every ALLOCATE.
- command
- A valid Debug Tool command.
Usage notes
- The AT ALLOCATE command is not available to debug Enterprise PL/I programs.
- The AT ALLOCATE command cannot be used while you replay
recorded statements by using the PLAYBACK commands.
Examples
- When the major structure area_name is allocated,
display the address of the storage that was obtained.
AT ALLOCATE area_name LIST ADDR (area_name);
- List the changes to temp where the storage for temp has
been allocated.
DECLARE temp CHAR(80) CONTROLLED INITIAL('abc');
AT ALLOCATE temp;
BEGIN;
AT CHANGE temp;
BEGIN;
LIST (temp);
GO;
END;
GO;
END;
GO;
temp = 'The first time.';
temp = 'The second time.';
temp = 'The second time.';
When temp is allocated
the value of temp has not yet been initialized. When it
is initialized to 'abc' by the INITIAL phrase,
the first AT CHANGE is recognized and 'abc' is
listed. The three assignments to temp cause the value
to be set again but the third assignment doesn't change the value.
This example results in one ALLOCATE breakpoint and three CHANGE breakpoints.
Refer to the following topics for more information
related to the material discussed in this topic.
AT APPEARANCE command
Gives Debug Tool control when the specified compile unit is found in
storage. This is usually the result of a new load module being loaded.
However, for modules with the main compile unit in COBOL, the breakpoint
does not occur until the compile unit is first entered after being
loaded.
- *
- Sets a breakpoint at every APPEARANCE of any compile
unit.
- command
- A valid Debug Tool command.
Usage notes
- If this breakpoint is set in a parent enclave it can be triggered
and operated on with breakpoint commands while the application is
in a child enclave.
- If the compile unit is qualified with a load module name, the AT
APPEARANCE breakpoint will only be recognized for the compile
unit that is contained in the specified load module. For example,
if a compile unit cux that is in load module loady appears,
the breakpoint AT APPEARANCE loadx::>cux will not be triggered.
- If the compile unit is not qualified with
a load module name, the current load module qualification is not used.
- Debug Tool gains control when the specified compile unit is first
recognized by Debug Tool. This can occur when a program is reached that
contains a reference to that compile unit. This occurs late enough
that the program can be operated on (setting breakpoints, for example),
but early enough that the program has not yet been executed. In addition,
for C, static variables can also be referenced.
- The AT APPEARANCE command cannot be used while you
replay recorded statements by using the PLAYBACK commands.
- AT APPEARANCE is helpful when setting
breakpoints in unknown compile units. You can set breakpoints at
locations currently unknown to Debug Tool by using the proper qualification
and embedding the breakpoints in the command list associated with
an APPEARANCE breakpoint. However, there can be only one APPEARANCE breakpoint
set at any time for a given compile unit and you must include all
breakpoints for that unknown compile unit in a single APPEARANCE breakpoint.
- For a non-CICS application, the AT APPEARANCE breakpoint
is cleared at the end of a process.
- Before you enter the AT APPEARANCE command while you
debug an assembler or disassembled program, enter the SET ASSEMBLER
ON or SET DISASSEMBLY ON command.
- For C and C++ only: AT APPEARANCE is not triggered for compile
units that reside in a loaded module because the compile units are
known at the time of the load.
- For C, C++, and PL/I only: An APPEARANCE breakpoint is triggered when Debug Tool finds
the specified compile unit in storage. To be triggered, however,
the APPEARANCE breakpoint must be set before the compile
unit is loaded.
At the time the APPEARANCE breakpoint
is triggered, the compile unit you are monitoring has not become the
currently-running compile unit. The compile unit that is current
when the new compile unit appears in storage, triggering the APPEARANCE breakpoint,
remains the current compile unit until execution passes to the new
compile unit.
- For COBOL only: An APPEARANCE breakpoint is triggered when Debug Tool finds
the specified compile unit in storage. To be triggered, however, the
APPEARANCE breakpoint must be set before the compile unit is
called.
At the time the APPEARANCE breakpoint is triggered,
the compile unit you are monitoring has not become the currently-running
compile unit. The compile unit that is current when the new compile
unit appears in storage, triggering the APPEARANCE breakpoint,
remains the current compile unit until execution passes to the new
compile unit.
- For CICS only: The AT APPEARANCE breakpoint is cleared
at the end of the last process in the application.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
AT CALL command
Gives Debug Tool control when the application code attempts to call
the specified entry point. Using CALL breakpoints, you
can simulate the execution of unfinished subroutines, create dummy
or stub programs, or set variables to mimic
resultant values, allowing you to test sections of code before the
whole is complete.
- entry_name
- A valid external entry point name constant or zero (0);
however, 0 can only be specified if the current programming
language setting is C or PL/I.
- *
- Sets a breakpoint at every CALL of any entry point.
- command
- A valid Debug Tool command.
Usage notes
- AT CALL intercepts the call itself, not the subroutine
entry point. C, COBOL, and PL/I programs compiled with the PATH suboption
of the TEST or DEBUG compiler option identify
call targets even if they are unresolved.
- A breakpoint set with AT CALL for a call to a C, C++,
or PL/I built-in function is never triggered.
- AT CALL intercepts calls to entry points known to Debug Tool at
compile time. Calls to entry variables are not intercepted, except
when the current programming language setting is either C or COBOL
(compiled with the TEST run-time option).
- AT CALL 0 intercepts calls to unresolved entry points
when the current programming language setting is C or PL/I (compiled
with the TEST run-time option).
- AT CALL allows you to intercept or bypass the target
program by using GO BYPASS or GOTO. If resumed
by a normal GO or STEP, execution resumes by
performing the call.
- If you set a breakpoint in a parent enclave, the breakpoint can
be triggered and operated on with breakpoint commands while the application
is in a child enclave.
- While debugging a CICS application, the breakpoint is
cleared at the end of the last process in the CICS application.
While debugging a non-CICS application, the breakpoint is cleared
at the end of a process.
- The AT
CALL command cannot be used while you replay recorded statements
by using the PLAYBACK commands.
- You cannot use the AT CALL command while you debug
a disassembly program.
- Debug Tool does not support the AT CALL command while you
debug a non-Language Environment COBOL or any VS COBOL II program.
- For C and C++ only: The following usage notes apply:
- If your C and C++ program has unresolved entry points or entry variables,
enter the command AT CALL 0.
- To be able to set breakpoints in a C program using the AT
CALL command, you must compile your program in one of the following
ways:
- With either the PATH or ALL suboption of
the TEST compiler option.
- With either the PATH or ALL suboption of
the DEBUG compiler option.
- To be able to set breakpoints in a C++ program using the AT
CALL command, you must compile your program in one of the following
ways:
- With the TEST compiler option.
- With either the PATH or ALL suboption of
the DEBUG compiler option.
- For COBOL only: The following usage notes apply:
- entry_name can refer to a method as well as a procedure.
- If entry_name is case sensitive, enclose it in quotation
marks (") or apostrophes (').
- To be able to set breakpoints in a COBOL program by using the AT
CALL command, you must compile your program with the correct TEST compiler
suboptions. The following list describes the TEST compiler
suboptions to use for the corresponding version of the COBOL compiler:
- Specify the HOOK or NOHOOK suboption of
the TEST compiler option for Enterprise COBOL for z/OS®,
Version 4.1
- Specify the PATH, ALL, or NONE suboption
of the TEST compiler option for the following compilers:
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390® & VM, Version 2
If you compile your program with one of the following compilers
and suboptions, you cannot use the AT CALL entry_name command:
- NOHOOK suboption of the TEST compiler option
for Enterprise COBOL for z/OS, Version 4.1
- NONE suboption of the TEST compiler option
for the following compilers:
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390 & VM, Version 2
Instead, use AT CALL *.
- AT CALL 0 is not supported for use with COBOL programs.
However, COBOL is able to identify CALL targets even if
they are unresolved, and also identify entry variables and intercept
them. Therefore, not all external references need be resolved for
COBOL programs.
- For PL/I only: The following usage notes apply:
- To be able to set CALL breakpoints in PL/I, you must
compile your program with either the PATH or ALL suboptions
of the TEST compiler option. AT CALL 0 is supported
and is called for unresolved external references.
- CALL statements within an INITIAL attribute
on a PL/I variable declaration will not trigger AT CALL breakpoints.
- For assembler only: A CALL statement
can be a call to an internal or external routine. A CALL statement
is defined to be one of the following opcodes: BALR, BASR, BASSM,
BAL, BAS, BRASL, SVC, or PC. You can use the command AT CALL
MVS to give Debug Tool control at any SVC or PC instruction.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
AT CHANGE command (full screen mode, line mode,
batch mode)
Gives Debug Tool control when either the program or Debug Tool command
changes the specified variable value or storage location.
- condition
- A valid Debug Tool conditional expression.
- reference
- A valid Debug Tool reference in the current programming language.
- 'reference'
- A valid Debug Tool reference when the current programming language
is non-Language Environment COBOL.
- %STORAGE
- A built-in function that provides an alternative way to select
an AT CHANGE subject.
- address
- The starting address of storage to be watched for changes.
- length
- The number of bytes of storage being watched for changes. This
must be a positive integer constant. The default value is 1.
- command
- A valid Debug Tool command. If you are using remote debug mode,
you can specify only commands that are supported in remote debug mode.
Usage notes
- To use the AT CHANGE command for a COBOL level-88
variable, the PTF for Language Environment APAR PK12834 must be installed on z/OS Version
1 Release 6 and Version 1 Release 7.
- If an AT CHANGE breakpoint is set on a file record
of a BLOCKED QSAM file that is open OUTPUT or EXTEND, the breakpoint
might not occur as expected when the WRITE statement is used. The
breakpoint behavior in this case is not predictable because the file
record is mapped onto the data management buffer.
To get predictable AT
CHANGE behavior in this case, set up the file to use a SAME
RECORD AREA clause.
- Data is watched only in storage; hence a value that is being kept
in a register because of compiler optimization cannot be watched.
In addition, the Debug Tool variables %GPRn, %Rn, %FPRn, %LPRn, %EPRn,
and any assembler or disassembly symbols representing registers cannot
be watched.
- Only entire bytes are watched; bits or bit strings within a byte
cannot be singled out.
- Because AT CHANGE breakpoints are identified by storage
address and length, it is not possible to have two AT CHANGE breakpoints
for the same area (address and length) of storage. That is, an AT
CHANGE command replaces a previous AT CHANGE command
if the storage address and length are the same. However, any other
overlap is ignored and the breakpoints are considered to be for two
separate variables. For example, if the storage address is the same,
but the length is different, the AT CHANGE command does not replace the previous AT CHANGE.
- When more than one AT CHANGE breakpoint is triggered
at a time, AT CHANGE breakpoints are triggered in the order
that they were entered. However, if the triggering of one breakpoint
causes a variable watched by a different breakpoint to change, the
ordering of the triggers will not necessarily be according to when
they were originally entered. For example,
AT CHANGE y LIST y;
AT CHANGE x y = 4;
GO;
If the next statement to be executed in your program causes
the value of x to change, the CHANGE x breakpoint
is triggered when Debug Tool gains control. Processing of CHANGE
x causes the value of y to change. If you type GO; after
being informed that CHANGE x was triggered, Debug Tool triggers
the CHANGE y breakpoint (before returning control to your
program).
In this case, the CHANGE y breakpoint was
entered first, but the CHANGE x breakpoint was triggered
first (because it caused the CHANGE y breakpoint to be
triggered).
- %STORAGE is a Debug Tool built-in function that
is available only with the AT CHANGE command.
- For a CICS application on Debug Tool, the CHANGE %STORAGE breakpoint
is cleared at the end of the last process in the application. For
a non-CICS application on Debug Tool, it is cleared at the end of a process.
- The referenced variables must exist when the AT CHANGE breakpoint
is defined. One way to ensure this is to embed the AT CHANGE in
an AT ENTRY.
- An AT CHANGE breakpoint gets removed automatically
when the specified variable is no longer defined. AT CHANGEs
for C static variables are removed when the module defining the variable
is removed from storage. For C storage that is allocated using malloc() or calloc(),
this occurs when the dynamic storage is freed using free().
- Changes are not detected immediately, but only at the completion
of any command that has the potential of changing storage, variable
values, or the logical condition. If you specify a single reference,
you can restrict the circumstances under which the CHANGE condition
is raised by specifying a WHEN condition. If you enter
a Debug Tool command that modifies a variable being watched, the CHANGE condition
is raised immediately if no WHEN condition is specified.
If a WHEN condition is specified, the CHANGE condition
is only raised if the variable is modified and the WHEN condition
is true. You can force more or less frequent checking by using the SET
CHANGE command.
- C and C++ AT CHANGE breakpoint requirements
- The variable must be an lvalue or an array.
- The variable must be declared in an active block if the variable
is a parameter or has a storage class of auto.
- A CHANGE breakpoint defined for a static variable is
automatically removed when the file in which the variable was declared
is no longer active. A CHANGE breakpoint defined for an
external variable is automatically removed when the module where the
variable was declared is no longer active.
- If reference is a pointer, Debug Tool stops when the contents
of storage at the address given by that pointer changes.
- COBOL AT CHANGE breakpoint requirements
- AT CHANGE using a storage address should not reference
a data item that follows a variable-size element or subgroup within
a group. COBOL dynamically remaps the group when a variable-size
element changes size.
- Be careful when examining a variable whose allocated storage follows
that of a variable-size element. COBOL dynamically remaps the storage
for the element any time it changes size. This could alter the address
of the variable you want to examine.
- You cannot set a CHANGE breakpoint for a COBOL file
record before the file is opened.
- The variable, when in the local storage section, must be declared
in an active block.
- PL/I AT CHANGE breakpoint requirements
- CHANGE breakpoint is removed for based or controlled
variables when they are FREEd and for parameters and AUTOMATIC variables
when the block in which they are declared is no longer active.
- CHANGE monitors only structures with single scalar
elements. Structures containing more than one scalar element are
not supported.
- The variable must be a valid reference for the current block.
- The breakpoint is automatically removed after the referenced variable
ceases to exist.
- A CHANGE breakpoint monitors the storage allocated
to the current generation of a controlled variable. If you subsequently
allocate new generations, they are not monitored.
- When you free storage with the STORAGE RELEASE macro
in an assembler or disassembly program, it is not possible to detect
when the storage is freed. If you set an AT CHANGE breakpoint
on storage freed by a STORAGE RELEASE macro, unexpected
results might occur, such as the triggering of the breakpoint at unexpected
times.
- The AT CHANGE command cannot be used while you replay
recorded statements by using the PLAYBACK commands.
- For optimized COBOL programs, the specified variable cannot be
a variable that was discarded due to compiler optimization.
- When you use a level-88 variable on an AT CHANGE command,
the current setting of the value is saved. Debug Tool stops at the breakpoint
only if the setting of the level-88 variable changes from the
saved value to a different value. For example, if the saved value
was TRUE and the new value is FALSE, Debug Tool stops at the breakpoint.
- To use a level-88 variable with the AT CHANGE command,
you (through a Debug Tool command) or the program must have previously
set the variable to one of the values specified in the variable's
declaration. If you do not do this, Debug Tool behavior becomes unpredictable.
- When you use a condition, the variables used in the condition
or the condition are not evaluated at the time the breakpoint is set
but when the location associated with the AT CHANGE command
changes.
- Only the following conditional operators can be used in a condition:
- =
- Compare the two operands for equality.
- ¬=
- Compare the two operands for inequality.
- <
- Determines whether the left operand is less than the right operand.
- >
- Determines whether the left operand is greater than the right
operand.
- <=
- Determines whether the left operand is less than or equal to
the right operand.
- >=
- Determines whether the left operand is greater than or equal
to the right operand.
- &
- Logical "and" operation.
- |
- Logical "or" operation.
- If you use the AT CHANGE command with a WHEN condition,
every time the variable changes the condition is evaluated. If the
condition evaluates to true, Debug Tool stops and runs the command associated
with the breakpoint.
- When Debug Tool evaluates the condition and the condition is
invalid, Debug Tool does one of the following actions:
- If SET WARNING is set to ON, Debug Tool stops
and displays a message that it could not evaluate the condition.
You need to enter a command to indicate what action you want Debug Tool to
take.
- If SET WARNING is set to OFF, Debug Tool does
not stop nor display a message that it could not evaluate the condition. Debug Tool continues
running the program.
- If you specify address with more than 8 significant digits
or if reference references 64-bit addressable storage, Debug Tool assumes
that the storage location is 64-bit addressable storage. Otherwise, Debug Tool assumes
that the storage location is 31-bit addressable storage.
Examples
- Identify the current location each time variable varbl1 or varbl2 is
found to have a changed value. The current programming language setting
is COBOL.
AT CHANGE (varbl1, varbl2) PERFORM
QUERY LOCATION;
GO;
END-PERFORM;
- When storage at the hex address 22222 changes, print a message
in the log. Eight bytes of storage are to be watched. The current
programming language setting is C.
AT CHANGE %STORAGE (0x00022222, 8)
LIST "Storage has changed at hex address 22222";
- Set two breakpoints when storage at the hex address 1000 changes.
The variable x is defined at hex address 1000 and is 20
bytes in length. In the first breakpoint, 20 bytes of storage are
to be watched. In the second breakpoint, 50 bytes of storage are
to be watched. The current programming language setting is C.
AT CHANGE %STORAGE (0x00001000, 20) /* Breakpoint 1 set */
AT CHANGE %STORAGE (0x00001000, 50) /* Breakpoint 2 set */
AT CHANGE x /* Replaces breakpoint 1, since x is at */
/* hex address 1000 and is 20 bytes long */
- Stop when a variable reaches a value that is greater than 200.
AT CHANGE MYVAR WHEN MYVAR > 200 ;
MYVAR
> 200 is a condition. Every time the value of MYVAR changes,
the condition MYVAR > 200 is evaluated. Changes to MYVAR do
not trigger the AT CHANGE breakpoint. Only when MYVAR changes and the condition MYVAR > 200 becomes
true is the AT CHANGE breakpoint triggered.
Refer to the following topics for more information
related to the material discussed in this topic.
AT CHANGE command (remote debug mode)
Gives Debug Tool control when the program changes the specified variable
value.
- 'reference' or "reference"
- A valid Debug Tool reference in the current programming language.
Usage notes
- When you enter an AT CHANGE command, the breakpoint
is set relative to the location the program is stopped, which might
not be the program displayed in the source view. For example, your
program is stopped at program SUB1, which was called by program MAIN1,
and the source view displays the source for program SUB1. Then, you
click on MAIN1 in the Debug view so that the source view displays
the source for MAIN1. If you enter the command AT CHANGE "Var1",
a breakpoint is set to monitor any changes to a variable called "Var1" in
SUB1, not a variable called "Var1" in MAIN1.
- To use the AT CHANGE command for a COBOL
level-88 variable, the PTF for Language Environment APAR PK12834 must
be installed on z/OS Version 1 Release 6 and Version
1 Release 7.
- If an AT CHANGE breakpoint is set on a
file record of a BLOCKED QSAM file that is open OUTPUT or EXTEND,
the breakpoint might not occur as expected when the WRITE statement
is used. The breakpoint behavior in this case is not predictable because
the file record is mapped onto the data management buffer.
To get
predictable AT CHANGE behavior in this case, set up the
file to use a SAME RECORD AREA clause.
- Data is watched only in storage; hence a value that
is being kept in a register because of compiler optimization cannot
be watched. In addition, the Debug Tool variables %GPRn, %Rn, %FPRn, %LPRn, %EPRn,
and any assembler or disassembly symbols representing registers cannot
be watched.
- Only entire bytes are watched; bits or bit strings
within a byte cannot be singled out.
- Because AT CHANGE breakpoints are identified
by storage address and length, it is not possible to have two AT
CHANGE breakpoints for the same area (address and length) of
storage. That is, an AT CHANGE command replaces a previous AT
CHANGE command if the storage address and length are the same.
However, any other overlap is ignored and the breakpoints are considered
to be for two separate variables. For example, if the storage address
is the same, but the length is different, the AT CHANGE command does not replace the previous AT CHANGE.
- When more than one AT CHANGE breakpoint
is triggered at a time, AT CHANGE breakpoints are triggered
in the order that they were entered. However, if the triggering of
one breakpoint causes a variable watched by a different breakpoint
to change, the ordering of the triggers will not necessarily be according
to when they were originally entered. For example,
AT CHANGE y LIST y;
AT CHANGE x y = 4;
GO;
If the next statement to be executed in your program causes
the value of x to change, the CHANGE x breakpoint
is triggered when Debug Tool gains control. Processing of CHANGE
x causes the value of y to change. If you type GO; after
being informed that CHANGE x was triggered, Debug Tool triggers
the CHANGE y breakpoint (before returning control to your
program).
In this case, the CHANGE y breakpoint was
entered first, but the CHANGE x breakpoint was triggered
first (because it caused the CHANGE y breakpoint to be
triggered).
- The referenced variable must exist when the AT
CHANGE breakpoint is defined.
- An AT CHANGE breakpoint gets removed automatically
when the specified variable is no longer defined. AT CHANGEs
for C static variables are removed when the module defining the variable
is removed from storage. For C storage that is allocated using malloc() or calloc(),
this occurs when the dynamic storage is freed using free().
- Changes are not detected immediately, but only at
the completion of any command that has the potential of changing storage
or variable values.
- C and C++ AT CHANGE breakpoint requirements
- The variable must be an lvalue or an array.
- The variable must be declared in an active block if the variable
is a parameter or has a storage class of auto.
- A CHANGE breakpoint defined for a static variable is
automatically removed when the file in which the variable was declared
is no longer active. A CHANGE breakpoint defined for an
external variable is automatically removed when the module where the
variable was declared is no longer active.
- If reference is a pointer, Debug Tool stops
when the contents of storage at the address given by that pointer
changes.
- COBOL AT CHANGE breakpoint requirements
- AT CHANGE using a storage address should not reference
a data item that follows a variable-size element or subgroup within
a group. COBOL dynamically remaps the group when a variable-size
element changes size.
- Be careful when examining a variable whose allocated storage follows
that of a variable-size element. COBOL dynamically remaps the storage
for the element any time it changes size. This could alter the address
of the variable you want to examine.
- You cannot set a CHANGE breakpoint for a COBOL file
record before the file is opened.
- The variable, when in the local storage section, must be declared
in an active block.
- PL/I AT CHANGE breakpoint requirements
- CHANGE breakpoint is removed for based or controlled
variables when they are FREEd and for parameters and AUTOMATIC variables
when the block in which they are declared is no longer active.
- CHANGE monitors only structures with single scalar
elements. Structures containing more than one scalar element are
not supported.
- The variable must be a valid reference for the current block.
- The breakpoint is automatically removed after the referenced variable
ceases to exist.
- A CHANGE breakpoint monitors the storage allocated
to the current generation of a controlled variable. If you subsequently
allocate new generations, they are not monitored.
- When you free storage with the STORAGE RELEASE macro
in an assembler or disassembly program, it is not possible to detect
when the storage is freed. If you set an AT CHANGE breakpoint
on storage freed by a STORAGE RELEASE macro, unexpected
results might occur, such as the triggering of the breakpoint at unexpected
times.
- For optimized COBOL programs, the specified variable
cannot be a variable that was discarded due to compiler optimization.
- When you use a level-88 variable on an AT
CHANGE command, the current setting of the value is saved. Debug Tool stops
at the breakpoint only if the setting of the level-88 variable
changes from the saved value to a different value. For example, if
the saved value was TRUE and the new value is FALSE, Debug Tool stops
at the breakpoint.
- To use a level-88 variable with the AT
CHANGE command, you (through a Debug Tool command) or the program
must have previously set the variable to one of the values specified
in the variable's declaration. If you do not do this, Debug Tool behavior
becomes unpredictable.
- If reference references 64-bit addressable
storage, Debug Tool assumes that the storage location is 64-bit
addressable storage. Otherwise, Debug Tool assumes that the storage location
is 31-bit addressable storage.
Refer to the following topics for more information
related to the material discussed in this topic.
AT CURSOR command (full-screen mode)
Provides a cursor controlled method for setting a statement breakpoint.
It is most useful when assigned to a PF key.
- TOGGLE
- Specifies that if the cursor-selected statement already has
an associated statement breakpoint then the breakpoint is removed
rather than replaced.
Usage notes
- AT CURSOR does not allow specification of an every_clause or
a command.
- Do not use a semicolon.
- The cursor must be in the Source window and positioned on a line
where an executable statement begins. An AT STATEMENT command
for the first executable statement in the line is generated and executed
(or cleared if one is already defined and TOGGLE is specified).
For optimized COBOL programs, the first statement on the line might
have been discarded due to optimization effects. Therefore, the first
executable statement might be the second statement or later.
- The AT CURSOR command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
Example
Define a PF key to toggle the breakpoint setting at the cursor
position.
SET PF10 = AT TOGGLE CURSOR;
Refer to the following topics for more information
related to the material discussed in this topic.
AT DATE command (COBOL)
Gives Debug Tool control for each date processing statement within
the specified block. A date processing statement is a statement that
references a date field, or an EVALUATE or SEARCH statement WHEN phrase
that references a date field.
- *
- Sets a breakpoint at every date processing statement.
- command
- A valid Debug Tool command.
Usage notes
- When you use AT DATE, execution is halted only for
COBOL compile units compiled with the DATEPROC compiler
option.
- The AT DATE command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
AT DELETE command
Gives Debug Tool control when a load module is removed from storage
by a Language Environment, MVS, or CICS delete
service, such as on completion of a successful C release(),
COBOL CANCEL, PL/I RELEASE, assembler DELETE macro,
or EXEC CICS RELEASE.
- *
- Sets a breakpoint at every DELETE of any load module.
- command
- A valid Debug Tool command.
Usage notes
- Debug Tool gains control for deletes that are affected by the Language Environment delete
service, MVS delete service, or EXEC CICS RELEASE.
If the Dynamic Debug facility is deactivated (by entering the SET DYNDEBUG
OFF command) or SVC screening is disabled, Debug Tool is not notified
of deletes affected by the MVS delete service. Refer to Debug Tool Customization Guide for instructions on how to control SVC screening.
- AT DELETE cannot specify the initial load module.
- If this breakpoint is set in a parent enclave, it can be triggered
and operated on with commands while the application is in a child
enclave.
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- The AT DELETE command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
AT ENTRY command
Defines a breakpoint at the specified entry point in the specified
block.
- *
- Sets a breakpoint at every ENTRY of any block.
- command
- A valid Debug Tool command. If you are using remote debug mode,
you can specify only commands that are supported in remote debug mode.
- condition
- A valid Debug Tool conditional expression.
Usage notes
- For VS COBOL II programs, Debug Tool supports only the AT ENTRY
* command.
- To specify an AT ENTRY breakpoint for a program that
is not currently known to Debug Tool, you must do one of the following:
- If the name of the program is the same as the block_spec,
you do not need to qualify the block_spec with the name of
the program.
- If the name of the program is not the same as the block_spec,
you need to qualify the block_spec with a program name. When Debug Tool detects
a program name that matches the one you specified, it sets the breakpoint.
- An ENTRY breakpoint set for a compile unit that becomes
nonactive (one that is not in the current enclave), is suspended until
the compile unit becomes active. An ENTRY breakpoint set
for a compile unit that is deleted from storage is suspended until
the compile unit is reloaded. A suspended breakpoint cannot be triggered
until it is reactivated.
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- ENTRY breakpoints for blocks in a fetched or loaded
program are converted to deferred breakpoints when that program is
released.
- The AT ENTRY command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
- You cannot use the AT ENTRY command to stop at the
entry to a Language Environment MAIN routine for an enclave other than the first
enclave if you do not have debug data available for the containing
compile unit.
- You can restrict the circumstances under which the AT ENTRY break
point is raised by specifying a WHEN condition. If a WHEN condition
is specified, Debug Tool stops at the AT ENTRY break point
if the specified entry point matches the current entry point and the WHEN condition
is true.
- The following conditional operators can be used in a condition:
- =
- Compare the two operands for equality.
- ¬=
- Compare the two operands for inequality.
- <
- Determines whether the left operand is less than the right operand.
- >
- Determines whether the left operand is greater than the right
operand.
- <=
- Determines whether the left operand is less than or equal to
the right operand.
- >=
- Determines whether the left operand is greater than or equal
to the right operand.
- &
- Logical "and" operation.
- |
- Logical "or" operation.
- If you use the AT ENTRY command with a WHEN condition,
every time Debug Tool reaches the entry, it evaluates the condition. If
the condition evaluates to true, Debug Tool stops and runs the command
associated with the breakpoint.
- When Debug Tool evaluates the condition and the condition is invalid, Debug Tool does
one of the following actions:
- If SET WARNING is set to ON, Debug Tool stops
and displays a message that it could not evaluate the condition. You
need to enter a command to indicate what action you want Debug Tool to
take.
- If SET WARNING is set to OFF, Debug Tool does
not stop nor display a message that it could not evaluate the condition. Debug Tool continues
running the program.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
AT ENTRY command (remote debug mode)
Defines a breakpoint at the entry point of the specified block.
Refer to the following topics for more information
related to the material discussed in this topic.
AT EXIT command
Defines a breakpoint at the specified exit point in the specified
block.
- *
- Sets a breakpoint at every EXIT of any block.
- command
- A valid Debug Tool command.
Usage notes
- For VS COBOL II programs, Debug Tool supports only the AT EXIT
* command.
- An AT EXIT breakpoint can only be set for programs
that are currently fetched or loaded. To set an exit breakpoint for
a currently unknown compile unit, use the AT APPEARANCE command.
- An EXIT breakpoint set for a compile unit that becomes
nonactive (one that is not in the current enclave), is suspended until
the compile unit becomes active. An EXIT breakpoint set
for a compile unit that is deleted from storage is suspended until
the compile unit is reloaded. A suspended breakpoint cannot be triggered
until it is reactivated.
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- EXIT breakpoints for blocks in a fetched or loaded
program are removed when that program is released.
- The AT EXIT command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
- You cannot use the AT EXIT command when you are in
a disassembly compile unit.
- You cannot use the AT EXIT command when you are in
a non-Language Environment COBOL compile unit.
- For assembler only: AT EXIT gains
control on exit from internal or external routines. An EXIT is defined
to be one of the following opcodes:
- BR
- BALR, BASR, or BASSM when it is not followed by a valid instruction
Example
At exit of main, print a message and TRIGGER the SIGUSR1 condition.
The current programming language setting is C.
AT EXIT main {
puts("At exit of the program");
TRIGGER SIGUSR1;
GO;
}
Refer to the following topics for more information
related to the material discussed in this topic.
AT GLOBAL command
Gives Debug Tool control for every instance of the specified AT-condition.
These breakpoints are independent of their nonglobal counterparts
(except for AT PATH, which is identical to AT GLOBAL
PATH). Global breakpoints are always performed before their
specific counterparts.
- command
- A valid Debug Tool command.
You should use GLOBAL breakpoints where you don't have specific
information of where to set your breakpoint. For example, you want
to halt at entry to block Abcdefg_Unknwn but cannot
remember the name, you can issue AT GLOBAL ENTRY and Debug Tool will
halt every time a block is being entered. If you want to halt at
every function call, you can issue AT GLOBAL CALL.
Usage notes
- Debug Tool does not support the AT CALL, AT LABEL and AT
PATH commands for disassembled or VS COBOL II programs.
- Debug Tool does
not support the AT CALL command for non-Language Environment COBOL
programs.
- To set a global breakpoint, you can specify an asterisk (*)
with the AT command or you can specify an AT GLOBAL command.
- Although you can define GLOBAL breakpoints to coexist
with singular breakpoints of the same type at the same location or
event, COBOL does not allow you to define two or more single breakpoints
of the same type for the same location or event. The last breakpoint
you define replaces any previous breakpoint.
- The AT GLOBAL command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
Examples
- If you want to set a global AT ENTRY breakpoint, specify:
AT ENTRY *;
or
AT GLOBAL ENTRY;
- At every statement or line, display a message identifying the
statement or line. The current programming language setting is COBOL.
AT GLOBAL STATEMENT LIST ('At Statement:', %STATEMENT);
- If you enter (for COBOL):
AT EXIT table1 PERFORM
LIST TITLED (age, pay);
GO;
END-PERFORM;
then enter:
AT EXIT table1 PERFORM
LIST TITLED (benefits, scale);
GO;
END-PERFORM;
only benefits and scale are
listed when your program reaches the exit point of block table1.
The second AT EXIT replaces the first because the breakpoints
are defined for the same location. However, if you define the following GLOBAL breakpoint
with the first EXIT breakpoint, when your program reaches
the exit from table1, all four variables (age, pay, benefits,
and scale) are listed with their values, because the GLOBAL
EXIT breakpoint can coexist with the EXIT breakpoint
set for table1:
AT GLOBAL EXIT PERFORM
LIST TITLED (benefits, scale);
GO;
END-PERFORM;
- To set a GLOBAL DATE breakpoint, specify:
AT DATE *;
or
AT GLOBAL DATE;
- To combine a global breakpoint with other Debug Tool commands, specify:
AT GLOBAL DATE QUERY LOCATION;
Refer to the following topics for more information
related to the material discussed in this topic.
AT LABEL command
Gives Debug Tool control when execution has reached the specified statement
label or group of labels. For C and PL/I, if there are multiple labels
associated with a single statement, you can specify several labels
and Debug Tool gains control at each label. For COBOL, AT LABEL lets
you specify several labels, but for any group of labels that are associated
with a single statement, Debug Tool gains control for that statement only
once.
- *
- Sets a breakpoint at every LABEL.
- command
- A valid Debug Tool command.
Usage notes
- Debug Tool does
not support the AT LABEL command with VS COBOL II programs.
- A COBOL statement_label can have either of the following
forms:
- name
This form can be used in COBOL for reference
to a section name or for a COBOL paragraph name that is not within
a section or is in only one section of the block.
- name1 OF name2 or name1 IN name2
This
form must be used for any reference to a COBOL paragraph (name1) that
is within a section (name2), if the same name also exists in other
sections in the same block. You can specify either OF or IN,
but Debug Tool always uses OF for output.
Either form can be prefixed with the usual block, compile
unit, and load module qualifiers.
- For C, C++ or PL/I, you can set a LABEL breakpoint
at each label located at a statement. This is the only circumstance
where you can set more than one breakpoint at the same location.
- A LABEL breakpoint set for a nonactive compile unit
(one that is not in the current enclave) is suspended until
the compile unit becomes active. A LABEL breakpoint set
for a compile unit that is deleted from storage is suspended until
the compile unit is reloaded. A suspended breakpoint cannot be triggered
until it is reactivated.
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- You cannot set LABEL breakpoints at PL/I label variables.
- LABEL breakpoints for label constants in a fetched,
loaded program or DLL are removed when that program is released.
- To be able to set LABEL breakpoints in PL/I, you must
compile your program with either the PATH and SYM suboptions
or the ALL suboption of the TEST compiler option.
- For C, to be able to set LABEL breakpoints, you must
compile your program in one of the following ways:
- With either the PATH and SYM suboptions
or ALL suboption of the TEST compiler option.
- With either the PATH and SYM suboptions
or ALL suboption of the DEBUG compiler option.
- For C++, to be able to set LABEL breakpoints, you must
compile your program in one of the following ways:
- With the TEST compiler option.
- With either the PATH and SYM suboptions
or ALL suboption of the DEBUG compiler option.
- You can set breakpoints for more than one label at the same location.
Debug Tool is entered for each specified label.
- To be able to set LABEL breakpoints in COBOL programs,
you must compile your program with one of the following compilers
and TEST compiler suboptions:
- Specify the HOOK suboption with Enterprise COBOL for z/OS,
Version 4
- Specify the STMT, PATH, or ALL suboption
and the SYM suboption with one of the following compilers:
- any release of the Enterprise COBOL for z/OS and OS/390, Version 3, compiler
- any release of the COBOL for OS/390 and
VM, Version 2, compiler
When defining specific LABEL breakpoints Debug Tool sets
a breakpoint for each label specified, unless there are several labels
on the same statement. In this case, only the last LABEL breakpoint
defined is set.
- For COBOL, a reference to a label or a label constant can take
either of the following forms:
- name
This form is used to refer to
a section name or the name of a paragraph contained in not more than
one section of the block.
- name1 OF name2 or name1
IN name2
This form is used to refer to a paragraph contained
within a section if the paragraph name exists in other sections in
the same block. You can use either OF or IN,
but Debug Tool only uses OF for output to the log file.
- For PL/I users:
- If you are running any version of VisualAge® PL/I
or Enterprise PL/I Version 3 Release 1 through Version 3 Release 3
programs, you cannot use the AT LABEL command.
- If you are running Enterprise PL/I for z/OS, Version
3.4, or later, programs and you comply with the following requirements,
you can use the AT LABEL command to set breakpoints (except
at a label variable):
- If you are running z/OS Version 1 Release 6, apply the Language Environment PTF
for APAR PQ99039.
- If you are compiling with Enterprise PL/I Version 3 Release 4, apply
PTFs for APARs PK00118 and PK00339.
- You cannot use the AT LABEL command while you use the
disassembly view.
- The AT LABEL command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
Examples
- Set a breakpoint at label create in the currently qualified
block.
AT LABEL create;
- At program label para OF sect1 display variable names x and y and
their values, and continue program execution. The current programming
language setting is COBOL.
AT LABEL para OF sect1 PERFORM
LIST TITLED (x, y);
GO;
END-PERFORM;
- Set a breakpoint at labels label1 and label2,
even though both labels are associated to the same statement. The
current programming language setting is C.
AT LABEL label1 LIST 'Stopped at label1'; /* Label1 is first */
AT LABEL label2 LIST 'Stopped at label2'; /* Label2 is second */
Refer to the following topics for more information
related to the material discussed in this topic.
AT LINE command
Gives Debug Tool control at the specified line.
The AT LINE command is synonymous to the AT STATEMENT command.
You cannot use the AT LINE while you debug a disassembled
program. Instead, use the AT OFFSET command.
The AT LINE command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
Refer to the following topics for more information
related to the material discussed in this topic.
AT LOAD command
Gives Debug Tool control when the specified load module is brought
into storage. For example, Debug Tool gains control on completion of
a successful C fetch(), a PL/I FETCH, during
a COBOL dynamic CALL, MVS LOAD service,
or EXEC CICS LOAD. To stop at a compile unit or program
in a COBOL DLL, use AT APPEARANCE. Once the breakpoint
is raised for the specified load module, it is not raised again unless
either the load module is released and fetched again or another load
module with the specified name is fetched.
You can set LOAD breakpoints regardless of what compiler
options are in effect.
- *
- Sets a breakpoint at every LOAD of any load module.
- command
- A valid Debug Tool command.
Usage notes
- Debug Tool gains control for loads that are affected by the Language Environment load
service, the MVS LOAD service, or EXEC CICS
LOAD. A LOAD breakpoint is triggered when a new enclave
is entered. If the Dynamic Debug facility is deactivated (by entering the SET
DYNDEBUG OFF command) or SVC screening is disabled, Debug Tool is
not notified of any loads that are affected by the MVS LOAD service.
Refer to Debug Tool Customization Guide for instructions on how to control
SVC screening.
- AT LOAD can be used to detect the loading of specific
language library load modules; however, the loading of language library
load modules does not trigger an AT GLOBAL LOAD or AT
LOAD *.
- AT LOAD cannot specify the initial load module because
it is already loaded when Debug Tool is started.
- If this breakpoint is set in a parent enclave, it can be triggered
and operated on with breakpoint commands while the application is
in a child enclave.
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- AT LOAD on an implicitly or
explicitly loaded DLL is not supported by Debug Tool.
- Depending on the version of the C or C++ compiler used, Debug Tool might
recognize a compile unit in a DLL only after it has had a function
in it called. For example, if a DLL contains a function fn1 in
CU file1 and it contains a function fn2 in CU file2,
a call to fn1 will not enable Debug Tool to
recognize file2, only file1. Similarly, a call
to fn2 will not enable Debug Tool to
recognize file1.
- At the triggering of a LOAD breakpoint for C, C++,
and PL/I, Debug Tool has enough information about the loaded module to
set breakpoints and examine variables of static and extern storage
classes.
- At the triggering of a LOAD breakpoint for COBOL, C,
and C++ DLL’s, Debug Tool does not have enough information about
the loaded module to set breakpoints in blocks contained within the
module. At the triggering of an APPEARANCE breakpoint,
however, you can set such breakpoints.
- The AT LOAD command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
AT LOAD command (remote debug mode)
Gives Debug Tool control when the specified load module is brought
into storage. For example, Debug Tool gains control on completion of
a successful C fetch(), a PL/I FETCH, during
a COBOL dynamic CALL, MVS LOAD service,
or EXEC CICS LOAD. Once the breakpoint is raised for
the specified load module, it is not raised again unless either the
load module is released and fetched again or another load module with
the specified name is fetched.
You can set LOAD breakpoints regardless of what compiler
options are in effect.
AT OCCURRENCE command
Gives Debug Tool control on a language or Language Environment condition or exception or
an MVS or CICS ABEND.

- condition
- A valid condition or exception. This can be one of the following
codes or conditions:
- A Language Environment symbolic feedback code.
- A language-oriented keyword or code, depending on the current
programming language setting.
- An MVS System or User ABEND code Sxxx or
Uxxx, where xxx is
three hexadecimal digits corresponding to the desired ABEND code.
These codes are valid only when you are running without the Language Environment run
time.
- Any four-character string representing a CICS ABEND
code. This code is valid only when you are running without the Language Environment run
time.
Following are the C and C++ condition constants; they must be
uppercase and not abbreviated:
|
SIGABND
SIGABRT
SIGFPE
|
SIGILL
SIGINT
SIGIOERR
SIGSEGV
|
SIGTERM
SIGUSR1
SIGUSR2
THROWOBJ
|
When a C++ user specifies AT CONDITION THROWOBJ, Debug Tool transfers
control to the user at the point of the throw in C++ code.
PL/I
condition constants can be used. However, FILE condition constants
and CONDITION condition constants can not be used while debugging Enterprise PL/I programs.
There
are no COBOL condition constants. Instead, an Language Environment symbolic feedback
code must be used, for example, CEE347.
The TRAP(ON) run-time
option must be used to stop on Language Environment conditions or MVS or CICS Abends.
- command
- A valid Debug Tool command.
Program conditions and condition handling vary from language to
language. The methods the OCCURRENCE breakpoint uses to
adapt to each language are described below.
For C and C++:
When a C and C++ or an Language Environment condition occurs during your session,
the following series of events takes place:
- Debug Tool is started before any C or C++ signal handler.
- If you set an OCCURRENCE breakpoint for that condition, Debug Tool processes
that breakpoint and executes any commands you have specified. If
you did not set an OCCURRENCE breakpoint for that condition,
and:
- If the current test-level setting is ALL, Debug Tool prompts
you for commands or reads them from a commands file.
- If the current test-level setting is ERROR, and the
condition has an error severity level (that is, anything but SIGUSR1, SIGUSR2, SIGINT,
or SIGTERM), Debug Tool gets commands by prompting you or by
reading from a commands file.
- If the current test-level setting is NONE, Debug Tool ignores
the condition and returns control to the program.
You can set OCCURRENCE breakpoints for equivalent C and C++ signals
and Language Environment conditions. For example, you can set AT OCCURRENCE
CEE345 and AT OCCURRENCE SIGSEGV during the same
debug session. Both indicate an addressing exception and, if you
set both breakpoints, no error occurs. However, if you set OCCURRENCE breakpoints
for a condition using both its C, C++, and Language Environment designations, the Language Environment breakpoint
is the only breakpoint triggered. Any command list associated with
the C condition is not executed.
You can use OCCURRENCE breakpoints to control your program’s
response to errors.
Usage notes
- If the application program also has established an exception handler
for the condition then that handler is entered when Debug Tool releases
control, unless return is by use of GO BYPASS or GOTO or
a specific statement.
- OCCURRENCE breakpoints for COBOL IGZ conditions can only be set
after a COBOL run-time module has been initialized.
- For C, C++, and PL/I, certain Language Environment conditions map to C and C++ SIGxxx
values and PL/I condition constants. It is possible to enter two AT
OCCURRENCE breakpoints for the same condition. For example,
one could be entered with the Language Environment condition name and the other
could be entered with the C and C++ SIGxxx condition constant. In this
case, the AT OCCURRENCE breakpoint for the Language Environment condition
name is triggered and the AT OCCURRENCE breakpoint for
the C or C++ condition constant is not. However,
if an AT OCCURRENCE breakpoint for the Language Environment condition
name is not defined, the corresponding mapped C, C++, or PL/I condition
constant is triggered.
- If this breakpoint is set in a parent enclave it can be triggered
and operated on with breakpoint commands while the application is
in a child enclave.
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- For COBOL, Debug Tool detects Language Environment conditions. If a Language Environment condition
occurs during your session, the following series of events takes place:
- Debug Tool is started before any condition handler.
- If you set an OCCURRENCE breakpoint for that condition, Debug Tool processes
that breakpoint and executes any commands you have specified. If
you have not set an OCCURRENCE breakpoint for that condition,
and:
- If the current test-level setting is ALL, Debug Tool prompts
you for commands or reads them from a commands file.
- If the current test-level setting is ERROR, and the
condition has a severity level of 2 or higher, Debug Tool gets commands
by prompting you or by reading from a commands file.
- If the current test-level setting is NONE, Debug Tool ignores
the condition and returns control to the program.
You can use OCCURRENCE breakpoints to control your
program’s response to errors.
- For PL/I, Debug Tool detects Language Environment and PL/I conditions. If a condition
occurs, Debug Tool is started before any condition handler. If you have
issued an ON command or set an OCCURRENCE breakpoint for
the specified condition, Debug Tool runs the associated commands.
- If there is no AT OCCURRENCE or ON set,
then:
- If the current test-level setting is ALL, Debug Tool prompts
you for commands or reads them from a commands file.
- If the current test-level setting is ERROR, and the
condition has an error severity level of 2 or higher, Debug Tool gets
commands by prompting you or by reading from a commands file.
- If the current test-level setting is NONE, Debug Tool ignores
the condition and returns control to the program.
- Once Debug Tool returns control to the program, any relevant PL/I
ON-unit is run.
- If you are debugging a program that uses SPIE or ESPIE, while
SPIE or ESPIE is active, the program behaves as if TRAP(OFF) was
specified for all program checks except for a program check that might
arise from the use of the CALL command.
- If you are debugging a program that uses ESTAE or ESTAEX, while
ESTAE or ESTAEX is active, the program behaves as if TRAP(OFF) was
specified for all abends except program checks. Debug Tool does not handle
any conditions. The ESTAE or ESTAEX exit handles any abends except
for program checks.
- The AT OCCURRENCE command
cannot be used while you replay recorded statements using the PLAYBACK commands.
Examples
- When a data exception occurs, query the current location. The
current programming language setting is either C or COBOL.
AT OCCURRENCE CEE347 QUERY LOCATION;
- When you are running in MVS without the Language Environment run time, that
is under EQANMDBG, when a System 0C1 ABEND occurs, list information
about the current CUs with the following command:
AT OCCURRENCE S0C1 DESCRIBE CUS;
- When the SIGSEGV condition is raised, set an error
flag and call a user termination routine. The current programming
language setting is C.
AT OCCURRENCE SIGSEGV {
error = 1;
terminate (error);
}
- Suppose SIGFPE maps to CEE347 and the following breakpoints
are defined. The current programming language setting is C.
AT OCCURRENCE SIGFPE LIST "SIGFPE condition";
AT OCCURRENCE CEE347 LIST "CEE347 condition";
If the Language Environment condition
CEE347 is raised, the CEE347 breakpoint is triggered.
However,
if a breakpoint had not been defined for CEE347 and the CEE347 condition
is raised, the SIGFPE breakpoint is triggered (because
it is mapped to CEE347).
Refer to the following topics for more information
related to the material discussed in this topic.
AT OFFSET command (disassembly)
Gives Debug Tool control at the specified offset in the disassembly
view.
- command
- A valid Debug Tool command.
Usage
note
The AT OFFSET command cannot be used while you replay
recorded statements by using the PLAYBACK commands.
Examples
- Set a breakpoint at offset '2A' in the current block:
AT OFFSET X'2A';
- Set a breakpoint at offsets '2A' and '30' in the current block:
AT OFFSET (X'2A',X'30');
- Set a breakpoint in the block MYPROG at offset '3A':
AT OFFSET MYPROG:>X'3A';
Refer to the following topics for more information
related to the material discussed in this topic.
AT PATH command
Gives Debug Tool control when the flow of control changes (at a path
point). AT PATH is identical to AT GLOBAL PATH.
- command
- A valid Debug Tool command.
Usage notes
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- For C, to be able to set PATH breakpoints, you must
compile your program in one of the following ways:
- With either the PATH or ALL suboption of
the TEST compiler option.
- With either the PATH or ALL suboption of
the DEBUG compiler option.
- For C++, to be able to set PATH breakpoints, you must
compile your program in one of the following ways:
- With the TEST compiler option.
- With either the PATH or ALL suboption of
the DEBUG compiler option.
- For COBOL programs compiled with the following compilers, compile
your program with the NONE, PATH, or ALL suboption
of the TEST compiler option to be able to set PATH breakpoints:
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390 and VM, Version 2
- For PL/I, to be able to set PATH breakpoints, you must
compile your program with the PATH or ALL suboption
of the TEST compiler option.
- You cannot use the AT PATH command
while you replay recorded statements by using the PLAYBACK commands.
- Debug Tool does
not support the AT PATH command while you debug a disassembled
program or a VS COBOL II program.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
AT Prefix command (full-screen mode)
Sets a statement breakpoint when you issue this command through
the Source window prefix area. When one or more breakpoints have
been set on a line, the prefix area for that line is highlighted.
- integer
- Selects a relative statement (for C, C++, and PL/I) or a relative
verb (for COBOL) within the line. The default value is 1. For optimized
COBOL programs, the default value is the first executable statement
on the line, which was not discarded due to optimization effects.
Usage
note
The AT
Prefix command cannot be used while you replay recorded statements
by using the PLAYBACK commands.
Example
Set a breakpoint at the third statement or verb in the line (typed
in the prefix area of the line where the statement is found).
AT 3
No
space is needed as a delimiter between the keyword and the integer;
hence, AT 3 is equivalent to AT3.
Refer to the following topics for more information
related to the material discussed in this topic.
AT STATEMENT command
Gives Debug Tool control at each specified statement or line within
the given set of ranges.
- *
- Sets a breakpoint at every STATEMENT or LINE.
- command
- A valid Debug Tool command. If you are using remote debug mode,
you can specify only commands that are supported in remote debug mode.
- condition
- A valid Debug Tool conditional expression.
Usage notes
- You cannot use the AT STATEMENT command (except for
the AT STATEMENT * form) while you debug a disassembled
program. Instead, use the AT OFFSET command.
- A STATEMENT breakpoint set for a nonactive compile
unit (one that is not in the current enclave), is suspended until
the compile unit becomes active. A STATEMENT breakpoint
set for a compile unit that is deleted from storage is suspended until
the compile unit is reloaded. A suspended breakpoint cannot be triggered
until it is reactivated.
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- You can specify the first relative statement on each line in any
one of three ways. If, for example, you want to set a STATEMENT breakpoint
at the first relative statement on line three, you can enter AT
3, AT 3.0, or AT 3.1. However, Debug Tool logs
them differently according to the current programming language as
follows:
- For C and C++
The first relative statement
on a line is specified with "0". All of the above breakpoints
are logged as AT 3.0.
- For COBOL or PL/I
The first relative
statement on a line is specified with "1". All of the above
breakpoints are logged as AT 3.1. For optimized COBOL programs,
the first relative statement is the first executable statement. This
might not be the first statement if the optimizer discarded the first
statement.
- When the STORAGE run-time option is in effect, the AT
STATEMENT command cannot be used to set a breakpoint in the
prologue of an assembler compile unit between the first BALR 14,15
instruction and the following LR 13,x instruction.
- The AT STATEMENT command
cannot be used while you replay recorded statements by using the PLAYBACK command.
- You can restrict the circumstances under which the AT STATEMENT break
point is raised by specifying a WHEN condition. If a WHEN condition
is specified, Debug Tool stops at the AT STATEMENT break point
if the specified statement matches the current statement and the WHEN condition
is true.
- The following conditional operators can be used in a condition:
- =
- Compare the two operands for equality.
- ¬=
- Compare the two operands for inequality.
- <
- Determines whether the left operand is less than the right operand.
- >
- Determines whether the left operand is greater than the right
operand.
- <=
- Determines whether the left operand is less than or equal to
the right operand.
- >=
- Determines whether the left operand is greater than or equal
to the right operand.
- &
- Logical "and" operation.
- |
- Logical "or" operation.
- If you use the AT STATEMENT command with a WHEN condition,
every time Debug Tool reaches the statement, it evaluates the condition.
If the condition evaluates to true, Debug Tool stops and runs the command
associated with the breakpoint.
- Debug Tool evaluates references in a WHEN condition before it runs a statement.
- When Debug Tool evaluates the condition and the condition is invalid, Debug Tool does
one of the following actions:
- If SET WARNING is set to ON, Debug Tool stops
and displays a message that it could not evaluate the condition. You
need to enter a command to indicate what action you want Debug Tool to
take.
- If SET WARNING is set to OFF, Debug Tool does
not stop nor display a message that it could not evaluate the condition. Debug Tool continues
running the program.
Examples
- Set a breakpoint at statement or line number 23. The current
programming language setting is COBOL.
AT 23 LIST 'About to close the file';
- Set breakpoints at statements 5 through 9 of compile unit mycu.
The current programming language setting is C.
AT STATEMENT "mycu":>5 - 9;
- Set breakpoints at lines 19 through 23 and at statements 27 and
31.
AT LINE (19 - 23, 27, 31);
or
AT LINE (27, 31, 19 - 23);
- To set a breakpoint at statement or line 100 that is raised only
when the value of myvar is equal to 100, enter the following
command:
AT 100 WHEN myvar=100;
Refer to the following topics for more information
related to the material discussed in this topic.
AT STATEMENT command (remote debug mode)
Gives Debug Tool control at the specified statement or line.
Usage
note
When you enter an AT STATEMENT command, the breakpoint
is set relative to the location the program is stopped, which might
not be the program displayed in the source view. For example, your
program is stopped at program SUB1, which was called by program MAIN1,
and the source view displays the source for program SUB1. Then, you
click on MAIN1 in the Debug view so that the source view displays
the source for MAIN1. If you enter the command AT STATEMENT 13,
a breakpoint is set at statement 13 in SUB1, not statement 13 in MAIN1.
Refer to the following topics for more information
related to the material discussed in this topic.
AT TERMINATION command
Gives Debug Tool control when the application program is terminated.
- command
- A valid Debug Tool command.
Usage notes
- The setting of the current programming language when the application
program terminates might be unpredictable.
- AT TERMINATION does not allow specification of an every_clause because
termination can only occur once.
- If this breakpoint is set in a parent enclave, it can be triggered
and operated on with breakpoint commands while the application is
in a child enclave.
- When Debug Tool gains control, normal execution of the program is
complete; however, a CALL or function invocation from Debug Tool can
continue to perform program code. When the AT TERMINATION breakpoint
gives control to Debug Tool:
- Fetched load modules have not been released
- Files have not been closed
- Language-specific termination has been started yet no action has
been taken
In C, the user atexit() lists have already been
called.
In PL/I, the FINISH condition was already
raised.
- You are allowed to enter any command with AT TERMINATION.
However, normal error messages are issued for any command that cannot
be completed successfully because of lack of information about your
program.
- You can enter DISABLE AT TERMINATION; or CLEAR
AT TERMINATION; at any time to disable or clear the breakpoint.
It remains disabled or cleared until you reenable or reset it.
- For a CICS application on Debug Tool, this breakpoint is
cleared at the end of the last process in the application. For a
non-CICS application on Debug Tool, it is cleared at the end of a process.
- The AT TERMINATION command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
BEGIN command
BEGIN and END delimit a sequence of one or
more commands to form one longer command. The BEGIN and END keywords
cannot be abbreviated.
- command
- A valid Debug Tool command.
Usage notes
- The BEGIN command is most helpful when used in AT or PROCEDURE commands.
- For Enterprise PL/I, the BEGIN command is helpful when used
in IF or ON commands.
- The BEGIN command does not imply a new block or name
scope. It is equivalent to a PL/I simple DO.
- You cannot use the BEGIN command
while you replay recorded statements by using the PLAYBACK commands.
Examples
block command (C and C++)
The block command allows you to group any number of Debug Tool commands
into one command. When you enclose Debug Tool commands within a single
set of braces ({}), everything within the braces is treated
as a single command. You can place a block anywhere a command is
allowed.
- command
- A valid Debug Tool command.
Usage notes
- Declarations are not allowed within a nested block.
- The C block command does not end with a semicolon.
A semicolon after the closing brace is treated as a Null command.
- You cannot use the block command
while you replay recorded statements by using the PLAYBACK commands.
Example
Establish an entry breakpoint when load module a is
fetched.
AT LOAD a {
AT ENTRY a;
GO;
}
break command (C and C++)
The break command allows you to terminate and exit a
loop (that is, do, for, and while)
or switch command from any point other than the logical
end. You can place a break command only in the body of
a looping command or in the body of a switch command.
The break keyword must be lowercase and cannot be abbreviated.
In a looping statement, the break command ends the loop
and moves control to the next command outside the loop. Within nested
statements, the break command ends only the smallest enclosing do, for, switch,
or while commands.
In a switch body, the break command ends
the execution of the switch body and gives control to the
next command outside the switch body.
Usage notes
- You cannot use the break command
while you replay recorded statements by using the PLAYBACK commands.
Examples
- The following example shows a break command in the
action part of a for command. If the i-th element
of the array string is equal to '\0',
the break command causes the for command to
end.
for (i = 0; i < 5; i++) {
if (string[i] == '\0')
break;
length++;
}
- The following switch command contains several case clauses
and one default clause. Each clause contains a function
call and a break command. The break commands
prevent control from passing down through subsequent commands in the switch body.
char key;
key = '-';
AT LINE 15 switch (key)
{
case '+':
add();
break;
case '-':
subtract();
break;
default:
printf("Invalid key\n");
break;
}
CALL command
The CALL command calls either a procedure, entry name,
or program name, or it requests that a utility function be run. The C and C++ equivalent
for CALL is a function reference. PL/I subroutines or
functions cannot be called dynamically during a Debug Tool session. The CALL keyword
cannot be abbreviated.
In C++, calls can be made to any user function provided that
the function is declared with the following syntax:
extern "C"
In COBOL, the CALL command cannot be issued when Debug Tool is
at initialization.
The following table summarizes the forms of the CALL command.
CALL %CEBR command
Starts the CICS Temporary Storage Browser Program.
Usage notes
- Debug Tool performs an EXEC CICS LINK
to the CICS browser program. When CEBR processing is complete,
control is returned to Debug Tool through an EXEC CICS return.
- You can use this command only when you debug CICS programs
in single-terminal mode in full-screen mode.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related references
- CICS Supplied Transactions
- CICS Application Programming Guide
CALL %CECI command
Starts the CICS Command Level Interpreter Program.
Usage notes
- Debug Tool performs an EXEC CICS LINK
to the CICS command level interpreter program. When CECI
processing is complete, control is returned to Debug Tool through an EXEC CICS return.
- You can use this command only when you debug CICS programs
in single-terminal mode in full-screen mode.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related references
- CICS Supplied Transactions
- CICS Application Programming Guide
CALL %DUMP command
Calls a dump service to obtain a formatted dump.

- title
- Specifies the identification printed at the top of each page
of the dump. It must be a fixed-length character string. It must
conform to the syntax rules for a character string constant enclosed
in quotation marks (") or apostrophes (') for the current
programming language. The string length cannot exceed 80 bytes.
- options_string
- A fixed-length character string that specifies the type,
format, and destination of dump information. The string must conform
to the syntax rules for a character string constant enclosed in quotation
marks (") or apostrophes (') for the current programming language. The
string length cannot exceed 247 bytes.
Options are declared as
a string of keywords separated by blanks or commas. Some options
have suboptions that follow the option keyword and are contained in
parentheses. The options can be specified in any order, but the last
option declaration is honored if there is a conflict between it and
any preceding options.
The options_string can include
the following:
- THREAD(ALL|CURRENT)
- Dumps the current thread or all threads associated with the
current enclave. The default is to dump only the current thread.
Only one thread is supported. For enclaves that consist
of a single thread, THREAD(ALL) and THREAD(CURRENT) are
equivalent.
THREAD can be abbreviated as THR.
CURRENT can
be abbreviated as CUR.
CICS: This
option is not supported when you are running under CICS without Language Environment,
where Debug Tool issues an EXEC CICS DUMP TRANSACTION.
- TRACEBACK
- Requests a traceback of active procedures, blocks, condition
handlers, and library modules on the call chain. The traceback shows
transfers of control from either calls or exceptions. The traceback
extends backward to the main program of the current thread.
TRACEBACK can
be abbreviated as TRACE.
- NOTRACEBACK
- Suppresses traceback.
NOTRACEBACK can be abbreviated
as NOTRACE.
- FILES
- Requests a complete set of attributes of all files that are
open and the contents of the buffers used by the files.
FILES can
be abbreviated as FILE.
- NOFILES
- Suppresses file attributes of files that are open.
NOFILES can
be abbreviated as NOFILE.
- VARIABLES
- Requests a symbolic dump of all variables, arguments, and registers.
Variables
include arrays and structures. Register values are those saved in
the stack frame at the time of call. There is no way to print a subset
of this information.
Variables and arguments are printed only
if the symbol tables are available. A symbol table is generated if
a program is compiled using the compile options shown below for each
language:
| Language |
Compiler option |
| C |
TEST(SYM) |
| C++ |
TEST |
| COBOL |
TEST or TEST(h,SYM) |
| PL/I |
TEST(,SYM) |
The variables, arguments, and registers are dumped starting
with Debug Tool. The dump proceeds up the chain for the number of routines
specified by the STACKFRAME option.
VARIABLES can
be abbreviated as VAR.
- NOVARIABLES
- Suppresses dump of variables, arguments, and registers.
NOVARIABLES can
be abbreviated as NOVAR.
- BLOCKS
- Produces a separate hexadecimal dump of control blocks.
Global
control blocks and control blocks associated with routines on the
call chain are printed. Control blocks are printed for Debug Tool. The
dump proceeds up the call chain for the number of routines specified
by the STACKFRAME option.
If FILES is specified,
this is used to produce a separate hexadecimal dump of control blocks
used in the file analysis.
BLOCKS can be abbreviated
as BLOCK.
CICS: This
option is not supported when you are running under CICS without Language Environment,
where Debug Tool issues an EXEC CICS DUMP TRANSACTION.
- NOBLOCKS
- Suppresses the hexadecimal dump of control blocks.
NOBLOCKS can
be abbreviated as NOBLOCK.
- STORAGE
- Dumps the storage used by the program.
The storage is displayed
in hexadecimal and character format. Global storage and storage associated
with each routine on the call chain is printed. Storage is dumped
for Debug Tool. The dump proceeds up the call chain for the number of
routines specified by the STACKFRAME option. Storage for
all file buffers is also dumped if the FILES option is
specified. When the Dynamic Debug facility is activated, some of the original
application instructions are not displayed because they are replaced
by '0A91'x instructions.
STORAGE can be
abbreviated as STOR.
- NOSTORAGE
- Suppresses storage dumps.
NOSTORAGE can be abbreviated
as NOSTOR.
- STACKFRAME(n|ALL)
- Specifies the number of stack frames dumped from the call chain.
If STACKFRAME(ALL) is
specified, all stack frames are dumped. No stack frame storage is
dumped if STACKFRAME(0) is specified.
The particular
information dumped for each stack frame depends on the VARIABLE, BLOCK,
and STORAGE option declarations specified. The first stack
frame dumped is the one associated with Debug Tool, followed by its caller,
and proceeding backward up the call chain.
STACKFRAME can
be abbreviated to SF.
- PAGESIZE(n)
- Specifies the number of lines on each page of the dump.
This
value must be greater than 9. A value of zero (0) indicates
that there should be no page breaks in the dump.
PAGESIZE can
be abbreviated to PAGE.
- FNAME(s)
- Specifies the ddname of the file where the dump report is written.
The
default ddname CEEDUMP is used if this option is not specified.
- CONDITION
- Specifies that for each condition active on the call chain,
the following information is dumped from the Condition Information
Block (CIB):
- The address of the CIB
- The message associated with the current condition token
- The message associated with the original condition token, if different
from the current one
- The location of the error
- The machine state at the time the condition manager was started
- The ABEND code and REASON code, if the condition occurred because
of an ABEND.
The particular information that is dumped depends on the condition
that caused the condition manager to be started. The machine state
is included only if a hardware condition or ABEND occurred. The ABEND
and REASON codes are included only if an ABEND occurred.
CONDITION can
be abbreviated as COND.
- NOCONDITION
- Suppresses dump condition information for active conditions
on the call chain.
NOCONDITION can be abbreviated as NOCOND.
- ENTRY
- Includes in the dump a description of the Debug Tool routine that
called the dump service and the contents of the registers
at the point of the call. For the currently supported programming
languages, ENTRY is extraneous and will be ignored.
CICS: This option is not supported when you
are running under CICS without Language Environment, where Debug Tool issues
an EXEC CICS DUMP TRANSACTION.
- NOENTRY
- Suppresses the description of the Debug Tool routine that called
the dump service and the contents of the registers at the
point of the call.
CICS: This
option is not supported when you are running under CICS without Language Environment,
where Debug Tool issues an EXEC CICS DUMP TRANSACTION.
The defaults for the preceding options are:
- CONDITION
- FILES
- FNAME(CEEDUMP)
- NOBLOCKS
- NOENTRY
- NOSTORAGE
- PAGESIZE(60)
- STACKFRAME(ALL)
- THREAD(CURRENT)
- TRACEBACK
- VARIABLES
Usage notes
- If incorrect options are used, a default dump is written.
- The service used to format the dump is determined by the following
conditions:
- Language Environment is active
- Language Environment dump service: Debug Tool does not analyze any of the CALL %DUMP options,
but just passes them to the Language Environment dump service. Some of these options
might not be appropriate, because the call is being made from Debug Tool rather
than from your program.
- Language Environment not active and you are running under CICS
- The command: EXEC CICS DUMP TRANSACTION DUMPCODE('$DT$')
COMPLETE
- Language Environment not active and you are not running under CICS
- The MVS SNAP dump service
- When you use CALL %DUMP, one of the following
ddnames must be allocated for you to receive a formatted dump:
- CEEDUMP (default)
- SYSPRINT.
Control might not be returned to Debug Tool after the dump is produced,
depending on the option string specified.
CICS:
You do not need this allocation when you are running without Language Environment under CICS.
Under those conditions, EXEC CICS DUMP TRANSACTION is issued,
and a transaction dump with a code of $DT$ is written to
the CICS dump data set.
- COBOL does not do anything if the FILES option is specified;
the BLOCKS option gives the file information instead.
- Using a small n (like 1 or 2) with the STACKFRAME option
will not produce useful results because only
the Debug Tool stack frames appear in your dump. Larger values of n or ALL should
be used to ensure that application stack frames are shown.
- When you use the CALL %DUMP command and the Language Environment run
time is not active, the MVS SNAP macro or the EXEC
CICS DUMP command is used to generate the dump. When you are
not running under CICS, the following restrictions apply:
- The specified or default ddname must be allocated to a data set
with these attributes: RECFM=VBA, LRECL=125, and BLKSIZE=1632
- The previously described options
are mapped into SNAP options as shown in the following
table:
Table 3. %DUMP options mapping to SNAP options
| %DUMP option |
SNAP option |
| THREAD |
ignored |
| TRACEBACK |
SDATA=(PCDATA),PDATA=(SA,SAH) |
| FILES |
SDATA=(DM,IO) |
| VARIABLES |
SDATA=(CB) |
| BLOCKS |
SDATA=(SQA,LSAQ,SWA) |
| STORAGE |
PDATA=(LPA,JPA,SPLS) |
| STACKFRAME |
ignored |
| PAGESIZE |
ignored |
| FNAME |
ddname for dump |
| CONDITION |
SDATA=(Q,TRT,ERR) |
| ENTRY |
PDATA=(SUBTASKS) |
- The CALL %DUMP command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
- Related references
- PLAYBACK commands
- z/OS Language Environment Programming Guide
- z/OS Language Environment Debugging Guide
CALL %FA command
Starts and instructs IBM Fault
Analyzer to provide a formatted dump of the current machine state.
Usage
note
If you are replaying recorded statements by using the PLAYBACK commands, CALL
%FA provides a formatted dump of the machine state when you
entered PLAYBACK START.
CALL %FM command
Starts IBM File
Manager for z/OS.
- userID
- The ID of an MVS user. If you do not specify a userID,
then File Manager takes one of the following options:
- If you sign on using CESN and File Manager has been installed
with either *DEFAULT=SIGNON or *PASSWORD=REMEMBER,
then userID is assigned the user ID used to sign on.
- If you have not signed on, then File Manager prompts you for a
user ID before it displays the logon panel.
- BACKGROUND
- Specifies that all non-terminal processing be routed
to a background task.
Usage notes
- You can use this command only when you debug CICS programs.
- You need to have IBM File Manager for z/OS V9R1
installed in the CICS region.
CALL %HOGAN command
Starts Computer Sciences Corporation's KORE-HOGAN application,
also known as SMART (System Memory Access Retrieval Tool).
Usage notes
- You can use this command only when you debug CICS programs
in single-terminal mode in full-screen mode.
- If you do not have the KORE-HOGAN application, do not use this
command. If you do use this command, a Program not loadable error
occurs, which raises an AEIO exception.
CALL %VER command
Adds a line to the
log describing the maintenance level of Debug Tool that you have installed
on your system.
Usage
note
You can use this command in remote debug mode.
Example
You have Debug Tool for z/OS, Version 9 Release 1, with the
PTF for APAR PKnnnnn installed on your system. Enter
the CALL %VER command to display the following information
in the Log window:
IBM Debug Tool Version 9 Release 1 Mod 0
2008/10/28 06:43:00 AM Level: V9R1 PKnnnnn
5655-U27: Copyright IBM Corp. 1992, 2008
The time stamp that is shown is the product build date and time.
Refer to the following topics for more information
related to the material discussed in this topic.
CALL entry_name command (COBOL)
Calls an entry name in the application program. The entry name
must be a valid external entry point name (that is, callable from
other compile units).
- identifier
- A valid Debug Tool COBOL identifier.
- literal
- A valid COBOL literal.
Usage notes
- If you have a COBOL entry point name that is the same as a Debug Tool procedure
name, the procedure name takes precedence when using the CALL command.
If you want the entry name to take precedence over the Debug Tool procedure
name, you must qualify the entry name when using the CALL command.
- You can use the CALL entry_name command
to change program flow dynamically. You can pass parameters to the
called module.
- The CALL follows the same rules as calls within the
COBOL language.
- The COBOL ON OVERFLOW and ON EXCEPTION phrases
are not supported, so END-CALL is not supported.
- Only calls to separately compiled programs are supported; nested
programs are not callable by this Debug Tool command (they can of course
be started by GOTO or STEP to a compiled-in CALL).
- All calls are dynamic, that is, the called program (whether specified
as a literal or as an identifier) is loaded when
it is called.
- See Enterprise COBOL for z/OS Language Reference for an explanation of the following
COBOL keywords: ADDRESS, BY, CONTENT, LENGTH, OF, REFERENCE,
USING.
- An entry_name cannot refer to a method.
- A windowed date field cannot be specified as the identifier containing
the entry name.
- The CALL entry_name command
cannot be used while you replay recorded statements by using the PLAYBACK commands
by using the PLAYBACK command.
Example
Call the entry name sub1 passing the variables a, b,
and c.
CALL "sub1" USING a b c;
Refer to the following topics for more information
related to the material discussed in this topic.
CALL procedure command
Calls a procedure that has been defined with the PROCEDURE command.
- procedure_name
- The name given to a sequence of Debug Tool commands delimited by
a PROCEDURE command and a corresponding END command.
Usage notes
- Because the Debug Tool procedure names are always uppercase, the procedure
name is converted to uppercase even for programming languages that
have mixed-case symbols.
- The CALL keyword is required even for programming languages
that do not use CALL for subroutine invocations.
- The CALL command is restricted to calling procedures
in the currently executing enclave.
Example
Create and call the procedure named proc1.
proc1: PROCEDURE;
LIST (r, c);
END;
AT 54 CALL proc1;
CHKSTGV command
Checks whether the CICS storage check zone of a user-storage
element has been overlaid.
Usage notes
- This command applies only to CICS applications.
- You can use this command in remote debug mode.
- Do not use this command to replace the practices described in CICS Problem Determination Guide in the section Dealing
with storage violations.
Refer to the following topics for more information
related to the material discussed in this topic.
CLEAR command
The CLEAR command removes the actions of previously
entered Debug Tool commands. Some breakpoints are removed automatically
when Debug Tool determines that they are no longer meaningful. For example,
if you set a breakpoint in a fetched or loaded compile unit, the breakpoint
is discarded when the compile unit is released.

- AT
- Removes all breakpoints, including GLOBAL breakpoints,
set by previously entered AT commands, except for AT
TERMINATION breakpoints.
- AT_command
- A valid AT command that includes at least one operand.
The AT command must be complete except that the every_clause and command are
omitted.
- generic_AT_command
- A valid AT command without operands. It can be one
of the following: ALLOCATE, APPEARANCE, CALL, CHANGE, CURSOR, DATE, DELETE, ENTRY, EXIT, LABEL, LOAD, OFFSET, OCCURRENCE, PATH, STATEMENT (the LINE keyword
can be used in place of STATEMENTS), or TERMINATION.
- DECLARE
- Removes previously defined variables and tags. If no identifier follows DECLARE,
all session variables and tags are cleared. DECLARE is
equivalent to VARIABLES.
- identifier
- The name of a session variable or tag declared during the Debug Tool session.
This operand must follow the rules for the current programming language.
- EQUATE
- Removes previously defined symbolic references. If no identifier follows EQUATE,
all existing SET EQUATE synonyms are cleared.
- identifier
- The name of a previously defined reference synonym declared
during the Debug Tool session using SET EQUATE. This operand
must follow the rules for the current programming language.
- LOAD
- Removes the load module. This command has the following sub-parameter:
- module_name
- The name of one or more load modules that were loaded by Debug Tool using
the LOAD command.
- LOG
- Erases the log file and clears out the data being retained for
scrolling. In line mode, CLEAR LOG clears only the log
file.
If the log file is directed to a SYSOUT type file, CLEAR
LOG will not clear the log contents in the file.
- MEMORY
- Clears the Memory window including the memory currently being
displayed, the base address, and the history area.
- MONITOR
- Clears the commands defined for MONITOR. If no number follows MONITOR,
the entire list of commands affecting the monitor window is cleared;
the monitor window is empty.
- number
- A positive integer that refers to a monitored command. If a
list of integers is specified, all commands represented by the specified
list are cleared.
- ON (PL/I)
- Removes the effect of an earlier ON command. If no pli_condition follows
ON, all existing ON commands are cleared.
- pli_condition
- Identifies an exception condition for which there is an ON command
defined.
- PROCEDURE
- Clears previously defined Debug Tool procedures. If no procedure_name follows PROCEDURE,
all inactive procedures are cleared.
- procedure_name
- The name given to a sequence of Debug Tool commands delimited by
a PROCEDURE command and a corresponding END command.
The procedure must be currently in storage and not active.
- VARIABLES
- Removes previously defined variables and tags. If no identifier follows VARIABLES,
all session variables and tags are cleared. VARIABLES is
equivalent to DECLARE.
- identifier
- The name of a session variable or tag declared during the Debug Tool session.
This operand must follow the rules for the current programming language.
Usage notes
Examples
- Remove the LABEL breakpoint set in the program at label create.
CLEAR AT LABEL create;
- Remove previously defined variables x, y,
and z.
CLEAR DECLARE (x, y, z);
- Remove the effect of the ninth command defined for MONITOR.
CLEAR MONITOR 9;
- Remove the structure type definition tagone (assuming
all variables declared interactively using the structure tag have
been cleared). The current programming language setting is C.
CLEAR VARIABLES struct tagone;
- Establish some breakpoints with the AT command and
then remove them with the CLEAR command (checking the results
with the LIST command).
AT 50;
AT 56;
AT 55 LIST (r, c);
LIST AT;
CLEAR AT 50;
LIST AT;
CLEAR AT;
LIST AT;
- If you want to clear an AT ENTRY * breakpoint,
specify:
CLEAR AT ENTRY *;
or
CLEAR AT GLOBAL ENTRY;
- If you want to remove the DATE breakpoint for block MYBLOCK, specify:
CLEAR AT DATE MYBLOCK;
- If you want to remove a generic DATE breakpoint, specify:
CLEAR AT DATE *;
Refer to the following topics for more information
related to the material discussed in this topic.
CLEAR prefix (full-screen mode)
Clears a breakpoint when you enter this command through the Source
window prefix area or clears a selected member of the current set
of MONITOR commands when you enter this command through the Monitor
window prefix area.
- integer
- Selects a relative statement (for C and PL/I) or a relative
verb (for COBOL) within the line to remove the breakpoint if there
are multiple statements on that line. The default value is 1. For
optimized COBOL programs, the first relative statements is the first
executable statement, which was not discarded by the optimizer.
Usage notes
- The CLEAR prefix command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
- Use CL in the Monitor window prefix area to clear a
member of Monitor window.
Examples
COMMENT command
The COMMENT command can be used to insert commentary
in to the session log. The COMMENT keyword cannot be abbreviated.
- commentary
- Commentary text not including a semicolon. An embedded semicolon
is not allowed; text after a semicolon is treated as another Debug Tool command.
DBCS characters can be used within the commentary.
The COMMENT command can be used as an executable command,
that is it can be the subject of a conditional command, but it is
treated as a Null command.
Examples
COMPUTE command (COBOL)
The COMPUTE command assigns the value of an arithmetic
expression to a specified reference. The COMPUTE keyword
cannot be abbreviated.
- reference
- A valid Debug Tool COBOL numeric reference.
- expression
- A valid Debug Tool COBOL numeric expression.
Usage notes
- If you are debugging an optimized COBOL program, you can use the COMPUTE command
to assign a value to a program variable only if you first enter the SET
WARNING OFF command.
- If you are debugging an optimized COBOL program and you specify
an expression, you can reference program variables that were
not discarded by the optimizer.
- If Debug Tool was started because of a computational condition or
an attention interrupt, using an assignment to set a variable might
not give expected results. This is due to the uncertainty of variable
values within statements as opposed to their values at statement boundaries.
- COMPUTE assigns a value only to a single receiver;
unlike COBOL, multiple receiver variables are not supported.
- Floating-point receivers are not supported; however, floating-point
values can be set by using the MOVE command.
- The COBOL EQUAL keyword is not supported ("="
must be used).
- The COBOL ROUNDED and SIZE ERROR phrases
are not supported, so END-COMPUTE is not supported.
- COMPUTE cannot be used to perform a computation with
a windowed date field if the expression consists of more
than one operand.
- Any expanded date field specified as an operand in the expression is
treated as a nondate field.
- The result of the evaluation of the expression is always
considered to be a nondate field.
- If the expression consists of a single numeric operand,
the COMPUTE will be treated as a MOVE and therefore
subject to the same rules as the MOVE command.
- If the DATA parameter of the PLAYBACK ENABLE command
is in effect for the current compile unit, the COMPUTE command
can be used while you replay recorded statements by using the PLAYBACK commands.
The target of the COMPUTE command must be a session variable.
- The value assigned to a variable is always assigned to the storage
for that variable. In an optimized program, a variable can be temporarily
assigned to a register, and a new value assigned to that variable
does not necessarily alter the value used by the program.
Examples
- Assign to variable x the value of a + 6.
COMPUTE x = a + 6;
- Assign to the variable mycode the value of the Debug Tool variable %PATHCODE
+ 1.
COMPUTE mycode = %PATHCODE + 1;
- Assign to variable xx the result of the expression (a
+ e(1)) / c * 2.
COMPUTE xx = (a + e(1)) / c * 2;
You
can also use table elements in such assignments as shown in the following
example.
COMPUTE itm-2(1,2) = (a + 10) / e(2);
- To assign a value to a session variable named TSO or SYSTEM, append
the "=" to the reference as shown in the following example.
COMPUTE tso= 5;
Refer to the following topics for more information
related to the material discussed in this topic.
CURSOR command (full-screen mode)
The CURSOR command moves the cursor between the last
saved position on the Debug Tool session panel (excluding the header fields)
and the command line.
Usage notes
- The cursor position can be saved by typing the CURSOR command
on the command line and moving the cursor before pressing Enter, or
by moving the cursor and pressing a PF key with the CURSOR command
assigned to it.
- If the CURSOR command precedes any command on the command
line, the cursor is moved before the other command is performed.
This behavior can be useful in saving cursor movement for commands
that are performed repeatedly in one of the windows.
- The CURSOR command is not logged.
Example
Move the cursor between the last saved position on the Debug Tool session
panel and the command line.
CURSOR;
Declarations (assembler, disassembly, and non-Language Environment COBOL)
Use declarations to declare session variables that are effective
during a Debug Tool session. Session variables remain in effect for the
entire debug session, or process in which they were declared. Variables
declared with declarations can be used in other Debug Tool commands as
if they were declared to the compiler. Declared variables are removed
when your Debug Tool session ends or when the CLEAR command
is used to remove them.
- identifier
- A valid assembler identifier.
- F, FLn, X, XLn, C, CLn, H,
HLn, A, ALn, B, BLn, P, PLn, Z,
ZLn, E, D, L
- Type codes that correspond to the types used in the assembler DC instruction.
See the High Level
Assembler for MVS & VM & VSE: Language Reference for details about the meaning of these type codes.
Usage
note
The range of valid n values depends on the type specifier
as follows:
- C and X: 1 to 65525
- F, H, and A: 1 to 4
- B: 1 to 256
- P and Z: 1 to 16
Declarations (C and C++)
Use declarations to declare session variables and tags
that are effective during a Debug Tool session. Session variables remain
in effect for the entire debug session, or process in which they were
declared. Variables and tags declared with declarations can
be used in other Debug Tool commands as if they were declared to the compiler.
Declared variables and tags are removed when your Debug Tool session ends
or when the CLEAR command is used to remove them. The
keywords must be the correct case and cannot be abbreviated.
You can also declare enum, struct, and union data
types. The syntax is identical to C except that enum members
can only be initialized to an optionally signed integer constant.
- *
- A C indirect operator.
- identifier
- A valid C identifier.
- integer
- A valid C array bound integer constant.
- constant_expr
- A valid C integer constant.
Usage notes
Examples
- Define two C integers.
int myvar, hisvar;
- Define an enumeration variable status that represents
the following values:
Enumeration Constant Integer Representation
run 0
create 1
delete 5
suspend 6
enum statustag {run, create, delete=5, suspend} status;
- Define a variable in a struct declaration.
struct atag {
char foo;
int var1;
} avar;
- Interactively declare variables using structure tags.
struct tagone {int a; int b;} c; then
specify:
struct tagone d;
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
Declarations (COBOL)
Use declarations to declare session variables that are effective
during a Debug Tool session. Session variables remain in effect for the
entire debug session, or process in which they were declared. Variables
declared with declarations can be used in other Debug Tool commands as
if they were declared to the compiler. Declared variables are removed
when your Debug Tool session ends or when the CLEAR command
is used to remove them. The keywords cannot be abbreviated.
- level
- 1 or 77.
- identifier
- A valid COBOL data name (including DBCS data names).
- picture
- A sequence of characters from the set: S X 9 (replication factor
is optional).
If picture is not X(*),
the COBOL USAGE clause is required.
Usage notes
- A declaration cannot be used in a command list; for example, as
the subject of an IF command or WHEN clause.
- BINARY and COMP are equivalent.
- Use BINARY or COMP for COMPUTATIONAL-4.
- COMP-1 is short floating point (4 bytes).
- COMP-2 is long floating point (8 bytes).
- Only COBOL PICTURE and USAGE clauses are
supported.
- Short forms of COMPUTATIONAL (COMP) are
supported.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
- Related references
- Enterprise COBOL for z/OS Language Reference
DECLARE command (PL/I)
The DECLARE command declares session variables that
are effective during a Debug Tool session. Variables declared this way
can be used in other Debug Tool commands as if they were declared to the
compiler. They are removed with the CLEAR command or when
your Debug Tool session ends. The keywords cannot be abbreviated.

- level
- An unsigned positive integer. Level 1 must be specified for
major structure names.
- name
- A valid PL/I identifier. The name must be unique within a particular
structure level.
When name conflicts occur, Debug Tool uses session
variables before using other variables of the same name that appear
in the running programs. Use qualification to refer to the program
variable during a Debug Tool session. For example, to display the variable a declared
with the DECLARE command as well as the variable a in
the program, issue the LIST command as follows:
LIST (a, %BLOCK:a);
If
a name conflict occurs because the variable was declared earlier with
a DECLARE command, the new declaration overrides the previous
one.
- attribute
- A PL/I data or storage attribute.
Acceptable PL/I data attributes
include:
BINARY CPLX FIXED LABEL PTR
BIT DECIMAL FLOAT OFFSET REAL
CHARACTERS EVENT GRAPHIC POINTER VARYING
COMPLEX
Acceptable PL/I storage attributes include:
BASED ALIGNED UNALIGNED
Pointers
cannot be specified with the BASED option.
Only simple
factoring of attributes is allowed. DECLAREs such as the
following are not allowed:
DCL (a(2), b) PTR;
DCL (x REAL, y CPLX) FIXED BIN(31);
Also, the precision
attribute and scale factor as well as the bounds of a dimension can
be specified. If a session variable has dimensions and bounds, these
must be declared following PL/I language rules.
Usage notes
- DECLARE is not valid as a subcommand. That is, it
cannot be used as part of a DO/END or BEGIN/END block.
- Initialization is not supported.
- Program DEFAULT statements do not affect the DECLARE command.
- If you are debugging a Enterprise PL/I program, you can not declare arrays,
structures, factor attributes, or multiple session variables in one
command line.
- The DECLARE command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
Examples
- Declare x, y, and z as variables
that can be used as pointers.
DECLARE (x, y, z) POINTER;
- Declare a as a variable that can represent binary,
fixed-point data items of 15 bits.
DECLARE a FIXED BIN(15);
- Declare d03 as a variable that can represent binary,
floating-point, complex data items.
DECLARE d03 FLOAT BIN COMPLEX;
This d03 will
have the attribute of FLOAT BINARY(21).
- Declare x as a pointer, and setx as a major
structure with structure elements a and b as
fixed-point data items.
DECLARE x POINTER, 1 setx, 2 a FIXED, 2 b FIXED;
This a and b will
have the attributes of FIXED DECIMAL(5).
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
Refer to the following topics for more information
related to the material discussed in this topic.
- Related references
- Enterprise PL/I for z/OS Language Reference
DESCRIBE command
The DESCRIBE command displays the file allocations or
attributes of references, compile units, known load modules, the run-time
environment, and CICS channels and containers.

- CURSOR (Full-Screen Mode only)
- Provides a cursor-controlled method for describing variables,
structures, and arrays. If you have assigned DESCRIBE to
a PF key, you can display the attributes of a selected variable by
positioning the cursor at that variable and pressing the assigned
PF key.
- ALLOCATIONS
- Lists the current file allocations.
- USER
- Indicates that files allocated in the user's address space are
to be described.
- ALL
- Indicates that both USER and SYSTEM allocations are to be described.
- SYSTEM
- Indicates that all of the following allocations are to be described.
- LINKLIST
- Indicates that the current LINKLIB, JOBLIB, STEPLIB, and TASKLIB
allocations are to be described.
- LPALIST
- Indicates that the current LPA list is to be described.
- APFLIST
- Indicates that the current list of APF authorized data sets
is to be described.
- CATALOG
- Indicates that the current list of active catalogs is to be
described.
- PARMLIB
- Indicates that the current PARMLIB concatenation is to be described.
- PROCLIB
- Indicates that the current PROCLIB concatenation is to be described.
- ATTRIBUTES
- Displays the attributes of a specified variable or, in C and C++,
an expression. The attributes are ordinarily those that appeared
in the declaration of a variable or are assumed because of the defaulting
rules. DESCRIBE ATTRIBUTES works only for variables accessible
to the current programming language. All variables in the currently
qualified block are described if no operand is specified.
- reference
- A valid Debug Tool reference in the current programming language.
Note the following points:
In C and C++, this can be a valid expression.
For a C and C++ expression, the type is the only attribute displayed.
For a C and C++ structure or class, DESCRIBE ATTRIBUTES displays
only the attributes of the structure or class. To display the attributes
of a data object within a structure or data member in a class, use DESCRIBE
ATTRIBUTES for the specific data object or member.
In
COBOL, this can be any user-defined name appearing in the DATA
DIVISION. Names can be subscripted or substringed per their
definitions (that is, if they are defined as alphanumeric data or
as arrays).
In PL/I, if the variable is in a structure, it can
have inherited dimensions from a higher level parent. The inherited
dimensions appear as if they have been part of the declaration of
the variable.
In optimized COBOL programs, if reference refers
to a variable that was discarded by the optimizer, the address information
is replaced with a message.
- 'reference'
- A valid Debug Tool non-Language Environment COBOL reference. This form
must be used for non-Language Environment COBOL. It can contain a simple
variable or a variable with IN or OF qualifications.
- *
- Describes all variables in the compile unit. The * is
not supported for assembler, disassembly, PL/I, or non-Language Environment COBOL
programs.
- CHANNEL
- Describes CICS channels and containers, including
containers that hold Web services state data. You can specify one
of the following suboptions:
- channel_name
- Describe all containers in the channel channel_name.
- *
- Describe all the containers in all the channels in the current
scope.
- SOAP
- Describe all SOAP containers. SOAP is a synonym for DFHNODE.
If you do not specify a suboption, Debug Tool lists all of the
containers in the current channel.
- CUS
- Describes the attributes of compile units, including such things
as the compiler options and list of internal blocks. The information
returned is dependent on the HLL that the compile unit was compiled
under. CUS is equivalent to PROGRAMS.
- cu_spec
- The name of the compile unit whose attributes you want to list.
- *
- Describes all compile units.
- PROGRAMS
- Is equivalent to CUS.
- ENVIRONMENT
- The information returned includes a list of the currently opened
files. Names of files that have been opened but are currently closed
are excluded from the list. COBOL, assembler, and disassembly do not
provide any information for DESCRIBE ENVIRONMENT.
- LOADMODS
- This command displays information about load modules known to Debug Tool and
the known or potential CUs in these load modules.
If no operand
is specified, the currently active load module is assumed.
- *
- Displays a list of all load modules known to Debug Tool along
with the address, length, entry point, and the dataset from which
the module was loaded.
- load_spec
- Display information about the specified load module or load
modules and all known and potential CUs in these load modules. This
CU information consists of CSECT name, address, length, and programming
language.
Usage notes
- You can use the DESCRIBE CUS, DESCRIBE CHANNEL,
and DESCRIBE LOADMODS commands in remote debug mode.
- The DESCRIBE ALLOCATIONS command is not available under CICS.
- Cursor pointing can be used by typing the DESCRIBE CURSOR command
on the command line and moving the cursor to a variable in the Source
window before pressing Enter, or by moving the cursor and pressing
a PF key with the DESCRIBE CURSOR command assigned to it.
- When using the DESCRIBE CURSOR command for a variable
that is located by the cursor position, the variable’s name cannot
be split across different lines of the source listing.
- In C, C++, and COBOL, expressions containing parentheses ()
must be enclosed in another set of parentheses when used with the DESCRIBE
ATTRIBUTES command. For example, DESCRIBE ATTRIBUTES ((x
+ y) / z);.
- For COBOL, if DESCRIBE ATTRIBUTES * is specified and
your compile unit is large, you might receive an out
of storage error message.
- For PL/I, DESCRIBE ATTRIBUTES returns only the top-level
names for structures. DESCRIBE ATTRIBUTES * is not supported
for PL/I. To get more detail, specify the structure name as the reference.
In
order to use DESCRIBE ATTRIBUTES in an Enterprise PL/I
program, the PTF for Language Environment® APAR
PK30522 must be installed on z/OS Version
1 Release 6, Version 1 Release 7, and Version 1 Release 8.
- Non-Language Environment COBOL PIC attributes might not match the
original PIC specification in the following situations:
- A COMP-3 variable will always have an odd number of digits in
its PIC value.
- All non-numeric strings will have a PIC value of X's.
- If the DATA option of the PLAYBACK ENABLE command
is in effect for the current compile unit, the DESCRIBE ATTRIBUTES and DESCRIBE
CURSOR commands can be used while you replay recorded statements
by using the PLAYBACK commands.
- The DESCRIBE ENVIRONMENT command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
- The DESCRIBE LOADMODS command does not display information
about load modules or compile units provided by operating system,
subsystem, or run time software (for example: MVS, CICS, DB2®, IMS™,
and Language Environment) because Debug Tool ignores these modules.
- The DESCRIBE LOADMODS command cannot display the DSNAME
of load modules loaded by LPA, LLA, AOS loader, or an unknown provider
because the DSNAME for these providers is not available.
- CU information displayed by DESCRIBE LOADMODS includes
information about the following types of CUs:
- Known CUs (CUs that appear in LIST NAMES CUS output)
- Hidden disassembly CUs (If SET DISASSEMBLY OFF is in
effect these are the names of the CUs that would be created if you SET
DISASSEMBLY ON)
- Hidden COBOL CUs (COBOL CUs that have not yet been entered)
- You can use the DESCRIBE CHANNEL command only if your
application program runs on CICS Transaction
Server Version 3.1 or later.
- For PL/I, COBOL, assembler, and disassembly, if a channel name
is mixed case, you must enclose it in quotation marks (") or apostrophes
('). If you do not enclose it in quotation marks or apostrophes, Debug Tool converts
it to all upper case.
- For C and C++, all channels names are case sensitive. The following
table compares how the same command must be typed differently, depending
on the programming language you are debugging:
Table 4. Comparison of the same command used in different programming languages
| If the container name is... |
If the programming language is PL/I, COBOL,
assembler or disassembly, type in... |
If the programming language is C or C++, type
in... |
| chname |
DESCRIBE CHANNEL 'chname' |
DESCRIBE CHANNEL chname |
| conNAME |
DESCRIBE CHANNEL 'conNAME' |
DESCRIBE CHANNEL conNAME |
Examples
- Describe the attributes of argc, argv, boolean, i, ld,
and structure.
DESCRIBE ATTRIBUTES (argc, argv, boolean, i, ld, structure);
- Describe the current environment.
DESCRIBE ENVIRONMENT;
- Display information describing program myprog.
DESCRIBE PROGRAMS myprog;
Refer to the following topics for more information
related to the material discussed in this topic.
DISABLE command
The DISABLE command makes an AT or pattern-match
breakpoint inoperative. However, the breakpoint is not cleared. Later,
you can make the breakpoint operative by using the ENABLE command.
- AT_command
- An enabled AT command. The AT command
must be complete except that the every_clause and command are
omitted. Valid forms are the same as those allowed with CLEAR
AT.
- DTCN PROGRAM, CADP PROGRAM, or CADP
CU
- Prevents Debug Tool from being started by a program or compile unit
specified in prog_id or cu_id that matches a program
or compile unit specified in a DTCN or CADP profile. The following
comparisons are made:
- For DTCN, prog_id is compared to what is specified in
the Program Id field.
- For CADP, prog_id is compared to what is specified in
the Program field and cu_id is compared to what is specified
in the Compile Unit field.
You can specify a specific name (for example, PROG1) or a
partial name with the wild card character (for example, EMPL*).
Usage notes
- You can use the DISABLE CADP and DISABLE DTCN commands
in remote debug mode.
- You can use the DISABLE command to disable either active
or suspended breakpoints. However, you cannot use it to disable suspended
label breakpoints.
- If you want to disable a suspended breakpoint, you must specify
both the load module and CU name.
- To reenable a disabled AT command, use the ENABLE command.
- Disabling an AT command does not affect its replacement
by a new (enabled) version if an overlapping AT command
is later specified. It also does not prevent removal by a CLEAR
AT command.
- Breakpoints already disabled within the range(s) specified in
the specific AT command are unaffected; however, a warning
message is issued for any specified range found to contain no enabled
breakpoints.
- The DISABLE command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
- For pseudo-conversational applications running under CICS,
the DISABLE CADP or DISABLE DTCN commands apply
only to the current CICS pseudo-conversational task.
- For PL/I, COBOL, assembler and disassembly, if the cu_id or prog_id is
mixed case or case sensitive, you must enclose the name in quotation
marks (") or apostrophes (').
- For C and C++, the cu_id or prog_id is always treated
as case sensitive, even if it is not enclosed in quotation marks (").
Examples
- Disable the breakpoint that was set by the command AT ENTRY
myprog CALL proc1;.
DISABLE AT ENTRY myprog;
- If statement 25 is in a loop and you set the following breakpoint:
AT EVERY 5 FROM 1 TO 100 STATEMENT 25 LIST x;
to
disable it, enter:
DISABLE AT STATEMENT 25;
You do not
need to reenter the every_clause or the command list. To restore
the breakpoint, enter:
ENABLE AT STATEMENT 25;
- Debug Tool is started every time PROGA is run because you have a DTCN
profile that specifies PROGA in the Program ID field. If you do not
want Debug Tool to start every time PROGA is run, enter the following
command:
DISABLE DTCN PROGRAM(PROGA);
- You have a CADP profile that specifies PROG1 in the Program field
and CU1 in the Compile Unit field. If you do not want Debug Tool to start
every time this program and compile unit are run, enter the following
command:
DISABLE CADP PROGRAM PROG1 CU CU1;
- You have a CADP profile that specifies CU1 in the Compile Unit
field. If you do not want Debug Tool to start every time the compile unit
is run, enter one of the following commands:
- DISABLE CADP PROGRAM * CU CU1;
- DISABLE CADP CU CU1;
- You have several CADP profiles and Debug Tool is started every time
a program matches one of these profiles. If you do not want Debug Tool to
be started every time a program matches any of these profiles, enter
the following command:
DISABLE CADP *;
Refer to the following topics for more information
related to the material discussed in this topic.
DISABLE prefix (full-screen mode)
Disables a statement breakpoint or offset breakpoint when you issue
this command through the Source window prefix area.
- integer
- Selects a relative statement (for C and C++ or PL/I) or a relative
verb (for COBOL) within the line. The default value is 1.
Example
Disable the breakpoint at the third statement or verb in the line
by entering the following command in the prefix area of the line where
the statement is found.
DIS 3
You do not need to enter a space between the keyword and the integer: DIS
3 is equivalent to DIS3.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
DO command (assembler, disassembly, and non-Language Environment COBOL)
The DO command performs one or more commands that are
collected into a group. The DO and END keywords
delimit a group of commands called a DO group. The keywords
cannot be abbreviated.
- command
- A valid Debug Tool command.
do/while command (C and C++)
The do/while command performs a command before evaluating
the test expression. Due to this order of execution, the command
is performed at least once. The do and while keywords
must be lowercase and cannot be abbreviated.
- command
- A valid Debug Tool command.
- expression
- A valid Debug Tool C and C++ expression.
The body of the loop is performed before the while clause
(the controlling part) is evaluated. Further execution of the do/while command
depends on the value of the while clause. If the while clause
does not evaluate to false, the command is performed again. Otherwise,
execution of the command ends.
A break command can cause the execution of a do/while command
to end, even when the while clause does not evaluate to
false.
Usage
note
The do/while command cannot be used
while you replay recorded statements by using the PLAYBACK commands
by using the PLAYBACK command.
Example
The following command prompts you to enter a 1. If
you enter a 1, the command ends execution. Otherwise,
the command displays another prompt.
int reply1;
do {
printf("Enter a 1.\n");
scanf("%d", &reply1);
} while (reply1 != 1);
DO command (PL/I)
The DO command allows one or more commands to be collected
into a group that can (optionally) be repeatedly executed. The DO and END keywords
delimit a group of commands collectively called a DO group.
The keywords cannot be abbreviated.
Simple
- command
- A valid Debug Tool command.
Repeating
- WHILE
- Specifies that expression is evaluated before each
execution of the command list. If the expression evaluates to true,
the commands are executed and the DO group begins another
cycle; if it evaluates to false, execution of the DO group
ends.
- expression
- A valid Debug Tool PL/I Boolean expression.
- UNTIL
- Specifies that expression is evaluated after each execution
of the command list. If the expression evaluates to false, the commands
are executed and the DO group begins another cycle; if
it evaluates to true, execution of the DO group ends.
- command
- A valid Debug Tool command.
Iterative

- reference
- A valid Debug Tool PL/I reference.
- expression
- A valid Debug Tool PL/I expression.
- BY
- Specifies that expression is evaluated at entry to
the DO specification and saved. This saved value specifies
the increment to be added to the control variable after each execution
of the DO group.
If BY expression is
omitted from a DO specification and if TO expression is
specified, expression defaults to the value of 1.
If BY 0 is
specified, the execution of the DO group continues indefinitely
unless it is halted by a WHILE or UNTIL option,
or control is transferred to a point outside the DO group.
The BY option
allows you to vary the control variable in fixed positive or negative
increments.
- TO
- Specifies that expression is evaluated at entry of
the DO specification and saved. This saved value specifies
the terminating value of the control variable.
If TO expression is
omitted from a DO specification and if BY expression is
specified, repetitive execution continues until it is terminated by
the WHILE or UNTIL option, or until some statement
transfers control to a point outside the DO group.
The TO option
allows you to vary the control variable in fixed positive or negative
increments.
- REPEAT
- Specifies that expression is evaluated and assigned
to the control variable after each execution of the DO group.
Repetitive execution continues until it is terminated by the WHILE or UNTIL option,
or until some statement transfers control to a point outside the DO group.
The REPEAT option
allows you to vary the control variable nonlinearly. This option
can also be used for nonarithmetic control variables, such as pointers.
- WHILE
- Specifies that expression is evaluated before each
execution of the command list. If the expression evaluates to true,
the commands are executed and the DO group begins another
cycle; if it evaluates to false, execution of the DO group
ends.
- UNTIL
- Specifies that expression is evaluated after each execution
of the command list. If the expression evaluates to false, the commands
are executed and the DO group begins another cycle; if
it evaluates to true, execution of the DO group ends.
- command
- A valid Debug Tool command.
Usage
note
You cannot use the DO command
while you replay recorded statements by using the PLAYBACK commands
by using the PLAYBACK command.
Examples
- At statement 25, initialize variable a and display
the values of variables x, y, and z.
AT 25 DO; %BLOCK:>a = 0; LIST (x, y, z); END;
- Execute the DO group until ctr is greater
than 4 or less than 0.
DO UNTIL (ctr > 4) WHILE (ctr >= 0); END;
- Execute the DO group with i having the values
1, 2, 4, 8, 16, 32, 64, 128, and 256.
DO i = 1 REPEAT 2*i UNTIL (i = 256); END;
- Repeat execution of the DO group with j having
values 1 through 20, but only if k has the value 1.
DO j = 1 TO 20 BY 1 WHILE (k = 1); END;
ENABLE command
The ENABLE command activates an AT or pattern-match
breakpoint after it was disabled with the DISABLE command.
- AT_command
- A disabled AT command. The AT command
must be complete except that the every_clause and command are
omitted. Valid forms are the same as those allowed with CLEAR
AT.
- DTCN PROGRAM, CADP PROGRAM, or CADP
CU
- Re-enable a CADP or DTCN profile that was previously
disabled by the DISABLE command. The names you specify
for prog_id or cu_id must match the prog_id or cu_id you
specified in the DISABLE command.
If you do not specify
a prog_id or cu_id, Debug Tool enables all previously
disabled DTCN or CADP profiles. If you try to specify a prog_id or cu_id for
a profile that was not disabled, Debug Tool displays an error message.
Usage notes
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
ENABLE prefix (full-screen mode)
Enables a disabled statement breakpoint or a disabled offset breakpoint
when you issue this command through the Source window prefix area.
- integer
- Selects a relative statement (for C and C++ or PL/I) or a relative
verb (for COBOL) within the line. The default value is 1. For optimized
COBOL programs, the default value is the first executable statement
which was not discarded by the optimizer.
Example
Enable the breakpoint at the third statement or verb in the line
(typed in the prefix area of the line where the statement is found).
ENABLE 3
No
space is needed as a delimiter between the keyword and the integer;
hence, ENABLE 3 is equivalent to ENABLE3.
EVALUATE command (COBOL)
The EVALUATE command provides a shorthand notation for
a series of nested IF statements. The keywords cannot
be abbreviated.
- constant
- A valid Debug Tool COBOL constant.
- expression
- A valid Debug Tool COBOL arithmetic expression.
- reference
- A valid Debug Tool COBOL reference.
- condition
- A simple relation condition.
- command
- A valid Debug Tool command.
Usage notes
- Only a single subject is supported.
- Consecutive WHENs without associated commands are not
supported.
- THROUGH/THRU ranges can be specified as constants
or references.
- See Enterprise COBOL for z/OS Language Reference for an explanation of the following
COBOL keywords:
- ANY
- FALSE
- NOT
- OTHER
- THROUGH
- THRU
- TRUE
- WHEN
- Debug Tool implements the EVALUATE command as a series
of IF commands.
- If the DATA option of the PLAYBACK ENABLE command
is in effect for the current compile unit, the EVALUATE command
can be used while you replay recorded statements by using the PLAYBACK commands.
- For optimized COBOL programs, the value of reference cannot
refer to any variables discarded by the optimizer.
- If a COBOL variable is defined
as National and it is an operand in a relation condition with an alphabetic,
alphanumeric operand, or National numeric, the operand that is not
National is converted to Unicode before that
comparison is done, except for Group items. See Enterprise COBOL for z/OS Language Reference for
more information about using COBOL variables in conditional expressions.
Example
The following example shows an EVALUATE command and
the equivalent coding for an IF command:
EVALUATE menu-input
WHEN "0"
CALL init-proc
WHEN "1" THRU "9"
CALL process-proc
WHEN "R"
CALL read-parms
WHEN "X"
CALL cleanup-proc
WHEN OTHER
CALL error-proc
END-EVALUATE;
The equivalent IF command:
IF (menu-input = "0") THEN
CALL init-proc
ELSE
IF (menu-input >= "1") AND (menu-input <= "9") THEN
CALL process-proc
ELSE
IF (menu-input = "R") THEN
CALL read-parms
ELSE
IF (menu-input = "X") THEN
CALL cleanup-proc
ELSE
CALL error-proc
END-IF;
END-IF;
END-IF;
END-IF;
Refer to the following topics for more information
related to the material discussed in this topic.
Expression command (C and C++)
The Expression command evaluates the given expression.
The expression can be used to either assign a value to a variable
or to call a function.
- expression
- A valid Debug Tool C and C++ expression. Assignment is affected by
including one of the C and C++ assignment operators in the expression.
No use is made of the value resulting from a stand-alone expression.
Usage notes
- Function invocations in expressions are restricted to functions
contained in the currently executing enclave.
- The Expression command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
Examples
- Initialize the variables x, y, z.
You can use functions to provide values for variables.
x = 3 + 4/5;
y = 7;
z = 8 * func(x, y);
- Increment y and assign the remainder of the integer
division of omega by 4 to alpha.
alpha = (y++, omega % 4);
- To list and assign a new value to R1 in the disassembly
view:
LIST(R1);
R1 = 0x0001FAF0;
FIND command
The FIND command provides full-screen and line mode
search capability in the source object, and full-screen searching
of the log and monitor objects.

- string
- The string you want to find, which conforms to the syntax for
a character string constant of the current programming language. The
string must comply with the following restrictions:
- The length of the string cannot exceed 128 bytes.
- If the string contains spaces, or is an asterisk (*), a question
mark (?) or a semicolon (;) it must be enclosed in quotation marks
(") or apostrophes (') as described in the following rules:
- For C and C++, use quotation marks (").
- For COBOL, assembler, disassembly, or PL/I, use quotation marks
(") or apostrophes (').
Table 5. Examples of how to specify quotation marks (") and apostrophes (') for strings in a FIND command.
| C |
C++ |
COBOL or non-Language Environment COBOL |
Assembler or disassembly |
PL/I |
| "ABC" |
"IntLink::*" |
"A5" or 'A5' |
'ABC' or "ABC" or C'ABC' |
'ABC' or "ABC" |
- If the string contains a quotation mark (") or apostrophe
('), you might have to specify the string with an even number
of quotation marks or apostrophes (also known as
balance).
Use the following rules to determine how to balance the string:
- For PL/I, if the string has an apostrophe, you must add an apostrophe
immediately following that apostrophe. If the string contains a space,
surround the entire string with apostrophes.
- For C and C++, if the string has a quotation mark, you must add
a quotation mark immediately following that quotation mark. If the
string contains a space, surround the entire string with quotation
marks.
- For assembler, COBOL, or disassembly, if the string contains an
apostrophe and it is delimited by apostrophes, you must add an apostrophe
immediately after the apostrophe that is in the string. If the string
contains a quotation mark and it is delimited by quotation marks,
you must add a quotation mark immediately after the quotation mark
that is in the string. If the string contains a space, you do not
have to balance the quotation marks; however you must surround the
entire string with a quotation marks or apostrophes.
If no operands are specified, a repeat FIND is performed.
The usage notes and Debug Tool User’s Guide describes repeat FIND.
- *
- Use the string from the previous FIND command.
- leftcolumn
- A positive integer that specifies the leftmost column for the
search. This is supported only in the Source window and in line mode.
It is ignored in the Log and Monitor windows. If rightcolumn and * are
omitted, then the string must start in leftcolumn.
- rightcolumn
- A positive integer that specifies the rightmost column for the
search. This is supported only in the Source window and in line mode.
It is ignored in the Log and Monitor windows.
- *
- Specifies that the length of each source record is used as the
right column for the search. This is supported only in the Source
window and in line mode. It is ignored in the Log and Monitor windows.
- FIRST
- Starts at the beginning of the object and searches forward to
find the first occurrence of the string.
- LAST
- Starts at the end of the object and searches backward to find
the last occurrence of the string.
- NEXT
- Starts at the first position after the current cursor location
and searches forward to find the next occurrence of the string.
- PREV
- Starts at the current cursor location and searches backward
to find the previous occurrence of the string.
- CURSOR (Full-Screen Mode)
- Specifies that the current cursor position selects the object
searched.
- LOG (Full-Screen Mode)
- Selects the object in the session log window.
- MONITOR (Full-Screen Mode)
- Selects the object in the monitor window.
- SOURCE (Full-Screen Mode)
- Selects the object in the source listing window.
Usage notes
Examples
- Indicate that you want to search the monitor window for the name myvar.
FIND myvar MONITOR;
- If you want to search the Source window for the next occurrence
of var1, just enter:
FIND
You do not need to
provide the variable name, because the Debug Tool remembers the string
you last searched for. Again, the Source window is scrolled forward, var1 is
highlighted, and the cursor points to the variable.
- If you want to find a question mark (?) in the Source
window and you are debugging a PL/I program, enter the following command:
FIND '?' ;
- If you want to find the string User's in
the Source window and you are debugging a PL/I program, enter the
following command:
FIND User''s ;
- If you want to find the string User's in
the Source window and you are debugging a C program, enter the following
command:
FIND User's ;
- If you want to find the string User's Guide in
the Source window and you are debugging a PL/I program, enter the
following command:
FIND 'User''s Guide' ;
- If you want to find the string User's Guide in
the Source window and you are debugging a C program, enter the following
command:
FIND "User's Guide" ;
- If you entered the command FIND xyz LAST; or FIND
xyz PREV; and the cursor is on the found string ("xyz"),
then press the PF key assigned to the FIND command to repeat
the search. Debug Tool runs the command FIND xyz PREV;.
- If you entered the command FIND xyz;, Debug Tool searches
in the forward direction. To find the string "xyz" in the
backward direction, enter the command FIND * PREV;.
- If you want to find a COBOL paragraph definition named paraa that
starts in column 8 in COBOL's Area A, enter the following command:
FIND paraa 8 ;
- If you want to find a reference to a COBOL paragraph named paraa in
COBOL's Area B, then enter one of the following commands:
for command (C and C++)
The for command provides iterative looping similar to
the C and C++ for statement. It enables you to do the following:
- Evaluate an expression before the first iteration of the command
("initialization").
- Specify an expression to determine whether the command should
be performed again ("controlling part").
- Evaluate an expression after each iteration of the command.
- Perform the command, or block, if the controlling part
does not evaluate to false.
The for keyword must be lowercase and cannot be abbreviated.
- expression
- A valid Debug Tool C and C++ expression.
- command
- A valid Debug Tool command.
Debug Tool evaluates the first expression only before the
command is performed for the first time. You can use this expression
to initialize a variable. If you do not want to evaluate an expression
before the first iteration of the command, you can omit this expression.
Debug Tool evaluates the second expression before each execution
of the command. If this expression evaluates to false, the command
does not run and control moves to the command following the for command.
Otherwise, the command is performed. If you omit the second expression,
it is as if the expression has been replaced by a nonzero constant
and the for command is not terminated by failure of this
expression.
Debug Tool evaluates the third expression after each execution
of the command. You might use this expression to increase, decrease,
or reinitialize a variable. If you do not want to evaluate an expression
after each iteration of the command, you can omit this expression.
A break command can cause the execution of a for command
to end, even when the second expression does not evaluate to false.
If you omit the second expression, you must use a break command
to stop the execution of the for command.
Usage notes
- The for command cannot be used while you replay recorded
statements by using the PLAYBACK commands.
Examples
- The following for command lists the value of count 20
times. The for command initially sets the value of count to
1. After each execution of the command, count is incremented.
for (count = 1; count <= 20; count++)
LIST TITLED count;
Alternatively, the preceding example
can be written with the following sequence of commands to accomplish
the same task.
count = 1;
while (count <= 20) {
printf("count = %d\n", count);
count++;
}
- The following for command does not contain an initialization
expression.
for (; index > 10; --index) {
varlist[index] = var1 + var2;
printf("varlist[%d] = %d\n", index, varlist[index]);
}
FREE command
The FREE command frees a file that is currently allocated.
- ddname
- Name of the file to free.
GO command
The GO command causes Debug Tool to start or resume running
your program.
- BYPASS
- Bypasses the user or system action for the condition that caused
the breakpoint. It is valid only when Debug Tool is entered for an:
- AT CALL breakpoint
- HLL or Language Environment condition
- Condition raised by an MVS or CICS ABEND
when running without the Language Environment run time
Usage notes
- If GO is specified in a command list (for example,
as the subject of an IF command or WHEN clause),
all subsequent commands in the list are ignored.
- If GO is specified within the body of a loop, it causes
the execution of the loop to end.
- To suppress the logging of GO commands, use the SET
ECHO command.
- GO with no operand specified does not actually resume
the program if there are additional AT-conditions that
have not yet been processed.
- The GO command cannot be used while you replay recorded
statements by using the PLAYBACK commands by using the PLAYBACK command.
- You can use the GO command in remote debug mode only by
entering it in the Action field, which
is in the Optional Parameters section
of the Add a Breakpoint task.
Examples
- Resume execution.
GO;
- Resume execution and bypass user and system actions for the condition
that caused the breakpoint.
GO BYPASS;
- Your application has abended with a protection exception, so an OCCURRENCE breakpoint
has been triggered. Correct the results of the instruction that caused
the exception and issue GO BYPASS; to continue processing
as if the abend had not occurred.
Refer to the following topics for more information
related to the material discussed in this topic.
GOTO command
The GOTO command causes Debug Tool to resume program execution
at the specified statement id. The GOTO keyword cannot
be abbreviated. If you want Debug Tool to return control to you at a
target location, make sure there is a breakpoint at that location.
Usage notes
- You cannot
use the GOTO command while you debug a disassembled program.
- If GOTO is specified in a command list (for example,
as the subject of an IF command or WHEN clause),
all subsequent commands in the list are ignored.
- Statement GOTO’s are not restricted if the program
is compiled with minimum optimization.
- The GOTO command cannot be
used while you replay recorded statements by using the PLAYBACK command.
- For C, C++, and PL/I, statements can be removed by the compiler
during optimization, specify a reference or statement with the GOTO command
that can be reached during program execution. You can issue the LIST
STATEMENT NUMBERS command to determine the reachable statements.
- PL/I allows GOTO in a command list on a call to PLITEST or CEETEST.
- In PL/I, out-of-block GOTOs are allowed. However,
qualification might be needed.
- For COBOL, the GOTO command follows
the COBOL language rules for the GOTO statement. You can
use the GOTO command in the following situations:
- A COBOL program compiled with hooks inserted by the compiler.
If you are using Enterprise COBOL for z/OS, Version
4.1, compile your program with the HOOK suboption of the TEST compiler
option. If you are using any of the following compilers, compile your
program with either PATH or ALL suboption and
the SYM suboption of the TEST compiler option:
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390 & VM, Version 2
- A COBOL program compiled without hooks inserted by the compiler
and without optimization. If you are using Enterprise COBOL for z/OS,
Version 4.1, compile your program with the NOHOOK suboption
of the TEST compiler option. If you are using any of the
following compilers, compile your program with the NONE suboption
of the TEST compiler option:
- Enterprise COBOL for z/OS and OS/390,
Version 3 Release 2 or later
- Enterprise COBOL for z/OS and OS/390,
Version 3 Release 1, with APAR PQ63235 installed
- COBOL for OS/390 & VM, Version 2 Release
2
- COBOL for OS/390 & VM, Version 2 Release
1, with APAR PQ63234 installed
- A COBOL program compiled without hooks inserted by the compiler
and with optimization. You must compile your program with Enterprise
COBOL for z/OS, Version 4.1, and specify the EJPD and NOHOOK suboption
of the TEST compiler option. Specifying the EJPD suboption
might cause some loss of optimization.
Examples
- Resume execution at statement 23, where statement 23 is in a currently
active block.
GOTO 23;
If there’s no breakpoint at
statement 23, Debug Tool will run from statement 23 until a breakpoint
is hit.
- Resume execution at statement 45, where statement 45 is in a currently
active block.
AT 45
GOTO 45
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
- Related references
- statement_id
GOTO LABEL command
The GOTO LABEL command causes Debug Tool to resume program
execution at the specified statement label. The specified label must
be in the same block. If you want Debug Tool to return control to you
at the target location, make sure there is a breakpoint at that location.
- statement_label
- A valid statement label within the currently executing program
or, in PL/I, a label variable.
Usage notes
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
%IF command (programming language neutral)
The %IF command lets you conditionally perform a command.
You can optionally specify an ELSE clause on the %IF command.
If the test expression evaluates to false and the ELSE clause
exists, the command associated with the ELSE clause is
performed. The keywords cannot be abbreviated.
- condition
- A simple relation condition valid for all supported programming
languages.
- command
- A valid Debug Tool command or a BEGIN-END group containing
one or more valid Debug Tool commands. The Debug Tool commands must be valid
for all supported programming languages.
When %IF commands are nested and ELSE clauses
are present, a given ELSE is associated with the closest
preceding %IF clause within the same block.
Usage notes
- The IF commands that are specific to a programming
language might contain restrictions or usage notes. Those restrictions
and usage notes also apply to the %IF command.
- The variable names used in condition must be syntactically
valid for all supported programming languages.
- If you want to nest %IF commands, you cannot mix them
with programming language-specific IF commands.
Refer to the following topics for more information
related to the material discussed in this topic.
IF command (assembler, disassembly, and non-Language Environment COBOL)
The IF command lets you conditionally perform a command.
You can optionally specify an ELSE clause on the IF command.
If the test expression evaluates to false and the ELSE clause
exists, the command associated with the ELSE clause is
performed. The IF and ELSE keywords cannot
be abbreviated.
- condition
- An assembler conditional expression.
- 'condition'
- A non-Language Environment COBOL conditional expression enclosed
in apostrophes (').
- command
- A valid Debug Tool command or a DO group containing one
or more valid Debug Tool Commands.
When IF commands are nested and ELSE clauses
are present, a given ELSE is associated with the closest
preceding IF clause within the same block.
Usage
note
You cannot use the IF command while you replay recorded
statements by using the PLAYBACK command.
Examples
if command (C and C++)
The if command lets you conditionally perform a command.
You can optionally specify an else clause on the if command.
If the test expression evaluates to false and an else clause
exists, the command associated with the else clause is
performed. The if and else keywords must be
lowercase and cannot be abbreviated.
- expression
- A valid Debug Tool C and C++ expression.
- command
- A valid Debug Tool command.
When if commands are nested and else clauses
are present, a given else is associated with the closest
preceding if clause within the same block.
Usage notes
- An else clause should always be included if the if clause
causes Debug Tool to get more input (for example, an if containing USE or
other commands that cause Debug Tool to be restarted because an AT-condition
occurs).
- The if command
cannot be used while you replay recorded statements by using the PLAYBACK commands
by using the PLAYBACK command.
Examples
IF command (COBOL)
The IF command lets you conditionally perform a command.
You can optionally specify an ELSE clause on the IF command.
If the test expression evaluates to false and an ELSE clause
exists, the command associated with the ELSE clause is
performed. The keywords cannot be abbreviated.
- condition
- A simple relation condition with the following form: Item-1 operator Item-2. Item-1 and Item-2 can
be a data-item or a literal. The operator can be one of the
following operations:
- >
- <
- =
- NOT =
- >=
- <=
- NOT <
- NOT >
- command
- A valid Debug Tool command.
When IF commands are nested and ELSE clauses
are present, a given ELSE or END-IF is associated
with the closest preceding IF clause within the same block.
Unlike COBOL, Debug Tool requires terminating punctuation (;) after
commands. The END-IF keyword is required.
Usage notes
- An ELSE clause should always be included if the IF clause
causes Debug Tool to get more input (for example, an IF containing USE or
other commands that cause Debug Tool to be restarted because an AT-condition
occurs).
- The COBOL NEXT SENTENCE phrase is not supported.
- Comparison combinations with windowed date fields are not supported.
- Comparisons between expanded date fields with different DATE FORMAT
clauses are not supported.
- If the DATA option of the PLAYBACK ENABLE command
is in effect, the IF command can be used while you replay
recorded statements by using the PLAYBACK commands.
- For optimized COBOL programs, the IF clause cannot
reference any variables discarded by the optimizer.
- If a COBOL variable is defined
as National and it is an operand in a relation condition with an alphabetic,
alphanumeric operand, or National numeric, the operand that is not
National is converted to Unicode before that
comparison is done, except for Group items. See Enterprise COBOL for z/OS Language Reference for
more information about using COBOL variables in conditional expressions.
Refer to the following topics for more information
related to the material discussed in this topic.
Allowable comparisons for the IF command (COBOL)
The following table shows the allowable comparisons for the Debug Tool IF command.
A description of the codes follows the table.
| OPERAND |
GR |
AL |
AN |
ED |
BI |
NE |
ANE |
NDI |
NNDI |
ID |
IN |
IDI |
PTR |
@ |
IF |
EF |
D1 |
| Group (GR) |
NN |
NN |
NN |
NN |
NN |
NN |
NN |
NN10 |
|
NN |
|
NN |
|
|
NN |
NN |
|
| Alphabetic (AL) |
NN |
NN |
|
|
|
|
|
NN |
|
|
|
|
|
|
|
|
|
| Alpha numeric (AN)8 |
NN |
|
NN |
|
|
|
|
NN |
|
|
|
|
|
|
|
|
|
| External Decimal (ED)8 |
NN |
|
|
NU |
|
|
|
|
|
|
|
|
|
|
|
|
|
| Binary |
NN |
|
|
|
NU |
|
|
|
|
|
NU4 |
|
|
|
|
|
|
| Numeric Edited (NE) |
NN |
|
|
|
|
NN |
|
|
|
|
|
|
|
|
|
|
|
| Alphanumeric Edited (ANE) |
NN |
|
|
|
|
|
NN |
NN |
|
|
|
|
|
|
|
|
|
| FIGCON ZERO7 |
NN |
|
|
NU |
NU |
|
|
NN |
|
NU |
|
|
|
|
NU |
NU |
|
| FIGCON1,7 |
NN |
NN |
NN |
|
|
|
NN |
NN9 |
NU |
|
|
|
|
|
|
|
|
| National Data Item (NDI) |
NN10 |
NN |
NN |
|
|
|
NN |
NN |
|
|
|
|
|
|
|
|
|
| National Numeric Data Item (NNDI) |
|
|
|
|
|
|
|
|
NN |
|
|
|
|
|
|
|
|
| Numeric Literal7 |
NN |
|
|
NU |
NU |
|
|
|
NN |
NU |
NU4 |
|
|
|
NU |
NU |
|
| Alphanumeric Literal2,7 |
NN |
NN3 |
NN |
|
|
NN |
NN |
NN |
|
|
|
|
|
|
|
|
|
| Alphanumeric hex literal11 |
NN |
NN |
NN |
|
|
NN |
NN |
|
|
|
|
|
|
|
|
|
|
| Internal Decimal (ID)8 |
NN |
|
|
|
|
|
|
|
|
NU |
|
|
|
|
|
|
|
| Index Name (IN) |
NN |
|
|
|
NU4 |
|
|
|
|
|
IO4 |
NU |
|
|
|
|
|
| Index Data Item (IDI) |
NN |
|
|
|
|
|
|
|
|
|
NU |
IV |
|
|
|
|
|
| Pointer Data Item (PTR) |
|
|
|
|
|
|
|
|
|
|
|
|
NU5 |
NU5 |
|
|
|
| Address of (@) |
|
|
|
|
|
|
|
|
|
|
|
|
NU5 |
NU5 |
|
|
|
| Floating Point Literal7 |
X |
|
|
|
|
|
|
|
|
|
|
|
|
|
NU |
NU |
|
| Internal Floating Point (IF) |
NN |
|
|
|
|
|
|
|
|
|
|
|
|
|
NU |
NU |
|
| External Floating Point (EF) |
NN |
|
|
|
|
|
|
|
|
|
|
|
|
|
NU |
NU |
|
| DBCS data item (D1) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
NN |
| DBCS Literal7 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
NN |
| Address hex Literal6 |
|
|
|
|
|
|
|
|
|
|
|
|
NU5 |
NU5 |
|
|
|
| National Literal |
NN10 |
|
|
|
|
|
|
NN |
|
|
|
|
|
|
|
|
|
| National Hex Literal12 |
NN10 |
|
|
|
|
|
|
NN |
|
|
|
|
|
|
|
|
|
Notes:
- 1
- FIGCON includes all figurative constants except ZERO and ALL.
- 2
- A alphanumeric literal must be enclosed in quotation marks (")
or apostrophes ('). A quotation mark or apostrophe embedded in
the string must be followed by another quotation mark or apostrophe
when it is used as the opening delimiter.
- 3
- Must contain only alphabetic characters.
- 4
- Index name converted to subscript value before compare.
- 5
- Only comparison for equal and not equal can be made.
- 6
- Must be hexadecimal characters only, delimited by either quotation
marks (") or apostrophes (') and preceded by H.
- 7
- Constants and literals can also be compared against constants
and literals of the same type.
- 8
- Comparisons using windowed date fields are not supported.
- 9
- The figurative constants HIGH-VALUES and LOW-VALUES are
not allowed in comparisons with national data items.
- 10
- Conversion of internal format is not done before the comparison.
- 11
- Must be hexadecimal characters only, delimited by either quotation
marks (") or apostrophes (') and preceded by X.
- 12
- Must be hexadecimal characters only, delimited by either quotation
marks (") or apostrophes (') and preceded by NX.
Allowable comparisons are comparisons as described in IBM OS Full American National Standard COBOL for the following:
- NN
- Nonnumeric operands
- NU
- Numeric operands
- IO
- Two index names
- IV
- Index data items
- X
- High potential for user error
Refer to the following topics for more information
related to the material discussed in this topic.
- Related references
- IBM OS Full American National Standard COBOL
IF command (PL/I)
The IF command lets you conditionally perform a command.
You can optionally specify an ELSE clause on the IF command.
If the test expression evaluates to false and an ELSE clause
exists, the command associated with the ELSE clause is
performed. The keywords cannot be abbreviated.
- expression
- A valid Debug Tool PL/I expression.
If necessary, the expression
is converted to a BIT string.
- command
- A valid Debug Tool command.
When IF commands are nested and ELSE clauses
are present, a given ELSE is associated with the closest
preceding IF clause within the same block.
Usage notes
- An ELSE clause should always be included if the IF clause
causes Debug Tool to get more input (for example, an IF containing USE or
other commands that cause Debug Tool to be restarted because an AT-condition
occurs).
- The if command
cannot be used while you replay recorded statements by using the LAYBACK commands.
Examples
- If the value of array1 is equal to the value of array2,
go to the statement with label constant label_1. Execution
of the user program continues at label_1. If array1 does
not equal array2, the GOTO is not performed
and control is passed to the user program.
IF array1 = array2 THEN GOTO LABEL label_1; ELSE GO;
- Set a breakpoint at statement 23, which will test if variable j is
equal to 10, display the names and values of variables rmdr, totodd,
and terms(j). If variable j is not equal to
10, continue program execution.
AT 23 IF j = 10 THEN LIST TITLED (rmdr, totodd, terms(j)); ELSE GO;
IMMEDIATE command (full-screen mode)
The IMMEDIATE command causes a command within a command
list to be performed immediately. It is intended for use with commands
assigned to a PF key.
IMMEDIATE can only be entered as an unnested command
or within a compound command.
It is recommended that PF key definitions for FIND, RETRIEVE, SCROLL,
and WINDOW commands be prefixed with IMMEDIATE.
This makes it possible to do things like SCROLL even when
entering a group of commands.
- command
- One of the following Debug Tool commands:
- FIND
- RETRIEVE
- SCROLL commands
- BOTTOM
- DOWN
- LEFT
- NEXT
- RIGHT
- TO
- TOP
- UP
- WINDOW commands
Usage notes
- The IMMEDIATE command is not logged.
Examples
INPUT command (C, C++, and COBOL)
The INPUT command provides input for an intercepted
read and is valid only when there is a read pending for an intercepted
file. The INPUT keyword cannot be abbreviated.
- text
- Specifies text input to a pending read.
Usage notes
- The text consists of everything between the INPUT keyword
and the semicolon (or end-of-line). Any leading or trailing blanks
are removed by Debug Tool.
- If a semicolon (;) is included as part of the text, the text must
be surrounded in quotation marks (") or apostrophes (') and
conform to the syntax rules for a character string constant enclosed
in quotation marks or apostrophes for the current programming language.
- If the text contains a quotation mark (") or apostrophe
('), the quotation mark or apostrophe must be followed by a matching
quotation mark or apostrophe.
- This command is not supported for CICS.
- To set interception to and from a file, use the SET INTERCEPT (C,
C++, and COBOL) command.
- The INPUT command cannot be
used while you replay recorded statements by using the PLAYBACK commands.
Example
You have used SET INTERCEPT ON to make Debug Tool prompt
you for input to a sequential file. The prompt and the file’s
name appears in the Command Log.
To substitute the input that would have come from the DD name specified
by the SET INTERCEPT ON command with your desired input,
enter:
INPUT text you want to input ;
Program input is recorded in your Log window.
A closing semicolon (;) is required for this command. Everything
between the INPUT keyword and the semicolon is considered
input text. If you want to include a semicolon, you must enter
your input as a valid character string for your programming language.
If you want to include a quotation mark (") or apostrophe (')
in your input, you must follow each quotation mark or apostrophe with
a matching quotation mark or apostrophe and enter the input as a valid
character string for your programming language.
Indicate that the phrase "quick brown fox" is input to
a pending read. The phrase is written to the file.
INPUT quick brown fox;
Refer to the following topics for more information
related to the material discussed in this topic.
JUMPTO command
The JUMPTO command moves the point at which the program
resumes running to the specified statement but does not resume running
the program.
Usage notes
- You cannot
use the JUMPTO command while you debug a disassembled program.
- If you specify the JUMPTO command in a command list
(for example, as the subject of an IF command or WHEN clause),
all subsequent commands in the list are ignored.
- If the program is compiled with minimum optimization, the JUMPTO command
is not restricted to specific statements.
- You cannot use the JUMPTO command
while you replay recorded statements by using the PLAYBACK command.
- For C, C++, and PL/I programs, statements can be removed by the
compiler during optimization. Specify a reference or statement for
the JUMPTO command that can be reached while the program
is running. You can use the LIST STATEMENT NUMBERS command
to determine the statements that can be reached.
- For PL/I programs, you can use JUMPTO in a command
list on a call to PLITEST or CEETEST.
- For PL/I programs, you cannot specify a statement that is out
of the currently active block. However, you might have to qualify
the statement.
- For COBOL programs, the JUMPTO command follows the
COBOL language rules that apply to the GOTO statement. You can use
the JUMPTO command in the following situations:
- A COBOL program compiled with hooks inserted by the compiler.
If you are using Enterprise COBOL for z/OS, Version
4.1, compile your program with the HOOK suboption of the TEST compiler
option. If you are using any of the following compilers, compile your
program with either PATH or ALL suboption and
the SYM suboption of the TEST compiler option:
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390 & VM, Version 2
- A COBOL program compiled without hooks inserted by the compiler
and without optimization. If you are using Enterprise COBOL for z/OS,
Version 4.1, compile your program with the NOHOOK suboption
of the TEST compiler option. If you are using any of the
following compilers, compile your program with the NONE suboption
of the TEST compiler option:
- Enterprise COBOL for z/OS and OS/390,
Version 3 Release 2 or later
- Enterprise COBOL for z/OS and OS/390,
Version 3 Release 1, with APAR PQ63235 installed
- COBOL for OS/390 & VM, Version 2 Release
2
- COBOL for OS/390 & VM, Version 2 Release
1, with APAR PQ63234 installed
- A COBOL program compiled without hooks inserted by the compiler
and with optimization. You must compile your program with Enterprise
COBOL for z/OS, Version 4.1, and specify the EJPD and NOHOOK suboption
of the TEST compiler option. Specifying the EJPD suboption
might cause some loss of optimization.
- You can use the JUMPTO command in remote debug mode only
by entering it in the Action field,
which is in the Optional Parameters section
of the Add a Breakpoint task.
Example
You want to jump to statement 24 and then stop there. Enter the
following command:
JUMPTO 24;
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
- Related references
- statement_id
JUMPTO LABEL command
The JUMPTO LABEL command moves the point at which the
program resumes running to the specified label but does not
resume running the program.
- statement_label
- A valid statement label within the currently executing program
or, in PL/I, a label variable.
Usage notes
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
LIST command
The LIST command displays information about a program
such as values of specified variables, structures, arrays, registers,
statement numbers, frequency information, and the flow of program
execution. The LIST command can be used to display information
in any enclave. All information displayed will be saved in the log
file.
The following table summarizes the forms of the LIST command.
LIST (blank) command
Displays the Source Identification panel, where associations are
made between source listings or source files shown in the source window
and their program units. LIST is equivalent to PANEL
LISTINGS and PANEL SOURCES.
Refer to the following topics for more information
related to the material discussed in this topic.
LIST AT command
Lists the currently defined breakpoints, including the action taken
when the specified breakpoint is activated. If no action is defined, Debug Tool displays
the NULL command.

- AT_command
- A valid AT command that includes at least one operand.
The AT command must be complete except that the every_clause and command are
omitted.
- ENABLED
- Restricts the list to enabled breakpoints. The default is to
list both enabled and disabled breakpoints.
- DISABLED
- Restricts the list to disabled breakpoints. The default is
to list both enabled and disabled breakpoints.
- ALLOCATE
- Lists currently defined AT ALLOCATE breakpoints.
- APPEARANCE
- Lists currently defined AT APPEARANCE breakpoints.
- CALL
- Lists currently defined AT CALL breakpoints.
- CHANGE
- Lists currently defined AT CHANGE breakpoints. This
displays the storage address and length for all AT CHANGE subjects,
and shows how they were specified (if other than by the %STORAGE function).
- DATE
- Lists currently defined AT DATE breakpoints.
- DELETE
- Lists currently defined AT DELETE breakpoints.
- ENTRY
- Lists currently defined AT ENTRY breakpoints.
- EXIT
- Lists currently defined AT EXIT breakpoints.
- GLOBAL
- Lists currently defined AT GLOBAL breakpoints for
the specified AT-condition.
- LABEL
- Lists currently defined AT LABEL breakpoints.
- LINE
- Lists currently defined AT LINE or AT STATEMENT breakpoints. LINE is
equivalent to STATEMENT.
- LOAD
- Lists currently defined AT LOAD breakpoints.
- OCCURRENCE
- Lists currently defined AT OCCURRENCE breakpoints.
- OFFSET
- Lists currently defined AT OFFSET breakpoints.
- PATH
- Lists currently defined AT PATH breakpoints.
- STATEMENT
- Is equivalent to LINE.
- SUSPENDED
- Lists all suspended breakpoints.
- TERMINATION
- Lists currently defined AT TERMINATION breakpoint.
If the AT command type (for example, LOAD)
is not specified, LIST AT lists all currently defined breakpoints
(both disabled and enabled).
Usage notes
- To display a global breakpoint, you can specify an asterisk (*)
with the LIST AT command or you can specify a LIST
AT GLOBAL command. For example, if you want to display an AT
ENTRY * breakpoint, specify:
LIST AT ENTRY *;
or
LIST AT GLOBAL ENTRY;
If you have only a global breakpoint
set and you specify LIST AT ENTRY without the asterisk
(*) or GLOBAL keyword, you get a message saying
there are no such breakpoints.
- The LIST AT command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
LIST CALLS command
Displays the dynamic chain of active blocks. For languages without
block structure, this is the CALL chain. Under z/OS batch
and TSO, LIST CALLS lists the call chain of every active
enclave in the process.
Usage notes
- For programs containing interlanguage communication (ILC), routines
from previous enclaves are only listed if they are written in a language
that is active in the current enclave.
- If the enclave was created with the system() function,
compile units in parent enclaves are not listed.
- If you are debugging a program that does not follow the standard
linkage conventions for R13, R14, and R15,
the output of the LIST CALLS command can be incorrect or
incomplete.
- If you are debugging a disassembled program and you encounter
one of the following situations:
- The registers' save area has not been created.
- The registers are not chained to the other save areas.
Some of the programs or CSECTs in the call chain are not displayed.
- The LIST CALLS command
cannot be used while you replay recorded statements by using the PLAYBACK commands.
Example
Display the current dynamic chain of active blocks.
LIST CALLS;
LIST CONTAINER command
Displays the contents of a container.

- channel_name
- The name of the channel that Debug Tool searches through to find
a container. If you do not provide a channel name, Debug Tool searches
through the current channel.
- container_name
- The name of the container.
- index
- A decimal or hexadecimal value indicating the location of a
single byte in the container to display.
- sub_string_start
- A decimal or hexadecimal value indicating the starting location
of a series of bytes to display.
- sub_string_end
- A decimal or hexadecimal value indicating the ending location
of a series of bytes to display.
- sub_string_length
- A decimal or hexadecimal value indicating the number of bytes
to display.
- XML
- Indicates that the specified area contains a complete XML 1.0
or 1.1 document. The specified area is passed to the z/OS XML
parser for processing. If the parser detects any syntax errors, the
error data is shown in the Debug Tool log. Otherwise, Debug Tool displays
a formatted version of the XML document in the Debug Tool log.
- EBCDIC
- Indicates that the specified area contains EBCDIC characters.
- ASCII
- Indicates that the specified area contains ASCII characters.
Usage notes
- You can use the LIST CONTAINER command in remote debug mode,
except for the XML option.
- For PL/I, COBOL, assembler, and disassembly, if the name is mixed
case or case sensitive, you must enclose the name in quotation marks
(") or apostrophes (').
- For C and C++, the name is always treated as case sensitive, even
if it is not enclosed in quotation marks (").
- XML is supported only when you run on z/OS Version
1.8 or later.
- If you specify XML but neither EBCDIC nor ASCII, Debug Tool attempts
to detect the proper encoding of the XML document.
- Some information in the XML document (for example, most of the
DTD specification and some white space) might not be listed because
the z/OS XML parser does not return it to Debug Tool.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
LIST CURSOR command (full-screen mode)
Provides a cursor controlled method for displaying variables, structures,
and arrays. It is most useful when assigned to a PF key.
Usage notes
- Cursor pointing can be used by typing the LIST CURSOR command
on the command line and moving the cursor to a variable in the source
window before pressing Enter, or by moving the cursor and pressing
a PF key with the LIST CURSOR command assigned to it.
- When you use the LIST CURSOR command for a variable
that is located by the cursor position, the variable's name nor its
full qualification cannot be split across different lines of the source
listing.
- If the DATA option of the PLAYBACK ENABLE command
is in effect for the current compile unit, the LIST CURSOR command
can be used while you replay recorded statements by using the PLAYBACK commands.
- For optimized COBOL programs, you cannot use the LIST CURSOR command
to display the value of variables discarded by the optimizer.
Examples
- Display the value of the variable at the current cursor position.
LIST CURSOR
- A COBOL program has a statement of the form:
MOVE a TO b
OF c
You cannot use the LIST CURSOR on the variable b because
part of its qualification (OF c) is on the next line.
LIST DTCN or CADP command
List the programs and compile units that were disabled by the DISABLE
CADP or DISABLE DTCN command.
- DTCN
- List the programs that were disabled by the DISABLE DTCN command.
- CADP
- List the programs and compile units that were disabled by the DISABLE
CADP command.
Usage
note
You can use the LIST DTCN or LIST CADP command
in remote debug mode.
Refer to the following topics for more information
related to the material discussed in this topic.
LIST expression command
Displays values of expressions.

- TITLED
- Displays each expression in the list with its value. For PL/I,
this is the default. For C and C++, this is the default for expressions
that are lvalues. For COBOL, this is the
default except for expressions consisting
of only a single constant. For assembler, disassembly, and non-Language Environment COBOL,
this is the default for expressions that are valid as receivers of
a Debug Tool assembler assignment statement.
If you specify TITLED with
no keyword, all variables in the currently qualified block are listed.
If you specify TITLED with an asterisk (*) and you are
debugging a C, C++, or COBOL program, all variables in the currently
qualified compile unit are listed.
If you are debugging a COBOL
program, the following additional options are available with TITLED:
- FS
- Lists all variables defined in the COBOL File Section in the
currently qualified compile unit.
- WSS
- Lists all variables defined in the COBOL Working-Storage Section
in the currently qualified compile unit.
- LS
- Lists all variables defined in the COBOL Linkage Section in
the currently qualified compile unit.
- LOS
- List all variables defined in the COBOL Local-Storage
Section in the currently qualified compile unit.
- * (C, C++, and COBOL)
- Lists all variables in the currently qualified compile unit.
- UNTITLED
- Lists expression values without displaying the expressions themselves.
For C and C++, this is the default for expressions that are not lvalues. For COBOL, this is the default for
expressions consisting of only a single constant. For assembler,
disassembly, and non-Language Environment COBOL, this is the default for
expressions that are not valid as receivers of a Debug Tool assembler
assignment statement. For the LIST command, an expression
also includes character strings enclosed in either quotation marks
(") or apostrophes ('), depending on the current programming
language.
In C and COBOL, expressions containing parentheses ()
must be enclosed in another set of parentheses when used with the LIST command
as in example LIST ((x + y) / z);.
In COBOL,
an expression can be the GROUP keyword followed by a reference.
If specified, the GROUP keyword causes the reference to
be displayed as if it were an elementary item. If GROUP is
specified for an elementary item, it has no effect. The operand of
a GROUP keyword can only be a reference (expressions are
not allowed) as in example LIST TITLED GROUP y;.
- expression
- An expression valid in the current programming language other
than non-Language Environment COBOL.
- 'expression'
- A valid non-Language Environment COBOL expression enclosed in apostrophes
(').
Usage notes
- If you want to use the LIST TITLED with the parameters FS, WSS, LS or LOS,
the PTF for Language Environment APAR PK12834 must be installed on z/OS Version
1 Release 6 and Version 1 Release 7.
- For COBOL programs, if you want to use the LIST
TITLED command with a variable that is named FS, WSS, LS, or
LOS, you must enclose the name of the variable in parenthesis. For
example, the command LIST TITLED (FS) lists the variable
FS; the command LIST TITLED FS lists the variables in the
File Section.
- Debug Tool allows you to abbreviate many commands. This might result
in unexpected results when you use the LIST command with a single-letter
expression. For example, LIST A can be interpreted as
the LIST AT command, which lists all breakpoints. However,
if you wanted to display the value of a variable labeled A in
your program, you need to use parenthesis: LIST (A).
- If LIST TITLED * is specified and your compile
unit is large, slow performance might result.
- For COBOL, if LIST TITLED * is specified and your compile
unit is large, you might receive an out of storage error
message.
- For COBOL, the LIST command can reference a condition
name, a file name, or an expression.
- For optimized COBOL programs, the LIST command cannot
reference a variable that was discarded by the optimizer.
- When using LIST TITLED with no parameters within the
PL/I compile unit, only the first element of any array will be listed.
If the entire array needs to be listed, use LIST and specify
the array name (i.e., LIST array where array is the name
of an array).
- If a character variable contains character data that cannot be
displayed in its declared data type, Debug Tool displays the data with
a special character. The topic "How Debug Tool handles
characters that can't be displayed in their declared data type" in Debug Tool User’s Guide describes what Debug Tool does in this situation. If
you display the data in hexadecimal, it will require twice as many
bytes. The maximum number of bytes that can be displayed is 65,535.
- If the DATA option of the PLAYBACK ENABLE command
is in effect for the current compile unit, the LIST expression command
can be used while you replay recorded statements by using the PLAYBACK commands.
- If you are trying to display a scalar item, the maximum length
that LIST can display is 65,535 bytes.
- If your program is compiled with Enterprise PL/I or Enterprise COBOL,
you can enter the L prefix command through the Source window
prefix area to display the value of the variables on that line.
Examples
- Display the values for variables size and r and
the expression c + r, with their respective names.
LIST TITLED (size, r, c + r);
- Display the COBOL references as if they were elementary items.
The current programming language setting is COBOL.
LIST (GROUP x OF z(1,2), GROUP a, w);
- Display the value of the Debug Tool variable %ADDRESS.
LIST %ADDRESS;
- In the disassembly view, display the value of register 1 (R1),
which is the value of Debug Tool variable %R1.
LIST R1 ;
- In COBOL, display the names and values of variables defined in
the File Section.
LIST TITLED FS;
Refer to the following topics for more information
related to the material discussed in this topic.
L prefix command (full-screen mode)
The L prefix command, which is entered through the prefix
area of the Source window, displays the value of a variable or variables
on that line in the Log window.
- integer
- Identifies the position of a variable on a line, beginning from
the left. The first variable on the line is position 1, the second
variable on the line is position 2, and this pattern repeats until
there are no more variables. If a variable is on the line more than
once, only the first instance of the variable is assigned a position
number. If no integer is specified, the values of all the variables
on the line are displayed.
Usage notes
- The L prefix command can be entered only on lines that
have valid statements.
- You can enter the L prefix command on multiple lines.
- To use the L prefix command, you must compile your
program with the following compilers:
- Enterprise COBOL
- Enterprise PL/I for z/OS, Version 3.6 or 3.7 with the
PTF for APAR PK70606 applied, or later
- You cannot use the L prefix command on a line that
is in a block that is not currently active.
Examples
The examples use the following lines of code:
...
293 move 0 to c; move 0 to b; move 0 to IND; move b to a;
...
319 if a + b < b + c
320 then move ind to c;
321 end-if;
...
- To display the value of IND on line 293, enter the L3 command
in the prefix area of line 293.
- To display the value of c on line 319, enter the L3 command
in the prefix are of line 319. The position of c is not
4 because b is counted only once, the first time it is
encountered, which is to the left of the < operator.
The second b, which is to the right of the < operator,
is not assigned a position number.
- To display the value of all variables on line 293, enter the L command
in the prefix area of 293.
Refer to the following topics for more information
related to the material discussed in this topic.
LIST FREQUENCY command
Lists statement execution counts.
- *
- Lists frequency for all statements in the currently qualified
compile unit. If currently executing at the AT TERMINATION breakpoint
where there is no qualification available, it will list frequency
for all statements in all the compile units in the terminating enclave
where frequency data exists.
- LINES
- Displays the source line after the frequency count.
- STATEMENT
- Equivalent to LINES.
Usage notes
- In the disassembly view, LIST FREQUENCY and LIST
FREQUENCY * are not supported.
- When you replay recorded statements by using the PLAYBACK commands,
the frequency count is not updated.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
LIST LAST command
Displays a list of recent entries in the history table.
- integer
- Specifies the number of most recently processed breakpoints
and conditions displayed.
- HISTORY
- Displays all processed breakpoints and conditions.
- LINES
- Displays processed statement or line breakpoints. LINES is
equivalent to STATEMENTS.
- PATHS
- Displays processed path breakpoints.
- STATEMENTS
- Is equivalent to LINES.
Usage notes
- The LAST keyword is provided to make the LIST command
readable. It does not perform any function.
- In the disassembly view, LIST LAST is not supported.
Examples
- Display all processed path breakpoints in the history table.
LIST PATHS;
- Display all program breakpoints and conditions for the last five
times Debug Tool gained control.
LIST LAST 5 HISTORY;
Refer to the following topics for more information
related to the material discussed in this topic.
LIST LINE NUMBERS command
Equivalent to LIST STATEMENT NUMBERS.
Refer to the following topics for more information
related to the material discussed in this topic.
LIST LINES command
Equivalent to LIST STATEMENTS.
Refer to the following topics for more information
related to the material discussed in this topic.
LIST MONITOR command
Lists all or selected members of the current set of MONITOR commands
and any suspended MONITOR LOCAL commands.
- integer
- An unsigned integer identifying a MONITOR command.
If two integers are specified, the first must not be greater than
or equal to the second. If omitted, all MONITOR commands
are displayed.
Usage notes
- You can enter LIST in the prefix area of the monitor
window to list the monitor command of the selected line.
- When the current programming language setting is COBOL, blanks
are required around the hyphen (-). Blanks are optional for C.
- If integer is not specified, both the active monitors
and any suspended local monitors are listed.
Example
List the fifth through the seventh commands currently being monitored.
LIST MONITOR 5 - 7;
LIST NAMES command
Lists the names of variables, programs, or Debug Tool procedures.
If LIST NAMES is issued with no keyword specified, the
names of all program and session variables that can be referenced
in the current programming language and that are visible to the currently
qualified block are displayed. A subset of the names can be specified
by supplying a pattern to be matched.

- pattern
- The pattern searched for, conforming to the current programming
language syntax for a character string constant. The pattern length
cannot exceed 128 bytes, excluding the quotation marks (") or
apostrophes (').
If the DBCS setting is ON, the pattern
can contain DBCS characters. DBCS shift codes are not considered significant
characters in the pattern. Within the pattern, an SBCS or DBCS asterisk
represents a string of zero or more insignificant SBCS or DBCS characters.
As many as eight asterisks can be included in the pattern, but adjacent
asterisks are equivalent to a single asterisk.
Some examples
of possible strings follow:
| C |
Assembler, COBOL, and non-Language Environment COBOL |
PL/I |
|
"ABC"
|
"A5"
|
'MY'
|
|
|
'A5'
|
|
Pattern matching is not case-sensitive outside of DBCS.
Both the pattern and potential names outside of shift codes are effectively
uppercased, except when the current programming language setting is
C. Letters in the pattern must be the correct case when the current
programming language setting is C.
- BLOCK
- Displays variable names that are defined within one or more
specified blocks.
- CUS
- Displays the compile unit names. CUS is equivalent
to PROGRAMS.
- PROCEDURES
- Displays the Debug Tool procedure names.
- PROGRAMS
- Is equivalent to CUS.
- TEST
- Displays the Debug Tool session variable names.
Usage notes
- LIST NAMES CUS applies to compile unit names.
- LIST NAMES TEST shows only those session variable names
that can be referenced in the current programming language.
- The output of LIST NAMES without any options depends
on both the current qualification and the current programming language
setting. If the current programming language differs from the programming
language of the current qualification, the output of the command shows
only those session variable names that can be referenced in the current
programming language.
- For structures, the pattern is tested against the complete name,
hence "B" is not satisfied by "C OF B
OF A" (COBOL).
- If the DATA option of the PLAYBACK ENABLE command
is in effect for the current compile unit, you can use the LIST
NAMES command while you replay recorded statements by using
the PLAYBACK commands.
- For optimized COBOL programs, the LIST NAMES command
does not display variables discarded by the optimizer.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
LIST ON (PL/I) command
Lists the action (if any) currently defined for the specified PL/I
conditions.
- pli_condition
- A valid PL/I condition specification. If omitted, all currently
defined ON command actions are listed.
Usage notes
- You cannot use the LIST ON command
while you replay recorded statements by using the PLAYBACK commands.
Example
List the action for the ON ZERODIVIDE command.
LIST ON ZERODIVIDE;
Refer to the following topics for more information
related to the material discussed in this topic.
LIST PROCEDURES command
Lists the commands contained in the specified Debug Tool PROCEDURE definitions.
- name
- A valid Debug Tool procedure name. If no procedure name is specified,
the commands contained in the currently running procedure are displayed.
If no procedure is currently running, an error message is issued.
Usage
note
Examples
LIST REGISTERS command
Displays the current register contents.
- REGISTERS
- Displays the General Purpose Registers (%GPRn). When this command
is issued when you are qualified to an Assembler or Disassembly CU
other than the CU where execution was suspended, it also displays
the values of the %Rn symbols.
- 32BIT
- Displays the 32-bit decimal General Purpose Registers
(%GPRn).
- 64BIT
- Displays the 64-bit decimal General Purpose Registers
(%GPRGn).
- LONG
- Displays the decimal value of the long-precision floating-point
registers.
- SHORT
- Displays the decimal value of the short-precision floating-point
registers.
- FLOATING
- Displays the long-precision floating-point registers.
Usage
note
If your program is running on hardware that does not support 64-bit
instructions or your program is suspended at a point where the 64-bit
general-purpose registers are not available, only the 32-bit
general-purpose registers are displayed.
Examples
- Display the General Purpose Registers at the point of a program
interruption:
LIST REGISTERS;
- Display the floating-point registers.
LIST FLOATING REGISTERS;
LIST STATEMENT NUMBERS command
Lists all statement or line numbers that are valid locations for
an AT LINE or AT STATEMENT breakpoint.
- NUMBERS
- Displays the statement numbers that can be used to set STATEMENT breakpoints,
assuming the compile options used to generate statement hooks were
specified at compile time. The list can also be used for the GOTO command,
however, you might not be able to GOTO all of the statement
numbers listed.
- block_spec
- A valid block specification. This operand lists all statement
or line numbers in the specified block.
- cu_spec
- A valid compile unit specification. For C programs, cu_spec can
be used to list the statement numbers that are defined within the
specified compile unit before the first function definition.
- statement_id_range
- A valid range of statement ids, separated by a hyphen (-).
Usage notes
- In the disassembly view, LIST STATEMENT NUMBERS is
not supported.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
LIST STATEMENTS command
Lists one or more statements or lines from a file. It is primarily
intended for viewing portions of the source listing or source file
in line mode, but can also be used in full-screen mode to copy a portion
of a source listing or source file to the log.
Usage notes
- The specified lines are displayed in the same format as they would
appear in the full-screen Source window, except that wide lines are
truncated.
- You might need to specify a range of line numbers to ensure that
continued statements are completely displayed.
- This command is not to be confused with the LIST LAST STATEMENTS command.
- In the disassembly view, LIST STATEMENTS is not supported.
Examples
- List lines 25 through 30 in the source file associated with the
currently qualified compile unit.
LIST LINES 25 - 30;
- List statement 100 from the current program listing file.
LIST STATEMENT 100;
Refer to the following topics for more information
related to the material discussed in this topic.
LIST STORAGE command
Displays the contents of storage at a particular address in hexadecimal
or XML format.

- address
- The starting address of storage to be listed.
- reference
- A variable whose storage location is to be listed.
In
assembler or disassembly, this operand might be specified as any assembler
expression that represents a storage location. If the assembler expression
does not have an implied length (for example, R3->+10), you must specify
the number of bytes to display by using the integer operand.
- 'reference'
- A non-Language Environment COBOL variable whose storage location
is to be listed. A non-Language Environment COBOL reference must
be enclosed in apostrophes (').
- offset
- The decimal or hexadecimal number of bytes indicating the starting
offset from the memory location pointed to by the reference's
address or the address provided by the user. offset can be
a negative number. If offset is a hex constant, you must
follow the same syntax rules for address. The default is
0.
- length
- The decimal number of bytes of storage displayed. The default
is 16 bytes. The length must be an integer number.
- XML
- Indicates that the specified area contains a complete XML 1.0
or 1.1 document. The specified area is passed to the z/OS XML
parser for processing. If the parser detects any syntax errors, the
error data is shown in the Debug Tool log. Otherwise, Debug Tool displays
a formatted version of the XML document in the Debug Tool log file.
- EBCDIC
- Indicates that the specified area contains EBCDIC characters.
- ASCII
- Indicates that the specified area contains ASCII characters.
Usage notes
- For C and C++, if reference is a pointer, Debug Tool displays
the contents at the address given by that pointer.
- Using Debug Tool, cursor pointing can be used by typing the LIST
STORAGE command on the command line and moving the cursor to
a variable in the Source window before pressing Enter, or by moving
the cursor and pressing a PF key with the LIST STORAGE command
assigned to it.
- When using the LIST STORAGE command in Debug Tool for a
variable that is located by the cursor position, the variable’s
name cannot be split across different lines of the source listing.
- If the referenced variable is a General Purpose Register (GPR)
such as %GPR1, the result depends on the programming language that
is in effect:
- For all languages except assembler and disassembly, Debug Tool displays
the storage at the address contained in the referenced GPR.
- For assembler and disassembly, you must use the indirection notation
(%GPR1->) to instruct Debug Tool to display the storage at the address
contained in the referenced register.
- If no operand is specified with LIST STORAGE, the command
is cursor-sensitive.
- If you are replaying recorded statements by using PLAYBACK commands,
the LIST STORAGE command displays the contents of storage
at the point where you entered the PLAYBACK START command.
- For optimized COBOL programs, LIST STORAGE cannot display
variables that were discarded by the optimizer.
- XML is supported only when you run on z/OS Version
1.8 or later.
- If you specify XML but neither EBCDIC nor ASCII, Debug Tool attempts
to detect the proper encoding of the XML document.
- Some information in the XML document (for example, most of the
DTD specification and some white space) might not be listed because
the z/OS XML parser does not return it to Debug Tool.
- If you specify address with more than 8 significant digits
or if reference references 64-bit addressable storage, Debug Tool assumes
that the storage location is 64-bit addressable storage. Otherwise, Debug Tool assumes
that the storage location is 31-bit addressable storage.
Examples
- Display the first 64 bytes of storage beginning at the address
of variable table.
LIST STORAGE (table, 64);
- Display 16 bytes of storage at the address given by pointer table(1).
LIST STORAGE (table(1));
- Display the 16 bytes contained at locations 20CD0-20CDF. The
current programming language setting is COBOL.
LIST STORAGE (H'20CD0');
- Display the 16 bytes contained at locations 20CD0-20CDF. The
current programming language setting is PL/I.
LIST STORAGE ('20CD0'PX);
- In the disassembly view, display the storage at the address given
by register R13.
LIST STORAGE (R13->);
- Display 10 characters starting at offset 2 for variable MYVAR. MYVAR is
declared as CHAR (20).
LIST STORAGE (MYVAR, 2, 10);
- Display 20 bytes starting at offset 10 from address '20ACD0'PX.
The current programming language setting is PL/I.
LIST STORAGE ('20ACD0'PX, 10, 20);
- Display 10 bytes starting at offset -5 from address '20ACD0'PX.
The current programming language setting is PL/I.
LIST STORAGE ('20ACD0'PX, -5, 10);
Refer to the following topics for more information
related to the material discussed in this topic.
LOAD command
Specifies that the named module should be loaded for debugging
purposes. The LOAD command enables you to debug preloaded
load modules.
If you are running in Language Environment, the enclave-level load service
is used to load the load module or modules. The load module or modules
remain active until the current enclave terminates or you enter the CLEAR
LOAD command for those load modules.
If you are not running in Language Environment, the load module or modules
remain active until the debugging task terminates or you enter the CLEAR
LOAD command for those load modules. If you are debugging CICS programs,
the load is done by EXEC CICS LOAD. For all other programs,
the load is done by MVS LOAD services.

- module_name
- The name of one or more load modules to be loaded by Debug Tool.
- LE
- Use the Language Environment enclave-level load service to load the load
module or modules. The load module or modules remain active until
the current enclave terminates or you enter a CLEAR LOAD command
for the load module or modules.
- NONLE
- Use non-Language Environment services to load the load module or
modules. The load module or modules remain active until the debugging
task terminates or you enter a CLEAR LOAD command for the
load module or modules. For CICS programs,
the load module or modules are loaded by using EXEC CICS LOAD.
For all other programs, the load module or modules are loaded by using
the MVS LOAD services.
Usage notes
- You can use this command in remote debug mode.
- You can enter the QUALIFY CU command for a program
or CSECT in the load module or load modules that you just loaded unless
the program is COBOL.
- If you set breakpoints in the programs or CSECTS in the module
and then the same load module is loaded again, the breakpoints might
not work because location of the load module has changed.
- If the module to be debugged is RESIDENT or was loaded before Debug Tool was
started, you can use the LOAD command to make the module
known to Language Environment.
- You cannot use this command to load a DLL.
Refer to the following topics for more information
related to the material discussed in this topic.
LOADDEBUGDATA command
Specifies that a compile unit (CU) is an assembler or non-Language Environment COBOL
CU and loads debug data from the default data set name, userid.EQALANGX(cu_name).
If the debug data is stored in a different data set, you can specify
that data set name by using the SET SOURCE, SET DEFAULT
LISTINGS command, or the EQADEBUG DD statement. In remote debug mode,
you can specify the data set name by using the EQADEBUG DD statement
or let the remote debugger prompt you for the data set name.
You can generate the required debug data by using the EQALANGX
program or, if you are debugging an assembler program, by assembling
your program through Debug Tool Utilities. Both methods are described
in Debug Tool User’s Guide.

- load_module_name
- The name of the load module containing the specified compile
unit (cu_name). If the corresponding load module is known
to Debug Tool, the specified compile unit must be a disassembly compile
unit within the specified load module. If the load module is not
known to Debug Tool, Debug Tool defers the LOADDEBUGDATA command
until a load module by the specified name and containing the specified
compile unit is loaded.
If you do not specify load_module_name, Debug Tool applies
the LOADDEBUGDATA command to all compile units by the specified
name found in any load module.
- cu_name
- The name of the assembler or non-Language Environment COBOL
compile unit. If this compile unit is currently known to Debug Tool,
it must be a disassembly compile unit. If it is not currently known
to Debug Tool, the LOADDEBUGDATA command is deferred until
a disassembly compile unit by the specified name becomes known to Debug Tool.
Usage notes
- When you use the SET SAVE command to save breakpoints
or monitor specifications or you use the RESTORE command
to restore breakpoints or monitor specifications, all LDD settings
including the data set name of the data set from which the debug data
was loaded is saved and restored.
- For CICS only: When a DTCN profile
is active for a full screen mode debugging session, Debug Tool preserves
all LDD settings, including the data set name of the data set from
which the debug data was loaded, until the DTCN profile is deleted
or the terminal session is terminated.
- You can use this command for assembler CUs (but not for non-Language Environment COBOL
CUs) in remote debug mode.
- After Debug Tool successfully processes a LOADDEBUGDATA command
for a CU, if the CU is deleted and then appears later, an implicit LDD command
is run for the CU using the same EQALANGX data set that was used initially.
- You cannot enter the LDD command for the same compile
unit more than once.
Refer to the following topics for more information
related to the material discussed in this topic.
MEMORY command
Specifies an address to use as the starting address for the memory
displayed in the Memory window.
If the address you specify is invalid, Debug Tool displays an error
message.
The MEMORY command cannot be saved and restored.
- address
- The address to use as the starting address for the memory displayed
in the Memory window.
- reference
- A variable whose location in memory is used as the starting
address of the memory displayed in the Memory window.
- 'reference'
- A non-Language Environment COBOL variable whose location in memory
is used as the starting address of the memory displayed in the Memory
window.
- simple_expression
- The address with a positive or negative hexadecimal or integer
displacement. The resulting value is the starting address of the
memory displayed in the Memory window.
Usage notes
- For COBOL, if you specify a variable with reference modification,
then the storage location of that variable is used as a base address,
not the location of the specified reference.
- If you specify address with more than 8 significant digits
or if reference references 64-bit addressable storage, Debug Tool assumes
that the storage location is 64-bit addressable storage. Otherwise, Debug Tool assumes
that the storage location is 31-bit addressable storage.
- For C and C++, if reference is a pointer, Debug Tool displays
the contents at the address given by that pointer.
Examples
- Display memory starting at X'2503D008' by entering the
following command:
MEMORY X'2503D008';
This address becomes
the base address.
- Display memory starting at the storage location of variable Employee_name by
entering the following command:
MEMORY Employee_name;
The
address of Employee_name becomes the base address.
- Display memory starting 100 hex bytes after X'0045CB00' by
entering the following command:
MEMORY x'0045CB00' + x'100'
The
base address is X'0045CC00'.
Refer to the following sections for more information related to
the material discussed in this section.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- "Debug Tool session panel" in Debug Tool User’s Guide
- "Switching between
the Memory window and Log window" in Debug Tool User’s Guide
- "Displaying the Memory
window" in Debug Tool User’s Guide
- "Displaying memory
through the Memory window" in Debug Tool User’s Guide
- Related references
- address
MONITOR command
The MONITOR command defines or redefines a command and
then displays the output in the monitor window (full-screen mode)
or log file (batch mode). The following commands are the only commands
you can use with the MONITOR command:
Debug Tool maintains a list of your most recently entered MONITOR commands.
Each command entered is assigned a number between 1 and 99 or you
can assign it a number. Use these numbers to indicate to Debug Tool which MONITOR command
you want to redefine.

- GLOBAL
- Specifies that the monitor definition is global. That is, it
is not associated with a particular compile unit.
- LOCAL
- Specifies that the monitor definition is local to a specific
compile unit. Using Debug Tool, the specified output is displayed only
when the current qualification is within the associated compile unit.
- cu_spec
- A valid compile unit specification. This specifies the compile
unit associated with the monitor definition.
- integer
- An integer in the range 1 to 99, indicating what command in
the list is replaced with the specified command and the order that
the monitored commands are evaluated. If omitted, the next monitor
integer is assigned. An error message is displayed if the maximum
number of monitoring commands already exists.
- command
- A DESCRIBE, LIST, Null, or QUERY command
whose output is displayed in the monitor window or log file.
- HEX
- Specifies that the value of the variable be displayed in hexadecimal
format. You can specify the HEX parameter only with a MONITOR
LIST expression command or the MONITOR n command
where n is the nth command in the MONITOR list and
it must be a LIST expression command.
- DEFAULT
- Specifies that the value of the variable be displayed in its
declared data type. You can specify the DEF parameter only
with a MONITOR LIST expression command or the MONITOR n command
where n is the nth command in the MONITOR list and
it must be a LIST expression command.
Usage notes
- You can enter HEX or DEF in the prefix area
of the monitor window to display the selected line in hexadecimal
or the default representation, respectively.
- The HEX and DEF prefix commands operate
only on an individual structure element or array element when you
enter them in the prefix area associated with that element.
- A monitor number identifies a global monitor command, a local
monitor command, or neither.
- Using Debug Tool, monitor output is presented in monitor number sequence.
- If a number is provided and a command omitted, a Null command
is inserted on the line corresponding to the number in the monitor
window. This reserves the monitor number.
- You can only specify a monitor number that is at most one greater
than the highest existing monitor number.
- To clear a command from the monitor, use the CLEAR MONITOR command.
- The MONITOR command displays up to a maximum of 1000
lines of output in the monitor window.
- Replacement only occurs if the command identified by the monitor
number already exists.
- When SET AUTOMONITOR ON is in effect, Debug Tool adds an
entry that is not visible after the last active entry in the monitor
list. If you specify a number and it is either equal to or
one more than the last active entry, Debug Tool inserts the new MONITOR command
in the last active entry and uses the next higher entry for SET
AUTOMONITOR ON.
- The MONITOR LIST command does not allow the POPUP, TITLED,
and UNTITLED options.
- When using the MONITOR LIST command, simple references
(or C lvalues) display identifying information with the
values, whereas expressions and literals do not.
- The GLOBAL and LOCAL keywords also affect
the default qualification for evaluation of an expression. GLOBAL indicates
that the default qualification is the currently executing point in
the program. LOCAL indicates that the default qualification
is to the compile unit specified.
- LOCAL monitors are suspended when the enclave containing
the compile unit terminates or when the load module containing the
compile unit is deleted. If the associated compile unit reappears
later in the same debugging session, the LOCAL monitors
are restored. However, because the original monitor number might be
in use at that time, they will not always be restored with the same
monitor number.
- If the DATA option of the PLAYBACK ENABLE command
is in effect for the current compile unit, you can use the MONITOR command
while you replay recorded statements by using the PLAYBACK commands.
- A MONITOR LIST command can be evaluated only when the
programming language currently in effect is the same as it was when
the MONITOR LIST command was issued. Therefore, if the
programming language is changed by one of the following actions, the
evaluation of the MONITOR LIST command fails, and a message
is displayed:
- Suspending execution in a compile unit written in a language different
from the programming language that was in effect when the original MONITOR command
was entered.
- Entering the SET PROGRAMMING LANGUAGE command.
- Entering the SET QUALIFY command.
- Entering the LOADDEBUGDATA command.
- If your program is compiled with Enterprise PL/I or Enterprise COBOL,
you can enter the M prefix command through the Source window
prefix area to add the variables on that line to the Monitor window.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
M prefix (full-screen mode)
The M prefix command, which is entered through the prefix
area of the Source window, adds a variable or variables to the Monitor
window.
- integer
- Identifies the position of a variable on a line, beginning from
the left. The first variable on the line is position 1, the second
variable on the line is position 2, and this pattern repeats until
there are no more variables. If a variable is on the line more than
once, only the first instance of the variable is assigned a position
number. If no integer is specified, all the variables on the line
are added to the Monitor window.
Usage notes
- The M prefix command can be entered only on lines that
have valid statements.
- You can enter the M prefix command on multiple lines.
- To use the M prefix command, you must compile your
program with the following compilers:
- Enterprise COBOL
- Enterprise PL/I for z/OS, Version 3.6 or 3.7 with the
PTF for APAR PK70606 applied, or later
- You cannot use the M prefix command on a line that
is in a block that is not currently active.
Example
The example uses the following lines of code:
...
293 move 0 to c; move 0 to b; move 0 to IND; move b to a;
...
319 if a + b < b + c
320 then move ind to c;
321 end-if;
...
To add the variable c on line 293 to the Monitor window,
enter the M1 command in the prefix area of line 293.
Refer to the following topics for more information
related to the material discussed in this topic.
MOVE command (COBOL)
The MOVE command transfers data from one area of storage
to another. The keywords cannot be abbreviated.
- reference
- A valid Debug Tool COBOL reference.
- literal
- A valid COBOL literal.
Usage notes
- If Debug Tool was started because of a computational condition or
an attention interrupt, using an assignment to set a variable might
not give expected results. This is due to the uncertainty of variable
values within statements as opposed to their values at statement boundaries.
- MOVE assigns a value only to a single receiver; unlike
COBOL, multiple receiver variables are not supported.
- The COBOL CORRESPONDING phrase is not supported.
- MOVE does not support date windowing. Therefore, you
cannot use the MOVE command to assign the value of a windowed
date field to an expanded date field or to a nondate field.
- You cannot use the MOVE command to assign the value
of one expanded date field to another expanded date field with a different
DATE FORMAT clause, or to assign the value of one windowed date field
to another windowed date field with a different DATE FORMAT clause.
- If the DATA parameter of the PLAYBACK ENABLE command
is in effect for the current compile unit, the MOVE command
can be used while you replay recorded statements by using the PLAYBACK commands.
The target of the MOVE command must be a session variable,
not a program variable.
- If you are debugging an optimized COBOL program, you can use the MOVE command
to assign a value to a program variable only if you first enter the SET
WARNING OFF command.
- If you are debugging a COBOL program that was compiled with the OPTIMIZE compiler
option, neither operand of the MOVE command can be a variable
that was discarded by the optimizer.
- If a COBOL variable defined as National is used as the receiving
field in a MOVE command with an alphabetic or alphanumeric
operand, the operand that is not National is converted to Unicode before that move is done, except for Group items.
See Enterprise COBOL for z/OS Language Reference for more information about using COBOL variables
with the MOVE statement.
- Literals with an N or NX prefix are always treated
as National data and can be moved only to other National Data Items
or Group items.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
Allowable moves for the MOVE command (COBOL)
The following table shows the allowable moves for the Debug Tool MOVE command.
| Source
field |
Receiving field |
| GR |
AL |
AN |
ED |
BI |
NE |
ANE |
NDI |
NNDI |
ID |
IF |
EF |
D1 |
| GROUP (GR) |
Y |
Y |
Y |
Y1 |
Y1 |
Y1 |
Y1 |
Y1 |
|
Y1 |
Y1 |
Y1 |
|
| ALPHABETIC (AL) |
Y |
Y |
|
|
|
|
|
Y |
|
|
|
|
|
| ALPHANUMERIC (AN)4,5 |
Y |
|
Y |
|
|
|
|
Y |
|
|
|
|
|
| EXTERNAL DECIMAL (ED)4,5 |
Y1 |
|
|
Y |
|
|
|
|
|
|
|
|
|
| BINARY (BI) |
Y1 |
|
|
|
Y |
|
|
|
|
|
|
|
|
| NUMERIC EDITED (NE) |
Y |
|
|
|
|
|
|
|
|
|
|
|
|
| ALPHANUMERIC EDITED (ANE) |
Y |
|
|
|
|
|
Y |
Y |
|
|
|
|
|
| FIGCON ZERO |
Y |
|
Y |
Y2 |
Y2 |
|
Y |
|
NU |
Y2 |
Y |
Y |
|
| FIGCON ZERO, SPACE, or QUOTE |
|
|
|
|
|
|
|
Y |
|
|
|
|
|
| SPACES (AL) |
Y |
Y |
Y |
|
|
|
Y |
|
|
|
|
|
|
| HIGH-VALUE, LOW-VALUE, QUOTES |
Y |
|
Y |
|
|
|
Y |
|
|
|
|
|
|
| NATIONAL DATA ITEM (NDI) |
Y1 |
|
|
|
|
|
|
Y |
|
|
|
|
|
| NATIONAL NUMERIC DATA ITEM (NNDI) |
|
|
|
|
|
|
|
|
NN |
|
|
|
|
| NUMERIC LITERAL |
Y1 |
|
|
Y |
Y |
|
|
|
NN |
Y |
Y |
Y |
|
| ALPHANUMERIC LITERAL |
Y |
Y |
Y |
|
|
Y1 |
Y |
Y |
|
|
|
|
|
| ALPHANUMERIC HEX LITERAL6 |
Y |
Y |
Y |
Y |
Y |
Y |
Y |
|
|
Y |
Y |
Y |
|
| INTERNAL DECIMAL (ID)4,5 |
Y1 |
|
|
|
|
|
|
|
|
Y |
|
|
|
| FLOATING POINT LITERAL |
Y1 |
|
|
|
|
|
|
|
|
|
Y |
Y |
|
| INTERNAL FLOATING POINT (IF) |
Y1 |
|
|
|
|
|
|
|
|
|
Y |
Y |
|
| EXTERNAL FLOATING POINT (EF) |
Y1 |
|
|
|
|
|
|
|
|
|
Y |
Y3 |
|
| DBCS DATA ITEM (D1) |
|
|
|
|
|
|
|
|
|
|
|
|
Y |
| DBCS LITERAL |
|
|
|
|
|
|
|
|
|
|
|
|
Y |
| NATIONAL LITERAL (NL) |
Y |
|
|
|
|
|
|
Y |
|
|
|
|
|
| NATIONAL HEX LITERAL (NHL)7 |
Y1 |
|
|
|
|
|
|
Y |
|
|
|
|
|
Notes:
- 1
- Move without conversion (like AN to AN)
- 2
- Numeric move
- 3
- Decimal-aligned and truncated, if necessary
- 4
- MOVE does not support date windowing. For example, the MOVE
statement cannot be used to move a windowed date field to an expanded
date field, or to a nondate field.
- 5
- The MOVE command cannot be used to move one windowed date field
to another windowed date field with a different DATE FORMAT clause,
or to move one expanded date field to another expanded date field
with a different DATE FORMAT clause.
- 6
- Must be hexadecimal characters only, delimited by either quotation
marks (") or apostrophes (') and preceded by X.
- 7
- Must be hexadecimal characters only, delimited by either quotation
marks (") or apostrophes (') and preceded by NX.
Refer to the following topics for more information
related to the material discussed in this topic.
NAMES command
Use the NAMES command only as instructed in "Debugging
user programs that use system prefixed names" in Debug Tool User’s Guide.
NAMES DISPLAY command
Use the NAMES DISPLAY command to indicate that you want
a list of all the load modules or compile units that are currently
excluded or included. If you do not specify the ALL parameter,
only the names excluded by user commands appear in the list that is
displayed. Names that Debug Tool excludes by default are not included
in the list that is displayed.

- USER
- Indicates that you want a list of load modules or compile units
that are currently excluded at your request (by using NAMES EXCLUDE command).
- ALL
- Indicates that you want a list of all load modules or compile
units that are currently excluded, including those that Debug Tool excludes
by default.
- LOADMODS
- Indicates that you want a list of load module names.
- CUS
- Indicates that you want a list of compile unit names.
- pattern
- Specifies the name of the load module or compile unit, or a
string surrounded by quotation marks (") or apostrophes (')
that contains a partial load module or compile unit name followed
by an asterisk to indicate that you want a list of all load modules
or compile units beginning with the specified string.
Usage
note
You can use this command in remote debug mode.
Refer to the following topics for more information
related to the material discussed in this topic.
NAMES EXCLUDE command
The NAMES EXCLUDE command enables you to indicate to Debug Tool the
names of load modules or compile units that you do not need to debug.
If these are data-only modules, Debug Tool does not process them.
If they contain executable code, Debug Tool might process them in some
cases. See "Optimizing the
debugging of large applications" in the Debug Tool User’s Guide for
more information about these situations.
- LOADMOD
- Indicates that you do not want to debug the specified load module.
- CU
- Indicates that you do not want to debug the specified compile
unit.
- NOTEST
- Indicates that you do not want to debug any compile units that
were not compiled with debug data.
- pattern
- Specifies the name of the load module or compile unit, or a
string surrounded by quotation marks (") or apostrophes (')
that contains a partial load module or compile unit name followed
by an asterisk to indicate that you do not want to debug all load
modules or compile units beginning with the specified string.
Usage notes
- You can use this command in remote debug mode.
- You cannot use the NAMES EXCLUDE command on load modules
or compile units that are already known to Debug Tool.
If you specify
the name of a currently known load module or compile unit, it is added
to the exclude list so that if the name becomes unknown, it is excluded
in subsequent appearances. However, the currently known load module
or compile unit remains known.
- You cannot use the NAMES EXCLUDE command to indicate
to Debug Tool that you want to exclude the initial load module or the
compile units contained in the initial load module. If you want to
do this, you must code control statements into the EQAOPTS Debug Tool
customization module with the equivalent NAMES EXCLUDE command.
See "Using EQAOPTS
to implement NAMES commands" in the Debug Tool User’s Guide for
instructions.
- For C and C++ programs, the pattern parameter is case
sensitive. For all other languages, the pattern is not case sensitive.
Refer to the following topics for more information
related to the material discussed in this topic.
NAMES INCLUDE command
Use the NAMES INCLUDE command to indicate to Debug Tool that
your program is a user load module or compile unit, not a system program.
See "Debugging
user programs that use system prefix names" in Debug Tool User’s Guide for more information.
- LOADMOD
- Indicates that you want to debug the specified load module.
- CU
- Indicates that you want to debug the specified compile unit.
- name
- Specifies the name of the load module or compile unit.
Usage notes
- You can use this command in remote debug mode.
- You cannot use the NAMES INCLUDE command on load modules
or compile units that are already known to Debug Tool.
- You cannot use the NAMES INCLUDE command to indicate
to Debug Tool that you want to debug the initial load module or the compile
units contained in the initial load module. If you want to do this,
you must code control statements into the EQAOPTS Debug Tool customization
module with the equivalent NAMES INCLUDE command. See "Using EQAOPTS to implement
NAMES commands" in Debug Tool User’s Guide for instructions.
- Do not use the NAMES INCLUDE command
to debug system components (for example, Debug Tool, Language Environment, CICS, IMS,
or compiler run-time modules). If you attempt to debug these
system components, you might experience unpredictable failures. Only
use this command to debug user programs that
are named with prefixes that Debug Tool recognizes as system components.
Refer to the following topics for more information
related to the material discussed in this topic.
Null command
The Null command is a semicolon written where a command
is expected. It is used for such things as an IF command
with no action in its THEN clause.
Example
Do nothing if array[x] > 0; otherwise,
set a to 1. The current programming language setting is
C.
if (array[x] > 0); else a = 1;
ON command (PL/I)
The ON command establishes the actions to be executed
when the specified PL/I condition is raised. This command is equivalent
to AT OCCURRENCE.
- condition_name
- A valid PL/I CONDITION condition name.
- file_reference
- A valid PL/I file constant or file variable (can be qualified).
- command
- A valid Debug Tool command.
Usage notes
- You must abide by the PL/I restrictions for the particular condition.
- An ON action for a specified PL/I condition remains
established until:
- Another ON command establishes a new action for the
same condition. In other words, the breakpoint is replaced.
- A CLEAR command removes the ON definition.
- The ON command occurs before any existing ON-unit
in your application program. The ON-unit is processed
after Debug Tool returns control to the language.
- The following are accepted PL/I abbreviations for the PL/I condition
constants:
- ATTENTION or ATTN
- FIXEDOVERFLOW or FOFL
- OVERFLOW or OFL
- STRINGRANGE or STRG
- STRINGSIZE or STRZ
- SUBSCRIPTRANGE or SUBRG
- UNDEFINEDFILE([file_reference]) or UNDF([file_reference])
- UNDERFLOW or UFL
- ZERODIVIDE or ZDIV
- The preferred form of the ON command is AT OCCURRENCE.
For compatibility with PLITEST and INSPECT, however, it is recognized
and processed. ON should be considered a synonym of AT
OCCURRENCE. Any ON commands entered are logged as AT
OCCURRENCE commands.
- The ON command cannot
be used while you replay recorded statements by using the PLAYBACK commands.
Examples
- Display a message if a division by zero is detected.
ON ZERODIVIDE BEGIN;
LIST 'A zero divide has been detected';
END;
- Display and patch the error character when converting character
data to numeric.
Given a PL/I program that contains the following
statements:
DECLARE i FIXED BINARY(31,0);
.
..
..
i = '1s3';
The following Debug Tool command would
display and patch the error character when converting the character
data to numeric:
ON CONVERSION
BEGIN;
LIST (%STATEMENT, ONCHAR);
ONCHAR = '0';
GO;
END;
'1s3' cannot be converted to
a binary number so CONVERSION is raised. The ON CONVERSION command
lists the offending statement number and the offending character: 's'.
The data will be patched by replacing the 's' with
a character zero, 0, and processing will continue.
Refer to the following topics for more information
related to the material discussed in this topic.
PANEL command (full-screen mode)
The PANEL command displays special panels. The PANEL keyword
is optional.
The PANEL command cannot be used in a command list,
any conditional command, or any multiway command.

- COLORS
- Displays the Color Selection panel that allows the selection
of color, highlighting, and intensity of the fields of the Debug Tool session
panel.
- LAYOUT
- Displays the Window Layout Selection panel that controls the
configuration of the windows on the Debug Tool session panel.
- RESET
- Restores the relative sizes of windows for the current configuration,
without displaying the window layout panel. For configurations 1
and 4, the three windows are evenly divided. For other configurations,
the point where the three windows meet is approximately the center
of the screen.
- LISTINGS
- Displays the Source Identification panel, where associations
are made between source listings or source files shown in the Source
window and their program units. LISTINGS is equivalent
to SOURCES.
Debug Tool provides the Source Identification panel to maintain
a record of compile units associated with your program, as well as
their associated source or listing.
You can also make source
or listings available to Debug Tool by entering their names on the Source
Identification panel.
The Source Identification panel associates
compile units with the names of their respective listing or source
files and controls what appears in the Source window. To explicitly
name the compile units being displayed in the source window, access
the Source Identification panel (shown below) by entering the PANEL
LISTINGS or PANEL SOURCES command.
Source Identification Panel
Command ===>
Compile Unit Listings/Source File Display
---------------------- --------------------------------- -------
DBKP515 TS64081.TEST.LISTING(IBME73) Y
___________ ____________________________ _
Enter QUIT to return with current settings saved.
CANCEL to return without current settings saved.
UP/DOWN to scroll up and down.
- Compile Unit
- Is the name of a valid compile unit currently known to Debug Tool.
New compile units are added to the list as they become known.
- Listing/Source File
- Is the name of the listing or source file containing the compilation
unit to be displayed in the Source window. If the file is a listing,
only source program statements are shown. The minimum required is
the compile unit name. The default file specification is pgmname
LISTING * (COBOL and PL/I), where pgmname is
the name of your program. For TSO, the default file specification
is userid.pgmname.C (C and C++), userid.pgmname.list (COBOL),
or userid.pgmname.list (PL/I) for sequential data sets
and userid.dsname.C(membername) (C and C++), userid.dsname.Listing(membername) (COBOL),
or userid.dsname.List(membername) (PL/I) for partitioned
data sets.
- Display
- Is a flag that specifies whether the listing or source is to
be displayed in the Source window.
To display a listing view, take the following steps:
- Compile the program with the proper option to generate a source
or source listing file.
- Make sure the file is available and accessible on your host operating
system.
- Set the Display field on the Source Identification
panel to Y for the compile unit. To save time and avoid displaying
listings or source you do not want to see, specify N.
If any of these conditions are not satisfied, the Source
window remains empty until control reaches a compile unit where the
conditions are satisfied.
You can change the source or source
listing associated with a compile unit by entering the new name over
the source or source listing file displayed in the LISTING/SOURCE
FILE field.
Note:
The new name must be followed
by at least one blank.
After you modify the panel,
return to the Debug Tool session panel either by issuing the QUIT command,
or by pressing the QUIT PF key.
- PROFILE
- Displays the Profile Settings panel, where parameters of a full-screen Debug Tool session
can be set.
- SOURCES
- Is equivalent to LISTINGS.
Usage notes
- All information about the panels displayed by the PANEL command
is saved when QUIT is used to leave them. Saving the changes
to the specified panels in this manner returns you to your Debug Tool session
with the current settings in effect. In addition, CANCEL can
be used to leave the panels without saving the changes.
- The PANEL command is not logged.
Examples
- Display the color and attribute panel.
PANEL COLORS;
- Reset the relative sizes of the windows for the current layout
configuration.
PANEL LAYOUT RESET;
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
PERFORM command (COBOL)
The PERFORM command transfers control explicitly to
one or more statements and implicitly returns control to the next
executable statement after execution of the specified statements is
completed. The keywords cannot be abbreviated.
Simple:
- command
- A valid Debug Tool command.
Repeating:
- reference
- A valid Debug Tool COBOL reference.
- condition
- A simple relation condition.
- command
- A valid Debug Tool command.
Usage notes
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
- Related references
- Enterprise COBOL for z/OS Language Reference
PLAYBACK commands
The PLAYBACK commands help you record and replay:
- Statements that you have run.
- Information about your program. For example, the value of variables
and registers and the status of files.
The following table summarizes the forms of the PLAYBACK commands.
| PLAYBACK ENABLE command |
Informs Debug Tool to record all subsequent statements
that you run and other information about your program. |
| PLAYBACK START command |
Informs Debug Tool to suspend normal debugging and
to prepare to replay recorded statements. |
| PLAYBACK FORWARD command |
Informs Debug Tool to replay recorded statements
in forward direction. |
| PLAYBACK BACKWARD command |
Informs Debug Tool to replay recorded statements
in backward direction. |
| PLAYBACK STOP command |
Informs Debug Tool to stop replaying statements,
resume normal debugging, and continue recording the statements that
you run and other information about your program. |
| PLAYBACK DISABLE command |
Informs Debug Tool to stop recording the statements
that you run and discard the information about your program that it
recorded. |
Usage
note
You cannot
use the PLAYBACK commands while you debug a disassembled
program.
PLAYBACK ENABLE command
The PLAYBACK ENABLE command informs Debug Tool to
begin recording the statements that you run and information about
your program. If Debug Tool is already recording the statements that you
run, you can use the PLAYBACK ENABLE command to inform Debug Tool to
record the statements that you run in other compile units or to change
the effect of the DATA option.

- cuname
- Name of the compile unit or compile units where Debug Tool is to
record the statements that you run. You can specify only the names
of the compile units currently known.
- *
- Specifies that Debug Tool is to record the statements that you run
in all compile units. This is the default.
- integer
- Specifies the maximum amount of memory to use to store data
that is collected. The integer value specifies a unit of K (1024)
bytes. For example, an integer value of 2000 indicates 2,048,000 bytes.
The default value is 8000.
- DATA
- Specifies that Debug Tool is to save information about your program,
such as the value of variables and registers. Debug Tool saves this information
for the compile units that you specify in the cuname parameter
or, if you specified the * parameter, for all compile units.
The DATA parameter is effective only for compile units
compiled with the following compilers:
- Enterprise COBOL for z/OS, Version 4.1
- With the following compilers, you must also specify the SYM suboption
of the TEST compiler option:
- Enterprise COBOL for z/OS, Version 3.3 and Version 3.4
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 2
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 1, with APAR PQ63235
- COBOL for OS/390 & VM, Version 2, with APAR PQ63234
DATA is the default.
- NODATA
- Specifies that Debug Tool does not save information about your program.
Usage notes
- For COBOL only: If you enter the PLAYBACK ENABLE DATA command,
and a compile unit supports the DATA parameter, the following
information is recorded:
- FILE SECTION
- WORKING-STORAGE SECTION
- LOCAL-STORAGE SECTION
- LINKAGE SECTION
- All special registers except for: ADDRESS OF, LENGTH
OF, and WHEN-COMPILED
PLAYBACK START command
The PLAYBACK START command suspends normal debugging
and informs Debug Tool to prepare to replay the statements it recorded.
When normal debugging is suspended, all breakpoints are disabled and
many commands are unavailable. Use the STEP and RUNTO commands
to navigate through recorded statements in a forward or backward direction.
Backward is the initial direction of the navigation.
Usage notes
The following commands are available while you replay recorded
statements:
1Refer to PERFORM command (COBOL) for restrictions.
If the DATA option is in effect and the compile unit
supports the DATA option, the following commands are available:
2 The target must be session variable.
The following commands are not available while you replay recorded
statements:
PLAYBACK FORWARD command
The PLAYBACK FORWARD command informs Debug Tool to
perform STEP and RUNTO commands forward, starting
from the current statement and going to the next statement.
PLAYBACK BACKWARD command
The PLAYBACK BACKWARD command informs Debug Tool to
perform STEP and RUNTO commands backward, starting
from the current statement and going to previous statements. Backward
is the initial direction when you enter the PLAYBACK START command.
PLAYBACK STOP command
The PLAYBACK STOP command resumes normal debugging
at the statement where you entered the PLAYBACK START command.
All suspended breakpoints are enabled and all commands are available. Debug Tool continues
to record the statements you run and, if you specified the DATA option,
information about your program.
PLAYBACK DISABLE command
The PLAYBACK DISABLE command informs Debug Tool to
stop recording the statements that you run and, if you specified the DATA option,
information about your program. The information about the program
that Debug Tool collected while recording is discarded. You can instruct Debug Tool to
stop recording for one or more compile units. If you stop recording
for one compile unit and continue recording for other compile units,
the information that you collected for the one compile unit is discarded.
- cuname
- Indicates to Debug Tool to stop recording for the compile unit or
compile units specified. Only the names of currently known compile
units can be specified.
- *
- Indicates to Debug Tool to stop recording for all compile units.
This is the default.
Prefix commands (full-screen mode)
The prefix commands apply to source listing lines and monitor lines.
Prefix commands are commands that are typed into the prefix area of
the Source window or Monitor window, including the automonitor section.
For more information about the commands, see the section corresponding
to the command name.
The following tables summarize the forms of the prefix commands.
Table 7. Monitor window prefix commands
| HEX (MONITOR n HEX)MONITOR command |
Displays selected member of the current set of
MONITOR commands in hexadecimal representation. |
| DEF (MONITOR n DEFAULT)MONITOR command |
Displays selected member of the current set of
MONITOR commands in default representation. |
| CL (CLEAR MONITOR n)CLEAR command |
Clears selected member of the current set of MONITOR
commands. |
| LIST (LIST MONITOR n) LIST MONITOR command |
Lists selected member of the current set of MONITOR
commands. |
PROCEDURE command
The PROCEDURE command allows the definition of a group
of commands that can be accessed by using the CALL procedure
command. The CALL command is the only way to perform the
commands within the PROCEDURE. PROCEDURE definitions
remain in effect for the entire debug session.
The PROCEDURE keyword can be abbreviated only as PROC. PROCEDURE definitions
can be subcommands of other PROCEDURE definitions. The
name of a nested procedure has the scope of only the containing procedure.
Session variables cannot be declared within a PROCEDURE definition.
In addition, a procedure must be defined before it is called on
a CALL statement.
- name
- A valid Debug Tool procedure name. It must be a valid identifier
in the current programming language. The maximum length is 31 characters.
- command
- A valid Debug Tool command other than a declaration or PANEL command.
Usage notes
- Because the Debug Tool procedure names are always uppercase, the procedure
names are converted to uppercase even for programming languages that
have mixed-case symbols.
- If a GO or STEP command is issued within
a procedure or a nested procedure, any statements following the GO or STEP in
that procedure and the containing procedure are ignored. If control
returns to Debug Tool, it returns to the statement following the CALL of
the containing PROCEDURE.
- It is recommended that procedure names be chosen so that they
are valid for all possible programming language settings throughout
the entire Debug Tool debug session.
Examples
- When procedure proc1 is called, the values of variables x, y,
and z are displayed.
proc1: PROCEDURE; LIST (x, y, z); END;
- Define a procedure named setat34 that sets a breakpoint
at statement 34. Procedure setat34 contains a nested procedure lister that
lists current statement breakpoints. Procedure lister can
be called only from within setat34.
setat34: PROCEDURE;
AT 34;
lister: PROCEDURE;
LIST AT STATEMENT;
END;
CALL lister;
END;
QUALIFY RESET command
The QUALIFY
RESET command is equivalent to the SET QUALIFY RESET command.
QUERY command
The QUERY command displays the current value of the
specified Debug Tool setting, the current setting of all the Debug Tool settings,
or the current location in the suspended program.
For an explanation of the Debug Tool settings, see the SET command.
Notes:
- You can use this command in remote debug mode.
- Available only if the Dynamic Debug facility is installed.
- Only for PL/I.
- ASSEMBLER
- Displays the current ASSEMBLER setting.
- AUTOMONITOR
- Displays the current AUTOMONITOR setting.
- CHANGE
- Displays the current CHANGE setting.
- COLORS (full-screen mode)
- Displays the current COLOR setting.
- COUNTRY
- Displays the current COUNTRY setting.
- CURRENT VIEW
- Displays the name of the view being used for the currently qualified
CU.
- DBCS
- Displays the current DBCS setting.
- DEFAULT LISTINGS
- Displays the current DEFAULT LISTINGS setting.
- DEFAULT SCROLL (full-screen mode)
- Displays the current DEFAULT SCROLL setting.
- DEFAULT VIEW
- Displays the name of the view that will be used as the initial
view when you enter the LOADDEBUGDATA command for an assembler
CU.
- DEFAULT WINDOW (full-screen mode)
- Displays the current DEFAULT WINDOW setting.
- DISASSEMBLY
- Displays the current DISASSEMBLY setting.
- DYNDEBUG
- Displays the current DYNDEBUG setting.
- ECHO
- Displays the current ECHO setting.
- EQUATES
- Displays the current EQUATE definitions.
- EXECUTE
- Displays the current EXECUTE setting.
- FIND BOUNDS
- Displays the current FIND BOUNDS setting.
- FREQUENCY
- Displays the current FREQUENCY setting.
- HISTORY
- Displays the current HISTORY setting and size.
- IGNORELINK
- Displays the current IGNORELINK setting.
- INTERCEPT
- Displays the current INTERCEPT setting.
- KEYS (full-screen mode)
- Displays the current KEYS setting.
- LDD
- Displays the current LDD setting.
- LIST TABULAR
- Displays the current LIST TABULAR setting.
- LOCATION
- Displays the statement identifier where execution is suspended.
The current statement identified by QUERY LOCATION has
not yet executed. If suspended at a breakpoint, the description of
the breakpoint is also displayed.
- LOG
- Displays the current LOG setting.
- LOG NUMBERS (full-screen mode)
- Displays the current LOG NUMBERS setting.
- LONGCUNAME
- Displays the current LONGCUNAME setting.
- MONITOR COLUMN
- Displays the current MONITOR COLUMN setting. SET
MONITOR COLUMN is accepted in batch mode, but has no effect.
- MONITOR DATATYPE
- Displays the current MONITOR DATATYPE setting.
- MONITOR NUMBERS (full-screen mode)
- Displays the current MONITOR NUMBERS setting.
- MONITOR WRAP
- Displays the current MONITOR WRAP setting. SET
MONITOR WRAP is accepted in batch mode, but has no effect.
- MSGID
- Displays the current MSGID setting.
- NATIONAL LANGUAGE
- Displays the current NATIONAL LANGUAGE setting.
- PACE
- Displays the current PACE setting. This setting
is not supported in batch mode.
- PFKEYS
- Displays the current PFKEY definitions. This setting
is not supported in batch mode.
- PLAYBACK
- Displays the current status of PLAYBACK.
- PLAYBACK LOCATION
- Displays the statement identifier of the statement being replayed.
- PROGRAMMING LANGUAGE
- Displays the current PROGRAMMING LANGUAGE setting. Debug Tool does
not differentiate between C and C++, use this option for C++ as
well a C programs.
- PROMPT (full-screen mode)
- Displays the current PROMPT setting.
- QUALIFY
- Displays the current QUALIFY BLOCK setting.
- REFRESH (full-screen mode)
- Displays the current REFRESH setting.
- RESTORE
- Displays the current RESTORE setting.
- REWRITE
- Displays the current REWRITE setting. This setting
is not supported in batch mode.
- SAVE
- Displays the current SAVE setting.
- SCREEN (full-screen mode)
- Displays the current SCREEN setting.
- SCROLL DISPLAY (full-screen mode)
- Displays the current SCROLL DISPLAY setting.
- SEQUENCE (PL/I)
- Displays current SEQUENCE setting.
- SETS
- Displays all settings that are controlled by the SET command.
- SOURCE
- Displays the current SOURCE setting.
- SUFFIX (full-screen mode)
- Displays the current SUFFIX setting.
- TEST
- Displays the current TEST setting.
- WARNING (C)
- Displays the current WARNING setting.
- WINDOW SIZES
- Displays the current WINDOW SIZE values and WINDOW CLOSE information.
The window sizes are the values that apply when all windows are open.
Usage
note
You can use the QUERY ASSEMBLER, QUERY AUTOMONITOR, QUERY
CURRENT VIEW, QUERY DEFAULT LISTINGS, QUERY
DEFAULT VIEW, QUERY DISASSEMBLY, QUERY DYNDEBUG, QUERY
IGNORELINK, QUERY INTERCEPT, QUERY LDD, QUERY
LOCATION, QUERY LOG, QUERY QUALIFY, QUERY
REWRITE, and QUERY WARNING commands in remote debug mode.
Examples
- Display the current ECHO setting.
QUERY ECHO;
- Display all current settings.
QUERY SETS;
Refer to the following topics for more information
related to the material discussed in this topic.
QUERY prefix (full-screen mode)
Queries what statements on a particular line have statement breakpoints
when you issue this command through the Source window prefix area.
Usage notes
Refer to the following topics for more information
related to the material discussed in this topic.
QUIT command
The QUIT command ends a Debug Tool session and, if an expression
is specified, sets the return code. In full-screen mode,
it also displays a prompt panel that asks if you really want to quit
the debug session. In line, batch, and remote debug mode, the QUIT command
ends the session without prompting.

- expression
- A valid Debug Tool expression in the current programming language.
If expression is
specified, this value is used as the application return code value.
The actual return code for the run is determined by the execution
environment.
You cannot use expression in remote debug mode.
- ABEND
- If you specify ABEND, Debug Tool raises a CEE2F1 exception
to terminate each active enclave.
- DEBUG
- If you specify DEBUG, Debug Tool ends and your program
keeps running. Any calls to restart Debug Tool are ignored. By default,
when running under CICS, a pseudo-conversational application
will run until the end of the conversation (until EXEC CICS RETURN
without TRANSID is issued to return to CICS).
- TASK
- TASK applies to CICS pseudo-conversational
applications. If you specify TASK, Debug Tool processing will
be terminated until the end of the current CICS pseudo-conversational
task (EXEC CICS RETURN TRANSID). When a new task is started
in the pseudo-conversation, Debug Tool debugging will resume.
Usage notes
- Debug Tool will only resume in a new pseudo-conversational task if
CADP or DTCN successfully match on a pattern.
- QUIT is always logged in a comment line except where
it appears in a command list. This enables you to reuse the log file
as a primary commands file.
- If QUIT is entered from a Debug Tool commands file, no
prompt is displayed. This behavior applies to the Debug Tool preferences
files, primary commands files, and USE files.
- For PL/I, the expression will be converted to FIXED BINARY
(31,0), if necessary. In addition, if an expression is specified,
it is used as if your program called the PLIRETC built-in
subroutine.
- For PL/I, the value of the expression must be nonnegative and
less than 1000.
- If you enter the QUIT DEBUG command and then want to
restart Debug Tool, you must first restart your program
- If you enter the QUIT or QQUIT command while
you are debugging a non-Language Environment assembler or non-Language Environment COBOL
program running under CICS, Debug Tool behaves the same as if
you entered a QUIT ABEND command and a U4038 abend occurs.
Examples
- End a Debug Tool session.
QUIT;
- End a Debug Tool session and use the value in variable x as
the application return code.
QUIT (x);
- End a Debug Tool session without ending the program.
QUIT DEBUG;
Refer to the following topics for more information
related to the material discussed in this topic.
QQUIT command
The QQUIT command ends a Debug Tool session without further
prompting.
Usage notes
- In full-screen mode, the QQUIT command does not display a prompt
panel to verify that you want to quit the debug session.
- If you enter the QQUIT command while you are debugging
a non-Language Environment assembler or non-Language Environment COBOL program running
under CICS, Debug Tool behaves the same as if you had entered
the QUIT ABEND command and a U4038 abend occurs.
Example
End a Debug Tool session.
QQUIT;
Refer to the following topics for more information
related to the material discussed in this topic.
RESTORE command
The RESTORE command enables you to explicitly restore
the settings, breakpoints, and monitor specifications that were previously
saved by the SET SAVE AUTO command when Debug Tool terminated.

- SETTINGS
- Indicates that all SET values except the following values are
to be restored:
- SET DBCS
- SET FREQUENCY
- SET NATIONAL LANGUAGE
- SET PROGRAMMING LANGUAGE
- FILE operand of SET RESTORE SETTINGS
- SET QUALIFY
- SET SOURCE
- SET TEST
- BPS
- Indicates that breakpoints and LOADDEBUGDATA (LDD)
specifications are to be restored. The following breakpoints are
restored:
- APPEARANCE breakpoints
- CALL breakpoints
- DELETE breakpoints
- ENTRY breakpoints
- EXIT breakpoints
- GLOBAL APPEARANCE breakpoints
- GLOBALCALL breakpoints
- GLOBAL DELETE breakpoints
- GLOBAL ENTRY breakpoints
- GLOBAL EXIT breakpoints
- GLOBAL LABEL breakpoints
- GLOBAL LOAD breakpoints
- GLOBAL STATEMENT and GLOBAL LINE breakpoints
- LABEL breakpoints
- LOAD breakpoints
- OCCURRENCE breakpoints
- STATEMENT and LINE breakpoints
- TERMINATION breakpoint
If a deferred AT ENTRY breakpoint has not been
encountered, it is not saved nor restored.
- MONITORS
- Indicates that monitor and LOADDEBUGDATA (LDD)
specifications are to be restored.
Usage notes
- The data restored by this command is retrieved from the default
data set or the data set specified by the SET RESTORE SETTINGS, SET
RESTORE BPS, or SET RESTORE MONITORS commands.
- The member name used to restore the breakpoints or monitor specifications
is the name of the initial load module for the current enclave.
- Do not precede the RESTORE command with any other Debug Tool command
except SET SAVE or another RESTORE command.
Example
- Restore the settings:
RESTORE SETTINGS;
- Restore the breakpoints and monitor specifications:
RESTORE BPS MONITORS;
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
RETRIEVE command (full-screen mode)
The RETRIEVE command displays the last command entered
on the command line. For long commands this might be only the last
line of the command.
- COMMAND
- Retrieves commands. Any command retrieved to the command line
can be performed by pressing Enter. The retrieved command can also
be modified before it is performed. Successive RETRIEVE commands
continue to display up to 12 commands previously entered on the command
line. This operand is most useful when assigned to a PF key.
Usage notes
- The RETRIEVE command is not logged.
Example
Retrieve the last line so that it can be reissued or modified.
RETRIEVE COMMAND;
RUN command
The RUN command is synonymous to the GO command.
Refer to the following topics for more information
related to the material discussed in this topic.
RUNTO command
The RUNTO command runs your program to a valid executable
statement without setting a breakpoint. You can indicate at which
statement to stop by specifying the statement id or by positioning
the cursor on a statement.
- statement_id
- A valid statement identifier. If you are debugging a disassembled
program, specify the statement identifier as an offset in hexadecimal
form (X'offset').
Usage notes
- If you indicate a statement by positioning the cursor on the statement,
the cursor must be in the Source window and positioned on a line where
an executable statement begins.
- If you indicate a statement by positioning the cursor on the statement
and there are multiple statements on the same line, the target of
the RUNTO command is the first relative statement on the
line. For optimized COBOL programs, the target of the command is the
first executable command which was not discarded by the optimizer.
- If you indicate a statement by providing a statement id, the statement
id must be an executable statement.
- Execution continues until one of the following conditions occurs:
- The location indicated by the cursor position or the statement
id is reached.
- A previously set breakpoint is encountered.
- The end of the job is reached.
- For optimized COBOL programs, the RUNTO command remains
in effect until the statement you indicated is reached. For example,
if your program encounters a breakpoint and then you enter the GO or RUN command,
the program runs until the next breakpoint is encountered or the statement
you indicated is reached.
- You can use the RUNTO command in remote debug mode only
by entering it in the Action field,
which is in the Optional Parameters section
of the Add a Breakpoint task.
Examples
- Run to statement 67, where statement 67 is in a currently active
block.
RUNTO 67;
- Run to the statement 11 in the block IPLI11A, where IPLI11A is
known in the current enclave.
RUNTO IPLI11A :> 11
- Run to statement 36, where statement 36 is located in the Source
window.
- Type RUNTO in the command line.
- Place the cursor on statement 36.
- Press Enter.
- Run to the statement 74, using a PF key.
- Define a PF key to run to the cursor position.
SET PF13 = RUNTO;
- Place the cursor at the statement 74 and hit shift+PF1 key.
Refer to the following topics for more information
related to the material discussed in this topic.
RUNTO prefix command (full-screen mode)
Runs to the statement when you issue this command through the Source
window prefix area.
Usage notes
- For RUNTO prefix , no space is needed as a delimiter
between the keyword and the integer; RUNTO 67 is equivalent
to RUNTO67.
- For optimized COBOL programs, if there are multiple statements
on a line, the RUNTO prefix runs to the first executable
statement which was not discarded by the optimizer.
Example
Run to the statement 67, where statement 67 is located in the
Source window.
- Type RUNTO in the prefix area of statement 67, then
press Enter.
SCROLL command (full-screen mode)
The SCROLL command provides horizontal and vertical
scrolling in full-screen mode. Scroll commands can be made immediately
effective with the IMMEDIATE command. The SCROLL keyword
is optional.
The Log, Monitor, Memory, or Source window will not wrap around
when scrolled.

- DOWN
- Scrolls the specified number of lines in a window toward the
top margin of that window. DOWN is equivalent to NEXT.
- LEFT
- Scrolls the specified number of columns in a window toward the
right margin of that window. If SET MONITOR WRAP OFF is
in effect, using LEFT allows you to scroll toward the right
the specified number of characters in the monitor value area so data
that is not visible to the left becomes visible.
- NEXT
- Is equivalent to DOWN.
- RIGHT
- Scrolls the specified number of columns in a window toward the
left margin of that window. If SET MONITOR WRAP OFF is
in effect, using RIGHT allows you to scroll toward the
left the specified number of characters in the monitor value area
so data that is not visible to the right becomes visible.
- UP
- Scrolls the specified number of lines in a window toward the
bottom margin of that window.
- CSR
- Specifies scrolling based on the current position of the cursor
in a selected window. The window scrolls up, down, left, or right
of the cursor position until the character where the cursor is positioned
reaches the edge of the window. If the cursor is not in a window or
if it is already positioned at the edge of a window, a full-page scroll
occurs. If the cursor is in the monitor value area then the monitor
value area is scrolled left or right to the position of the cursor.
- DATA
- Scrolls by one line less than the window size or by one character
less than the window size (if moving left or right). If the cursor
is in the monitor value area then the monitor value area scrolls left
or right by one character less than the monitor value area width.
- HALF
- Scrolls by half the window size or by half the monitor value
area.
- integer
- Scrolls the specified number of lines (up or down) or the specified
number of characters (left or right). Maximum value is 9999.
- MAX
- Scrolls in the specified direction until the limit of the data
is reached. To scroll the maximum amount, you must use the MAX keyword.
You cannot scroll the maximum amount by filling in the scroll amount
field. If the cursor is placed in the monitor value area then the
monitor value area is scrolled left or right until the limit of the
data is reached.
- PAGE
- Scrolls by the window size or by the monitor value area size.
- BOTTOM
- Scrolls to the bottom of the data.
- TO integer
- Specifies that the selected window is to scroll to the given
line (as indicated in the prefix area of the selected window). This
can be in either the UP or DOWN direction (for
example, if you are line 30 and issue TO 20, it will return
to line 20). Maximum value is 999999.
- TOP
- Scrolls to the top of the data.
- CURSOR
- Selects the window where the cursor is currently positioned.
- LOG
- Selects the session log window.
- MEMORY
- Selects the Memory window.
- MONITOR
- Selects the monitor window.
- SOURCE
- Selects the source listing window.
Usage notes
- You cannot use the following commands in the Memory window:
- SCROLL TOP
- SCROLL BOTTOM
- SCROLL TO
- SCROLL LEFT
- SCROLL RIGHT
- SCROLL MAX
- If you do not specify an operand with the DOWN, LEFT, NEXT, RIGHT,
or UP keywords, and the cursor is outside the window areas,
the window scrolled is determined by the current default window setting
(if the window is open) and the scroll amount is determined by the
current default scroll setting, shown in the SCROLL field on the Debug Tool session
panel. Default scroll and default window settings are controlled
by SET DEFAULT SCROLL and SET DEFAULT WINDOW commands.
- When the SCROLL field on the Debug Tool session panel is typed over
with a new value, the equivalent SET DEFAULT SCROLL command
is issued just as if you had typed the command into the command line
(that is, it is logged and retrievable).
- The SCROLL command is not logged.
- To scroll the monitor value area left or right, SET MONITOR
WRAP OFF must be in effect and the cursor must be in the monitor
value area.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
SELECT command (PL/I)
The SELECT command chooses one of a set of alternate
commands.
If the reference can be satisfied by more than one of the WHEN clauses,
only the first one is performed. If there is no reference, the first WHEN clause
containing an expression that is true is executed. If none of the WHEN clauses
are satisfied, the command specified on the OTHERWISE clause,
if present, is performed. If the OTHERWISE clause should
be executed and it is not present, a Debug Tool message is issued.
- reference
- A valid Debug Tool PL/I scalar reference. An aggregate (array or
structure) cannot be used as a reference.
- WHEN
- Specifies that an expression or a group of expressions be evaluated
and either compared with the reference immediately following the SELECT keyword,
or evaluated to true or false (if reference is omitted).
- expression
- A valid Debug Tool PL/I expression.
- command
- A valid Debug Tool command.
- OTHERWISE
- Specifies the command to be executed when every test of the
preceding WHEN statements fails.
Usage notes
- You cannot use the SELECT command while you replay
recorded statements by using the PLAYBACK commands.
Example
When sum is equal to the value of c+ev, display
a message. When sum is equal to either fv or 0,
display a message. If sum is not equal to the value of
either c+ev, fv, or 0, a Debug Tool error
message is issued.
SELECT (sum);
WHEN (c + ev) LIST ('Match on when group number 1');
WHEN (fv, 0) LIST ('Match on when group number 2');
END;
SET command
The SET command sets various switches that affect the
operation of Debug Tool. Except where otherwise specified, settings remain
in effect for the entire debug session.
The following table summarizes the forms of the SET command.
| SET ASSEMBLER ON/OFF command |
Controls the enablement of assembler debugging. |
| SET ASSEMBLER STEPOVER command |
Controls the behavior of the STEP OVER command
while debugging assembler compile units. |
| SET AUTOMONITOR command |
Controls the addition of data items to the Monitor
window. |
| SET CHANGE command |
Controls the frequency of checking the AT
CHANGE breakpoints. |
| SET COLOR command (full-screen and line mode) |
Provides control of the color, highlighting, and
intensity attributes. |
| SET COUNTRY command |
Changes the current national country setting. |
| SET DBCS command |
Controls whether DBCS shift-in and shift-out codes
are recognized. |
| SET DEFAULT LISTINGS command |
Defines a default partitioned data set (PDS) ddname
or dsname searched for program source listings or source files. |
| SET DEFAULT SCROLL command (full-screen mode) |
Sets the default scroll amount. |
| SET DEFAULT VIEW command |
Controls the default view for assembler compile
units. |
| SET DEFAULT WINDOW command (full-screen mode) |
Sets the window that is affected by a window
referencing command. |
| SET DISASSEMBLY command |
Controls whether the disassembly view is displayed
in the Source window. |
| SET DYNDEBUG command |
Controls whether the Dynamic Debug facility is activated. |
| SET ECHO command |
Controls whether GO and STEP commands
are recorded in the log window. |
| SET EQUATE command |
Equates a symbol to a string of characters. |
| SET EXECUTE command |
Controls whether commands are performed or just
syntax checked. |
| SET FIND BOUNDS command |
Controls the columns searched in the Source
window and in line mode. |
| SET FREQUENCY command |
Controls whether statement executions are counted. |
| SET HISTORY command |
Specifies whether entries to Debug Tool are recorded
in the history table. |
| SET IGNORELINK command |
Specifies whether to ignore any new LINK level
(nested enclave). |
| SET INTERCEPT command (C and C++) |
Intercepts input to and output from specified
files. Output and prompts for input are displayed in the log. |
| SET INTERCEPT command (COBOL, full-screen mode, line
mode, batch mode) |
Intercepts input to and output from the CONSOLE.
Output and prompts for input are displayed in the log. |
| SET INTERCEPT command (COBOL, remote debug mode) |
Intercepts output from COBOL DISPLAY statements.
Output is displayed in the Debug Console. |
| SET KEYS command (full-screen mode) |
Controls whether PF key definitions are displayed. |
| SET LDD command |
Controls how debug data is loaded for assemblies
containing multiple CSECTs. |
| SET LIST TABULAR command |
Controls the formatting of the output of the
LIST command. |
| SET LOG command |
Controls the logging of output and assignment
to the log file. |
| SET LOG NUMBERS command (full-screen mode) |
Controls whether line numbers are shown in the
log window. |
| SET LONGCUNAME command |
Controls whether a long or a short CU name is
shown. |
| SET MONITOR command |
Controls the format and layout of variable names
and values displayed in the Monitor window. |
| SET MSGID command |
Controls whether message identifiers are shown. |
| SET NATIONAL LANGUAGE command |
Switches your application to a different run-time
national language. |
| SET PACE command |
Specifies the maximum pace of animated execution. |
| SET PFKEY command |
Associates a Debug Tool command with a PF key. |
| SET PROGRAMMING LANGUAGE command |
Sets the current programming language. |
| SET PROMPT command (full-screen mode) |
Controls the display of the current program location. |
| SET QUALIFY command |
Simplifies the identification of references and
statement numbers by resetting the point of view. |
| SET REFRESH command (full-screen mode) |
Controls screen refreshing when the SCREEN setting
is ON. |
| SET RESTORE command |
Controls the automatic and manual restoring
of settings, breakpoints, and monitor specifications. |
| SET REWRITE command (full-screen mode) |
Forces a periodic screen rewrite. |
| SET SAVE command |
Controls the automatic saving of settings, breakpoints,
and monitor specifications. |
| SET SCREEN command (full-screen mode) |
Controls how information is displayed on the screen. |
| SET SCROLL DISPLAY command (full-screen mode) |
Controls whether the scroll field is displayed. |
| SET SEQUENCE command (PL/I) |
Controls whether Debug Tool interprets data after
column 72 as a sequence number. |
| SET SOURCE command |
Associates a source listing or source file with
one or more compile units. |
| SET SUFFIX command (full-screen mode) |
Controls the display of the Source window suffix
area. |
| SET TEST command |
Overrides the initial TEST run-time
options specified at invocation. |
| SET WARNING command (C, C++, COBOL, and PL/I) |
Controls display of the Debug Tool warning messages
and whether exceptions are reflected to the application program. |
Refer to the following topics for more information
related to the material discussed in this topic.
SET ASSEMBLER ON/OFF command
A disassembled compilation unit is a CU that was not
compiled with the TEST compiler option and has not been
used as the operand of a LOADDEBUGDATA command. The SET
ASSEMBLER ON command enables a subset of the functions enabled
by the SET DISASSEMBLY ON command. The following behavior
is enabled for disassembled compilation units by the SET ASSEMBLER
ON command:
- You can stop in a disassembly CU by using the commands:
- AT APPEARANCE *
- AT APPEARANCE name
- You can display the names of disassembled CUs by using the following
commands:
- DESCRIBE CUS
- LIST
- LIST NAMES CUS
- QUERY SOURCE
- OFF
- Disables the display of data that is useful while you debug
an assembler program.
- ON
- Enables the display of data that is useful while you debug an
assembler program.
Usage notes
- You can also use the SET DISASSEMBLY ON to control
the display of information that is useful while you debug an assembler
program.
- You can use this command in remote debug mode.
Example
To include disassembly compile units in the list of compile units
displayed by the LIST NAMES CUS and DESCRIBE CUS commands,
enter the following command:
SET ASSEMBLER ON ;
The next time you enter the LIST NAMES CUS or DESCRIBE
CUS command, the disassembly compile units are displayed in
the list of compile units.
Refer to the following topics for more information
related to the material discussed in this topic.
SET ASSEMBLER STEPOVER command
Specifies how Debug Tool processes STEP OVER commands in
assembler compile units. When EXTONLY is in effect, Debug Tool only
steps over calls to external subroutines. When EXTINT is
in effect, Debug Tool steps over calls to external and internal subroutines.
External subroutines are subroutines that are outside the current
compile unit; internal subroutines are subroutines that are inside
the current compile unit.
Debug Tool returns control to you the next time it runs any instruction
in the current compile unit (CSECT) when either of the following situations
occur:
- EXTONLY is in effect
- EXTINT is in effect and the assembler program calls
an external subroutine
Debug Tool assumes that the subroutine you want to step over returns
to the instruction that follows the call to that subroutine when all
of the following situations occur:
- EXTINT is in effect
- The function is an internal subroutine
- The address that immediately follows the instruction where you
are currently stopped contains an executable instruction (not data)
Debug Tool assumes that you use one of the following instructions
to call internal subroutines:
- BAL
- BAS
- BRAS
- BALR
- BASR
- BASSM
- BRASL
- EXTONLY
- Specifies that Debug Tool steps over external
subroutines and steps through internal subroutines.
- EXTINT
- Specifies that Debug Tool steps over external and internal
subroutines.
Usage notes
- If EXTINT is in effect and an internal subroutine does
not return to the instruction that immediately follows the call to
that subroutine, one of the following situations might occur:
- Debug Tool might not regain control
- Debug Tool might regain control only when another breakpoint is run
- Debug Tool might regain control only when an external event occurs
- Debug Tool might not regain control and the program runs until it
terminates
- You can use this command in remote debug mode.
Refer to the following topics for more information
related to the material discussed in this topic.
SET AUTOMONITOR command
Controls the monitoring of data items for the statement that Debug Tool will
run next, the most recent statement that Debug Tool ran, or both. The
initial setting is OFF.
AUTOMONITOR works only for the following compile units:
- COBOL or PL/I compile units compiled with the SYM suboption
of the TEST compiler option. COBOL programs compiled with
Enterprise COBOL for z/OS, Version 4.1, do not need the SYM suboption
of the TEST compiler option.
- assembler, disassembly, or non-Language Environment COBOL compile
units
The SET AUTOMONITOR command does not work for compile
units written in any other language. In addition, the compile unit
must be compiled or assembled with one of the following compilers
or assemblers:
- Enterprise COBOL for z/OS, Version 4.1
- Enterprise COBOL for z/OS and OS/390,
Version 3 Release 2 or later
- Enterprise COBOL for z/OS and OS/390,
Version 3 Release 1, with APAR PQ63235 installed
- COBOL for OS/390 & VM, Version 2, with APAR
PQ63234 installed
- OS/VS COBOL, Version 1 Release 2.4
- Enterprise PL/I for z/OS and OS/390,
Version 3 Release 2 or later
- High Level Assembler for MVS &
VM & VSE, Version 1 Release 4 or later

- ON
- Enables monitoring of data items for the statement that Debug Tool will
run next, the most recent statement that Debug Tool ran, or both. Specify
the LOG suboption to save information in the log file.
- OFF
- Disables monitoring of all data items. Information is not saved
in the log file.
- LOG
- Saves information in the log file.
- NOLOG
- Does not save information in the log file.
- CURRENT
- Monitor data items on the statement that Debug Tool will run next.
This is the default.
- PREVIOUS
- Monitor data items on the most recent statement that Debug Tool ran.
- BOTH
- Monitor data items for the statement that Debug Tool will run next
and the most recent statement that Debug Tool ran.
Usage notes
- You can use this command in remote debug mode.
- If the DATA option of the PLAYBACK ENABLE command
is in effect for the current compile unit, you can use the SET
AUTOMONITOR command while you replay recorded statements with
the PLAYBACK commands. However, you cannot use the BOTH or PREVIOUS parameters.
- If you enter the SET AUTOMONITOR ON LOG command for
a compile unit that was compiled with a compiler that does not supports
automonitoring, then Debug Tool writes the breakpoint location into the
log. This provides a record of the breakpoints encountered (breakpoint
trace). No variable information is displayed.
- To record the breakpoints encountered (breakpoint trace) in the
log file, enter the following commands: SET AUTOMONITOR ON LOG;
AT * GO;. For compile units compiled with a compiler that supports
automonitoring, the statement location, the variable names, and the
value of the variables are saved into the log. For other compile units,
the statement location is saved into the log.
- If you are debugging programs compiled with a PL/I compiler earlier
than Enterprise PL/I for z/OS Version 3 Release 5, target variables
are not listed. For example, in the following PL/I statement only J and
its value is displayed:
I = J + 1
- For assembler and disassembly, Debug Tool displays only 32-bit general
registers, floating-point registers, and storage operands. Debug Tool displays
them in the following manner:
- Register operands are displayed in numeric order.
- Storage operands are displayed in the order S1, S2, and S4.
- When the storage operand is a single symbol, the symbol name is
displayed in the automonitor section of the Monitor window. Otherwise,
the specified operand is displayed as a comment and the _STORAGE function
is used to display the storage contents. For example, _STORAGE(X'1F3C8'::4))
is used to display a four-byte storage operand at address X'1F3C8'.
- In an assembler compile unit, the SET AUTOMONITOR command
provides information about a single machine instruction only. Even
in the NOMACGEN view, SET AUTOMONITOR provides information
about only one machine instruction and not all operands of the current
macro invocation.
- For non-Language Environment COBOL, array references are not included
in the AUTOMONITOR output.
- To disable monitoring of all data items, you can enter the SET
AUTOMONITOR OFF or CLEAR MONITOR n commands,
where n is the monitor number of an automonitor entry. You
can also use CL prefix command on an entry in Monitor window.
- Use the PREVIOUS and BOTH options while
you step (by using the STEP command) through a program
to see the values of a variables before and after a statement is run.
- If you use The PREVIOUS or BOTH options
and run through your program with the GO command, Debug Tool displays
the value of a variable on the line that Debug Tool ran most recently,
which might not be the line that you see in the Source window immediately
before the current line.
- When control is transferred between enclaves and any of the following
settings are in effect, Debug Tool cannot determine the data from the
previous enclave:
- SET AUTOMONITOR ON LOG with PREVIOUS or BOTH
- SET AUTOMONITOR ON NOLOG with PREVIOUS or BOTH
Debug Tool displays a message.
Refer to the following topics for more information
related to the material discussed in this topic.
SET CHANGE command
Controls the frequency of checking the AT CHANGE breakpoints.
The initial setting is STATEMENT/LINE.
- STATEMENT
- Specifies that the AT CHANGE breakpoints are checked
at all statements. STATEMENT is equivalent to LINE.
- ALL
- Specifies that the AT CHANGE breakpoints are checked
at all statements, block entry and exits, and path points.
- BLOCK
- Specifies that the AT CHANGE breakpoints are checked
at all block entry and exits.
- LINE
- Is equivalent to STATEMENT.
- PATH
- Specifies that the AT CHANGE breakpoints are checked
at all path points.
Examples
- Specify that AT CHANGE breakpoints are checked at all
statements.
SET CHANGE;
- Specify that AT CHANGE breakpoints are checked at all
path points.
SET CHANGE PATH;
SET COLOR command (full-screen and line mode)
Provides control of the color, highlighting, and intensity attributes
when the SCREEN setting is ON. The color, highlighting,
and intensity keywords can be specified in any order.

- CYCLE
- Causes the color to change to the next one in the sequence of
colors. The sequence follows the order shown in the syntax diagram.
- BLINK
- Causes the characters to blink (if supported by the terminal).
- NONE
- Causes the characters to appear in normal type.
- REVERSE
- Transforms the characters to reverse video (if supported by
the terminal).
- UNDERLINE
- Causes the characters to be underlined (if supported by the
terminal).
- HIGH
- Causes screen colors to be high intensity (if supported by the
terminal).
- LOW
- Causes screen colors to be low intensity (if supported by the
terminal).
- CURSOR
- Specifies that cursor pointing is used to select the field.
Optionally, you can type in the field name (for example, COMMAND
LINE) as shown in the syntax diagram.
- COMMAND LINE
- Selects the command input line (preceded by ===>).
- LOG LINES
- Selects the line number portion of the log window.
- MEMORY ADDRESS
- Selects the address column of the memory dump area.
- MEMORY BASE ADDRESS
- Selects the history lines and the base address of the information
area.
- MEMORY CHARACTER
- Selects the character column of the memory dump area.
- MEMORY HEXADECIMAL
- Selects the hexadecimal column of the memory dump area.
- MEMORY INFORMATION
- Selects the history lines of the information area.
- MEMORY OFFSET
- Selects the offset column of the memory dump area.
- MONITOR AREA
- Selects the primary area of the monitor window.
- MONITOR LINES
- Selects the line number portion of the monitor window.
- PROGRAM OUTPUT
- Selects the application program output displayed in the log
window.
- SOURCE AREA
- Selects the primary area of the Source window.
- SOURCE BREAKPOINTS
- Selects the source prefix fields next to statements where breakpoints
are set.
- SOURCE CURRENT
- Selects the line containing the source statement that is about
to be performed.
- SOURCE PREFIX
- Selects the statement identifier column at the left of the source
window.
- SOURCE SUFFIX
- Selects the frequency column at the right of the Source window.
- TARGET FIELD
- Selects the target of a FIND command in full-screen
mode, if found.
- TEST INPUT
- Selects the Debug Tool input displayed in the log window.
- TEST OUTPUT
- Selects the Debug Tool output displayed in the log window.
- TITLE FIELDS
- Selects the information fields in the top line of the screen,
such as current programming language setting or the current location
within the program.
- TITLE HEADERS
- Selects the descriptive headers in the top line of the screen,
such as location.
- TOFEOF MARKER
- Selects the top-of-file and end-of-file lines in the session
panel windows.
- WINDOW HEADERS
- Selects the header lines for the windows in the main session
panel.
Examples
SET COUNTRY command
Changes the current national country setting for the application
program. It is available only where supported by Language Environment or when
running without the Language Environment run time. The IBM-supplied initial
country code is US.
- country_code
- A valid two-letter set that identifies the country code used.
The country code can have one of the following values:
- United States: US
- Japanese: JP
Country codes cannot be truncated.
Usage notes
- This setting affects both your application and Debug Tool.
- At the beginning of an enclave, the settings are those provided
by Language Environment, your operating system, or the Debug Tool run-time options.
For nested enclaves, the parent’s settings are restored upon
return from a child enclave.
Example
Change the current country code to correspond to Japan.
SET COUNTRY JP;
SET DBCS command
Controls whether shift-in and shift-out codes are interpreted on
input and supplied on DBCS output. SET DBCS is valid for
all programming languages. The initial setting is OFF.
- ON
- Interprets shift-in and shift-out codes. If you debugging in
full-screen mode and your terminal is not capable of displaying DBCS
characters, this option is not available.
- OFF
- Ignores shift-in and shift-out codes.
Usage notes
- If you enter the commands SET NATIONAL LANGUAGE ENU and
then SET DBCS ON, Debug Tool resets the national language to
UEN to remain compatible with DBCS characters.
- If NATIONAL LANGUAGE is set to JPN or KOR and
you are using full-screen mode, enter the SET DBCS ON command
so that Debug Tool displays messages correctly.
Example
Specify that shift-in and shift-out codes are interpreted.
SET DBCS ON;
Refer to the following topics for more information
related to the material discussed in this topic.
SET DEFAULT LISTINGS command
Defines a default partitioned data set DD name or DS name whose
members are searched for program source, listings, or separate debug files.
- ddname
- Specifies a valid z/OS DD name. If the operand is less
than nine characters long and does not contain a period, it is interpreted
as a DD name.
The ddname form can not be used if the data
set allocated to it is C, C++ or Enterprise PL/I source and the EQAOPTS
SUBSYS=ssss option is being used to access a source file
in a library system.
- dsn
- Specifies a valid, fully-qualified z/OS partitioned
data set name.
- ( dsn, dsn, ...)
- Specifies a list of valid z/OS partitioned
data set names.
Usage notes
- You can use this command in remote debug mode.
- The LISTINGS keyword cannot be abbreviated.
- If you do not specify a ddname or dsn, any previous
default listing setting is cleared.
- If the data set name is too long to be typed on one line, suffix
it with a trailing hyphen.
- The SET SOURCE ON command has a higher precedence than
the SET DEFAULT LISTINGS command.
- The SET DEFAULT LISTINGS command has no effect on a
disassembly compile unit. However, it is saved and it might apply
later if the compile unit is specified as the operand of the LOADDEBUGDATA command.
- If you are debugging in a CICS environment,
you can not use the ddname parameter.
- If you compiled your C or C++ program with the FORMAT(DWARF) suboption
of the DEBUG compiler option, you cannot use the SET
DEFAULT LISTINGS command to specify the new location of the
.dbg file. Use the EQADEBUG DD statement or an EQAUEDAT user
exit to specify the new location of the file.
Examples
- Indicate that the default listings file is allocated to DS name SVTRSAMP.TS99992.MYPROG.
SET DEFAULT LISTINGS SVTRSAMP.TS99992.MYPROG;
- The listing for the program MYPROG is in SVTRSAMP.TS99992.MYPROG,
which was allocated by using the following command:
ALLOC DDNAME(ITEM1) DSNAME('SVTRSAMP.TS99992.MYPROG') SHRTo
specify the location, enter the following command:
SET DEFAULT LISTINGS ITEM1;
- The listing for the program MYPROG is in JSMITH.COBPGMS.LISTING,
which was allocated by using the following command:
ALLOC FI(CBLIST) DAT('MJONES.OTHER.LISTING' 'JSMITH.COBPGMS.LISTING')To
specify the location, enter the following command:
SET DEFAULT LISTINGS CBLIST
- The listing for the program AVER is in myid.source.listing(AVERLIST).
If you enter the command SET DEFAULT LISTINGS myid.source.listing, Debug Tool looks
for a member named AVER in the PDS myid.source.listing.
Because the member is called AVERLIST, the listing is not
found. To specify the location, enter the following command:
SET SOURCE ON (AVER) myid.source.listing(AVERLIST);
Refer to the following topics for more information
related to the material discussed in this topic.
SET DEFAULT SCROLL command (full-screen mode)
Sets the default scroll amount that is used when a SCROLL command
is issued without the amount specified. The initial setting is PAGE.
- CSR
- Scrolls in the specified direction until the character where
the cursor is positioned reaches the edge of the window.
- DATA
- Scrolls by one line less than the window size or by one character
less than the window size (if moving left or right).
- HALF
- Scrolls by half the window size.
- integer
- Scrolls the specified number of lines (up or down) or the specified
number of characters (left or right). Maximum value is 9999.
- MAX
- Scrolls in the specified direction until the limit of the data
is reached.
- PAGE
- Scrolls by the window size.
Example
Set the default amount to half the size of the window.
SET DEFAULT SCROLL HALF;
SET DEFAULT VIEW command
Controls the default view for assembler compile units.
- STANDARD
- Indicates that whenever a LOADDEBUGDATA (LDD) command is issued
for an assembler CU, the initial view is to contain all source statements.
- NOMACGEN
- Indicates that whenever a LOADDEBUGDATA (LDD) command is issued
for an assembler CU, the initial view is to contain only source statements
that were not generated via macro expansion (similar to the assembler
listing when PRINT NOGEN is in effect).
Usage notes
- SET DEFAULT VIEW applies only to assembler compile
units.
- You can use this command in remote debug mode.
Refer to the following topics for more information
related to the material discussed in this topic.
SET DEFAULT WINDOW command (full-screen mode)
Specifies which physical window is selected when a window referencing
command (for example, FIND, SCROLL, or WINDOW)
is issued without explicit window identification and the cursor is
outside the physical window areas. The initial setting is SOURCE.
- LOG
- Selects the session log window.
- MEMORY
- Selects the Memory window.
- MONITOR
- Selects the monitor window.
- SOURCE
- Selects the source listing window.
Example
Set the default to the monitor window for use with scrolling commands.
SET DEFAULT WINDOW MONITOR;
SET DISASSEMBLY command
A disassembled compilation unit is a CU that was not
compiled with the TEST compiler option and has not been
used as the operand of a LOADDEBUGDATA command. The SET
DISASSEMBLY ON command enables the following behavior for disassembled
compilation units:
- A disassembly view appears in the source window whenever you qualify
a disassembled compilation unit. You can set breakpoints in the CU
using the AT OFFSET command and you can step within the
CU using the STEP command.
- You can stop in a disassembly CU by using the following commands:
- AT APPEARANCE *
- AT APPEARANCE name
- AT ENTRY *
- STEP INTO
- You can display the names of disassembled CUs by using the following
commands:
- DESCRIBE CUS
- LIST
- LIST NAMES CUS
- QUERY SOURCE
- ON
- Specifies that the disassembly view is displayed in the Source
window.
- OFF
- Turns off the disassembly view. This is the default setting.
Usage notes
- The disassembly view is provided only for disassembled programs
or programs written in supported languages that do not have debug
information.
- You can use this command in remote debug mode.
Refer to the following topics for more information
related to the material discussed in this topic.
SET DYNDEBUG command
Controls the activation or deactivation of the Dynamic Debug facility.
The Dynamic Debug facility must be installed and activated in order to debug
the following types of programs:
- COBOL programs compiled with the NONE or NOHOOK suboptions
of the TEST compiler option.
- PL/I programs compiled with Enterprise PL/I for z/OS, Version
3 Release 4 or later, and the NOHOOK suboption of the TEST compiler
option
- assembler programs
- disassembled programs (using the disassembly view)
- non-Language Environment COBOL programs1
- programs that run without the Language Environment run time1
You can use the Dynamic Debug facility to improve the performance of programs
with compiled-in hooks (compiled with COBOL, C/C++, and PL/I compilers)
while you debug them.
If the Dynamic Debug facility has been installed, the initial setting is ON.
If it was not installed, the initial setting is OFF and
you cannot activate the Dynamic Debug facility.
- ON
- Activates the Dynamic Debug facility.
- OFF
- Deactivates the Dynamic Debug facility.
Usage notes
- After a dynamic debug hook has been inserted, either explicitly
or implicitly, into any program during a debugging session, you cannot
use the SET DYNDEBUG OFF command.
- You can use this command in remote debug mode.
- You can debug COBOL programs compiled with the NOHOOK suboption
of the TEST compiler option of Enterprise COBOL for z/OS,
Version 4.1, with the Dynamic Debug facility.
- To debug COBOL programs compiled with the TEST(NONE) compiler
option and use the Dynamic Debug facility, you must compile with one of the
following compilers:
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390 & VM, Version 2 Release 2
- COBOL for OS/390 & VM, Version 2 Release 1, with APAR PQ40298
- For COBOL programs, you can use the GOTO or JUMPTO commands
in the following situations:
- A COBOL program compiled with hooks inserted by the compiler.
If you are using Enterprise COBOL for z/OS, Version
4.1, compile your program with the HOOK suboption of the TEST compiler
option. If you are using any of the following compilers, compile your
program with either PATH or ALL suboption and
the SYM suboption of the TEST compiler option:
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390 & VM, Version 2
- A COBOL program compiled without hooks inserted by the compiler
and without optimization. If you are using Enterprise COBOL for z/OS,
Version 4.1, compile your program with the NOHOOK suboption
of the TEST compiler option. If you are using any of the
following compilers, compile your program with the NONE suboption
of the TEST compiler option:
- Enterprise COBOL for z/OS and OS/390,
Version 3 Release 2 or later
- Enterprise COBOL for z/OS and OS/390,
Version 3 Release 1, with APAR PQ63235 installed
- COBOL for OS/390 & VM, Version 2 Release
2
- COBOL for OS/390 & VM, Version 2 Release
1, with APAR PQ63234 installed
- A COBOL program compiled without hooks inserted by the compiler
and with optimization. You must compile your program with Enterprise
COBOL for z/OS, Version 4.1, and specify the EJPD and NOHOOK suboption
of the TEST compiler option. Specifying the EJPD suboption
might cause some loss of optimization.
- The Dynamic Debug facility does not support attention interrupts with programs
compiled using the following suboptions of the compilers:
- NOHOOK suboption of the TEST compiler option
for the following compilers:
- Enterprise COBOL for z/OS, Version 4.1
- Enterprise PL/I for z/OS, Version 3.4 or later
- NONE suboption of the TEST compiler option
for the following compilers:
- Enterprise COBOL for z/OS and OS/390,
Version 3
- COBOL for OS/390 & VM, Version 2
- When the following compilers are used with the suboption of the TEST compiler
option that adds compiled-in hooks, the Dynamic Debug facility can be used
to add hooks at run time, which Debug Tool uses instead of the compiled-in
hooks. This can improve the performance of the program while running
under the control of Debug Tool.
- Any COBOL compiler supported by Debug Tool
- Any C/C++ compiler supported by Debug Tool
- Any PL/I compiler supported by Debug Tool
- Refer to your system administrator to determine if the Dynamic Debug facility
is installed on your system.
- The same program compiled with different TEST options may halt
execution at different locations or the same scenarios. For instance,
if you compile a program with TEST(ALL,...) and step through
the first three lines, execution is halted on line four. However,
if you compile the same program with TEST(NONE,SYM,...) and
step through the first three lines, execution is halted on line five.
The difference is due to optimization techniques used by the compiler.
A small arrowhead indicates where a Debug Tool would stop if the
same program were compiled in two different ways.
| Program compiled with TEST(ALL) |
Program compiled with TEST(NONE) |
| 000001 MOVE... |
000001 MOVE... |
| 000002 ADD... |
000002 ADD... |
| >000003 LABEL: ... |
000003 LABEL: ... |
| 000004 MOVE... |
>000004 MOVE... |
Refer to the following topics for more information
related to the material discussed in this topic.
SET ECHO command
Controls whether GO and STEP commands are
recorded in the log window when they are not subcommands. The presence
of long sequences of GO and STEP commands clutters
the log window and provides little additional information. SET
ECHO makes it possible to suppress the display of these commands.
The contents of the log file are unaffected. The initial setting
is ON.
- ON
- Shows given commands in the log window.
- OFF
- Suppresses given commands in the log window.
- keyword
- Can be GO (with no operand) or STEP.
- *
- Specifies that the command is applied to the GO and STEP commands.
This is the default.
Examples
- Specify that the display of GO and STEP commands
is suppressed.
SET ECHO OFF;
- Specify that GO and STEP commands are displayed.
SET ECHO ON *;
SET EQUATE command
Equates a symbol to a string of characters. The equated symbol
can be used anywhere a keyword, identifier, or punctuation is used
in a Debug Tool command. When an equated symbol is found in a Debug Tool command
(other than the identifier operand in SET EQUATE and CLEAR
EQUATE), the equated symbol is replaced by the specified string
before parsing continues.
- identifier
- An identifier that is valid in the current programming language.
The maximum length of the identifier is:
- For C, 32 SBCS characters
- For COBOL and non-Language Environment COBOL, 30 SBCS characters
- For PL/I, 31 SBCS characters
The identifier can contain DBCS characters.
- string
- A string constant in the current programming language. The
maximum length of the replacement string is 255 SBCS characters.
Usage notes
- Operands of the following commands are for environments other
than the standard Debug Tool environment (that is, TSO DS name, and so
forth) and are not scanned for EQUATEd symbol substitution:
- COMMENT
- INPUT
- SET DEFAULT LISTINGS
- SET INTERCEPT ON/OFF FILE
- SET LOG ON FILE
- SET SOURCE (cu_spec)
- SYSTEM/SYS
- TSO
- USE
- To remove an EQUATE definition, use the CLEAR
EQUATE command.
- To remain accessible when the current programming language setting
is changed, symbols that are equated when the current programming
language setting is C must be entered in uppercase and must be valid
in the other programming languages.
- If an EQUATE identifier coincides with an existing
keyword or keyword abbreviation, EQUATE takes precedence.
If the EQUATE identifier is already defined, the new definition
replaces the old.
- The equate string is not scanned for, or substituted with, symbols
previously set with a SET EQUATE command.
Examples
- Specify that the symbol INFO is equated to "ABC,
DEF (H+1)". The current programming language setting is either
C or COBOL.
SET EQUATE INFO = "ABC, DEF (H+1)";
- Specify that the symbol tstlen is equated to the equivalent
of a #define for structure pointing. The current
programming language setting is C. If the programming language changes,
this lowercase symbol might not be accessible.
SET EQUATE tstlen = "struct1->member.b->c.len";
- Specify that the symbol VARVALUE is equated to the
command LIST x.
SET EQUATE VARVALUE = "LIST x";
SET EXECUTE command
Controls whether commands from all input sources are performed
or just syntax checked (primarily for checking USE files).
The initial setting is ON.
- ON
- Specifies that commands are accepted and performed.
- OFF
- Specifies that commands are accepted and parsed; however, only
the following commands are performed: END, GO, SET
EXECUTE ON, QUIT, and USE.
Example
Specify that all commands are accepted and performed.
SET EXECUTE ON;
SET FIND BOUNDS command
Specifies the default left and right columns for a FIND command
in the Source window and in line mode that does not specify any columns
information. It is ignored in the Log and Monitor windows.
- leftcolumn
- A positive integer that specifies the leftmost column for the
search. This is supported only in the Source window and in line mode.
It is ignored in the Log and Monitor windows.
- rightcolumn
- A positive integer that specifies the rightmost column for the
search. This is supported only in the Source window and in line mode.
It is ignored in the Log and Monitor windows.
- *
- Specifies that the length of each source record is used as the
right column for the search. This is supported only in the Source
window and in line mode. It is ignored in the Log and Monitor windows.
Usage notes
- If SET FIND BOUNDS has not been set, the default is
1 for leftcolumn and * for rightcolumn.
- If you enter SET FIND BOUNDS without operands, the
result is 1 for leftcolumn and * for rightcolumn.
- If you do not specify column boundaries in a FIND command
for the Source window or in line mode, the boundaries set by the SET
FIND BOUNdS command are used for the FIND command.
Example
If you want to find two different strings (paraa and variable-b)
in COBOL's Area B, first enter the following command to set the
boundaries of the search:
SET FIND BOUNDS 12 72;
Then enter
the following FIND commands to search for the two strings:
FIND paraa;
FIND variable-b;
Refer to the following topics for more information
related to the material discussed in this topic.
SET FREQUENCY command
Controls whether statement executions are counted. The initial
setting is OFF.
- ON
- Specifies that statement executions are counted.
- OFF
- Specifies that statement executions are not counted.
- cu_spec
- A valid compile unit specification. If omitted, all compile
units with statement information are processed.
Usage notes
- In the disassembly view, SET FREQUENCY is not supported.
- Because the collection of frequency data can add a substantial
amount of overhead, set the SET FREQUENCY command to ON only
when you intend to make use of this data. Do not routinely set the SET
FREQUENCY command to ON in debug sessions in which
you do not intend to make use of this data.
- If the DATA option of the PLAYBACK ENABLE command
is in effect for the current compile unit, you can use the SET
FREQUENCY command while you replay recorded statements by using
the PLAYBACK commands.
Example
Specify that statement executions are counted in compile units main and subr1.
SET FREQUENCY ON (main, subr1);
Refer to the following topics for more information
related to the material discussed in this topic.
SET HISTORY command
Specifies whether entries to Debug Tool are recorded in the history
table and optionally adjusts the size of the table. The history table
contains information about the most recently processed breakpoints
and conditions. The initial setting is ON; the initial
size is 100.
- ON
- Maintains the history of invocations.
- OFF
- Suppresses the history of invocations.
- integer
- The number of entries kept in the history table.
Usage notes
- History is not collected for disassembly compile units.
Examples
- Adjust the history table size to 50 lines.
SET HISTORY 50;
- Turn off history recording.
SET HISTORY OFF;
Refer to the following topics for more information
related to the material discussed in this topic.
SET IGNORELINK command
Specifies that any new LINK level (nested enclave) is ignored while
the setting is ON. Debug Tool does not gather information or stop at the
programs in this newly created enclave. The initial setting is
OFF.
- ON
- Programs in new enclaves (links) are ignored. Debug Tool does not
stop at programs in new enclaves.
- OFF
- Programs in new enclaves (links) are not ignored. Debug Tool stops
at any breakpoint for a program in new enclaves.
Usage notes
- A new enclave is created by language constructs like EXEC LINK
or EXEC XCTL, which invoke a new main program.
- This command is valid only in CICS programs.
- You can use this command in remote debug mode.
- DTCN or CADP profiles override the setting of SET IGNORELINK.
- You can use the STEP INTO command to step into a new
enclave, which overrides the SET IGNORELINK setting. However,
this does not change the setting of SET IGNORELINK.
- If you use the STEP RETURN command, you can only return
to the parent enclave if it was not ignored by Debug Tool because at the
time it was created, the setting of SET IGNORELINK was OFF.
Otherwise, Debug Tool runs to the next breakpoint in a previous enclave
that was not ignored by Debug Tool or it runs to the end of the application.
- The DISABLE DTCN, ENABLE DTCN, DISABLE
CADP, and ENABLE CADP commands override the setting
of SET IGNORELINK. This allows you to debug the new
enclave, but does not change the setting of SET IGNORELINK.
- Breakpoints are not restored for a compile unit in a new enclave
when the SET IGNORELINK setting is ON.
- Debug Tool does not stop for any deferred entry breakpoints for a
compile unit in a new enclave when the SET IGNORELINK setting
is ON.
- Debug Tool does not stop for any breakpoint in the new enclave when
the SET IGNORELINK setting is ON.
- Conditions raised in the application are reported regardless of
the setting of SET IGNORELINK.
- You can use this command in a preferences, commands, or global
preferences file so that it is run at the beginning of every new debugging
session.
Refer to the following topics for more information
related to the material discussed in this topic.
SET INTERCEPT command (C and C++)
Intercepts input to and output from specified files. Output and
prompts for input are displayed in the log.
Only sequential I/O can be intercepted. I/O intercepts remain in
effect for the entire debug session, unless you terminate them by
entering SET INTERCEPT OFF command. The initial setting
is OFF.
- ON
- Turns on I/O interception for the specified file. Output appears
in the log, preceded by the file specifier for identification. Input
causes a prompt entry in the log, with the file specifier identified.
You can then enter input for the specified file on the command line
by using the INPUT command.
- OFF
- Turns off I/O interception for the specified file.
- FILE file_spec
- A valid fopen() file specifier including stdin, stdout,
or stderr. The FILE keyword cannot be abbreviated.
Usage notes
- Intercepted streams or files cannot be part of any C I/O redirection
during the execution of a nested enclave.
- You
cannot use the SET INTERCEPT command while you replay recorded
statements by using the PLAYBACK commands.
Examples
Turn on the I/O interception for the fopen() file specifier dd:mydd.
The current programming language setting is C.
SET INTERCEPT ON FILE dd:mydd;
Refer to the following topics for more information
related to the material discussed in this topic.
SET INTERCEPT command (COBOL, full-screen mode, line
mode, batch mode)
Intercepts input to and output from the console. Output and prompts
for input are displayed in the log.
Console I/O intercepts remain in effect for the entire debug session,
unless you terminate them by entering SET INTERCEPT OFF command.
The initial setting is OFF.
- ON
- Turns on console I/O interception. Debug Tool displays
output in the log, preceded by the CONSOLE keyword to identify the
output. Input causes a prompt entry in the log, with the CONSOLE
identified. You can then enter input for the console on the command
line by using the INPUT command.
- OFF
- Turns off console I/O interception.
- CONSOLE
- Turns I/O interception on or off for the console.
This consists
of:
- Job log output from DISPLAY UPON CONSOLE
- Screen output (and confirming input) from STOP 'literal'
- Terminal input for ACCEPT FROM CONSOLE or ACCEPT
FROM SYSIN.
Usage notes
- For CICS, SET INTERCEPT is not supported.
- You
cannot use the SET INTERCEPT command while you replay recorded
statements by using the PLAYBACK commands.
Examples
Turn on the I/O interception for the console. The current programming
language setting is COBOL.
SET INTERCEPT CONSOLE;
Refer to the following topics for more information
related to the material discussed in this topic.
SET INTERCEPT command (COBOL, remote debug mode)
Intercepts output from COBOL DISPLAY statements. Output is displayed
in the Debug Console. Output intercepts remain in effect for the entire
debug session, unless you terminate them by entering the SET
INTERCEPT OFF command. The initial setting is OFF.
- ON
- Turns on output interception. Output appears in the Debug Console.
- OFF
- Turns off output interception.
Examples
Turn on the output interception for the console.
SET INTERCEPT ON;
Refer to the following topics for more information
related to the material discussed in this topic.
SET KEYS command (full-screen mode)
Controls whether PF key definitions are displayed when the SCREEN setting
is ON. The initial setting is ON.
- ON
- Displays PF key definitions.
- OFF
- Suppresses the display of the PF key definitions.
- 12
- Shows PF1-PF12 on the screen bottom.
- 24
- Shows PF13-PF24 on the screen bottom.
Example
Specify that the display of the PF key definitions is suppressed.
SET KEYS OFF;
Refer to the following topics for more information
related to the material discussed in this topic.
SET LDD command
Controls how debug data is loaded for assemblies containing multiple
CSECTs. The initial setting is SINGLE.
- SINGLE
- Indicates that subsequent LOADDEBUGDATA (LDD)
commands that load debug data for a CU that was assembled with other
CSECTs are to load the debug data for the specified CU only.
- ALL
- Indicates that subsequent LOADDEBUGDATA (LDD)
commands that load debug data for a CU that was assembled with other
CSECTs are to load the debug data for all CUs in the assembly.
Usage notes
- This command affects both deferred and non-deferred LDD commands.
- If the target of the LDD is a non-Language Environment COBOL
CU, the command has no effect.
- If SET LDD ALL is in effect and you do the following
tasks, you must enter a separate SET SOURCE command for
each CU in the assembly for which you previously entered an LDD command:
- You enter an LDD command for more than one CU in the
same assembly.
- The debug data could not be found for these CUs.
- Subsequently, you enter a SET SOURCE command for one
of these CUs.
- You can use this command in remote debug mode.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
SET LIST TABULAR command
Controls whether to format the output of the LIST command
in a tabular format. The default setting is OFF.
- ON
- Display the output of the LIST command in tabular
format.
- OFF
- Display the output of the LIST command in linear
format. This is the default setting.
SET LOG command
Controls whether each performed command and the resulting output
is written to the log file and defines (or redefines) the file that
is used. The initial setting is ON FILE INSPLOG. This
is a valid DD name in z/OS.

- ON
- Specifies that commands and output are written to the log file.
- FILE fileid
- Identifies the log file used. The FILE keyword cannot
be abbreviated.
In non-CICS, fileid is a DD name
or a fully-qualified data set name. Partitioned data sets cannot be
used.
In CICS, fileid is a fully-qualified
data set name.
If fileid has the form of a DD name, Debug Tool checks
to see if the file is allocated.
In full-screen mode, the log
file should not be allocated to the 3270 terminal
device.
- OLD
- Specifies that the new information is to replace any existing
information in the specified file. This operand is ignored if fileid specifies
a DD name.
- MOD
- Specifies that the new information is appended after any existing
information in the specified file. This operand is ignored if fileid specifies
a DD name.
- KEEP count
- Specifies the number of lines of log output retained for display.
The initial setting is 1000; count cannot equal zero (0).
- OFF
- Specifies that commands and output are not written to a log
file.
Usage notes
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
SET LOG NUMBERS command (full-screen mode)
Controls whether line numbers are shown in the log window. The
initial setting is ON.
- ON
- Shows line numbers in the log window.
- OFF
- Suppresses line numbers in the log window.
Example
Specify that log line numbers are not shown.
SET LOG NUMBERS OFF;
SET LONGCUNAME command
Controls whether a short or long CU name is displayed.
- ON
- Specifies that a long CU name is displayed.
- OFF
- Specifies that a short CU name is displayed. The short CU name
is displayed in the session panel header, source window header area,
and the Source Identification Panel.
Usage notes
- You can enter the SET LONGCUNAME at any time, but it
applies only to C, C++, and Enterprise PL/I programs. If you compiled your
program with one of the following compilers and it is running in the
following environment, this command has no effect.
- Enterprise PL/I for z/OS, Version 3.6 or later
- Enterprise PL/I for z/OS, Version 3.5, compiler with the
PTFs for APARs PK35230 and PK35489 applied
- Language Environment Version 1.6 through 1.8 with the PTF for APAR PK33738
applied, or later
- The CU name for programs compiled with C, C++, or Enterprise PL/I (before Enterprise PL/I for z/OS,
Version 3.6) compilers can have one of the following forms:
- Fully qualified partitioned data set name and member name
- A sequential file name
- A HFS path and file name
These forms can result in long CU names that are truncated
in the session panel header, which makes it difficult for you to identify
the CU.
For these forms of compile unit names, Debug Tool displays
short names in one of the following manners:
- For PDS file names, the short name is only the member name
- For sequential file names, the short name is the lowest level
qualifier (name segment)
- For HFS file names, the short name is the file name, without path
name
- Debug Tool commands affected by the LONGCUNAME setting: QUERY
LOCATION, SET SOURCE, and AT ENTRY. All
the other commands continue to require the long form of the CU name.
For example, if you use the short name with the AT command
(AT ARRAY3 ::> 'ARRAY3' :> 10), Debug Tool displays an error
message and does not set the breakpoint. However, if you enter the
command AT ENTRY ARRAY3 ::> 'ARRAY3' :>ARRAY3, Debug Tool sets
the breakpoint or defers setting the breakpoint until the entry point
is known to Debug Tool.
- You cannot use the SET LONGCUNAME command in remote debug mode.
Examples
- If the CU name is SMITH.TEST.SRC(ARRAY3), the short
name is ARRAY3.
- If the CU name is SMITH.TEST.SOURCE.ABCD, the short
name is ABCD.
- If the CU name is /testenvir/applications/cicsprograms/project1/prog2.cpp,
the short name is prog2.cpp.
SET MONITOR command
Controls the format and layout of variable names and values displayed
in the Monitor window.

- COLUMN
- Controls whether to display the output in the Monitor window
in column format. The initial setting is SET MONITOR COLUMN ON. SET
MONITOR COLUMN is accepted in batch mode, but has no effect.
- DATATYPE
- Controls whether to display the data type of the variable in
the Monitor window. The initial setting is SET MONITOR DATATYPE
OFF.
- NUMBERS (full-screen mode)
- Controls whether to display line numbers in the Monitor window.
The initial setting is SET MONITOR NUMBERS ON.
- WRAP
- Controls whether to wrap the output in the Monitor window.
The initial setting is SET MONITOR WRAP ON. SET MONITOR
WRAP is accepted in batch mode, but has no effect.
- ON
- Sets the corresponding switch to the following values:
- COLUMN
- Display the Monitor window output in column-aligned format.
- DATATYPE
- Display the data type attribute for variables in the Monitor
window.
- NUMBERS
- Display line numbers in the Monitor window.
- WRAP
- Wraps the monitor value area variable in the monitor window.
- OFF
- Sets the corresponding switch to the following values:
- COLUMN
- Display the Monitor window output in non-column-aligned
format.
- DATATYPE
- Do not display the data type attribute for variables in the
Monitor window.
- NUMBERS
- Do not display line numbers in the Monitor window.
- WRAP
- Display the variable name and value on the same line in the
monitor window. If any values are too long to display in the Monitor
window, then the area becomes scrollable.
Usage notes
If you enter the SET MONITOR WRAP OFF command while
the SET MONITOR COLUMN switch is set to OFF,
the command is rejected because Debug Tool can only display values in
one scrollable line when the setting of MONITOR COLUMN
is ON. You must first enter the SET MONITOR COLUMN
ON command.
If you enter the SET MONITOR COLUMN OFF command while
the SET MONITOR WRAP switch is set to OFF,
the command is rejected. The Monitor window must be in columnar format
to be able to display values in one scrollable line. You must first
enter the SET MONITOR WRAP ON command.
Example
- Enter the following command to specify that you do not want line
numbers displayed in the Monitor window:
SET MONITOR NUMBERS OFF;
- Enter the following command to specify that you do not want variable
values to wrap to the next line:
SET MONITOR WRAP OFF;
SET MSGID command
Controls whether the Debug Tool messages are displayed with the message
prefix identifiers. The initial setting is OFF.
- ON
- Displays message identifiers. The first 7 characters of the
message contain the EQAnnnn message prefix identifier, then a blank,
then the original message text, such as: 'EQA2222 Program does
not exist.'
- OFF
- Displays only the message text.
Example
Specify that message identifiers are suppressed.
SET MSGID OFF;
SET NATIONAL LANGUAGE command
Switches your application to a different run-time national language
that determines what translation is used when a message is displayed.
The switch is effective for the entire run-time environment; it is
not restricted to Debug Tool activity only. The initial setting is supplied
by Language Environment or the NATLANG Debug Tool run-time option, according
to the setting in the current enclave.

- language_code
- A valid three-letter set that identifies the language used or
(for compatibility) one of the two-letter language codes that was
accepted in the previous release of INSPECT for C/370™ and
PL/I. The language code can have one of the following values:
- United States English: ENU
- United States English (Uppercase): UEN
- Japanese: JPN
- Korean: KOR
- If you enter the SET DBCS ON command and then you set
the national language to ENU, Debug Tool resets the national language
to UEN to remain compatible with DBCS characters.
For compatibility with the previous release of INSPECT for C/370 and
PL/I:
- EN or ENGLISH is mapped to ENU
- UE or UENGLISH is mapped to UEN
- JA, JAPANESE, NI, or NIHONGO is
mapped to JPN
Usage notes
- In order to display DBCS characters correctly in full-screen mode,
the high order bit of the Language field in the VTAM® Attribute
Byte that must be set ON. To verify that this bit is set ON:
- In ISPF, select option 0 (Settings).
- On the command line, enter: environ.
- Tab to the section Terminal Status (TERMSTAT). In the Enable field,
enter 2 (Query terminal information).
- Several pages of statistics appear. In the section GTTERM Information,
note the value of the highest bit in the second byte of the field
Attribute Byte. The value of this bit must be 1 (ON). For example,
if the value of the Attribute Byte field is x'008000C9',
then DBCS characters display correctly because the second byte is X'80'.
However, if the value of the Attribute Byte field is x'000000C9',
DBCS characters are not displayed properly. Contact the VTAM System
Administrator to set the high order bit of the Language Field of the VTAM Attribute
Byte to 1 (ON).
- The language you select by using the SET NATIONAL LANGUAGE command
affects both your application and Debug Tool.
- At the beginning of an enclave, the settings are those provided
by Language Environment, your operating system, or the NATLANG Debug Tool run-time
option. For nested enclaves, the parent’s settings are restored
upon return from a child enclave.
- If NATIONAL LANGUAGE is set to JPN or KOR and
you are using full-screen mode, enter the SET DBCS ON command
so that Debug Tool displays messages correctly.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
SET PACE command
Specifies the maximum pace of animated execution, in steps per
second. The initial setting is two steps per second. This setting
is not supported in batch mode.
- number
- A decimal number between 0 and 9999; it must be a multiple of
0.5.
Usage notes
- If you are debugging a CICS program, choose your pace carefully.
After animated execution begins, you might not be able to stop it.
See the Debug Tool User’s Guide for information about requesting an
attention interrupt during interactive sessions.
- Associated with the SET PACE command is the STEP command.
Animated execution is achieved by defining a PACE and
then issuing a STEP n command where n is the
number of steps to be seen in animated mode. STEP * can
be used to see all steps to the next breakpoint in animated mode.
- When PACE is set to 0, no animation occurs.
Example
Set the animated execution pace to 1.5 steps per second.
SET PACE 1.5;
SET PFKEY command
Associates a Debug Tool command with a Program Function key (PF key).
This setting is not supported in batch mode.
- PFn
- A valid program function key specification (PF1 - PF24).
- string
- The label shown in the PF key display (if the KEYS setting
is ON) that is entered as a string constant. The string
is truncated if longer than eight characters. If the string is omitted,
the first eight characters of the command are displayed. For C
and C++, the string must be surrounded by quotation marks (").
For COBOL, PL/I, assembler, and disassembly, the string can be surrounded
by either quotation marks (") or apostrophes (').
- command
- A valid Debug Tool command or partial command.
Usage notes
Example
Define the PF5 key to scroll the cursor-selected window forward.
- If the programming language setting is COBOL:
SET PF5 "Down" = IMMEDIATE SCROLL DOWN;
- If the programming language setting is PL/I:
SET PF5 'Down' = IMMEDIATE SCROLL DOWN;
- If the programming language setting is C++:
SET PF5 "Down" = IMMEDIATE SCROLL DOWN;
In all cases, the setting for PF17 remains
the same.
SET PROGRAMMING LANGUAGE command
Sets the current programming language. You can only set the current
programming language to the selection of languages of the programs
currently loaded. For example, if the current load module contains
both C and COBOL compile units, but not PL/I, you can set the language
only to C or COBOL. However, if you later STEP or GO into
another load module that contains C, COBOL, and PL/I compile units,
you can set the language to any of the three.
The programming language setting affects the parsing of incoming Debug Tool commands.
The execution of a command is always consistent with the current
programming language setting that was in effect when the command was
parsed. The programming language setting at execution time is ignored.

- CYCLE
- Specifies that the programming language is set to the next language
in the alphabetic sequence of supported languages.
- AUTOMATIC
- Cancels a HOLD by specifying that the programming
language is set according to the current qualification and thereafter
changed automatically each time the qualification changes or STEP or GO is
issued.
- HOLD
- Specifies that the given language (or the current language,
if no language is specified) remains in effect regardless of qualification
changes. The language remains in effect until SET PROGRAMMING
LANGUAGE changes the language or releases the hold.
- ASSEMBLER
- Sets the current programming language to ASSEMBLER.
- C
- Sets the current programming language to C. Debug Tool does not
differentiate between C and C++, use this option for C++ as well
as C programs.
- COBOL
- Sets the current programming language to COBOL.
- DISASSEMBLY
- Sets the current programming language to disassembly.
- NONLECOBOL
- Sets the current programming language to non-Language Environment COBOL.
- PLI
- Sets the current programming language to PL/I.
Usage notes
- If CYCLE or one of the explicit programming language
names is specified, the current programming language setting is changed
regardless of the currently suspended program or the current qualification.
- The current programming language setting affects how commands
are parsed, not how they are performed. Commands are always performed
according to the programming language setting where they were parsed.
For example, it is not possible for a Debug Tool procedure to contain
a mixture of C and COBOL commands; there is no way for the programming
language setting to be changed while the procedure is being parsed.
Also, it is not possible for a command parsed with one programming
language setting to reference variables, types, or labels in another
programming language.
- If SET PROGRAMMING LANGUAGE AUTOMATIC is in effect
(that is, HOLD is not in effect), changing the qualification
automatically sets the current programming language to the specified
block or compile unit.
- SET PROGRAMMING LANGUAGE can be used to set the programming
language to any supported language in the current or parent enclaves.
Example
Specify that C or C++ is the current programming language.
SET PROGRAMMING LANGUAGE C;
SET PROMPT command (full-screen mode)
Controls whether the current program location is automatically
shown as part of the prompt message in line mode. It has no effect
in full-screen mode, because the current location is always shown
in the panel header in that case. The initial setting is LONG.
- LONG
- Uses long form of prompt message.
- SHORT
- Uses short form of prompt message.
Example
Specify that the long form of prompt message is used.
SET PROMPT LONG;
SET QUALIFY command
Simplifies the identification of references and statement numbers
by resetting the point of view to a new block, compile unit, or load
module. In full-screen mode this affects the contents of the Source
window. If you are currently viewing one compile unit in your Source
window and you want to view another, enter the SET QUALIFY command
to change the qualification. The SET keyword is optional.
The QUALIFY keyword can be abbreviated.

- BLOCK
- Sets the current point of view to the specified block.
- block_spec
- A valid block specification.
- CU
- Sets the current point of view to the specified compile unit. CU is
equivalent to PROGRAM.
- cu_spec
- A valid compile unit specification.
- PROGRAM
- Is equivalent to CU.
- LOAD
- Sets the current point of view to the specified load module.
- load_spec
- A valid load module specification. If omitted, the initial
(primary) load module qualification is used.
- RESET
- Resets qualification to the block of the suspended program and
(if the SCREEN setting is ON) scrolls the source
window to display the current statement line.
- RETURN
- Switches qualification to the next higher calling program.
- UP
- Switches qualification up one lexical level to the statically
containing block.
Usage notes
- If SET PROGRAMMING LANGUAGE AUTOMATIC is in effect
(that is, HOLD is not in effect), changing the qualification
automatically sets the current programming language to the specified
block or compile unit.
- If you are debugging a program that has multiple enclaves, you
can issue the SET QUALIFY command only for the following
items:
- Load modules, compile units, and blocks that are known to Debug
Tool and are in the current enclave
- Load modules, compile units, and blocks that are not known to
Debug Tool
- Non-Language Environment assembler compile units in a higher-level enclave
You cannot issue the SET QUALIFY command for a load
module that is part of a higher-level enclave. You cannot issue
the SET QUALIFY command for compile units in a higher-level
enclave unless the compile unit is non-Language Environment.
- The SET QUALIFY command does not imply a change in
flow of control when the program is resumed with the GO command.
- The SET QUALIFY command cannot modify the point of
view to a Debug Tool or library block.
- SET QUALIFY LOAD will not change the results of the QUERY
QUALIFY command.
- If you specify cu_spec as a CU name without a load module
name, Debug Tool searches for the CU in the following order:
- CUs in the currently qualified load module.
- All known CUs.
- A CU by the specified name in a load module of the same name.
- If you enter the SET QUALIFY LOAD command or SET
QUALIFY CU command and specify the name of a load module that
is not currently known to Debug Tool, Debug Tool runs an implicit LOAD command
for the load module. If the implicit LOAD is successful, implicit
CUs are created for the following types of programs:
- All CUs in the load module except COBOL and disassembly CUs
- If SET DISASSEMBLY ON is in effect, disassembly CUs
- If the entry point of the load module is a disassembly program,
regardless of the setting of SET DISASSEMBLY.
With implicit CUs, you can do debugging tasks such as setting
breakpoints and browsing the source of the CU. When you run the program
by entering a command such as GO or STEP, the
implicitly loaded modules are deleted, any breakpoints created in
the implicitly created CUs are suspended, and all implicitly created
CUs are destroyed. If the CU is later created during normal program
execution, the suspended breakpoints are reactivated.
- You cannot use the SET QUALIFY LOAD or SET QUALIFY
CU command to implicitly load a DLL.
- If you enter a SET QUALIFY CU command that specifies
the name of a COBOL CU that has not yet been created because the CU
has not been run, Debug Tool creates an implicit CU. With implicit
CUs, you can do debugging tasks such as setting breakpoints and browsing
the source of the CU. When you run the program by entering a command
such as GO or STEP, any breakpoints created
in the implicitly created CUs are suspended and all implicitly created
CUs are destroyed. If the CU is later created during normal program
execution, the suspended breakpoints are reactivated.
- In order use the SET QUALIFY LOAD or SET QUALIFY
CU commands to create implicit CUs for a COBOL program, the
PTF for Language Environment APAR PK30521
must be installed on z/OS Version 1 Release 6, Version
1 Release 7, and Version 1 Release 8.
- If you stop in an enclave where Language Environment is not yet active, you
cannot use SET QUALIFY LOAD or SET QUALIFY CU commands
to load a Language Environment load module or to create a Language Environment compile unit.
You can only use these commands to load a Language Environment load module or
create a Language Environment compile unit after Language Environment has been initialized
in the current enclave.
- You can use the SET QUALIFY CU and SET QUALIFY
LOAD commands in remote debug mode.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
SET REFRESH command (full-screen mode)
Controls screen refreshing. This command is only valid when in
full-screen mode, that is the SET SCREEN setting is ON.
The initial setting for REFRESH is OFF.
- ON
- Clears the screen before each rewrite. This is a required setting
if your application handles line mode I/O.
- OFF
- Rewrites without clear.
Usage
note
SET REFRESH ON is needed for applications that also
make use of the screen; for example, applications using ISPF services
to display panels.
Example
Specify that rewrites only occur on those portions of the screen
that have changed. The screen is not cleared before being rewritten.
SET REFRESH OFF;
SET RESTORE command
Controls the restoring of settings, breakpoints, and monitor specifications.

- SETTINGS
- Indicates that SET values and WINDOW SIZE and WINDOW CLOSE
settings are to be restored. The following SET values are not restored:
- SET DBCS
- SET FREQUENCY
- SET NATIONAL LANGUAGE
- SET PROGRAMMING LANGUAGE
- FILE operand of SET RESTORE SETTINGS
- SET QUALIFY
- SET SOURCE
- SET TEST
- BPS
- Indicates that breakpoints and LOADDEBUGDATA (LDD) specifications
are to be restored. The following breakpoints are restored:
- APPEARANCE breakpoints
- CALL breakpoints
- DELETE breakpoints
- ENTRY breakpoints
- EXIT breakpoints
- GLOBAL APPEARANCE breakpoints
- GLOBALCALL breakpoints
- GLOBAL DELETE breakpoints
- GLOBAL ENTRY breakpoints
- GLOBAL EXIT breakpoints
- GLOBAL LABEL breakpoints
- GLOBAL LOAD breakpoints
- GLOBAL STATEMENT and GLOBAL LINE breakpoints
- LABEL breakpoints
- LOAD breakpoints
- OCCURRENCE breakpoints
- STATEMENT and LINE breakpoints
- TERMINATION breakpoint
- MONITORS
- Indicates that monitor and LOADDEBUGDATA (LDD) specifications
are to be restored.
- NOAUTO
- Indicates that the specified data is not to be restored automatically
at Debug Tool startup. It will be restored only when you explicitly request
it by entering the RESTORE command. NOAUTO is the default until AUTO
is specified.
- AUTO
- Indicates that, if possible, the specified data set is to be
automatically restored by Debug Tool at startup.
Usage notes
SET REWRITE command (full-screen mode)
Forces a periodic screen rewrite during long sequences of output.
- number
- Specifies how many lines of intercepted output are written by
the application program before Debug Tool refreshes the screen. The initial
setting is 50.
Examples
Force screen rewrite after each 100 lines of screen output.
SET REWRITE EVERY 100;
SET REWRITE command (remote debug mode)
Sets the maximum number of COBOL DISPLAY statements that the remote
debugger displays in the Debug Console.
- number
- Specifies the maximum number of COBOL DISPLAY statements that
the remote debugger displays in the Debug Console. The initial setting
is 50.
Usage
note
If the remote debugger needs to display more than number,
the remote debugger begins to delete the oldest DISPLAY statements
so that it can display the newest DISPLAY statements.
Examples
Set the maximum number of COBOL DISPLAY statements to display to
100:
SET REWRITE 100;
SET SAVE command
Controls the saving of settings, breakpoints, and monitor specifications.

- SETTINGS
- Indicates that SET values and WINDOW SIZE and WINDOW CLOSE
settings are to be saved. The following SET values are not saved:
- SET DBCS
- SET FREQUENCY
- SET NATIONAL LANGUAGE
- SET PROGRAMMING LANGUAGE
- FILE operand of SET RESTORE SETTINGS
- SET QUALIFY
- SET SOURCE
- SET TEST
- BPS
- Indicates that breakpoints and LOADDEBUGDATA (LDD) specifications
are to be saved. The following breakpoints are saved:
- APPEARANCE breakpoints
- CALL breakpoints
- DELETE breakpoints
- ENTRY breakpoints
- EXIT breakpoints
- GLOBAL APPEARANCE breakpoints
- GLOBALCALL breakpoints
- GLOBAL DELETE breakpoints
- GLOBAL ENTRY breakpoints
- GLOBAL EXIT breakpoints
- GLOBAL LABEL breakpoints
- GLOBAL LOAD breakpoints
- GLOBAL STATEMENT and GLOBAL LINE breakpoints
- LABEL breakpoints
- LOAD breakpoints
- OCCURRENCE breakpoints
- STATEMENT and LINE breakpoints
- TERMINATION breakpoint
- MONITORS
- Indicates that all monitor and LOADDEBUGDATA (LDD)
specifications are to be saved.
- NOAUTO
- Indicates that at Debug Tool termination, the specified settings,
breakpoint, or specifications are not to be saved. NOAUTO is the default
until AUTO is specified.
- AUTO
- Indicates that, if possible, the specified data is to be saved
at Debug Tool termination.
- ONCE
- Indicates that the settings information is to be saved once.
The settings information is saved at the termination of the current
debugging session but the saved value for SET SAVE SETTINGS is NOAUTO.
This enables you save the settings of the current debugging session
and not have the settings updated at the termination of subsequent
debug sessions.
- *
- Indicates that the default file name is to be used to save settings,
breakpoints, and monitor specifications at termination. The default
name is userid.DBGTOOL.SAVESETS for settings and userid.DBGTOOL.SAVEBPS for
breakpoints and monitor specifications. You can modify the default
names by using EQAOPTS.
- FILE setfileid
- Indicates the data set name to be used to save and restore settings. The
data set must exist before running this command.
In z/OS, setfileid is
a DD name, a fully-qualified data set name (without apostrophes (')),
or an HFS path and file name. In CICS, setfileid is
a fully-qualified data set name or an HFS path and file name.
If setfileid is
less than nine characters in length and does not contain a period, Debug Tool assumes
it is a DD name. Otherwise, it is assumed to be a fully-qualified
data set name.
In batch mode, the data set name is ignored.
Use the INSPSAFE DD statement to indicate the name of the data set
to use to restore and save settings.
This data set must be a
sequential data set with a record format (RECFM) of VB and with a
record length (LRECL) greater than or equal to 3204.
- FILE bpfileid
- Indicates the data set to be used to save breakpoints and monitor
specifications. The data set must exist before running this command.
In z/OS, bpfileid is
a DD name, a fully-qualified data set name (without apostrophes (')),
or an HFS path and file name. In CICS, bpfileid is
a fully-qualified data set name or an HFS path and file name.
If bpfileid is
less than nine characters in length and does not contain a period, Debug Tool assumes
it is a DD name. Otherwise, it is assumed to be a fully-qualified
data set name.
In batch mode, the data set name is ignored.
Use the INSPBPM DD statement to indicate the name of the data set
to use to save breakpoints and monitor specifications.
This
data set must be a PDS or PDSE (a PDSE is recommended) and you cannot
specify a member name. This data set must have a record format (RECFM)
of VB and with a record length (LRECL) greater than or equal to 3204.
Debug Tool assigns a member name that is the load module name at enclave
start. The breakpoints for each enclave are saved in a separate member
of the PDS or PDSE. If you want to discard any saved breakpoints,
LDD specifications, and monitor specifications, you can delete the
member that has the name of the load module that started the enclave.
Do not alter the contents of the member.
Usage notes
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
SET SCREEN command (full-screen mode)
Controls how information is displayed on the screen. The initial
setting is ON.
- CYCLE
- Switches to the next window configuration in sequence.
- integer
- An integer in the range 1 to 6, selecting the window configuration.
The initial setting is 1.
- LOG or MONITOR or SOURCE or MEMORY
- Specifies the sequence of window assignments within the selected
configuration (left to right, top to bottom). There must be no more
than three objects specified and they must all be different. You cannot
specify both MEMORY and LOG in the same sequence.
- ON
- Activates the Debug Tool full-screen services.
- OFF
- Activates line mode. This mode is forced if the terminal is
not a supported full-screen device.
Usage notes
- If neither CYCLE nor integer is specified,
there is no change in the choice of configuration. If no windows
are specified, there is no change in the assignment of windows to
the configuration.
- If SET SCREEN OFF is entered while debugging in full-screen
mode using a VTAM terminal under TSO, the session enters line
mode using the TSO terminal. If SET SCREEN ON is later
entered from the TSO terminal, control reverts to full-screen mode
using a VTAM terminal.
- SET SCREEN OFF is ignored in CICS full-screen
mode and in z/OS batch while debugging in full-screen mode
using a VTAM terminal.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
SET SCROLL DISPLAY command (full-screen mode)
Controls whether the scroll field is displayed when operating in
full-screen mode. The initial setting is ON.
- ON
- Displays scroll field.
- OFF
- Suppresses scroll field.
Example
Specify that the scroll field is suppressed.
SET SCROLL DISPLAY OFF;
SET SEQUENCE command (PL/I)
Controls whether Debug Tool interprets data after column 72 in a commands
or preference file as a sequence number.
- ON
- Allows sequence numbers in 73-80 columns in the commands or
preferences file.
- OFF
- Does not allow sequence numbers in the commands or preferences
file.
Usage
note
If you have sequence numbers placed in 73-80 columns, you have
to enter the SET SEQUENCE ON command as the first command
of your commands or preferences file. Afterward, Debug Tool processes
1-72 columns and ignores everything after column 72.
SET SOURCE command
Associates a source file, compiler listing or separate debug file
with one or more compile units and specifies whether the source file
or listing is displayed when the compile unit is active.

- ON
- Displays the source or listing for a compile unit when the compile
unit is active.
- OFF
- Specifies that the file is not displayed.
- cu_spec
- A valid compile unit specification. Multiple compile units
can be associated with the same source, listing or separate debug file.
- fileid
- Identifies the source, listing or separate debug file to be used for
the compile unit. The file that you specify must be of fixed block
format. You cannot specify concatenated data sets.
In z/OS, fileid is
a DD name, a fully qualified partitioned data set and member name,
a sequential file, or an HFS path and file name.
In CICS, fileid is
a fully-qualified data set name or an HFS path and file name.
If fileid is
less than nine characters in length and does not contain a period, Debug Tool assumes
it is a DD name. Debug Tool checks to see if it is allocated. If it is
not allocated, then fileid is assumed to be a data set name.
Fileid specifies
a file identifier used in place of the default file identifier for
the compile unit. A valid fileid is required unless it is
already known to Debug Tool (by using a previous SET SOURCE command)
or the default fileid is valid.
Fileid can
not be a DD name if the data set allocated to it is C, C++ or Enterprise
PL/I source and the EQAOPTS SUBSYS=ssss option is being used
to access a source file in a library system.
Usage notes
- If you compiled your C or C++ program with the FORMAT(DWARF) suboption
of the DEBUG compiler option, you cannot use the SET
SOURCE command to specify the new location of the .dbg file. Use
the EQADEBUG DD statement or an EQAUEDAT user exit to specify the
new location of the file.
- When SET SOURCE is issued for the currently executing
compile unit, a test is performed for the existence of the file. If
the compile unit is not the current compile
unit, this test is not performed until the compile unit becomes current.
The file associated with the source might not exist and the error
message for the nonexistent file does not appear until a function
that requires this file is attempted.
- When you specify a cu_spec that identifies a compile
unit that is not currently known to Debug Tool, Debug Tool looks for a deferred LOADDEBUGDATA command
with the specific cu_spec. If Debug Tool finds such a deferred LOADDEBUGDATA command, Debug Tool associates
the fileid with the deferred LOADDEBUGDATA command.
When the compile unit appears and is activated, Debug Tool loads the
EQALANGX data from the specified file.
- The SET SOURCE ON command has a higher precedence than
the SET DEFAULT LISTINGS command.
- For COBOL, if the cu_spec includes any names that
are case sensitive, enclose the name in quotation marks (") or
apostrophes (').
- The SET SOURCE command has no effect on a disassembly
compile unit. However, it is saved and might apply later if the compile
unit is specified as the operand of the LOADDEBUGDATA command.
- If the file name does not fit on one line, suffix it with a trailing
hyphen.
Examples
- Indicate that the COBOL listing associated with compile unit prog1 is
found in DD name mainprog. In a TSO session, allocate the
listing data set:
ALLOCATE FI(MAINPROG) DA('JSMITH.COBOL.LISTING(PROG1)') SHR Start Debug Tool and
issue:
SET SOURCE ON (prog1) mainprog;
When prog1 is
made current during the debug session, Debug Tool searches for the listing
in JSMITH.COBOL.LISTING(PROG1).
- Indicate that the COBOL listing associated with compile unit prog1 is
found in DD name mainprog. In a TSO session:
SET SOURCE ON (prog1) JSMITH.COBOL.LISTING(PROG1)
This
accomplishes the same result as the previous example without the execution
of the ALLOCATE command.
- Indicate that the source associated with compile unit "/u/userid/code/oefun.c" is
found in the HFS under the path and file name "/u/userid/code/oefun.c".
SET SOURCE ON ("/u/userid/code/oefun.c") /u/userid/code/oefun.c;
- Indicate that the PL/I listing file associated with compile unit AVER is
found in MYID.PLI.LISTING(AVER)
SET SOURCE ON (AVER) myid.pli.listing(AVER) ;
- Indicate that the C source associated with compile unit JSMITH.C.SOURCE(myprog) is
found in the PDS and member CODE.CLIB.SOURCE(myprog).
SET SOURCE ON ("JSMITH.C.SOURCE(myprog)") CODE.CLIB.SOURCE(myprog)
- Enter the SET LONGCUNAME OFF command to indicate that
you want to use short CU names, then indicate that the C source associated
with compile unit JSMITH.C.SOURCE(myprog) is found in the
PDS and member CODE.CLIB.SOURCE(myprog):
SET LONGCUNAME OFF;
SET SOURCE ON (myprog) CODE.CLIB.SOURCE(myprog)
- A PL/I program is compiled with a version of the Enterprise PL/I compiler
that is earlier than Enterprise PL/I for z/OS, Version
3.5 with the PTFs for APARs PK35230 and PK35489 applied. Indicate
that the PL/I source associated with compile unit JSMITH.PLI.SOURCE(myprog) is
found in the PDS and member CODE.PLILIB.SOURCE(myprog):
SET LONGCUNAME OFF;
SET SOURCE ON (myprog) CODE.PLILIB.SOURCE(myprog)
- A PL/I program is compiled with one of the following compilers
and it is running in the following environment:
- Enterprise PL/I for z/OS, Version 3.6 or later
- Enterprise PL/I for z/OS, Version 3.5, compiler with the
PTFs for APARs PK35230 and PK35489 applied
- Language Environment Version 1.6 through 1.8 with the PTF for APAR PK33738
applied, or later
Indicate that the PL/I source associated with compile unit JSMITH.PLI.SOURCE(myprog) is
found in the PDS and member CODE.PLILIB.SOURCE(myprog):
SET SOURCE ON (myprog) CODE.PLILIB.SOURCE(myprog)
Refer to the following topics for more information
related to the material discussed in this topic.
SET SUFFIX command (full-screen mode)
Controls the display of frequency counts at the right edge of the
Source window when in full-screen mode. The initial setting is ON.
- ON
- Displays the suffix column.
- OFF
- Suppresses the suffix column.
Example
Specify that the suffix column is displayed.
SET SUFFIX ON;
SET TEST command
Overrides the initial TEST run-time options specified
at invocation. The initial setting is ALL.

- test_level
- Specifies what exception conditions cause Debug Tool to gain control,
even though no breakpoint exists. The parentheses are optional.
Test_level can
include the following:
- ALL
- Specifies that Debug Tool gains control when any of the following
conditions occur:
- An attention interrupt occurs.
- A Language Environment enclave is abnormally terminated or there is an MVS or CICS ABEND
when a program is running without the Language Environment run time.
- Language Environment terminates normally due to a COBOL STOP RUN, PL/I STOP,
or EXEC CICS RETURN.
- Language Environment raises a condition of severity 1 or above. If the FINISH,
CEE066 or CEE067 thread termination condition is raised by Language Environment and
the THREADTERMCOND option in the EQAOPTS option file is
specified, Debug Tool does not gain control. Contact your system administrator
to determine if this option was specified.
If a condition occurs and a breakpoint exists for the condition, Debug Tool runs
the commands specified in the breakpoint. If a condition occurs and
a breakpoint does not exist for that condition, or if an attention
interrupt occurs, Debug Tool does one of the following options:
- In interactive mode, Debug Tool reads commands from a commands file
(if it exists) or prompts you for commands.
- In noninteractive mode, Debug Tool reads commands from the commands
file.
- ERROR
- Specifies that only the following conditions cause Debug Tool to
gain control without a user-defined breakpoint.
- An MVS or CICS ABEND that occurs when you are
running without the Language Environment run time
- For C:
- An attention interrupt
- A predefined Language Environment condition of Severity 2 or above
- Any C condition other than SIGUSR1, SIGUSR2, SIGINT or SIGTERM.
- For COBOL:
- An attention interrupt
- A predefined Language Environment condition of Severity 2 or above.
- For PL/I:
- An attention interrupt, directed at either PL/I or Debug Tool
- A predefined Language Environment condition of Severity 2 or above.
If a breakpoint exists for one of the above conditions, any
commands specified in the breakpoint are executed. If no commands
are specified, Debug Tool reads commands from a commands file or prompts
you for commands in interactive mode.
- NONE
- Specifies that Debug Tool gains control only at an attention interrupt,
or at a condition if a breakpoint is defined for that condition.
If a breakpoint does exist for the condition, the commands specified
in the breakpoint are executed.
Usage
note
If the THREADTERMCOND option in the EQAOPTS file is set to prevent Debug Tool from
stopping when a FINISH, CEE066, or CEE067 thread termination condition
is raised by Language Environment, Debug Tool does not gain control when these conditions
are raised. If you want Debug Tool to gain control when these conditions
are raised, you can set an AT OCCURRENCE breakpoint or change the
THREADTERMCOND option to allow Debug Tool to gain control.
Examples
- Indicate that only an attention interrupt or exception causes Debug Tool to
gain control when no breakpoint exists.
SET TEST ERROR;
- Indicate that no condition causes Debug Tool to gain control unless
a breakpoint exists for that condition.
SET TEST NONE;
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- Debug Tool User’s Guide
- Related references
- AT OCCURRENCE command
- z/OS Language Environment Debugging Guide
SET WARNING command (C, C++, COBOL, and PL/I)
Controls display of the Debug Tool warning messages and whether exceptions
are reflected to the C, C++, and PL/I programs. For COBOL programs,
controls the ability to modify variables while you debug optimized
code. The initial setting is ON.
- ON
- Displays the Debug Tool warning messages, and conditions such as
a divide check result in a diagnostic message. For COBOL programs,
prohibits the modification of variables while you debug optimized
programs.
- OFF
- Suppresses the Debug Tool warning messages, and conditions raise
an exception in the program. For COBOL programs, allows the modification
of variables while you debug optimized programs.
Exceptions that occur due to interaction with you are likely to
be due to typing errors and are probably not intended to be passed
to the application program. However, you might want to raise a real
exception in the program, for example, to test some error recovery
code. (TRIGGER is not always appropriate for this because
it does not set up the exception information.)
Usage notes
- You can use this command in remote debug mode.
- Debug Tool detects C conditions such as the following:
- Division by zero
- Array subscript out of bounds for defined arrays
- Assignment of an integer value to a variable of enumeration data
type where the integer value does not correspond to an integer value
of one of the enumeration constants of the enumeration data type.
- Debug Tool detects the following PL/I computational conditions:
- Invalid decimal data
- CHARACTER to BIT conversion errors
- Division by zero
- Invalid length in varying strings
-
You
can modify variables in an optimized program that was compiled with
one the following compilers:
- Enterprise COBOL for z/OS, Version 4.1
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 2 or later
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR PQ63235 installed
- COBOL for OS/390 & VM, Version 2 Release 2
- COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ63234 installed
However, results might be unpredictable. To obtain more predictable
results, compile your program with Enterprise COBOL for z/OS,
Version 4.1, and specify the EJPD suboption of the TEST compiler
option. However, variables that are declared with the VALUE clause
to initialize them cannot be modified.
- When Debug Tool evaluates a conditional expression (for example, the condition of
the WHEN clause of the AT CHANGE command) and
the conditional expression is invalid, then Debug Tool does one of the
following actions:
- If SET WARNING is set to ON, Debug Tool stops
and displays a message that it could not evaluate the conditional
expression. You need to enter a command to indicate what action you
want Debug Tool to take.
- If SET WARNING is set to OFF, Debug Tool does
not stop nor display a message that it could not evaluate the conditional
expression. Debug Tool continues running the program.
Example
Specify that conditions result in a diagnostic message.
SET WARNING ON;
Refer to the following topics for more information
related to the material discussed in this topic.
SET command (COBOL)
The SET command assigns a value to a COBOL reference.
The SET keyword cannot be abbreviated.
- reference
- A valid Debug Tool COBOL reference.
- literal
- A valid COBOL numeric literal constant.
- TRUE
- The value assigned to a level-88 reference.
In
order to assign the value TRUE, the PTF for Language Environment APAR PK30521 must be installed
on z/OS Version 1 Release 6, Version 1 Release 7,
and Version 1 Release 8.
Usage notes
- You can assign the value TRUE only to a level-88 reference.
- If Debug Tool was started because of a computational condition or
an attention interrupt, using an assignment to set a variable might
not give expected results. This is due to the uncertainty of variable
values within statements as opposed to their values at statement boundaries.
- SET assigns a value only to a single receiver; unlike
COBOL, multiple receiver variables are not supported.
- Only formats 1, 4 and 5 of the COBOL SET command are
supported.
- Index-names can only be program variables (because OCCURS is
not supported for the Debug Tool session variables).
- COBOL ADDRESS OF identifier is supported only for identifiers
that are LINKAGE SECTION variables. In addition, COBOL ADDRESS
OF as a receiver must be level 1 or 77, and COBOL ADDRESS
OF as a sender can be any level except 66 or 88.
- Debug Tool provides a hexadecimal constant that can be used with the SET command,
where the hexadecimal value is preceded by an "H" and delimited
by quotation marks (") or apostrophes (').
- If the DATA option of the PLAYBACK ENABLE command
is in effect, you can use the SET command to assign a value
only to a session variable. You cannot assign a value to a program
variable.
- If you are debugging an optimized COBOL program, you can use the SET command
to assign a value to a program variable only if you first enter the SET
WARNING OFF command. The source or target of the SET command
cannot reference a variable that was discarded by the optimizer.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
Allowable moves for the Debug Tool SET command
The following table shows the allowable moves for the Debug Tool SET command.
| Source
field |
|
Receiving field |
| AO |
IN |
IDI |
PTR |
ED |
BI |
ID |
OR |
| Address Of (AO) |
Y |
|
|
Y |
|
|
|
|
| Index Name (IN) |
|
Y |
Y |
|
Y |
Y |
Y |
|
| Index Data Item (IDI) |
|
Y |
Y |
|
|
|
|
|
| Pointer Data Item (PTR) |
Y |
|
|
Y |
|
|
|
|
| Address Hex Literal1 |
Y |
|
|
Y |
|
|
|
|
| NULL (NUL) |
Y |
|
|
Y |
|
|
|
|
| Integer Literal |
|
Y2 |
|
|
|
|
|
|
| External Decimal (ED) |
|
Y |
|
|
|
|
|
|
| Binary (BI) |
|
Y |
|
|
|
|
|
|
| Internal Decimal (ID) |
|
Y |
|
|
|
|
|
|
| Object Reference (OR) |
|
|
|
|
|
|
|
Y |
Notes:
- 1
- Must be hexadecimal characters only, delimited by either quotation
marks (") or apostrophes (') and preceded by H.
- 2
- Index name is converted to index value.
SHOW prefix command (full-screen mode)
The SHOW prefix command specifies what relative statement
(for C) or relative verb (for COBOL) within the line is to have its
frequency count temporarily shown in the suffix area.
- integer
- Selects a relative statement (for C) or a relative verb (for
COBOL) within the line. The default value is 1. For optimized COBOL
programs, the default value is the first executable statement which
was not discarded by the optimizer.
Usage notes
- If SET SUFFIX is currently OFF, SHOW
prefix forces it ON.
- The suffix display returns to normal on the next interaction.
- The SHOW prefix command is not logged.
Example
Display the frequency count of the third statement or verb in the
line (typed in the prefix area of the line where the statement is
found).
SHOW 3
No space is needed as a delimiter between
the keyword and the integer; hence, SHOW 3 is equivalent
to SHOW3.
STEP command
The STEP command causes Debug Tool to dynamically step through
a program, executing one or more program statements. In full-screen
mode, it provides animated execution.
STEP ends if one or more of the following conditions
is reached:
- User attention interrupt
- A breakpoint is encountered
- Normal or unusual termination of the program

- integer
- Indicates the number of statements performed. The default value
is 1. If integer is greater than 1, the statement is performed
as if it were that many repetitions of STEP with the same
keyword and a count of one. The speed of execution, or the pace of stepping, is set by either the SET
PACE command, or with the Pace of visual
trace field on the Profile panels.
- *
- Specifies that the program should run until interrupted. STEP * is
equivalent to GO.
- INTO
- Steps into any called procedures or
functions. This means that stepping continues within called procedures
or functions.
- OVER
- Steps over any procedure call or
function invocations. This operand provides full-speed execution (with
no animation) while in called procedures and functions, resuming STEP mode
on return.
If you are debugging a disassembled program, verify
that you have set a breakpoint in the calling program. Without the
breakpoint, Debug Tool can not resume STEP mode on return and
the application continues to run until it ends.
- RETURN
- Steps to the return point the specified
number of levels back, halting at the statement following the corresponding
procedure call or function invocation. This operand provides full-speed
execution (with no animation) for the remainder of the current procedure
or function, and for any called procedures or functions, resuming STEP mode
on return.
If you are debugging a non-Language Environment COBOL
or disassembled program, do not use the STEP RETURN command
because Debug Tool cannot identify the return point. Instead, set
a breakpoint in the calling program and enter the GO command.
Usage notes
- In the figure below, PGM A calls PGM B.
Assume that the current execution point is on PGM
B and, at the line ADD 5 TO MYNUM. At this point,
you decide you don't need to see any more of the code in PGM
B. By issuing STEP RETURN on the command line, Debug Tool returns
to the first line of code after the CALL command that called PGM
B, as indicated by the arrow. You can then continue stepping
through PGM A.
- If STEP is specified in a command list (for example,
as the subject of an IF command or WHEN clause),
all subsequent commands in the list are ignored.
- If STEP is specified within the body of a loop, it
causes the execution of the loop to end.
- To suppress the logging of STEP commands, use the SET
ECHO command.
- If two operands are given, they can be specified in either order.
- The animation execution timing is set by the SET PACE command.
- The source panel provides a means of suppressing the display of
selected listings or files. This gives some control of "debugging
scope," because animated execution does not occur within a load
module where the source listing or source file is not displayed.
- If you are debugging a disassembled program and attempt to step
out of the current CU, a message appears. The message informs you
to set a breakpoint outside the current CU. Without that breakpoint, Debug Tool cannot
stop the application. After you have set the breakpoint, you can resume
running your application by entering a Debug Tool command like STEP or GO.
- If you are debugging a program that does not use the standard
linkage conventions for R13, R14, and R15,
and you enter the STEP RETURN or the STEP command
on a statement that returns to a higher level CU, Debug Tool does not
stop at the expected instruction in the higher-level CU.
- When PLAYBACK ENABLE is in effect, you can use the STEP command
to move forward or backward one or more statements. You cannot use
the INTO, OVER, and RETURN keywords.
Each STEP command moves forward or backward the number
of statements specified or implied by the integer parameter.
- If the DATA option of the PLAYBACK ENABLE command
is in effect, you can access program variables after each STEP command.
- You can use the STEP command in remote debug mode only
by entering it in the Action field,
which is in the Optional Parameters section
of the Add a Breakpoint task.
Examples
- Step through the next 25 statements and if an application subroutine
or function is called, continue stepping into that subroutine or function.
STEP 25 INTO;
- Step through the next 25 statements, but if any application subroutines
or functions are called, switch to full-speed execution without animation
until the subroutine or function returns.
STEP 25 OVER;
- Return at full speed through three levels of calls.
STEP 3 RETURN;
STORAGE command
The STORAGE command
enables you to alter storage. You must be careful when you alter storage
because the results can be unpredictable.

- address
- The address of the first byte of storage that you want to alter.
- reference
- A variable whose storage location is to be changed. In assembler
or disassembly, this operand may be specified as any assembler expression
that represents a storage location.
- 'reference'
- A non-Language Environment COBOL variable whose storage location
is to be changed. In non-Language Environment COBOL, reference must be
enclosed in apostrophes (').
- offset
- The decimal or hexadecimal number of bytes indicating the starting
offset from the memory location pointed to by reference's address
or the address provided by the user. Offset can be a negative
number. If offset is a hex constant, it must follow the same
syntax rules as address above. The default is 0.
- length
- The decimal number of bytes you want to alter. This must equal
the length of value.
- value
- The value you want to store. The notation for value must
be one of the following:
- An address.
- A hexadecimal value surrounded by apostrophes (') and preceded
by "X". You can also use a different notation for the following
programming languages:
- For PL/I, the hexadecimal value enclosed in quotation marks (")
or apostrophes (') followed by PX.
- For assembler, COBOL, or disassembly, the hexadecimal value enclosed
in quotation marks (") and preceded by "X".
- A decimal value. For any decimal value, four bytes are altered.
For example, STORAGE (H'12345678') = 3 is the same as STORAGE(H'12345678')
= H'00000003'.
- A character string up to 256 bytes long, using the character string
notation appropriate for each programming language or, for all programming
languages, you can use enclose the string in quotation marks (").
Usage notes
- If you specify only two parameters, Debug Tool assumes the second
parameter is the length.
- If you specify only one parameter, Debug Tool assumes the offset is
0 and that the length is equal to the length of value.
- The STORAGE command can not be used while you replay
recorded statements by using the PLAYBACK commands.
- If you specify address with more than 8 significant digits
or if reference references 64-bit addressable storage, Debug Tool assumes
that the storage location is 64-bit addressable storage. Otherwise, Debug Tool assumes
that the storage location is 31-bit addressable storage.
- If reference is
a pointer, Debug Tool changes the contents at the address given by that
pointer.
Examples
- For any programming language, enter the following command to alter
two bytes of storage at address X'12345678':
STORAGE (X'12345678') = 0x1234;
- For C, enter the following command to alter two bytes of storage
at address X'12345678':
STORAGE (0x12345678) = 0x1234;
- For COBOL, enter the following command to alter four bytes of
storage at address X'12345678':
STORAGE (H'12345678') = H'1234'
The
command is changed to:
STORAGE (H'12345678') = H'00001234'
- For COBOL, enter the following command to alter six bytes of storage
at address X'12345678':
STORAGE (H'12345678') = X'C1C1C1C1C1C1'
- For PL/I, enter the following command to alter six bytes of storage
at address X'12345678':
STORAGE ('12345678'PX) = 'C1C1C1C1C1C1'X
- For PL/I enter the following command to alter 23 bytes of storage
starting at address X'12345678':
STORAGE ('12345678'PX) = 'aaaaaaaaaaaaaaaaaaaaaaa'
- Enter the following command to alter 10 bytes of storage at MYVAR,
starting at offset 2:
STORAGE (MYVAR, 2, 10) = 'new text: ';
- Enter the following command to alter 4 bytes of storage at address X'20CD0',
starting at offset 10:
STORAGE ('20CD0'PX, 10, 4) = 99;
- Enter the following command to alter storage at MYVAR, starting
at offset 0, for the same number of bytes as the length of variable
MYVAR:
STORAGE (MYVAR) = 10;
- For C, update the storage pointed by an address 1A3BE910, starting
at offset -20 for 20 bytes:
STORAGE (0x1A3BE910,-20,20) = 'first and last name ';
- Update 20 bytes of storage pointed by an address 162F0, language
is Cobol, offset is 0:
STORAGE ( H'162F0', 20 ) = 'clear that string ' ;
- For Assembler, update the storage pointed by address 00020CD0,
starting at offset 16 for 4 bytes, and the offset is specified as
a hex constant:
STORAGE ( X'00020CD0', X'10', 4 ) = 5 ;
Refer to the following topics for more information
related to the material discussed in this topic.
switch command (C and C++)
The switch command enables you to transfer control to
different commands within the switch body, depending on
the value of the switch expression. The switch, case,
and default keywords must be lowercase and cannot be abbreviated.
- expression
- A valid Debug Tool C expression.
- case_expression
- A valid character or optionally signed integer constant.
- command
- A valid Debug Tool command.
The value of the switch expression is compared with
the value of the expression in each case clause. If a
matching value is found, control is passed to the command in the case clause
that contains the matching value. If a matching value is not found
and a default clause appears anywhere in the switch body,
control is passed to the command in the default clause.
Otherwise, control is passed to the command following the switch body.
If control passes to a command in the switch body, control
does not pass from the switch body until a break command
is encountered or the last command in the switch body is
performed.
Usage notes
- Declarations are not allowed within a switch command.
- The switch command does not end with a semicolon.
A semicolon after the closing brace is treated as a Null command.
- Although this command is similar to the switch statement
in C, it is subject to Debug Tool restrictions on expressions.
- Duplicate case_expression values are not supported.
- You cannot use the switch command
while you replay recorded statements by using the PLAYBACK commands.
Examples
- The following switch command contains several case clauses
and one default clause. Each clause contains a function
call and a break command. The break commands
prevent control from passing down through subsequent commands in the switch body.
If key has
the value '/', the switch command
calls the function divide. On return, control passes to
the command following the switch body.
char key;
printf("Enter an arithmetic operator\n");
scanf("%c",&key);
switch (key)
{
case '+':
add();
LIST (key);
break;
case '-':
subtract();
LIST (key);
break;
case '*':
multiply();
LIST (key);
break;
case '/':
divide();
LIST (key);
break;
default:
printf("Invalid key\n");
break;
}
- In the following example, break commands are not present.
If the value of c is equal to 'A', all 3 counters
are incremented. If the value of c is equal to 'a', lettera and total are
increased. Only total is increased if c is not
equal to 'A' or 'a'.
char text[100];
int capa, i, lettera, total;
for (i=0; i < sizeof(text); i++) {
switch (text[i]) {
case 'A':
capa++;
case 'a':
lettera++;
default:
total++;
}
}
SYSTEM command (z/OS)
The SYSTEM command lets you issue TSO commands
during a Debug Tool session. The SYSTEM keyword can only be
abbreviated as SYS.
- system_command
- A valid TSO system command or CLIST name that does not require
a parameter.
Usage notes
- No parameters can be specified as part of the system command or
CLIST invocation. To execute noninteractively when parameters are
required, you must enter the complete invocation in a CLIST and then
use a TSO or SYSTEM command to call that CLIST (without
parameters).
- You cannot introduce a new Debug Tool session using the SYSTEM command.
- When operating interactively in TSO, there is no provision for
entering a mode where commands are accepted repeatedly; however, it
is possible to write your own such iterative sequence in a CLIST.
- You cannot issue CICS commands using SYSTEM.
Examples
- List all the data sets in the user catalog.
SYSTEM LISTCAT;
- Temporarily places you in ISPF mode.
SYSTEM PDF;
Refer to the following topics for more information
related to the material discussed in this topic.
TRIGGER command
The TRIGGER command raises the specified AT-condition
in Debug Tool, or it raises the specified programming language condition
in your program.

- condition
- A valid condition or exception. Depending on the current programming
language setting, this code can be any one of the following types
of codes:
- A Language Environment symbolic feedback code
- A language-oriented keyword or code
- When an application runs without the Language Environment run time, one
of the ABEND codes shown below.
If no active condition handler exists for the specified condition,
the default condition handler can cause the program to end prematurely.
Following
are the C condition constants; they must be uppercase and not abbreviated.
|
SIGABND
SIGABRT
SIGFPE
|
SIGILL
SIGINT
SIGIOERR
SIGSEGV
|
SIGTERM
SIGUSR1
SIGUSR2
|
There are no COBOL condition constants. Instead, an Language Environment symbolic
feedback code must be used, for example, CEE347.
PL/I
condition constants can be used; for syntax and acceptable abbreviations
see the ON command.
When you are running without the Language Environment run
time, use one of the following codes:
- Codes Sxxx and Uxxx to
represent MVS System and User ABENDs. In this case the xxx is three hexadecimal digits representing the
ABEND code.
- Any four-character string to represent a CICS ABEND
code.
- cu_spec
- A valid compile unit specification.
- entry_name
- A valid external entry point name constant or zero (0);
however, 0 can only be specified if the current programming
language setting is C or PL/I.
- reference
- A valid Debug Tool reference in the current programming language.
- %STORAGE
- A built-in function that provides an alternative way to select
an AT CHANGE subject.
- address
- The starting address of storage to be watched for changes.
- length
- The number of bytes of storage being watched for changes. This
must be a positive integer constant. The default value is 1.
- load_spec
- A valid load module specification.
- block_spec
- A valid block specification.
- statement_label
- A valid source label constant.
- stmt_id_spec
- A valid statement id specification.
Usage notes
- If the THREADTERMCOND option in the EQAOPTS file is set to prevent Debug Tool from
stopping when a FINISH, CEE066, or CEE067 thread termination condition
is raised by Language Environment, Debug Tool does not gain control when these conditions
are raised. If you want Debug Tool to gain control when these conditions
are raised, you can set an AT OCCURRENCE breakpoint or change the
THREADTERMCOND option to allow Debug Tool to gain control.
- AT TERMINATION cannot be raised by the TRIGGER command.
- An enclave cannot be stopped by the TRIGGER command.
- If you are replaying recorded statements by using the PLAYBACK commands,
you cannot use the TRIGGER command.
Examples
In the first example, note the following differences
- Triggering a breakpoint (TRIGGER AT OCCURRENCE CEE347),
which performs Debug Tool commands associated with the breakpoint. The
condition is not raised.
- Triggering a condition (TRIGGER CEE347), which raises
the condition and causes a corresponding system action.
A corresponding system action can be a condition handler.
- Perform the commands in the AT OCCURRENCE CEE347 breakpoint
(the CEE347 condition is not raised). The current programming
language setting is COBOL.
AT OCCURRENCE CEE347 PERFORM
SET ix TO 5;
END-PERFORM;
TRIGGER AT OCCURRENCE CEE347; /* SET ix TO 5 is executed */
- Raise the SIGTERM condition in your program. The current
programming language setting is C.
TRIGGER SIGTERM;
- A previously defined STATEMENT breakpoint (for line
13) is triggered.
AT 13 LIST "at 13";
TRIGGER AT 13;
/* "at 13" will be the echoed output here */
- Assume the following breakpoints exist in a program:
AT CHANGE x LIST TITLED (x); AT STATEMENT 10;
If Debug Tool is
started for the STATEMENT breakpoint and you want to trigger
the commands associated with the AT CHANGE breakpoint,
enter:
TRIGGER AT CHANGE x;
Debug Tool displays the value of x.
Refer to the following topics for more information
related to the material discussed in this topic.
TSO command (z/OS)
The TSO command lets you issue TSO commands during a Debug Tool session
and is valid only in a TSO environment. The TSO keyword
cannot be abbreviated.
- tso_command
- A valid TSO system command or CLIST name that does not require
a parameter.
Usage notes
- TSO is synonymous to SYSTEM.
Example
List all the data sets in the user catalog.
TSO LISTCAT;
Refer to the following topics for more information
related to the material discussed in this topic.
USE command
The USE command causes the Debug Tool commands in the specified
file or data set to be either performed or syntax checked. This file
can be a log file from a previous session. The specified file or
data set can itself contain another USE command. The maximum
number of USE files open at any time is limited to eight.
The USE keyword cannot be abbreviated.
- ddname
- A valid ddname in z/OS.
- dsname
- A z/OS data set containing the Debug Tool commands to
be performed. If dsname is not enclosed in apostrophes
('), Debug Tool assumes it is a partially-qualified data set name
and the user ID is prefixed to form the fully-qualified data set name.
Usage notes
- To check the syntax of the commands in a USE file:
- Set the EXECUTE setting to OFF.
- Enter a USE command for the file.
- Commands read from a USE file are logged as comments.
- The log file can serve as a USE file in a subsequent Debug Tool session.
- Recursive calls are not allowed; that is, a commands file cannot
be used if it is already active. This includes the primary commands
and preferences files. If another invocation of Debug Tool occurs during
the execution of a USE file (for example, if a condition
is raised while executing a command from a USE file), the USE file
is not used for command input until control returns from the condition.
- The USE file is closed when the end of the file is
reached.
- If a nonreturning command (such as GO) is
performed from a USE file, the action taken (as far as
closing the USE file) depends on certain things:
- If the USE file was called directly or indirectly from
the primary commands file or preferences file, it has the same characteristics
as the primary commands file or preferences file. That is, it "keeps
its place" and the next time Debug Tool requests a command, it reads
from the USE file where it left off.
- If the USE file was not called
directly or indirectly from the primary commands file or preferences
file, the rest of the USE file and the file that called
the USE file is skipped.
- If the end of the USE file is reached without encountering
a QUIT command, Debug Tool returns to the command source where
the USE command was issued. This can be the terminal,
a command string, or another commands file.
- A USE file takes on the aspects of whatever command
source issued the USE command, relative to its behavior
when a GO, GOTO, or STEP is executed.
When called from the primary commands file, it continues with its
next sequential command at the next breakpoint. If it is called from
any other command sequence, the GO, GOTO, or STEP causes
any remaining commands in the USE file to be discarded.
Examples
while command (C and C++)
The while command enables you to repeatedly perform
the body of a loop until the specified condition is no longer met
or evaluates to false. The while keyword must be lowercase
and cannot be abbreviated.
- expression
- A valid Debug Tool C expression.
- command
- A valid Debug Tool command.
The expression is evaluated to determine whether the
body of the loop should be performed. If the expression evaluates
to false, the body of the loop never executes. Otherwise, the body
does execute. After the body has been performed, control is given
once again to the evaluation of the expression. Further
execution of the action depends on the value of the condition.
A break command can cause the execution of a while command
to end, even when the condition does not evaluate to false.
Usage notes
- If you are replaying recorded statements
by using the PLAYBACK commands, then you cannot use the while command.
Examples
- List the values of x starting at 3 and ending at 9,
in increments of 2.
x = 1;
while (x +=2, x < 10)
LIST x;
- While --index is greater than or equal to zero (0),
triple the value of the expression item[index].
while (--index >= 0) {
item[index] *= 3;
printf("item[%d] = %d\n", index, item[index]);
}
WINDOW command (full-screen mode)
The WINDOW command provides window manipulation functions. WINDOW commands
can be made immediately effective with the IMMEDIATE command.
The cursor-sensitive form is most useful when assigned to a PF key.
The WINDOW keyword is optional.
The following table summarizes the forms of the WINDOW command.
| WINDOW CLOSE command |
Closes the specified window in the Debug Tool full-screen
session panel. |
| WINDOW OPEN command |
Opens a previously-closed window in the Debug Tool full-screen
session panel. |
| WINDOW SIZE command |
Controls the relative size of currently visible
windows in the Debug Tool full-screen session panel. |
| WINDOW SWAP command |
Replaces the logical window being displayed
in a physical window with another logical window. |
| WINDOW ZOOM command |
Expands the indicated window to fill the entire
screen. |
Usage notes
- If no operand is specified and the cursor is on the command line,
then the default window id set by SET DEFAULT WINDOW is
used (if it is open, otherwise the precedence is SOURCE, LOG, MONITOR).
WINDOW CLOSE command
Closes the physical window of the specified logical window in the Debug Tool full-screen
session panel. The remaining open physical windows expand to fill
the remainder of the screen. Closing a physical window does not effect
the logical window. For example, closing the physical window that
is displaying the Monitor window does not stop the monitoring of variable
values assigned by the LIST MONITOR command.
If you specify a logical window that is not assigned to a physical
window, Debug Tool displays an error message.
If there is only one physical window visible, WINDOW CLOSE is
invalid.
- CURSOR
- Selects the window where the cursor is currently positioned
unless on the command line.
- LOG
- Selects the session log window.
- MEMORY
- Selects the Memory window.
- MONITOR
- Selects the monitor window.
- SOURCE
- Selects the source listing window.
Example
Close the window containing the cursor.
WINDOW CLOSE CURSOR;
WINDOW OPEN command
Opens a previously-closed physical window in the Debug Tool full-screen
session panel. Any existing physical windows are resized according
to the configuration selected with the PANEL LAYOUT command.
If you specify a logical window that is not assigned to a physical
window, Debug Tool displays an error message.
If the OPEN command is issued without an operand, Debug Tool opens
the last closed physical window.
- LOG
- Selects the session log window.
- MEMORY
- Selects the Memory window.
- MONITOR
- Selects the monitor window.
- SOURCE
- Selects the source listing window.
Example
Open the monitor window.
WINDOW OPEN MONITOR;
WINDOW SIZE command
Controls the relative size of the currently visible physical windows
in the Debug Tool full-screen session panel.
- integer
- Specifies the number of rows or columns, as appropriate for
the selected window and the current window configuration.
- CURSOR
- Selects the window where the cursor is currently positioned
unless on the command line. The cursor form of WINDOW SIZE applies
to that window if integer is specified. Otherwise, it redraws
the configuration of windows so that the intersection of the windows
is at the cursor, or if the configuration does not have a common intersection,
so that the nearest border is at the cursor.
- LOG
- Selects the session log window.
- MEMORY
- Selects the Memory window.
- MONITOR
- Selects the monitor window.
- SOURCE
- Selects the source listing window.
Usage notes
- You cannot use WINDOW SIZE if a window is zoomed or
if there is only one window open.
- Each window in any configuration has only one adjustable dimension:
- If one or more windows are as wide as the screen:
- The number of rows is adjustable for each window as wide as the
screen
- The number of columns is adjustable for the remaining windows
- If one or more windows are as high as the screen:
- The number of columns is adjustable for each window as high as
the screen
- The number of rows is adjustable for the remaining windows
Examples
- Adjust the size of the Source window to 15 rows.
WINDOW SIZE 15 SOURCE;
- Adjust the size of the window where the cursor is currently positioned
to 20 rows.
SIZE 20 CURSOR;
WINDOW SWAP command
The SWAP command replaces the logical window being displayed
in a physical window with another logical window. The order of the
operands is not important. The physical window retains its attributes.
For example, if the physical window was closed, it remains closed
when you entered the SWAP command, it remains closed until
you enter the WINDOW OPEN command.
- MEMORY
- Selects the Memory window.
- LOG
- Selects the Log window.
Examples
Refer to the following topics for more information
related to the material discussed in this topic.
- Related tasks
- "Debug Tool session panel" in Debug Tool User’s Guide
- "Switching between
the Memory window and Log window" in Debug Tool User’s Guide
WINDOW ZOOM command
Expands the specified logical window to fill the entire screen
or restores the screen to the currently defined physical window configuration.
The logical window does not have to be assigned to a physical window.
This command provides a convenient way to display any logical window
without having to reassign physical windows. For example, because
the MEMORY window and LOG window cannot be displayed
at the same time, you can use the WINDOW ZOOM LOG command
to display the Log window while the Memory window remains assigned
to its physical window.
- CURSOR
- Selects the window where the cursor is currently positioned
unless on the command line.
- LOG
- Selects the session log window.
- MEMORY
- Selects the Memory window.
- MONITOR
- Selects the monitor window.
- SOURCE
- Selects the source listing window.
If the selected window is currently zoomed, the zoom mode is toggled.
That is, the currently defined window configuration is restored.
Usage
note
The WINDOW ZOOM command is not logged.
Example
Expand the log window.
WINDOW ZOOM LOG;
In non-CICS environments, SVC screening must be
enabled to debug non-Language Environment COBOL programs, programs that
run without the Language Environment runtime, or programs that are loaded by
using the MVS LOAD and LINK macros. See Debug Tool Customization Guide for
instructions on how to manage SVC screening.
|
This information center is powered by Eclipse technology. (http://www.eclipse.org)