Rational Developer for System z, Version 7.6

Entering Debug Tool commands

Debug Tool commands can be issued in three modes: full-screen, line, and batch. Some Debug Tool commands are valid only in certain modes or programming languages. Unless otherwise noted, Debug Tool commands are valid in all modes, and for all supported languages.

For input typed directly at the terminal, input is free-form, optionally starting in column 1.

To separate multiple commands on a line, use a semicolon (;). This terminating semicolon is optional for a single command, or the last command in a sequence of commands.

For input that comes from a commands file or USE file, all of the Debug Tool commands must be terminated with a semicolon, except for the C block command.

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

Using uppercase, lowercase, and DBCS in Debug Tool commands

The character set and case vary with the double-byte character set (DBCS) or the current programming language setting in a Debug Tool session.

DBCS

When the DBCS setting is ON, you can specify DBCS characters in the following portions of all the Debug Tool commands:

When the DBCS setting is OFF, double-byte data is not correctly interpreted or displayed. However, if you use the shift-in and shift-out codes as data instead of DBCS indicators, you should issue SET DBCS OFF.

If you are debugging in full-screen mode and your terminal is not DBCS capable, the SET DBCS ON command is not available.

Character case and DBCS in C and C++

For both C and C++, Debug Tool sets the programming language to C. When the current programming language setting is C, the following rules apply:

Character case in COBOL and PL/I

When the current programming language setting is not C, commands can generally be either uppercase, lowercase, or mixed. Characters in the range a through z are automatically converted to uppercase except within comments and quoted literals. Also, in PL/I, only "|" and "¬" can be used as the boolean operators for OR and NOT.

Abbreviating Debug Tool keywords

When you issue the Debug Tool commands, you can truncate most command keywords. You cannot truncate reserved keywords for the different programming languages, system keywords (that is, SYS, SYSTEM, or TSO) or special case keywords such as BEGIN, CALL, COMMENT, COMPUTE, END, FILE (in the SET INTERCEPT and SET LOG commands), GOTO, INPUT, LISTINGS (in the SET DEFAULT LISTINGS command), or USE. In addition, PROCEDURE can only be abbreviated as PROC.

The system keywords, and COMMENT, INPUT, and USE keywords, take precedence over other keywords and identifiers. If one of these keywords is followed by a blank, it is always parsed as the corresponding command. Hence, if you want to assign the value 2 to a variable named TSO and the current programming language setting is C, the "=" must be abutted to the reference, as in "TSO<no space>= 2;" not "TSO<space>= 2;". If you want to define a procedure named USE, you must enter "USE<no space>: procedure;" not "USE<space>:: procedure;".

When you truncate, you need only enter enough characters of the command to distinguish the command from all other valid Debug Tool commands. You should not use truncations in a commands file or compile them into programs because they might become ambiguous in a subsequent release. The following shows examples of Debug Tool command truncations:

If you enter the following command... It will be interpreted as...
A 3 AT 3
G GO
Q B B QUALIFY BLOCK B
Q Q QUERY QUALIFY
Q QUIT

If you specify a truncation that is also a variable in your program, the keyword is chosen if this is the only ambiguity. For example, LIST A does not display the value of variable A, but executes the LIST AT command, listing your current AT breakpoints. To display the value of A, issue LIST (A).

In addition, ambiguous commands that cannot be resolved cause an error message and are not performed. That is, there are two commands that could be interpreted by the truncation specified. For example, D A A; is an ambiguous truncation since it could either be DESCRIBE ATTRIBUTES a; or DISABLE AT APPEARANCE;. Instead, you would have to enter DE A A; if you wanted DESCRIBE ATTRIBUTES a; or DI A A; if you wanted DISABLE AT APPEARANCE;. There are, of course, other variations that would work as well (for example, D ATT A;).

Entering multiline commands in full-screen

If you need to use more than one line when entering a command, you must use a continuation character.

When you are entering a command in interactive mode, the continuation character must be the last nonblank character in each line that is to be continued. In the following example:

LIST (" this is a very very very vvvvvvvvvvvvvvvvvvvvvvvvvvvvv -
very long string");

the continuation character is the single-byte character set (SBCS) hyphen (-).

If you want to end a line with a character that would be interpreted as a continuation character, follow that character with another valid nonblank character. For example, in C and C++, if you want to enter "i--", you could enter "(i--)" or "i--;". When the current programming language setting is C and C++, the backslash character (\) can also be used.

When Debug Tool is awaiting the continuation of a command in full-screen mode, you receive a continuation prompt of "MORE..." until the command is completely entered and processed.

Entering multiline commands in a commands file

The rules for line continuation when input comes from a commands file are language-specific:

Entering multiline commands without continuation

You can enter the following command parts on separate lines without using the SBCS hyphen (-) continuation character:

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

Using blanks in Debug Tool commands

Blanks cannot occur within keywords, identifiers, and numeric constants; however, they can occur within character strings. Blanks between keywords, identifiers, or constants are ignored except as delimiters. Blanks are required when no other delimiter exists and ambiguity is possible.

Entering comments in Debug Tool commands

Debug Tool lets you insert descriptive comments into the command stream (except within constants and other comments); however, the comment format depends on the current programming language. The entire line, including comments and delimeters, must not extend beyond column 72.

For C++ only: Comments in the form "//" are not processed by Debug Tool in C++.

Comments are most helpful in file input. For example, you can insert comments in a USE file to explain and describe the actions of the commands.

Using constants in Debug Tool commands

Constants are entered as required by the current programming language setting. Most constants defined for each of the supported HLLs are also supported by Debug Tool.

Debug Tool allows the use of hexadecimal addresses in COBOL and PL/I.

The COBOL H constant is a fullword address value that can be specified in hex using numeric-hex-literal format (hexadecimal characters only, delimited by either quotation marks (") or apostrophes (') and preceded by H). The value is right-justified and padded on the left with zeros.

Note:
The H constant can only be used where an address or POINTER variable can be used. You can use this type of constant with the SET command. For example, to assign a hexadecimal value of 124BF to the variable ptr, specify:
SET ptr TO  H"124BF";
The COBOL hexadecimal notation for alphanumeric literals, such as MOVE X'C1C2C3C4' TO NON-PTR-VAR, must be used for all other situations where a hexadecimal value is needed.

The PL/I PX constant is a hexadecimal value, delimited by apostrophes (') and followed by PX. The value is right-justified and can be used in any context in which a pointer value is allowed. For example, to display the contents at a given address in hexadecimal format, specify:

LIST STORAGE ('20CD0'PX);

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

Getting online help for Debug Tool command syntax

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.

For example, in full-screen mode, enter on the command line:

?
WINDOW ?
WINDOW CLOSE ?
WINDOW CLOSE SOURCE

Now reopen the Source window with:

WINDOW OPEN SOURCE

to see the results.

The Debug Tool SYSTEM and TSO commands followed by ? do not invoke the syntax help; instead the ? is sent to the host as part of the system command. The COMMENT command followed by ? also does not invoke the syntax help.


Terms of use | Feedback

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