Rational Developer for System z, Version 7.6

Debug Tool built-in functions

Debug Tool provides you with several built-in functions which allow you to manipulate variables. All Debug Tool built-in function names begin with a percent sign (%).

The table below summarizes the Debug Tool built-in functions. Unless otherwise indicated, the functions can be used with all supported languages.

Debug Tool built-in function Returns
%DEC (assembler, disassembly, and non-Language Environment COBOL) Decimal value of an operand.
%GENERATION (PL/I) A specific generation of a controlled variable
%HEX Hexadecimal value of an operand
%INSTANCES (C, C++, and PL/I) Maximum value of %RECURSION for a block
%RECURSION (C, C++, and PL/I) An automatic variable or a parameter in a specific instance of a recursive procedure
%WHERE (assembler, disassembly, and non-Language Environment COBOL) A string indicating the address of the operand.

%DEC (assembler, disassembly, and non-Language Environment COBOL)

Returns the decimal value of an operand.

Syntax diagram for the %DEC built-in function
expression
A valid assembler, disassembly, or non-Language Environment COBOL expression.

Examples

Assuming register R1 contains the value 14, to display the value of the expression R1+2 in decimal, enter the following command:

LIST %DEC(R1+2);

The Log window displays the value 16.

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

%GENERATION (PL/I)

Returns a specific generation of a controlled variable in your program.

Syntax diagram for the PL/I %GENERATION built-in function
reference
A controlled variable.
expression
The generation number n of a controlled variable x, where:
1 <= n <= ALLOCATION(x)

To return the oldest instance of x, specify:

%GENERATION(x,1)

To return the most recent instance of x, specify:

%GENERATION(x,ALLOCATION(x))

Usage notes

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

%HEX

Returns the hexadecimal value of an operand.

Syntax diagram for the %HEX built-in function
reference
One of the following:

Examples

C and C++: To display the internal representation of the packed decimal variable zvar1 whose external representation is 235, enter the following command.

LIST %HEX(zvar1);

The Log window displays the hexadecimal string 235C.

COBOL: To display the external representation of the packed decimal pvar3, defined as PIC 9(9), from 1234 as its hexadecimal (or internal) equivalent, enter the following command.

LIST %HEX (pvar3);

The Log window displays the hexadecimal string 01234F.

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

%INSTANCES (C, C++, and PL/I)

Returns the maximum value of %RECURSION (the most recent recursion number) for a given block.

Syntax diagram for the C, C++, and PL/I %INSTANCES built-in function
reference
An automatic variable or a subroutine parameter. If necessary, you can use qualification to specify the variable.

%INSTANCES can be used like a Debug Tool variable.

Usage notes

Debug Tool does not support the %INSTANCES built-in function for Enterprise PL/I programs.

You cannot use the %INSTANCES built-in function while you replay recorded steps.

Examples

C and C++:

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

%RECURSION (C, C++, and PL/I)

Returns a specific instance of an automatic variable or a parameter in a recursive procedure.

Syntax diagram for the C, C++, and PL/I %RECURSION built-in function
reference
An automatic variable or a subroutine parameter. If necessary, you can use qualification to specify the variable.
expression
The recursion number of the variable or parameter.

To return the oldest recursion of x, specify:

%RECURSION(x,1)

To return the most recent recursion of x, specify:

%RECURSION(x,%INSTANCES(x))

Usage notes

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

%WHERE (assembler, disassembly, and non-Language Environment COBOL)

Returns a string that describes the named area (if any) whose address is specified as the operand. %WHERE can be used only as the outermost expression in the LIST command.

Syntax diagram for the assembler and disassembly %WHERE built-in function
expression
An expression that evaluates to a hexadecimal value that is one to four bytes in length.

The following rules are used to evaluate the value of the expression, in the order listed:

  1. If the expression value is less than 4096, a decimal number is returned.
  2. If the expression value is an address within any known compile unit, the name of the compile unit with a hexadecimal offset is returned.
  3. If the expression value is within 4095 bytes of the value in a general register and a USING is in effect for that register, the name of the DSECT that corresponds to the USING instruction with a hexadecimal offset is returned.
  4. A hexadecimal number representing the expression value is returned.

Although this function can be used only within an assembler, disassembly, or non-Language Environment COBOL compile unit, the expression can evaluate to a compile unit in any language.

Usage note

You cannot nest %WHERE into another expression. For example, the following command is not valid:

LIST %WHERE(X'14B0')||'ABC'

Examples


Terms of use | Feedback

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