# Debug commands supported by the System i5 Debugger

Note:The following information is a subset of the debug command documentation available from the System i5 Information Center located at http://publib.boulder.ibm.com/iseries/. Command syntax is shown in the following format:

> COMMAND variable or expression
> or
> COMMAND variable or expression [optional parameters]

For complete details, please consult the Information Center documentation.

The Console pane provides a command line entry area for debugging commands supported by the ILE system debugger as provided by the Submit Debug Commands(QteSubmitDebugCommand)API. The results of the command line entry appear in the console log.

The Submit Debug Command (QteSubmitDebugCommand) API allows a client program to issue debug language statements. Debug language statements permit client programs to enter breakpoints, run one or more statements of the program under investigation (step), and evaluate expressions. Watch conditions may also be entered to cause a breakpoint when the contents at a specified storage location are changed.

The Submit Debug Command API accepts the debug language statements of ATTR, BREAK, CLEAR, EVAL, QUAL, STEP, TBREAK, and WATCH.

ATTR

The variable appearing in an ATTR statement is found in the debug symbol table. The symbol table information for the variable is returned.

The following example shows an ATTR statement:

> ATTR variable

The locality of variables that appear in an ATTR statement is defined by the qualify statement that was most recently run. The program calling this API is advised to issue a qualify statement that defines the stop position when program operation is suspended.

BREAK

The BREAK statement allows a programmer to enter a breakpoint. Breakpoints are entered on the program under investigation. When the program under investigation encounters a breakpoint, operation is suspended.

The following examples show BREAK statements:

> BREAK position
> BREAK position [WHEN expression]

The position marks where program operation is suspended when a breakpoint is encountered. Line numbers are used to identify the position when the break statement is entered. The line number entered is mapped to a statement by the Submit Debug Command API. A breakpoint causes the program to stop just before the break statement is run.

Unconditional and conditional breakpoints can be entered. An unconditional breakpoint is entered by issuing the first form of the break statement.

> BREAK position

A line number is entered for the position. Line numbers are associated with each view in that they identify the lines of source in a view. Line numbers are assigned sequentially beginning with line one.

A conditional breakpoint is entered by issuing the second form of the break statement.

> BREAK position [WHEN expression]

The position of a conditional breakpoint is assigned in the same way as the position in an unconditional breakpoint. A line number is entered for the position.

The condition of a conditional breakpoint is the expression following the reserved word WHEN. The result of the expression must have a Boolean or a logical value when evaluated. The expression is interpreted before the statement on which the breakpoint was entered is run. If the value of the expression is TRUE, operation of the program investigation is suspended. If the value of the expression is FALSE, operation continues without interruption.

The locality of variables used in the conditional expression is defined by the line number that defines the position.

A breakpoint can be replaced by entering another breakpoint using the same position. The most recent breakpoint entered on a position is the active breakpoint.

BREAK may be replaced by the reserved word AT in the statement that defines the break statement.

> AT position
> AT position [WHEN expression]

For threaded applications, breakpoints that are specified with the break statement are global to all threads in the job being debugged. These are called job breakpoints. Thread-specific breakpoints are set with the tbreak statement. A job may not have both a job breakpoint and thread breakpoints at the same position. When a job breakpoint is in effect and a thread breakpoint is specified, the job breakpoint is replaced. When thread breakpoints are in effect and a job breakpoint is specified, the thread breakpoints are replaced.

Clear

The clear statement enables a programmer to remove a particular breakpoint or all breakpoints in a program. Particular breakpoints are identified by the number of the line on which they are active. All breakpoints in a program are designated by the keyword PGM. The clear statement is also used to clear one or all watch conditions. The keyword WATCH followed by the ALL keyword clears all watch conditions. If a watch number is specified after the WATCH keyword, only the watch represented by that watch number is cleared.

The following examples show clear statements:

> CLEAR position
> CLEAR PGM
> CLEAR WATCH ALL
> CLEAR WATCH watch number

For threaded applications, if a thread breakpoint is in effect at the position specified, it is cleared in the current thread only. If the breakpoint is a job breakpoint, it is cleared for the job. When the clear statement with the PGM keyword is specified, it will remove all job and thread breakpoints.

Evaluate

The expression appearing in an evaluate statement is evaluated, and the value of the expression is returned. The value of an expression is formatted according to the expression type.

The following example shows an evaluate statement:

> EVAL -&gt expression -&gt [formatting option]

An evaluate statement allows a programmer to display the value of an expression or an aggregate, or to alter the value of a variable. The precise definition of what can be displayed or altered is dependent on the language of the module being debugged.

Variables can be displayed or altered when program processing is suspended. Program operation is temporarily suspended as a result of encountering a breakpoint or completing a step statement. It is also suspended when a watch condition is satisfied.

Variables are formatted according to their type recorded in the high-level language (HLL) symbol table, and according to the language of the module being debugged. Formats available include integer, hexadecimal, exponential, and address, among others.

Variables also may be formatted using the formatting option. The formatting option has the general form of: <, format code >, <, length >, such as EVAL STRING :s 50.

The locality of variables that appear in an evaluate statement is defined by the qualify statement that was most recently run. The program calling this API is advised to issue a qualify statement that defines the stop position when program operation is suspended.

EVAL may be replaced by the reserved word LIST in the statement that defines the evaluate statement.

> LIST -&gt expression -&gt [formatting option]

For threaded applications, the EVAL statement is run in the current thread.

