OpenVMS Debugger Manual

The SET EDITOR command provides options for starting different editors, either in a subprocess or through a callable interface.

Related commands:

(SET,SHOW) EDITOR
(SET,SHOW,CANCEL) SOURCE

Examples

DBG> EDIT

This command spawns the DEC Language-Sensitive Editor (LSEDIT) in a subprocess to edit the source file whose code appears in the current source display. The editing cursor is positioned at the beginning of the line that was centered in the source display.

DBG> EDIT SWAP\12

This command spawns the DEC Language-Sensitive Editor (LSEDIT) in a subprocess to edit the source file containing the module SWAP. The editing cursor is positioned at the beginning of source line 12.

DBG> SET EDITOR/CALLABLE_EDT
DBG> EDIT

In this example, the SET EDITOR/CALLABLE_EDT command establishes that EDT is the default editor and is started through its callable interface (rather than spawned in a subprocess). The EDIT command starts EDT to edit the source file whose code appears in the current source display. The editing cursor is positioned at the beginning of source line 1, because the default qualifier /NOSTART_POSITION applies to EDT.

ENABLE AST

Enables the delivery of asynchronous system traps (ASTs) in your program.

Format

ENABLE AST

DESCRIPTION

The ENABLE AST command enables the delivery of ASTs while your program is running, including any pending ASTs (ASTs waiting to be delivered). If ASTs are delivered while the debugger is running (processing commands, and so on), they are queued and are delivered when control is returned to the program. Delivery of ASTs in your program is initially enabled by default.

Note
Any call by your program to the $SETAST system service that disables ASTs overrides a previous ENABLE AST command.

Related commands:

(DISABLE,SHOW) AST

Example

DBG> ENABLE AST
DBG> SHOW AST
ASTs are enabled
DBG>

The ENABLE AST command enables the delivery of ASTs in your program, as confirmed with the SHOW AST command.

EVALUATE

Displays the value of a language expression in the current language (by default, the language of the module containing the main program).

Format

EVALUATE language-expression[,...]

PARAMETERS

language-expression
Specifies any valid expression in the current language.

QUALIFIERS

/BINARY
Specifies that the result be displayed in binary radix.
/CONDITION_VALUE
Specifies that the expression be interpreted as a condition value (the kind of condition value you would specify using the condition-handling mechanism). The message text corresponding to that condition value is then displayed. The specified value must be an integer value.
/DECIMAL
Specifies that the result be displayed in decimal radix.
/HEXADECIMAL
Specifies that the result be displayed in hexadecimal radix.
/OCTAL
Specifies that the result be displayed in octal radix.

DESCRIPTION

The debugger interprets the expression specified in an EVALUATE command as a language expression, evaluates it in the syntax of the current language and in the current radix, and displays its value as a literal (for example, an integer value) in the current language.
The current language is the language last established with the SET LANGUAGE command. If you did not enter a SET LANGUAGE command, the current language is, by default, the language of the module containing the main program.
If an expression contains symbols with different compiler-generated types, the debugger uses the type-conversion rules of the current language to evaluate the expression.
The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The current radix is the radix last established with the SET RADIX command.
If you did not enter a SET RADIX command, the default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO--32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO--32, and MACRO--64, which have a default radix of hexadecimal.
You can use a radix qualifier (/BINARY, /OCTAL, and so on) to display integer data in another radix. These qualifiers do not affect how the debugger interprets the data you specify; they override the current output radix, but not the input radix.
The EVALUATE command sets the current value of built-in symbols %CURVAL and backslash (\) to the value denoted by the specified expression.
You cannot evaluate a language expression that includes a function call. For example, if PRODUCT is a function that multiplies two integers, you cannot use the command EVALUATE PRODUCT(3,5). If your program assigns the returned value of a function to a variable, you can examine the resulting value of that variable. On Alpha processors, the command EVALUATE procedure-name displays the procedure descriptor address (not the code address) of a specified routine, entry point, or Ada package.
For more information about debugger support for language-specific operators and constructs, type HELP Language.
Related commands:

EVALUATE/ADDRESS
MONITOR
(SET,SHOW) LANGUAGE
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE

Examples

