Rational Developer for System z, Version 7.6

Debug Tool variables

Debug Tool reserves several variables for its own information. These Debug Tool variable names begin with a percent sign (%), to distinguish them from program variables. You can access Debug Tool variables while testing programs in any supported language.

You can use all Debug Tool variables in expressions. Additionally, the variables %EPRn., %FPRn., %GPRn., and %LPRn. (representing the types of registers) can be modified, as shown in the COBOL example below.

MOVE name_table TO %GPR5;
Note:
Use caution when assigning new values to registers. Important program information can be lost. Do not modify the base register.

To display the value of a Debug Tool variable, use the LIST command, as shown in the example below.

LIST %GPR15

The table below summarizes the Debug Tool variables.

Debug Tool variable Value
%ADDRESS Address of the location where your program was interrupted
%AMODE Current AMODE of the suspended program
%BLOCK Name of the current block
%CAAADDRESS Address of the CAA control block associated with the suspended program
%CC (assembler and disassembly only) (Assembler and disassembly only) Condition code from current PSW
%CONDITION Name or number of the condition when Debug Tool is entered because of an AT OCCURRENCE
%COUNTRY Current country code
%CU Name of the primary entry point of the current compile unit
%EPA Address of the primary entry point in the current compile unit
%EPRn or %EPRHn (%EPRHn assembler and disassembly only) (Assembler, disassembly, C and C++, and PL/I only) Extended-precision floating-point registers
%EPRBn (assembler and disassembly only) (Assembler and disassembly only) Extended-precision floating-point registers in binary format
%EPRDn (assembler and disassembly only) (Assembler and Disassembly only) Extended-precision floating-point registers in decimal format
%FPRn or %FPRHn (%FPRHn assembler and disassembly only) Single-precision floating-point registers in hexadecimal format
%FPRBn (assembler and disassembly only) (Assembler and Disassembly only) Single-precision floating-point registers in binary format
%FPRDn (assembler and disassembly only) (Assembler and Disassembly only) Single-precision floating-point registers in decimal format
%GPRn 32-bit General Purpose Registers at the point of interruption in a program
%GPRGn 64-bit General Purpose Registers at the point of interruption in a program
%HARDWARE Type of hardware where the application is running
%LINE or %STATEMENT Current source line number
%LOAD Name of the load module of the current program, or an asterisk (*)
%LPRn or %LPRHn (%LPRHn assembler and disassembly only) Double-precision floating-point registers in hexadecimal format
%LPRBn (assembler and disassembly) (Assembler and Disassembly only) Double-precision floating-point registers in binary format
%LPRDn (assembler and disassembly) (Assembler and Disassembly only) Double-precision floating-point registers in decimal format
%NLANGUAGE National language currently in use
%PATHCODE Integer identifying the type of change occurring when the program flow reaches a point of discontinuity, and the path condition is raised
%PLANGUAGE Current programming language
%PROGMASK (assembler and disassembly only) (Assembler and disassembly only) Program mask from current PSW
%PROGRAM Equivalent to %CU
%PSW (assembler and disassembly only) (Assembler and disassembly only) Current Program Status Word
%RC Return code from the most recent Debug Tool command
%RSTDSETS A value of 1 if user settings have been restored and 0 otherwise
%RUNMODE String identifying the presentation mode of Debug Tool
%STATEMENT Equivalent to %LINE
%SUBSYSTEM Name of the underlying subsystem, if any, where the program is running
%SYSTEM Name of the operating system supporting the program

You can access Debug Tool variables even when they have no intrinsic meaning in your operating system or language.

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

%ADDRESS

Contains the address of the location where the program has been interrupted.

For COBOL only:

%AMODE

Contains the current AMODE of the suspended program: 24, 31, or 64. For COBOL programs, the value is always 31.

%BLOCK

Contains the name of the current block. The block name might not be unique within a compile unit.

To display the name of the current block, use one of the following commands:

To change the current block, use the SET QUALIFY command.

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

%CAAADDRESS

Contains the address of the Language Environment CAA control block associated with the suspended program. When you are running without the Language Environment run time, the value NONE is returned.

%CC (assembler and disassembly only)

Contains the condition code portion of the current PSW.

%CONDITION

Contains the name or number of the condition when Debug Tool is entered because of an AT OCCURRENCE.

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

%COUNTRY

Contains the current country code.

%CU

