HP OpenVMS Systems Documentation

On Alpha, 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

/LONG_FLOAT

/S_FLOAT

/LONG_LONG_FLOAT

/T_FLOAT

/LONGWORD

/OCTAL

/OCTAWORD

/PACKED:n

/PS

/PSR

/PSR

/QUADWORD

/S_FLOAT

/SFPCR

/SOURCE

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, 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

/TASK

/TYPE=(name)

/TYPE:(name)

/TYPE(name)

/VARIANT=variant-selector address-expression

/VARIANT=(variant-selector,...) address-expression

In a C program, a union contains members, only one of which is valid at any one time. When displaying a union, the debugger does not know which member is currently valid.

In a PASCAL program, a record with a variant part contains variants, only one of which is valid at any one time. When displaying a record with an anonymous variant part, the debugger does not know which variant is currently valid, and displays all variants by default.

You can use the /VARIANT qualifier of the EXAMINE command to select which member of a union (C) or anonymous variant (PASCAL) to display.

/WCHAR_T[:n]

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

/X_FLOAT

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 14. 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.

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.

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. The exceptions are BLISS and MACRO, which have a default radix of hexadecimal.

The EXAMINE command has four radix qualifiers (/BINARY, /DECIMAL, /HEXADECIMAL, /OCTAL) that enable you to display data in another radix. You can also use the SET RADIX and SET RADIX/OVERRIDE commands to change the default radix.

In addition to the type and radix qualifiers, the EXAMINE command has qualifiers for other purposes:

• The /SOURCE qualifier enables you to identify the line of source code corresponding to a line number, routine name, label, or any other address expression that is associated with an instruction rather than data.
• The /[NO]LINE and /[NO]SYMBOLIC qualifiers enable you to control the symbolization of address expressions.

The EXAMINE 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.

The /VARIANT qualifier enables the debugger to display the correct item when it encounters an anonymous variant.

In a C program, a union contains members, only one of which is valid at any one time. When displaying a union, the debugger does not know which member is currently valid. In a PASCAL program, a record with a variant part contains variants, only one of which is valid at any one time. When displaying a record with an anonymous variant part, the debugger does not know which variant is currently valid, and displays all variants by default.

You can use the /VARIANT qualifier of the EXAMINE command to select which member of a union (C program) or anonymous variant (PASCAL program) to display. The format is as follows:

DBG> EXAMINE /VARIANT=variant-selector address-expression

DBG> EXAMINE /VARIANT=(variant-selector,...) address-expression

The variant selector variant-selector specifies a name, a discriminant (PASCAL only), or a position; that is, one of the following:

• NAME = name-string
• DISCRIMINANT = expression
• POSITION = expression

The /VARIANT qualifier takes a list of zero or more variant selectors. /VARIANT without any variant selectors is the default: the first variant of all anonymous variant lists will be displayed.

Each variant selector specifies either the name, the discriminant, or the position of the variant to be displayed.

The debugger uses the variant selector as follows:

1. If the debugger encounters an anonymous variable list while displaying address-expression, the debugger uses the variant selector to choose which variant to display.
2. Each time the debugger encounters an anonymous variant list, it attempts to use the next variant selector to choose which variant to display. If the variant selector matches one of the variants of the variant list (union), the debugger displays that variant.
3. The debugger walks the structure top-to-bottom, depth first, so that children are encountered before siblings.
4. If the debugger encounters an anonymous variant list and does not have a variant selector to match it with, the debugger displays the first variant.
5. If the variant selector does not match any of the variants of an anonymous variant list, the debugger displays a single line to indicate that. This is similar to what the debugger does if the discriminant value fails to match any of the variants in a discriminated variant list. For example:

   [Variant Record omitted - null or illegal Tag Value: 3]

A name specifies a name string. A name matches a variant if that variant contains a field with the name specified by name.

A discriminant specifies a language expression that must be type compatible with the tag type of the variant part it is meant to match. The discriminant expression matches a variant if it evaluates to a value in the variant's case-label list. Discriminants apply only to Pascal programs, because C and C++ unions do not have discriminants.

A positional-selector specifies a language expression, which should evaluate to a integer between 1 and N, where N is the number of variants in a variant list. A positional-selector that evaluates to I specifies that the Ith variant is to be displayed.

You can use asterisk (*) as a wildcard, which matches all variants of an anonymous variant list.

Each of these variant selectors can be used to match all variants. In particular, each of the following variant selectors indicates that all of the variants of the first anonymous variant list are to be displayed.

/VAR=D=* /VAR=N=* /VAR=P=*

The variant selectors can themselves contain a list of selectors. For example, the following commands all mean the same thing.

EXAMINE /VARIANT=(DIS=3,DIS=1,DIS=54) x EXAMINE /VARIANT=(DIS=(3,1,54)) x EXAMINE /VARIANT=DIS=(3,1,54) x

