Rational Developer for System z, Version 7.6

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.

? command

The ? command displays a list of Debug Tool commands in the Log window.

Syntax diagram for the question mark (help) command

Usage note

In the following cases, Debug Tool does not display the syntax help after you enter the ? command:

ALLOCATE command

The ALLOCATE command allocates a file to an existing data set, a concatenation of existing data sets, or a temporary data set.

Syntax diagram for the ALLOCATE command
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.

Syntax diagram for the ANALYZE command
EXPRESSION
Requests that the accompanying expression be evaluated from the following points of view:
expression
A valid Debug Tool PL/I expression.

Usage notes

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.

Syntax diagram for the assembler assignment command
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.

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

Examples

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.

Syntax diagram for the non-Language Environment COBOL assignment command
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

Examples

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.

Syntax diagram for the PL/I assignment command
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:

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.

AT ALLOCATE (PL/I) command Gives Debug Tool control when storage for a named controlled variable or aggregate is dynamically allocated by PL/I.
AT APPEARANCE command Gives Debug Tool control:
  • For C and PL/I, when the specified compile unit is found in storage
  • For COBOL, the first time the specified compile unit is called
AT CALL command Gives Debug Tool control on an attempt to call the specified entry point.
AT CHANGE command (full screen mode, line mode, batch mode) Gives Debug Tool control when either the specified variable value or storage location is changed.
AT CHANGE command (remote debug mode) Gives Debug Tool control when the specified variable value is changed.
AT CURSOR command (full-screen mode) Defines a statement breakpoint by cursor pointing.
AT DATE command (COBOL) For COBOL, gives Debug Tool control for each date processing statement within the specified block.
AT DELETE command Gives Debug Tool control when a load module is deleted.
AT ENTRY command or AT ENTRY command (remote debug mode) Defines a breakpoint at the specified entry point.
AT EXIT command Defines a breakpoint at the specified exit point.
AT GLOBAL command Gives Debug Tool control for every instance of the specified AT-condition.
AT LABEL command Gives Debug Tool control at the specified statement label.
AT LINE command Gives Debug Tool control at the specified line.
AT LOAD command or AT LOAD command (remote debug mode) Gives Debug Tool control when the specified load module is loaded.
AT OCCURRENCE command Gives Debug Tool control on a language or Language Environment condition or exception.
AT OFFSET command (disassembly) Gives Debug Tool control at the specified offset in the disassembly view.
AT PATH command Gives Debug Tool control at a path point.
AT Prefix command (full-screen mode) Defines a statement breakpoint through the Source window prefix area.
AT STATEMENT command or AT STATEMENT command (remote debug mode) Gives Debug Tool control at the specified statement.
AT TERMINATION command Gives Debug Tool control when the application program is terminated.

Usage notes

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

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:

Syntax diagram for the every_clause
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

Examples

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.

Syntax diagram for the AT ALLOCATE command
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

Examples

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.

Syntax diagram for the AT APPEARANCE command
*
Sets a breakpoint at every APPEARANCE of any compile unit.
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.

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.

Syntax diagram for the AT CALL command
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

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.

Syntax diagram for the AT CHANGE command
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

Examples

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.

Syntax diagram for the AT CHANGE command (for remote debug mode)
'reference' or "reference"
A valid Debug Tool reference in the current programming language.

Usage notes

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.

Syntax diagram for the AT CURSOR command
TOGGLE
Specifies that if the cursor-selected statement already has an associated statement breakpoint then the breakpoint is removed rather than replaced.

Usage notes

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.

Syntax diagram for the COBOL AT DATE command
*
Sets a breakpoint at every date processing statement.
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.

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.

Syntax diagram for the AT DELETEcommand
*
Sets a breakpoint at every DELETE of any load module.
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.

AT ENTRY command

Defines a breakpoint at the specified entry point in the specified block.

Syntax diagram for the AT ENTRY command
*
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

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.

Syntax diagram for the AT ENTRY command (remote debug mode)

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.

Syntax diagram for the AT EXIT command
*
Sets a breakpoint at every EXIT of any block.
command
A valid Debug Tool command.

Usage notes

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.

Syntax diagram for the AT GLOBAL command
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

Examples

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.