Contains the name of the primary entry point of the current compile unit.

To change the current compile unit, use the SET QUALIFY command.

%CU is equivalent to %PROGRAM.

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

%EPA

Contains the address of the primary entry point of the currently interrupted program. If you are replaying recorded statements, the %EPA variable contains the name of the current location.

Usage note

The value of %EPA is valid only in programs that adhere to standard linkage conventions for R13, R14, and R15.

%EPRn or %EPRHn (%EPRHn assembler and disassembly only)

(%EPR0 , %EPR1, %EPR4, %EPR5, %EPR8, %EPR9, %EPR12, and %EPR13. %EPRH0 , %EPRH1, %EPRH4, %EPRH5, %EPRH8, %EPRH9, %EPRH12, and %EPRH13.)

Represent the extended-precision floating-point registers in hexadecimal format.

To modify one of these registers, assign a value to the associated %EPRn or %EPRHn variable.

%EPRn and %EPRHn cannot be used as the target of an assignment while debugging Enterprise PL/I programs.

You cannot use the %EPRn or %EPRHn variable while you are replaying recorded statements.

Usage note

For assembler and disassembly, the LIST %EPRn command displays values in hexadecimal but the LIST %EPRHn command displays values as hexadecimal floating point.

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

%EPRBn (assembler and disassembly only)

(%EPRB0 , %EPRB1, %EPRB4, %EPRB5, %EPRB8, %EPRB9, %EPRB12, and %EPRB13.)

Represent the extended-precision floating-point registers in binary format.

To modify one of these registers, assign a value to the associated %EPRBn variable.

If 64-bit hardware is not present, these variables are not supported. Any reference to them in such an environment will result in an "undefined symbol" message.

You cannot use the %EPRBn variable while you are replaying recorded statements.

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

%EPRDn (assembler and disassembly only)

(%EPRD0 , %EPRD1, %EPRD4, %EPRD5, %EPRD8, %EPRD9, %EPRD12, and %EPRD13.)

Represent the extended-precision floating-point registers in decimal format.

To modify one of these registers, assign a value to the associated %EPRDn variable.

If both Decimal Floating Point and 64-bit hardware are not present, these variables are not supported. Any reference to them in such an environment will result in an "undefined symbol" message.

You cannot use the %EPRDn variable while you are replaying recorded statements.

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

%FPRn or %FPRHn (%FPRHn assembler and disassembly only)

(%FPR0, %FPR1, %FPR2, %FPR3, %FPR4, %FPR5, %FPR6, %FPR7, %FPR8, %FPR9, %FPR10, %FPR11, %FPR12, %FPR13, %FPR14, and %FPR15. %FPRH0, %FPRH1, %FPRH2, %FPRH3, %FPRH4, %FPRH5, %FPRH6, %FPRH7, %FPRH8, %FPRH9, %FPRH10, %FPRH11, %FPRH12, %FPRH13, %FPRH14, and %FPRH15.)

Represent single-precision floating-point registers in hexadecimal format.

To modify one of these registers, assign a value to the associated %FPRn or %FPRHn variable.

%FPRn and %FPRHn cannot be used as the target of an assignment while debugging Enterprise PL/I programs.

Usage note

For assembler and disassembly, the LIST %FPRn command displays values in hexadecimal, but for the LIST %FPRHn command, values are listed as hexadecimal floating point.

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

%FPRBn (assembler and disassembly only)

(%FPRB0, %FPRB1, %FPRB2, %FPRB3, %FPRB4, %FPRB5, %FPRB6, %FPRB7, %FPRB8, %FPRB9, %FPRB10, %FPRB11, %FPRB12, %FPRB13, %FPRB14, and %FPRB5.)

Represent single-precision floating-point registers in binary format.

To modify one of these registers, assign a value to the associated %FPRBn variable.

If 64-bit hardware is not present, these variables are not supported. Any reference to them in such an environment will result in an "undefined symbol" message.

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

%FPRDn (assembler and disassembly only)

(%FPRD0, %FPRD1, %FPRD2, %FPRD3, %FPRD4, %FPRD5, %FPRD6, %FPRD7, %FPRD8, %FPRD9, %FPRD10, %FPRD11, %FPRD12, %FPRD13, %FPRD14, and %FPRD15.)

Represent single-precision floating-point registers in decimal format.

To modify one of these registers, assign a value to the associated %FPRDn variable.