You can specify a single discriminant or position value without parentheses if the value is a simple decimal integer. To use a general expression to specify the value, you enclose the expression in parentheses. In the following list of commands, the first four are legal while the last three are not.

EXAMINE /VARIANT=POS=3 EXAMINE /VARIANT=POS=(3) ! parentheses unnecessary EXAMINE /VARIANT=(POS=(3)) ! parentheses unnecessary EXAMINE /VARIANT=(POS=3) ! parentheses unnecessary EXAMINE /VARIANT=(POS=foo) ! parentheses necessary EXAMINE /VARIANT=POS=(foo) ! parentheses necessary EXAMINE /VARIANT=(POS=3-1) ! parentheses necessary

Related Commands:

CANCEL TYPE/OVERRIDE
DEPOSIT
DUMP
EVALUATE
SET MODE [NO]OPERANDS
SET MODE [NO]SYMBOLIC
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE

Examples

DBG> EXAMINE COUNT
SUB2\COUNT:  27
DBG>
      

This command displays the value of the integer variable COUNT in module SUB2.

DBG> EXAMINE PART_NUMBER
INVENTORY\PART_NUMBER:  "LP-3592.6-84"
DBG>
      

This command displays the value of the string variable PART_NUMBER.

DBG> EXAMINE SUB1\ARR3
SUB1\ARR3 
   (1,1):     27.01000 
   (1,2):     31.01000 
   (1,3):     12.48000 
   (2,1):     15.08000 
   (2,2):     22.30000 
   (2,3):     18.73000
DBG>
      

This command displays the value of all elements in array ARR3 in module SUB1. ARR3 is a 2 by 3 element array of real numbers.

DBG> EXAMINE SUB1\ARR3(2,1:3)
SUB1\ARR3 
   (2,1):     15.08000 
   (2,2):     22.30000 
   (2,3):     18.73000
DBG>
      

This command displays the value of the elements in a slice of array SUB1\ARR3. The slice includes "columns" 1 to 3 of "row" 2.

DBG> EXAMINE VALVES.INTAKE.STATUS
MONITOR\VALVES.INTAKE.STATUS:  OFF
DBG>
      

This command displays the value of the nested record component VALVES.INTAKE.STATUS in module MONITOR.

DBG> EXAMINE/SOURCE SWAP
module MAIN 
    47:  procedure SWAP(X,Y: in out INTEGER) is
DBG>
      

This command displays the source line in which routine SWAP is declared (the location of routine SWAP).

DBG> DEPOSIT/ASCII:7 WORK+20 = 'abcdefg'
DBG> EXAMINE/ASCII:7 WORK+20
DETAT\WORK+20:  "abcdefg"
DBG> EXAMINE/ASCII:5 WORK+20
DETAT\WORK+20:  "abcde"
DBG>
      

In this example, the DEPOSIT command deposits the entity 'abcdefg' as an ASCII string of length 7 bytes into the location that is 20 bytes beyond the location denoted by the symbol WORK. The first EXAMINE command displays the value of the entity at that location as an ASCII string of length 7 bytes (abcdefg). The second EXAMINE command displays the value of the entity at that location as an ASCII string of length 5 bytes (abcde).

DBG> EXAMINE/OPERANDS=FULL .0\%PC
X\X$START+0C: mov         r12 = r15 ;;
DBG>
      

On Integrity servers, this command displays the instruction (MOV) at the current PC value. Using /OPERANDS=FULL displays the maximum level of operand information.

DBG> SET RADIX HEXADECIMAL
DBG> EVALUATE/ADDRESS WORKDATA
0000086F
DBG> EXAMINE/SYMBOLIC 0000086F
MOD3\WORKDATA:  03020100
DBG> EXAMINE/NOSYMBOLIC 0000086F
0000086F:  03020100
DBG>
      

In this example, the EVALUATE/ADDRESS command indicates that the memory address of variable WORKDATA is 0000086F, hexadecimal. The two EXAMINE commands display the value contained at that address using /[NO]SYMBOL to control whether the address is symbolized to WORKDATA.

DBG> EXAMINE/HEX FIDBLK
FDEX1$MAIN\FIDBLK 
    (1):        00000008 
    (2):        00000100 
    (3):        000000AB
DBG>
      

This command displays the value of the array variable FIDBLK in hexadecimal radix.

DBG> EXAMINE/DECIMAL/WORD NEWDATA:NEWDATA+6
SUB2\NEWDATA:  256 
SUB2\NEWDATA+2:  770 
SUB2\NEWDATA+4:  1284 
SUB2\NEWDATA+6:  1798
DBG>
      

This command displays, in decimal radix, the values of word integer entities (2-byte entities) that are in the range of locations denoted by NEWDATA to NEWDATA + 6 bytes.

DBG> EXAMINE/TASK SORT_INPUT
MOD3\SORT_INPUT:  %TASK 12
DBG>
      

This command displays the task ID of a task object named SORT_INPUT.