Syntax diagram for the AT LABEL command
*
Sets a breakpoint at every LABEL.
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.

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.

Syntax diagram for the AT LOAD command
*
Sets a breakpoint at every LOAD of any load module.
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.

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.

Syntax diagram for the AT LOAD command (remote debug mode)

AT OCCURRENCE command

Gives Debug Tool control on a language or Language Environment condition or exception or an MVS or CICS ABEND.

Syntax diagram for the AT OCCURRENCE command
condition
A valid condition or exception. This can be one of the following codes or conditions:

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:

  1. Debug Tool is started before any C or C++ signal handler.
  2. 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:

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

Examples

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.

Syntax diagram for the AT OFFSET command
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

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.

Syntax diagram for the AT PATH command
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.

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.

Syntax diagram for the prefix AT command
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.

Syntax diagram for the AT STATEMENT command
*
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

Examples

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.

Syntax diagram for the AT STATEMENT command (remote debug mode)

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.

Syntax diagram for the AT TERMINATION command
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.

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.

Syntax diagram for the PL/I BEGIN command
command
A valid Debug Tool command.

Usage notes

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.

Syntax diagram for the C and C++ block command
command
A valid Debug Tool command.

Usage notes

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.

Syntax diagram for the C and C++ break command

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

Examples

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.
CALL %CECI command Starts the CICS Command Level Interpreter Program.
CALL %DUMP command Calls a dump service to obtain a formatted dump.
CALL %FA command Calls IBM® Fault Analyzer to provide a formatted dump of the current machine state.
CALL %HOGAN command Starts Computer Sciences Corporation's KORE-HOGAN application.
CALL %VER command Adds a line to the log describing the maintenance level of Debug Tool that you have installed on your system.
CALL entry_name command (COBOL) Calls an entry name in the application program (COBOL).
CALL procedure command Calls a procedure that has been defined with the PROCEDURE command.

CALL %CEBR command

Starts the CICS Temporary Storage Browser Program.

Syntax diagram for the CALL %CEBR command

Usage notes

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

CALL %CECI command

Starts the CICS Command Level Interpreter Program.

Syntax diagram for the CALL %CECI command

Usage notes

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

CALL %DUMP command

Calls a dump service to obtain a formatted dump.

Syntax diagram for the CALL %DUMP command
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:

Usage notes

Examples

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

CALL %FA command

Starts and instructs IBM Fault Analyzer to provide a formatted dump of the current machine state.

Syntax diagram for the CALL %FA command

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.

Syntax diagram for the CALL %FM command
userID
The ID of an MVS user. If you do not specify a userID, then File Manager takes one of the following options:
BACKGROUND
Specifies that all non-terminal processing be routed to a background task.

Usage notes

CALL %HOGAN command

Starts Computer Sciences Corporation's KORE-HOGAN application, also known as SMART (System Memory Access Retrieval Tool).

Syntax diagram for the CALL %HOGAN command

Usage notes

CALL %VER command

Adds a line to the log describing the maintenance level of Debug Tool that you have installed on your system.

Syntax diagram for the CALL %VER command

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).

Syntax diagram for the CALL entry_name command
identifier
A valid Debug Tool COBOL identifier.
literal
A valid COBOL literal.

Usage notes

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.

Syntax diagram for the CALL procedure
procedure_name
The name given to a sequence of Debug Tool commands delimited by a PROCEDURE command and a corresponding END command.

Usage notes

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.

Syntax diagram for the CHKSTGV command

Usage notes

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.

Syntax diagram for the CLEAR command
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

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.

Syntax diagram for the prefix CLEAR command
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

Examples

COMMENT command

The COMMENT command can be used to insert commentary in to the session log. The COMMENT keyword cannot be abbreviated.

Syntax diagram for the COMMENT command
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.

Syntax diagram for the COBOL COMPUTE command
reference
A valid Debug Tool COBOL numeric reference.
expression
A valid Debug Tool COBOL numeric expression.

Usage notes

Examples

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.

Syntax diagram for the CURSOR command

Usage notes

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.

Syntax diagram for the assembler declarations command
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:

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.

Syntax diagram for the C and C++ declarations command
*
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

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

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.

Syntax diagram for the COBOL declarations command
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