If both Decimal Floating Point and 64-bit hardware are not present, these variables are not supported. Any reference to them in such an environment will result in an "undefined symbol" message

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

%GPRn

(%GPR0 to %GPR15.)

Represent 32-bit General Purpose Registers at the point of interruption in a program.

To modify one of these registers, assign a value to the associated %GPRn variable.

Usage notes

C and C++ only:

Examples

COBOL:

MOVE name_table TO %GPR15;

C and C++:

%GPR15=name_table;

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

%GPRGn

(%GPRG0 to %GPRG15.)

Represent 64-bit General Purpose Registers at the point of interruption in a program.

To modify one of these registers, assign a value to the associated %GPRGn variable.

Usage notes

Examples

Assembler:

LIST %GPRG0;
%GPRG0 = 12;

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

%HARDWARE

Identifies the type of hardware where the application program is running. A possible value is: 370/ESA.

%LINE or %STATEMENT

Contains the current line number.

If the current statement is not the first statement on the line, then the line number is followed by a period and the number of the statement with the line. For example, if %LINE = 4.3, then the current statement is the third statement on the fourth source line.

If the program is at the entry or exit of a block, then %LINE contains ENTRY or EXIT, respectively.

If the line number cannot be determined (for example, a run-time line number does not exist or the address where the program is interrupted is not in the program), then %LINE contains an asterisk (*).

For COBOL, %LINE does not return a relative verb (within the line) for labels.

%LINE is equivalent to %STATEMENT.

In the disassembly view, %LINE and %STATEMENT are not supported.

%LOAD

If the current program is part of a fetched or called load module, then %LOAD contains the name of the load module.

If the current program is in the load module that was initially loaded, then %LOAD contains an asterisk (*).

Debug Tool uses the value of %LOAD when you make an unqualified reference to a program or variable.

To change the current load module, use the SET QUALIFY command.

When the Dynamic Debug facility is deactivated (by entering the SET DYNDEBUG OFF command) or SVC screening is disabled2, Debug Tool does not recognize load modules that have been loaded by the MVS LOAD service.

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

%LPRn or %LPRHn (%LPRHn assembler and disassembly only)

(%LPR0, %LPR1, %LPR2, %LPR3, %LPR4, %LPR5, %LPR6, %LPR7, %LPR8, %LPR9, %LPR10, %LPR11, %LPR12, %LPR13, %LPR14, and %LPR15. %LPRH0, %LPRH1, %LPRH2, %LPRH3, %LPRH4, %LPRH5, %LPRH6, %LPRH7, %LPRH8, %LPRH9, %LPRH10, %LPRH11, %LPRH12, %LPRH13, %LPRH14, and %LPRH15.)

Represent the double-precision floating-point registers in hexadecimal format.

To modify one of these registers, assign a value to the associated %LPRn or %LPRHn variable.

%LPRn cannot be used as the target of an assignment while debugging Enterprise PL/I programs.

Usage note

For assembler and disassembly, the LIST %LPRn command displays values in hexadecimal, but for the LIST %LPRHn command, values are listed as hexadecimal floating point.

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

%LPRBn (assembler and disassembly)

(%LPRB0, %LPRB1, %LPRB2, %LPRB3, %LPRB4, %LPRB5, %LPRB6, %LPRB7, %LPRB8, %LPRB9, %LPRB10, %LPRB11, %LPRB12, %LPRB13, %LPRB14, and %LPRB15.)

Represent the double-precision floating-point registers in binary format.

To modify one of these registers, assign a value to the associated %LPRBn variable.

If 64-bit hardware is not present, these variables are not supported. Any reference to them in such an environment will result in an "undefined symbol" message.

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

%LPRDn (assembler and disassembly)

(%LPRD0, %LPRD1, %LPRD2, %LPRD3, %LPRD4, %LPRD5, %LPRD6, %LPRD7, %LPRD8, %LPRD9, %LPRD10, %LPRD11, %LPRD12, %LPRD13, %LPRD14, and %LPRD15.)

Represent the double-precision floating-point registers in decimal format.

To modify one of these registers, assign a value to the associated %LPRDn variable.

If both Decimal Floating Point and 64-bit hardware are not present, these variables are not supported. Any reference to them in such an environment will result in an "undefined symbol" message.

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

%NLANGUAGE