DBG> EXAMINE /VARIANT=(NAME=m,DIS=4,POS=1) x
      

This command specifies that, for the first anonymous variant list encountered, display the variant part containing a field named "m", for the second anonymous variant list, display the part with the discriminant value 4, and, for the third anonymous variant list, display the first variant part.

DBG> ex %r9:%r12
    TEST\%R9:     0000000000000000 
   TEST\%R10:     0000000000000000 
   TEST\%R11:     0000000000000000 
   TEST\%SP:      000000007AC8FB70
 
DBG> ex/bin grnat0 <9,4,0>
TEST\%GRNAT0+1: 0110
DBG> 
 
      

Debugger displays the string "NaT" when the integer register's NaT bit is set.

Ends a debugging session, or terminates one or more processes of a multiprocess program, allowing any application-declared exit handlers to run. If used within a command procedure or DO clause and no process is specified, it exits the command procedure or DO clause at that point.

Format

EXIT [process-spec[,...]]

Parameters

process-spec

Specifies a process currently under debugger control. Use any of the following forms:

[%PROCESS_NAME] process-name	The process name, if that name does not contain spaces or lowercase characters. The process name can include the asterisk (*) wildcard character.
[%PROCESS_NAME] " process-name "	The process name, if that name contains spaces or lowercase characters. You can also use apostrophes (') instead of quotation marks (").
%PROCESS_PID process_id	The process identifier (PID, a hexadecimal number).
[%PROCESS_NUMBER] process-number (or %PROC process-number)	The number assigned to a process when it comes under debugger control. A new number is assigned sequentially, starting with 1, to each process. If a process is terminated with the EXIT or QUIT command, the number can be assigned again during the debugging session. Process numbers appear in a SHOW PROCESS display. Processes are ordered in a circular list so they can be indexed with the built-in symbols %PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name	A symbol defined with the DEFINE/PROCESS_SET command to represent a group of processes.
%NEXT_PROCESS	The next process after the visible process in the debugger's circular process list.
%PREVIOUS_PROCESS	The process previous to the visible process in the debugger's circular process list.
%VISIBLE_PROCESS	The process whose stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.

You can also use the asterisk (*) wildcard character to specify all processes.

Description

The EXIT command is one of the four debugger commands that can be used to execute your program (the others are CALL, GO, and STEP).

Ending a Debugging Session

To end a debugging session, enter the EXIT command at the debugger prompt without specifying any parameters. This causes orderly termination of the session: the program's application-declared exit handlers (if any) are executed, the debugger exit handler is executed (closing log files, restoring the screen and keypad states, and so on), and control is returned to the command interpreter. You cannot then continue to debug your program by entering the DCL command DEBUG or CONTINUE (you must restart the debugger).

Because EXIT runs any application-declared exit handlers, you can set breakpoints in such exit handlers, and the breakpoints are triggered upon typing EXIT. Thus, you can use EXIT to debug your exit handlers.

To end a debugging session without running any application-declared exit handlers, use the QUIT command instead of EXIT.

Using the EXIT Command in Command Procedures and DO Clauses

When the debugger executes an EXIT command (without any parameters) in a command procedure, control returns to the command stream that invoked the command procedure. A command stream can be the terminal, an outer (containing) command procedure, or a DO clause in a command or screen display definition. For example, if the command procedure was invoked from within a DO clause, control returns to that DO clause, where the debugger executes the next command (if any remain in the command sequence).

When the debugger executes an EXIT command (without any parameters) in a DO clause, it ignores any remaining commands in that clause and displays its prompt.

Terminating Specified Processes

If you are debugging a multiprocess program you can use the EXIT command to terminate specified processes without ending the debugging session. The same techniques and behavior apply, whether you enter the EXIT command at the prompt or use it within a command procedure or DO clause.

To terminate one or more processes, enter the EXIT command, specifying these processes as parameters. This causes orderly termination of the images in these processes, executing any application-declared exit handlers associated with these images. Subsequently, the specified processes are no longer identified in a SHOW PROCESS/ALL display. If any specified processes were on hold as the result of a SET PROCESS command, the hold condition is ignored.

When the specified processes begin to exit, any unspecified process that is not on hold begins execution. After execution is started, the way in which it continues depends on whether you entered a SET MODE [NO]INTERRUPT command. By default (SET MODE INTERRUPT), execution continues until it is suspended in any process. At that point, execution is interrupted in any other processes that were executing images, and the debugger prompts for input.

To terminate specified processes without running any application-declared exit handlers or otherwise starting execution, use the QUIT command instead of EXIT.

Related commands:

DISCONNECT
@ (Execute Procedure)
Ctrl/C
Ctrl/Y
Ctrl/Z
QUIT
RERUN
RUN
SET ABORT_KEY
SET MODE [NO]INTERRUPT
SET PROCESS

Examples

DBG> EXIT
$
      

---

Previous

Next

Contents

Index