Examples

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

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.

Syntax diagram for the PL/I DECLARE command
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

Examples

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

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

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.

Syntax diagram for the DESCRIBE command
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

Examples

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.

Syntax diagram for the DISABLE 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:

You can specify a specific name (for example, PROG1) or a partial name with the wild card character (for example, EMPL*).

Usage notes

Examples

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.

Syntax diagram for the prefix DISABLE command
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.

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.

Syntax diagram for the assembler DO command
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.

Syntax diagram for the C and C++ do/while command
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

Syntax diagram for the simple PL/I DO command
command
A valid Debug Tool command.

Repeating

Syntax diagram for the repeating PL/I DO command
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

Syntax diagram for the iterative PL/I DO command
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

ENABLE command

The ENABLE command activates an AT or pattern-match breakpoint after it was disabled with the DISABLE command.

Syntax diagram for the ENABLE 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.

Syntax diagram for the prefix ENABLE command
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.

Syntax diagram for the COBOL EVALUATE command
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

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.

Syntax diagram for the C, C++, and disassembly expression command
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

Examples

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.

Syntax diagram for the FIND command
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:

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

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:

The for keyword must be lowercase and cannot be abbreviated.

Syntax diagram for the C and C++ for command
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

Examples

FREE command

The FREE command frees a file that is currently allocated.

Syntax diagram for the FREE command
ddname
Name of the file to free.

GO command

The GO command causes Debug Tool to start or resume running your program.

Syntax diagram for the GO command
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:

Usage notes

Examples

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.

Syntax diagram for the GOTO command

Usage notes

Examples

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

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.

Syntax diagram for the GOTO LABEL command
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.

Syntax diagram for the programming language neutral IF command
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

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.

Syntax diagram for the assembler, disassembly, and non-Language Environment COBOL IF command
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.

Syntax diagram for the C and C++ if command
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

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.

Syntax diagram for the COBOL IF command
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:
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

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.

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.

Syntax diagram for the PL/I IF command
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

Examples

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.

Syntax diagram for the IMMEDIATE command
command
One of the following Debug Tool commands:

Usage notes

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.

Syntax diagram for the C, C++, and COBOL INPUT command
text
Specifies text input to a pending read.

Usage notes

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.

Syntax diagram for the JUMPTO command

Usage notes

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.

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.

Syntax diagram for the JUMPTO LABEL command
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 Source Identification panel
LIST AT command Lists the currently defined breakpoints.
LIST CALLS command Displays the dynamic chain of active blocks.
LIST CONTAINER command Displays the contents of a container.
LIST CURSOR command (full-screen mode) Displays the variable pointed to by the cursor.
LIST DTCN or CADP command List the programs and compile units that were disabled by the DISABLE command.
LIST expression command Displays values of expressions.
LIST FREQUENCY command Lists statement execution counts.
LIST LAST command Displays a list of recent entries in the history table.
LIST LINE NUMBERS command Lists all line numbers that are valid locations for an AT LINE breakpoint.
LIST LINES command Lists one or more lines from the current listing or source file displayed in the Source window.
LIST MONITOR command Lists the current set of MONITOR commands.
LIST NAMES command Lists the names of variables, programs, or Debug Tool procedures.
LIST ON (PL/I) command Lists the action (if any) currently defined for the specified PL/I conditions.
LIST PROCEDURES command Lists the commands contained in the specified Debug Tool procedure.
LIST REGISTERS command Displays the current register contents.
LIST STATEMENT NUMBERS command. Lists all statement numbers that are valid locations for an AT STATEMENT breakpoint.
LIST STATEMENTS command Lists one or more statements from the current listing or source file displayed in the Source window.
LIST STORAGE command Provides a dump-format display of storage.

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.

Syntax diagram for the LIST AT 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

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.

Syntax diagram for the LIST CALLS command

Usage notes

Example

Display the current dynamic chain of active blocks.

LIST CALLS;

LIST CONTAINER command

Displays the contents of a container.

Syntax diagram for the LIST CONTAINER command
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

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.

Syntax diagram for the LIST CURSOR command

Usage notes

Examples

LIST DTCN or CADP command

List the programs and compile units that were disabled by the DISABLE CADP or DISABLE DTCN command.