Indicates the national language currently in use: ENGLISH, UENGLISH, JAPANESE, or KOREAN.

%PATHCODE

Contains an integer value that identifies the kind of change occurring when the path of program execution has reached a point of discontinuity and the path condition is raised.

The possible values vary according to the language of your program.

If you are replaying recorded statements, you cannot use the %PATHCODE variable.

%PLANGUAGE

Indicates the programming language currently in use.

%PLANGUAGE returns C for both C and C++.

%PROGMASK (assembler and disassembly only)

Contains the program mask portion of the current PSW.

%PROGRAM

Contains the name of the primary entry point of the current program.

%PROGRAM is equivalent to %CU. See %CU for more information.

%PSW (assembler and disassembly only)

Contains the current Program Status Word.

%RC

Contains a return code whenever a Debug Tool command ends.

%RC initially has a value of zero unless the log file cannot be opened, in which case it has a value of -1.

Note:
The %RC return code is a Debug Tool variable. It is not related to the return code that can be found in Register 15.

%RSTDSETS

Contains a value of 1 if the user settings have been restored as a result of the SET RESTORE SETTINGS AUTO command or the RESTORE SETTINGS command or a value of 0 otherwise.

Usage note

You can use this variable as part of an %IF statement in a preferences or commands file to avoid modifying SET values that have been restored.

%RUNMODE

Contains a string identifying the presentation mode of Debug Tool. The possible values are listed below.

%Rn

(%R0 to %R15)

Represent the General Purpose Registers for the assembler or disassembly CU to which you are currently qualified. These symbols are not valid in a CU in any other language. In addition, these symbols are undefined in assembler and disassembly CUs that are not currently active or for which the applicable General Purpose Registers cannot be located. Registers can be located for active assembler and disassembly CUs only if:

To modify one of these registers, assign a value to the associated %Rn variable.

Usage notes

Examples

LIST %R1 ;

%R7 = 0 ;

%SUBSYSTEM

Contains the name of the underlying subsystem, if any, where the program is executing. The possible values are listed below.

%SYSTEM

Contains the name of the operating system supporting the program. The only possible value is MVS.

Attributes of Debug Tool variables in different languages

The table below shows the attributes for Debug Tool variables when used with different programming languages.

Debug Tool variable C and C++ attributes COBOL attributes PL/I attributes Assembler/disassembly attributes
%ADDRESS void * USAGE POINTER POINTER A
%AMODE signed short int PICTURE S9(4) USAGE COMP FIXED BINARY(15,0) H
%BLOCK unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%CAAADDRESS void * USAGE POINTER POINTER A
%CC n/a n/a n/a H
%CONDITION unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%COUNTRY unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%CU unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%EPA void * USAGE POINTER POINTER A
%EPRn long double n/a FLOAT DECIMAL(33) L
%EPRBn n/a n/a n/a LB
%EPRDn n/a n/a n/a LD
%EPRHn n/a n/a n/a LH
%FPRn float USAGE COMP-1 FLOAT DECIMAL(6) E
%FPRBn n/a n/a n/a EB
%FPRDn n/a n/a n/a ED
%FPRHn n/a n/a n/a EH
%GPRn signed int PICTURE S9(9) FIXED BINARY(31,0) F
%GPRGn n/a n/a n/a FD
%HARDWARE unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%LINE or %STATEMENT unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%LOAD unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%LPRn double USAGE COMP-2 FLOAT DECIMAL(16) D
%LPRBn n/a n/a n/a DB
%LPRDn n/a n/a n/a DD
%LPRHn n/a n/a n/a DH
%NLANGUAGE unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%PATHCODE signed short int PICTURE S9(4) USAGE COMP FIXED BINARY(15,0) H
%PLANGUAGE unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%PROGMASK n/a n/a n/a H
%PROGRAM unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%PSW n/a n/a n/a CL8
%RC signed short int PICTURE S9(4) USAGE COMP FIXED BINARY(15,0) H
%RSTDSETS signed int PICTURE S9(9) USAGE COMP FIXED BINARY(31,0) F
%RUNMODE unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%Rn n/a n/a n/a F
%SUBSYSTEM unsigned char[] PICTURE X(j) CHARACTER(j) CLj
%SYSTEM unsigned char[] PICTURE X(j) CHARACTER(j) CLj

2.
See the Debug Tool Customization Guide for instructions on how to control SVC screening.


Terms of use | Feedback

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