DBG> EVALUATE 100.34 * (14.2 + 7.9)
2217.514
DBG>

This command uses the debugger as a calculator by multiplying 100.34 by (14.2 + 7.9).

DBG> EVALUATE/OCTAL X
00000001512
DBG>

This command evaluates the symbol X and displays the result in octal radix.

DBG> EVALUATE TOTAL + CURR_AMOUNT
8247.20
DBG>

This command evaluates the sum of the values of two real variables, TOTAL and CURR_AMOUNT.

DBG> DEPOSIT WILLING = TRUE
DBG> DEPOSIT ABLE = FALSE
DBG> EVALUATE WILLING AND ABLE
False
DBG>

In this example, the EVALUATE command evaluates the logical AND of the current values of two Boolean variables, WILLING and ABLE.

DBG> EVALUATE COLOR'FIRST
RED
DBG>

In this Ada example, this command evaluates the first element of the enumeration type COLOR.

EVALUATE/ADDRESS

Evaluates an address expression and displays the result as a memory address or a register name.

Format

EVALUATE/ADDRESS address-expression[,...]

PARAMETERS

address-expression
Specifies an address expression of any valid form (for example, a routine name, variable name, label, line number, and so on).

QUALIFIERS

/BINARY
Displays the memory address in binary radix.
/DECIMAL
Displays the memory address in decimal radix.
/HEXADECIMAL
Displays the memory address in hexadecimal radix.
/OCTAL
Displays the memory address in octal radix.

DESCRIPTION

The EVALUATE/ADDRESS command enables you to determine the memory address or register associated with an address expression.
The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO--32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO--32, and MACRO--64, which have a default radix of hexadecimal.
You can use a radix qualifier (/BINARY, /OCTAL, and so on) to display address values in another radix. These qualifiers do not affect how the debugger interprets the data you specify; that is, they override the current output radix, but not the input radix.
If the value of a variable is currently stored in a register instead of memory, the EVALUATE/ADDRESS command identifies the register. The radix qualifiers have no effect in that case.
The EVALUATE/ADDRESS command sets the current entity built-in symbols %CURLOC and period (.) to the location denoted by the address expression specified. Logical predecessors (%PREVLOC or the circumflex character (^)) and successors (%NEXTLOC) are based on the value of the current entity.
On Alpha processors, the command EVALUATE/ADDRESS procedure-name displays the procedure descriptor address (not the code address) of a specified routine, entry point, or Ada package.
Related commands:

EVALUATE
(SET,SHOW,CANCEL) RADIX
SHOW SYMBOL/ADDRESS
SYMBOLIZE

Examples

DBG> EVALUATE/ADDRESS MODNAME\%LINE 110
3942
DBG>

This command displays the memory address denoted by the address expression MODNAME\%LINE 110.

DBG> EVALUATE/ADDRESS/HEX A,B,C
000004A4 
000004AC 
000004A0
DBG>

This command displays the memory addresses denoted by the address expressions A, B, and C in hexadecimal radix.

DBG> EVALUATE/ADDRESS X
MOD3\%R1
DBG>

This command indicates that variable X is associated with register R1. X is a nonstatic (register) variable.

EXAMINE

Displays the current value of a program variable. More generally, displays the value of the entity denoted by an address expression.

Format

EXAMINE [address-expression[:address-expression] [,...]]

PARAMETERS

address-expression
Specifies an entity to be examined. With high-level languages, this is typically the name of a variable and can include a path name to specify the variable uniquely. More generally, an address expression can also be a memory address or a register and can be composed of numbers (offsets) and symbols, as well as one or more operators, operands, or delimiters. For information about the debugger symbols for the registers and about the operators you can use in address expressions, type Help Built_in_Symbols or Help Address_Expressions.
If you specify the name of an aggregate variable (a composite data structure such as an array or record structure) the debugger displays the values of all elements. For an array, the display shows the subscript (index) and value of each array element. For a record, the display shows the name and value of each record component.
To specify an individual array element, array slice, or record component, follow the syntax of the current language.
If you specify a range of entities, the value of the address expression that denotes the first entity in the range must be less than the value of the address expression that denotes the last entity in the range. The debugger displays the entity specified by the first address expression, the logical successor of that address expression, the next logical successor, and so on, until it displays the entity specified by the last address expression. You can specify a list of ranges by separating ranges with a comma.
For information specific to vector registers and vector instructions, see /TMASK, /FMASK, /VMR, and /OPERANDS qualifiers.