Syntax diagram for the LIST DTCN or LIST CADP 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.

Syntax diagram for the LIST expression command
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

Examples

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.

Syntax diagram for the L prefix command
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

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;
...

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

LIST FREQUENCY command

Lists statement execution counts.

Syntax diagram for the LIST FREQUENCY command
*
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

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.

Syntax diagram for the LIST LAST command
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

Examples

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.

Syntax diagram for the LIST MONITOR command
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

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.

Syntax diagram for the LIST NAMES command
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

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.

Syntax diagram for the PL/I LIST ON command
pli_condition
A valid PL/I condition specification. If omitted, all currently defined ON command actions are listed.

Usage notes

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.

Syntax diagram for the LIST PROCEDURES command
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.

Syntax diagram for the LIST REGISTERS command
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

LIST STATEMENT NUMBERS command

Lists all statement or line numbers that are valid locations for an AT LINE or AT STATEMENT breakpoint.

Syntax diagram for the LIST STATEMENT NUMBERS command
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

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.

Syntax diagram for the LIST STATEMENTS command

Usage notes

Examples

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.

Syntax diagram for the LIST STORAGE command
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

Examples

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.

Syntax diagram for the LOAD command
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

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.

Syntax diagram for the LOADDEBUGDATA command
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

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.

Syntax diagram for the Memory command
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

Examples

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.

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.

Syntax diagram for the MONITOR command
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

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.

Syntax diagram for the M prefix command
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

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.

Syntax diagram for the COBOL MOVE command
reference
A valid Debug Tool COBOL reference.
literal
A valid COBOL literal.

Usage notes

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.

Syntax diagram for the NAMES DISPLAY command
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.

Syntax diagram for the NAMES EXCLUDE command
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

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.

Syntax diagram for the NAMES INCLUDE command
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

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.

Syntax diagram for the null command

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.

Syntax diagram for the PL/I ON command
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

Examples

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.

Syntax diagram for the PANEL 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:

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

Examples

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

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:

Syntax diagram for the simple COBOL PERFORM command
command
A valid Debug Tool command.

Repeating:

Syntax diagram for the repeating COBOL PERFORM command
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.

PLAYBACK commands

The PLAYBACK commands help you record and replay:

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.

Syntax diagram for the PLAYBACK ENABLE command
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: DATA is the default.
NODATA
Specifies that Debug Tool does not save information about your program.

Usage notes

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.

Syntax diagram for the PLAYBACK START command

Usage notes

The following commands are available while you replay recorded statements:

ALLOCATE command FIND command QQUIT command
CALL procedure command FREE command RETRIEVE command (full-screen mode)
CLEAR EQUATE IMMEDIATE command (full-screen mode) RUNTO command
CLEAR LOG null SCROLL command (full-screen mode)
CLEAR MONITOR PANEL command (full-screen mode) SET (most forms)
CLEAR PROCEDURE PERFORM command (COBOL)1 STEP command
COMMENT command PLAYBACK commands SYSTEM command (z/OS)
CURSOR command (full-screen mode) Prefix commands (full-screen mode) TSO command (z/OS)
Declarations (COBOL) PROCEDURE command USE command
DESCRIBE CUS QUERY command WINDOW command (full-screen mode)
DESCRIBE PROGRAMS QUIT command

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:

COMPUTE command (COBOL) LIST
DESCRIBE ATTRIBUTES MOVE command (COBOL) 2
DESCRIBE CURSOR MONITOR
EVALUATE command (COBOL) SET command (COBOL) 2
IF command (COBOL) SET AUTOMONITOR command

2 The target must be session variable.

The following commands are not available while you replay recorded statements:

ANALYZE command (PL/I) Declarations (C and C++) if command (C and C++)
Assignment command (assembler and disassembly) DECLARE command (PL/I) IF command (PL/I)
Assignment command (PL/I) DESCRIBE ENVIRONMENT INPUT command (C, C++, and COBOL)
AT command DISABLE command ON command (PL/I)
break command (C and C++) do/while command (C and C++) RUN command
CALL %DUMP command DO command (PL/I) SELECT command (PL/I)
CALL entry_name command (COBOL) ENABLE command SET INTERCEPT
CLEAR AT Expression command (C and C++) switch command (C and C++)
CLEAR DECLARE for command (C and C++) TRIGGER command
CLEAR ON GO command while command (C and C++)
CLEAR VARIABLES GOTO command

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.