Locality is the term used to describe the range over which an entity may be referred to in a module. The terms locality and scope are synonymous. By this definition, the locality of an entity is always confined to the compilation unit in which it was declared.

Entity is a formal way of describing all things that can be declared in a module. Variables, procedures, labels, types, and constants are entities.

The locality of an entity is defined by the block in which it is declared. An entity is visible in the block in which it is declared and all subordinate blocks. A variable can be referred to in the block in which it is declared.

An entity may be declared in a block that encloses other blocks. The entity declared in the outer, enclosing block is visible in inner blocks if the name does not collide with other entities in inner blocks. A variable declared in an outer block can be referred to in an inner block if no variable of the same name is declared in the inner block.

To fully qualify a particular locality in a program, both program and module must be identified.

Qualify

The qualify statement permits a programmer to define the locality of variables that appear in succeeding evaluate statements. Locality is defined by the line number operand on the qualify statement. The locality assigned is that block in which the line number appears.

The following example shows a qualify statement:

> QUAL position

The locality assigned when a qualify statement is issued remains in effect until the next qualify statement is issued. The Submit Debug Command API keeps the locality assigned for the purpose of evaluating expressions. If you use the Submit Debug Command API, you should issue the qualify statement whenever program operation is suspended. Use the line number of the stopped position to identify the current locality. In this way, programmers may issue several evaluate statements that refer to variables that are defined in the locality of the stopped position.

For threaded applications, the QUAL statement is run in the current thread.

Step

The step statement permits a programmer to run one or more statements of the program under investigation for testing purposes. The program being tested runs the number of statements specified in the statement-count operand. Operation of the program under test is suspended at completion of the step statement.

The following example shows a step statement:

> STEP [statement-count] [step-type]

If no value is entered for the statement-count, one statement is run.

The valid step-types are OVER, INTO, and OUTOF. The reserved words OVER and INTO direct the source debugger to step over or into procedures, respectively.

If OVER appears in a step statement, the source debugger does not suspend operation in any procedures that are called unless a breakpoint is encountered. Procedures and functions are run without interruption.

The INTO reserved word directs the source debugger to stop in procedures that are called.

The OUTOF reserved word directs the source debugger to run to the statement after the call of the current procedure. That is, it will run to the statement that the current procedure returns to.

If no step type is entered on the step statement, OVER is assumed.

There are some step limitations. The following code cannot be entered using the step statement:

- Procedures in modules that have no debug data.
- Modules that are optimized at level 40.

For threaded applications, the STEP statement is run in the current thread. Each thread can step independently of each other, at the same time.

TBreak

The TBREAK statement permits a programmer to enter a breakpoint for the current thread. Breakpoints are entered on the program under investigation. When the program under investigation encounters a breakpoint in the thread, operation is suspended. The tbreak statement has the same format and operation as the break statement.

Each thread in a threaded application may have a different thread breakpoint at the same position. Job breakpoints and thread breakpoints cannot coexist.

A tbreak statement entered at the same position as a tbreak that was specified earlier in the same thread is replaced by the new thread breakpoint.

A tbreak statement entered at the same position as a job breakpoint that was specified earlier replaces the job breakpoint with a thread breakpoint.

A break statement entered at the same position as thread breakpoints that were specified earlier replaces all thread breakpoints at that position with a job breakpoint that is in effect for all threads.

Watch

The watch statement permits a programmer to request a breakpoint when the content of a specified storage location is changed from its current value. After the watch condition is successfully set, a change to the content of the watched storage location causes program operation to be suspended. Then the Program Stop Handler exit program that is specified on the Start Source Debug API is called.

The following shows the syntax of the watch statement:

> WATCH expression [watch length]

The expression is used to determine the address of the storage location to watch. The expression must resolve to a value (that is, a location that can be assigned to). If an expression is specified that is not supported, error code CPF7E62 is returned. The scope of the expression variables in a watch statement is defined by the QUAL debug language statement that was most recently issued.

The length of the watch comparison operation is the same as the expression type length, or the length specified with the optional watch length parameter. For example, if a 4-byte binary integer is specified without the watch length parameter, the comparison length is 4 bytes. If the watch length parameter is specified, it overrides the length of the expression in determining the watch length. The watch length specification format is a colon character followed by the length in bytes to watch. For example, the watch command below would watch 2 bytes starting at the first byte of variable i:

> watch i : 2

The watch length must be in the range 1 through 128 bytes. If the watch length is not valid, error code CPF7E63 is returned.

The maximum number of watches that can be active across the entire system is guaranteed to be at least 128, but may range up through 256, depending on how the watched storage is mapped by the system. This includes dedicated service tools (DST) watches. Exceeding this number results in error code CPF8E2C being returned. A user session may have as many watches as are available.

There are some restrictions on overlapping watch locations. If any of the following conditions are true, error code CPF8E2B is returned:

- Watches in same job: Two watch locations may not overlap in any way.
- Watches in different jobs: Two watch locations may not start at the same storage address. Otherwise, overlap is permitted.

A watch condition is cleared by using the CLEAR debug language statement.

It is important to understand that the watch statement establishes the watched storage location address when the watch statement is entered, and it does not change. This can cause misleading results if a temporary storage location is watched and that storage location is reused while the application is running. An example of this is the automatic storage of an ILE C procedure, which can be reused if the procedure ends.

The WATCH debug statement cannot be specified with any other debug statement, including another WATCH statement.

For threaded applications, the WATCH statement is run in the current thread. The address watched is global to all threads. Any thread changing a watched location will cause a breakpoint in that thread.