QUALIFIERS

/ASCIC

/AC
Interprets each examined entity as a counted ASCII string preceded by a 1-byte count field that gives the length of the string. The string is then displayed.
/ASCID

/AD
Interprets each examined entity as the address of a string descriptor pointing to an ASCII string. The CLASS and DTYPE fields of the descriptor are not checked, but the LENGTH and POINTER fields provide the character length and address of the ASCII string. The string is then displayed.
/ASCII:n
Interprets and displays each examined entity as an ASCII string of length n bytes (n characters). If you omit n, the debugger attempts to determine a length from the type of the address expression.
/ASCIW

/AW
Interprets each examined entity as a counted ASCII string preceded by a 2-byte count field that gives the length of the string. The string is then displayed.
/ASCIZ

/AZ
Interprets each examined entity as a zero-terminated ASCII string. The ending zero byte indicates the end of the string. The string is then displayed.
/BINARY
Displays each examined entity as a binary integer.
/BYTE
Displays each examined entity in the byte integer type (length 1 byte).
/CONDITION_VALUE
Interprets each examined entity as a condition-value return status and displays the message associated with that return status.
/D_FLOAT
Displays each examined entity in the D_floating type (length 8 bytes).
/DATE_TIME
Interprets each examined entity as a quadword integer (length 8 bytes) containing the internal representation of date and time. Displays the value in the format dd-mmm-yyyy hh:mm:ss.cc.
/DECIMAL
Displays each examined entity as a decimal integer.
/DEFAULT
Displays each examined entity in the default radix.
The minimum abbreviation is /DEFA.
/DEFINITIONS=n
(Alpha only) When the code is optimized, displays n definition points for a split-lifetime variable. A definition point is a location in the program where the variable could have received its value. By default, up to five definition points are displayed. If more than the given number of definitions (explicit or default) are available, then the number of additional definitions is reported as well. (For more information on split-lifetime variables, see Chapter 13.)
The minimum abbreviation is /DEFI.

/EXTENDED_FLOAT

/X_FLOAT
(Alpha only) Displays each examined entity in the IEEE X_floating type (length 16 bytes).
/FLOAT
On VAX processors, same as /F_FLOAT. Displays each examined entity in the F_floating type (length 4 bytes).
On Alpha processors, same as T_FLOAT. Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes).
/F_FLOAT
(VAX only) Displays each examined entity in the F_floating type (length 4 bytes).
/FPCR
(Alpha only) Displays each examined entity in FPCR (floating-point control register) format.
/FMASK[=(mask-address-expression)]
Applies only to VAX vectorized programs. See the /TMASK qualifier.
/G_FLOAT
Displays each examined entity in the G_floating type (length 8 bytes).
/H_FLOAT
(VAX only) Displays each examined entity in the H_floating type (length 16 bytes).
/HEXADECIMAL
Displays each examined entity as a hexadecimal integer.
/INSTRUCTION
Displays each examined entity as an assembly-language instruction (variable length, depending on the number of instruction operands and the kind of addressing modes used). See also the /OPERANDS qualifier.
In screen mode, the output of an EXAMINE/INSTRUCTION command is directed at the current instruction display, if any, not at an output or DO display. The arrow in the instruction display points to the examined instruction.
On Alpha processors, the command EXAMINE/INSTRUCTION procedure-name displays the first instruction at the code address of a specified routine, entry point, or Ada package.
/LINE (default)

/NOLINE
Controls whether program locations are displayed in terms of line numbers (%LINE x) or as routine-name + byte-offset. By default (/LINE), the debugger symbolizes program locations in terms of line numbers.
/LONG_FLOAT

/S_FLOAT
(Alpha only) Displays each examined entity in the IEEE S_floating type (single precision, length 4 bytes).
/LONG_LONG_FLOAT