Syntax diagram for the PLAYBACK FORWARD command

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.

Syntax diagram for the PLAYBACK BACKWARD 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.

Syntax diagram for the PLAYBACK STOP command

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.

Syntax diagram for the PLAYBACK DISABLE command
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 6. Source window prefix commands
AT Prefix command (full-screen mode) Defines a statement breakpoint through the Source window prefix area.
CLEAR prefix (full-screen mode) Clears a breakpoint through the Source window prefix area.
DISABLE prefix (full-screen mode) Disables a breakpoint through the Source window prefix area.
ENABLE prefix (full-screen mode) Enables a disabled breakpoint through the Source window prefix area.
L prefix command (full-screen mode) Displays the values of the variables on that line.
M prefix (full-screen mode) Adds the variables on that line to the Monitor window.
QUERY prefix (full-screen mode) Queries what statements have breakpoints through the Source window prefix area.
RUNTO prefix command (full-screen mode) Runs the program to the location that the cursor or statement identifier indicate in the Source window prefix area.
SHOW prefix command (full-screen mode) Specifies what relative statement or verb within the line is to have its frequency count shown in the suffix area.
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.

Syntax diagram for the PROCEDURE command
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

Examples

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.

Syntax diagram for the QUERY command
Notes:
  1. You can use this command in remote debug mode.
  2. Available only if the Dynamic Debug facility is installed.
  3. 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

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.

Syntax diagram for the prefix QUERY command

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.

Syntax diagram for the QUIT command
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

Examples

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.

Syntax diagram for the QQUIT command

Usage notes

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.

Syntax diagram for the RESTORE command
SETTINGS
Indicates that all SET values except the following values are to be restored:
BPS
Indicates that breakpoints and LOADDEBUGDATA (LDD) specifications are to be restored. The following breakpoints are restored:

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

Example

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

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.

Syntax diagram for the RETRIEVE 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

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.

Syntax diagram for the RUNTO command
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

Examples

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

Example

Run to the statement 67, where statement 67 is located in the Source window.

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.

Syntax diagram for the SCROLL command
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

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.

Syntax diagram for the PL/I SELECT command
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

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:

Syntax diagram for the SET ASSEMBLER command
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

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:

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:

Debug Tool assumes that you use one of the following instructions to call internal subroutines:

Syntax diagram for the SET ASSEMBLER STEPOVER command
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

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:

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:

Syntax diagram for the SET AUTOMONITOR command
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

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.

Syntax diagram for the SET CHANGE command
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

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.

Syntax diagram for the SET COLOR command
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.

Syntax diagram for the SET COUNTRY command
country_code
A valid two-letter set that identifies the country code used. The country code can have one of the following values:

Country codes cannot be truncated.

Usage notes

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.

Syntax diagram for the SET DBCS command
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

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.

Syntax diagram for the SET DEFAULT LISTINGS command
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

Examples

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.

Syntax diagram for the SET DEFAULT SCROLL command
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.

Syntax diagram for the SET DEFAULT VIEW command
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

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.

Syntax diagram for the SET DEFAULT WINDOW command
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:

Syntax diagram for the SET DISASSEMBLY command
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

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:

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.

Syntax diagram for the SET DYNDEBUG command
ON
Activates the Dynamic Debug facility.
OFF
Deactivates the Dynamic Debug facility.

Usage notes

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.

Syntax diagram for the SET ECHO command
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

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.

Syntax diagram for the SET EQUATE command
identifier
An identifier that is valid in the current programming language. The maximum length of the identifier is:

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

Examples

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.

Syntax diagram for the SET EXECUTE command
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.

Syntax diagram for the SET FIND BOUNDS 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.
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

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.

Syntax diagram for the SET FREQUENCY command
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

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.

Syntax diagram for the SET HISTORY command
ON
Maintains the history of invocations.
OFF
Suppresses the history of invocations.
integer
The number of entries kept in the history table.

Usage notes

Examples

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.

Syntax diagram for the SET IGNORELINK command
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

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.

Syntax diagram for the C and C++ SET INTERCEPT command
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

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.

Syntax diagram for the COBOL SET INTERCEPT command
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:

Usage notes

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.

Syntax diagram for the COBOL SET INTERCEPT command in remote debug mode
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.

Syntax diagram for the SET KEYS command
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.

Syntax diagram for the SET LDD command
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

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.

Syntax diagram for the SET LIST command
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.

Syntax diagram for the SET LOG command
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.

Syntax diagram for the SET LOG NUMBERS command
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.

Syntax diagram for the SET LONGCUNAME command
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

Examples

SET MONITOR command

Controls the format and layout of variable names and values displayed in the Monitor window.

Syntax diagram for the SET MONITOR command
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

SET MSGID command

Controls whether the Debug Tool messages are displayed with the message prefix identifiers. The initial setting is OFF.

Syntax diagram for the SET MSGID command
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.

Syntax diagram for the SET NATIONAL LANGUAGE command
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:

For compatibility with the previous release of INSPECT for C/370 and PL/I:

Usage notes

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.

Syntax diagram for the SET PACE command
number
A decimal number between 0 and 9999; it must be a multiple of 0.5.

Usage notes

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.

Syntax diagram for the SET PFKEY command
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.

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.

Syntax diagram for the SET PROGRAMMING LANGUAGE command
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

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.

Syntax diagram for the SET PROMPT command
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.

Syntax diagram for the SET QUALIFY command
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

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.

Syntax diagram for the SET REFRESH command
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.

Syntax diagram for the SET RESTORE command
SETTINGS
Indicates that SET values and WINDOW SIZE and WINDOW CLOSE settings are to be restored. The following SET values are not restored:
BPS
Indicates that breakpoints and LOADDEBUGDATA (LDD) specifications are to be restored. The following breakpoints are restored:
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.

Syntax diagram for the SET REWRITE command
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.

Syntax diagram for the SET REWRITE command
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.

Syntax diagram for the SET SAVE command
SETTINGS
Indicates that SET values and WINDOW SIZE and WINDOW CLOSE settings are to be saved. The following SET values are not saved:
BPS
Indicates that breakpoints and LOADDEBUGDATA (LDD) specifications are to be saved. The following breakpoints are saved:
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.

SET SCREEN command (full-screen mode)

Controls how information is displayed on the screen. The initial setting is ON.

Syntax diagram for the SET SCREEN command
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

Examples

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

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.

Syntax diagram for the SET SCROLL DISPLAY command
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.

Syntax diagram for the SET SEQUENCE command
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.

Syntax diagram for the SET SOURCE command
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

Examples

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.

Syntax diagram for the SET SUFFIX command
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.

Syntax diagram for the SET TEST command
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

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

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.

Syntax diagram for the C, C++, COBOL, and PL/I SET WARNING command
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

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.

Syntax diagram for the COBOL SET command
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

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.

Syntax diagram for the SHOW command
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

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:

Syntax diagram for the STEP command
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

Examples

STORAGE command

The STORAGE command enables you to alter storage. You must be careful when you alter storage because the results can be unpredictable.

Syntax diagram for the STORAGE command
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:

Usage notes

Examples

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.

Syntax diagram for the C and C++ SWITCH command
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

Examples

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.

Syntax diagram for the SYSTEM command
system_command
A valid TSO system command or CLIST name that does not require a parameter.

Usage notes

Examples

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.

Syntax diagram for the TRIGGER command
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:

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:

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

Examples

In the first example, note the following differences

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.

Syntax diagram for the TSO command
tso_command
A valid TSO system command or CLIST name that does not require a parameter.

Usage notes

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.

Syntax diagram for the USE command
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

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.

Syntax diagram for the disassembly, C, and C++ while command
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

Examples

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

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.

Syntax diagram for the WINDOW CLOSE command
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.

Syntax diagram for the WINDOW OPEN command
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.

Syntax diagram for the WINDOW SIZE command
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

Examples

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.

Syntax diagram for the WINDOW SWAP 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.

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.

Syntax diagram for the WINDOW ZOOM command
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;

1.
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.


Terms of use | Feedback

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