/T_FLOAT
(Alpha only) Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes).
/LONGWORD
Displays each examined entity in the longword integer type (length 4 bytes). This is the default type for program locations that do not have a compiler-generated type.
/OCTAL
Displays each examined entity as an octal integer.
/OCTAWORD
Displays each examined entity in the octaword integer type (length 16 bytes).
/OPERANDS[=keyword]
(VAX only) Displays operand information associated with an examined instruction (displays each operand's address and its contents, using the operand's data type). The keywords BRIEF and FULL vary the amount of information displayed about any nonregister operands. The default is /OPERANDS=BRIEF.
Use /OPERANDS only when examining the instruction at the current PC value (for example, EXAMINE/OPERANDS .0\%PC). Examining the operands of an instruction that is not at the current PC value can give erroneous results, because the state of the machine (the contents of the registers) is not set up for that instruction.
In screen mode, operand information is directed at the current output display.
When you examine the operands of a vector instruction, any operand-element masking that might be associated with that instruction is performed by default. The /TMASK and /FMASK qualifiers enable you to specify some other mask. The current value of the vector length register (VLR) limits the highest element of a vector register that you can examine.
See also the SET MODE [NO]OPERANDS=keyword command, which lets you set a default level for the amount of operand information displayed when examining instructions.
/PACKED:n
Interprets each examined entity as a packed decimal number. The value of n is the number of decimal digits. Each digit occupies one nibble (4 bits).
/PS
(Alpha only) Displays each examined entity in PS (processor status register) format.
/PSL
(VAX only) Displays each examined entity in PSL (processor status longword) format.
/PSW
(VAX only) Displays each examined entity in PSW (processor status word) format. The /PSW qualifier is like /PSL except that only the low-order word (2 bytes) is displayed.
/QUADWORD
Displays each examined entity in the quadword integer type (length 8 bytes).
/S_FLOAT
(Alpha only) Displays each examined entity in the IEEE S_floating type (single precision, length 4 bytes).
/SFPCR
(Alpha only) Displays each examined entity in SFPCR (software floating-point control register) format.
/SOURCE

Note
This qualifier is not available in the DECwindows Motif interface to the debugger.

Displays the source line corresponding to the location of each examined entity. The examined entity must be associated with a machine code instruction and, therefore, must be a line number, a label, a routine name, or the memory address of an instruction. The examined entity cannot be a variable name or any other address expression that is associated with data.
In screen mode, the output of an EXAMINE/SOURCE command is directed at the current source display, if any, not at an output or DO display. The arrow in the source display points to the source line associated with the last entity specified (or the last one specified in a list of entities).
On Alpha processors, the command EXAMINE/SOURCE procedure-name displays the source code at the code address of a specified routine, entry point, or Ada package.
/SYMBOLIC (default)

/NOSYMBOLIC
Controls whether symbolization occurs. By default (/SYMBOLIC), the debugger symbolizes all addresses, if possible; that is, it converts numeric addresses into their symbolic representation. If you specify /NOSYMBOLIC, the debugger suppresses symbolization of entities you specify as absolute addresses. If you specify entities as variable names, symbolization still occurs. The /NOSYMBOLIC qualifier is useful if you are interested in identifying numeric addresses rather than their symbolic names (if symbolic names exist for those addresses). Using /NOSYMBOLIC may speed up command processing because the debugger does not need to convert numbers to names.
/TASK
Applies to tasking (multithread) programs. Interprets each examined entity as a task (thread) object and displays the task value (the name or task ID) of that task object. When examining a task object, use /TASK only if the programming language does not have built-in tasking services.
/T_FLOAT
(Alpha only) Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes).
/TMASK[=(mask-address-expression)]

/FMASK[=(mask-address-expression)]
These qualifiers apply only to VAX vectorized programs. They enable you to specify a mask in order to display certain elements of a vector register (V0 to V15), or of an array in memory, while not displaying other elements.
For example, when you examine the operands of a vector instruction (by using the /OPERANDS qualifier), these qualifiers enable you to override any operand-element masking that might be associated with that instruction.
The /TMASK qualifier applies the EXAMINE command only to the elements of the register or array that correspond to the set bits (bit value: 1) of the mask. The /FMASK qualifier applies the EXAMINE command only to the elements that correspond to the clear bits (bit value: 0) of the mask. The current value of the vector length register (VLR) limits the highest register element that you can examine but not the highest array element.
By default, if you do not specify a mask address expression with /TMASK or /FMASK, the vector mask register (VMR) is used. That is, the EXAMINE command is applied only to the elements of the vector register or array that correspond to the set bits (in the case of /TMASK) or clear bits (in the case of /FMASK) of VMR.
If you specify a mask address expression with /TMASK or /FMASK, the value at that address is used as the mask, subject to the following conventions:

You must use parentheses around the address expression.
The number of mask elements limits the number of register or array elements that you can examine.
If the mask address expression denotes a Boolean array, its values are used as the mask, in the same basic way that VMR is used in the default case.
If the mask address expression denotes a non-Boolean array, the least significant bit value of each array element is used as the mask for the corresponding element of the register or target array.
If the mask address expression denotes a Boolean scalar type, its value is used as the mask for the first element of the register or target array. No other elements are examined.
If the mask address expression denotes any other type, its least significant bit value is used as the mask for the first element of the register or target array. No other elements are examined.
For a multi-element mask, the lowest specified element of the mask is applied to the lowest specified element of the register or target array.

/TYPE=(name)
Interprets and displays each examined entity according to the type specified by name (which must be the name of a variable or data type declared in the program). This enables you to specify a user-declared type. You must use parentheses around the type expression.
/VMR
(VAX only) Applies only to VAX vectorized programs. Displays the Vector Mask Register.
/WCHAR_T[:n]
Interprets and displays each examined entity as a multibyte file code sequence of length n longwords (n characters). The default is 1 longword.
When converting the examined string, the debugger uses the locale database of the process in which the debugger runs. The default is C locale.
/WORD
Displays each examined entity in the word integer type (length 2 bytes).
/X_FLOAT
(Alpha only) Displays each examined entity in the IEEE X_floating type (length 16 bytes).

DESCRIPTION

The EXAMINE command displays the entity at the location denoted by an address expression. You can use the command to display the contents of any memory location or register that is accessible in your program. For high-level languages, the command is used mostly to obtain the current value of a variable (an integer, real, string, array, record, and so on).
If you are debugging optimized code on Alpha systems, the EXAMINE command displays the definition points at which a split-lifetime variable could have received its value. Split-lifetime variables are discussed in Chapter 13. By default, the EXAMINE command displays up to five definition points. With the /DEFINITIONS qualifier, you can specify the number of definition points.
The debugger recognizes the compiler-generated types associated with symbolic address expressions (symbolic names declared in your program). Symbolic address expressions include the following entities:

Variable names. When specifying a variable with the EXAMINE command, use the same syntax that is used in the source code.
Routine names, labels, and line numbers. These are associated with instructions. You can examine instructions using the same techniques as when examining variables.

In general, when you enter an EXAMINE command, the debugger evaluates the address expression specified to yield a program location. The debugger then displays the value stored at that location as follows:

If the location has a symbolic name, the debugger formats the value according to the compiler-generated type associated with that symbol (that is, as a variable of a particular type or as an instruction).
If the location does not have a symbolic name (and, therefore, no associated compiler-generated type) the debugger formats the value in the type longword integer by default. This means that, by default, the EXAMINE command displays the contents of these locations as longword (4-byte) integer values.

For information specific to vector registers (VAX only) and vector instructions (VAX only), see the /TMASK, /FMASK, /VMR, and /OPERANDS qualifiers.
There are several ways of changing the type associated with a program location so that you can display the data at that location in another data format:

To change the default type for all locations that do not have a symbolic name, you can specify a new type with the SET TYPE command.
To change the default type for all locations (both those that do and do not have a symbolic name), you can specify a new type with the SET TYPE/OVERRIDE command.
To override the type currently associated with a particular location for the duration of a single EXAMINE command, you can specify a new type by using a type qualifier (/ASCII:n, /BYTE, /TYPE=(name), and so on). Most qualifiers for the EXAMINE command are type qualifiers.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4538P036.HTM
  OSSG Documentation
  22-NOV-1996 13:02:26.95
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal