Updated: 11 December 1998

OpenVMS Alpha System Analysis Tools Manual

Assigns a value to a symbol.

Format

DEFINE [/qualifier...] symbol-name [=] expression

Parameters

symbol-name

Name, containing from 1 to 31 alphanumeric characters, that identifies the symbol. See Chapter 2, Section 2.6.2.4 for a description of SDA symbol syntax and a list of default symbols.

expression

Definition of the symbol's value. See Chapter 2, Section 2.6.2 for a discussion of the components of SDA expressions.

Qualifier

/PD

Defines a symbol as a procedure descriptor (PD). It also defines the routine address symbol corresponding to the defined symbol (the routine address symbol has the same name as the defined symbol, only with _C appended to the symbol name). See Section 2.6.2.4 for more information about symbols.

Description

The DEFINE command causes SDA to evaluate an expression and then assign its value to a symbol. Both the DEFINE and EVALUATE commands perform computations to evaluate expressions. DEFINE adds symbols to the SDA symbol table but does not display the results of the computation. EVALUATE displays the result of the computation but does not add symbols to the SDA symbol table.

Examples

SDA>  DEFINE BEGIN = 80058E00
SDA>  DEFINE END = 80058E60
SDA>  EXAMINE BEGIN:END
 
 
      

In this example, DEFINE defines two addresses, called BEGIN and END. These symbols serve as reference points in memory, defining a range of memory locations for the EXAMINE command to inspect.

SDA>  DEFINE NEXT = @PC
SDA>  EXAMINE/INSTRUCTION NEXT
NEXT:   HALT
      

The symbol NEXT defines the address contained in the program counter, so that the symbol can be used in an EXAMINE/INSTRUCTION command.

SDA>  DEFINE VEC SCH$GL_PCBVEC
SDA>  EXAMINE VEC
SCH$GL_PCBVEC:  00000000.8060F2CC   "Ìò`....."
SDA> 
      

After the value of global symbol SCH$GL_PCBVEC has been assigned to the symbol VEC, the symbol VEC is used to examine the memory location or value represented by the global symbol.

SDA>  DEFINE/PD VEC SCH$QAST
SDA>  EXAMINE VEC
SCH$QAST:  0000002C.00003008   ".0..,..."
SDA>  EXAMINE VEC_C
SCH$QAST_C:  B75E0008.43C8153E   ">.ÈC..^·"
SDA> 
 
      

In this example, the DEFINE/PD command defines not only the symbol VEC, but also the corresponding routine address symbol (VEC_C).

Associates an SDA command with a terminal key.

Format

DEFINE/KEY [/qualifier...] key-name command

Parameters

key-name

Name of the key to be defined. You can define the following keys under SDA:

Key Name	Key Designation
PF1	LK201, VT100, VT52 Red
PF2	LK201, VT100, VT52 Blue
PF3	LK201, VT100, VT52 Black
PF4	LK201, VT100
KP0...KP9	Keypad 0--9
PERIOD	Keypad period
COMMA	Keypad comma
MINUS	Keypad minus
ENTER	Keypad ENTER
UP	Up arrow
DOWN	Down arrow
LEFT	Left arrow
RIGHT	Right arrow
E1	LK201 Find
E2	LK201 Insert Here
E3	LK201 Remove
E4	LK201 Select
E5	LK201 Prev Screen
E6	LK201 Next Screen
HELP	LK201 Help
DO	LK201 Do
F7...F20	LK201 Function keys

command

SDA command to define a key. The command must be enclosed in quotation marks (" ").

Qualifiers

/KEY

Defines a key as an SDA command. To issue the command, press the defined key and the Return key. If you use the /TERMINATE qualifier as well, you do not have to press the Return key.

/PD

Defines a symbol as a procedure descriptor (PD). Also defines the routine address symbol corresponding to the defined symbol (the routine address symbol has the same name as the defined symbol, only with _C appended to the symbol name.)

/SET_STATE=state-name

Causes the key being defined to create a key state change rather than issue an SDA command. When you use the /SET_STATE qualifier, you supply the name of a key state in place of the key-name parameter. In addition, you must define the command parameter as a pair of quotation marks (" ").

For example, you can define the PF1 key as the GOLD key and use the /IF_STATE=GOLD qualifier to allow two definitions for the other keys, one in the GOLD state and one in the non-GOLD state. For more information on using the /IF_STATE qualifier, see the DEFINE/KEY command in the OpenVMS DCL Dictionary: A--M.

/TERMINATE

/NOTERMINATE

Causes the key definition to include termination of the command, which causes SDA to execute the command when the defined key is pressed. Therefore, you do not have to press the Return key after you press the defined key if the /TERMINATE qualifier is specified.

Description

The DEFINE/KEY command causes an SDA command to be associated with the specified key, in accordance with any of the specified qualifiers described previously.

If the symbol or key is already defined, SDA replaces the old definition with the new one. Symbols and keys remain defined until you exit from SDA.

Examples

SDA> DEFINE/KEY PF1 "SHOW STACK"
SDA> [PF1] SHOW STACK [RETURN]
Process stacks (on CPU 00)
-------------------------
Current operating stack (KERNEL):
 
      

The DEFINE/KEY command defines PF1 as the SHOW STACK command. When the PF1 key is pressed, SDA displays the command and waits for you to press the Return key.

SDA> DEFINE/KEY/TERMINATE PF1 "SHOW STACK"
SDA> [PF1] SHOW STACK
Process stacks (on CPU 00)
-------------------------
Current operating stack (KERNEL):
      00000000.7FF95D00  00000000.0000000B  
      00000000.7FF95D08  FFFFFFFF.804395C8  MMG$TBI_DATA_64+000B8
      00000000.7FF95D10  00000000.00000000  
      00000000.7FF95D18  0000FE00.00007E04  
SP => 00000000.7FF95D20  00000000.00000800  IRP$M_EXTEND
      00000000.7FF95D28  00000001.000002F7  UCB$B_PI_FKB+0000B
      00000000.7FF95D30  FFFFFFFF.804395C8  MMG$TBI_DATA_64+000B8
      00000000.7FF95D38  00000002.00000000  
   .
   .
   .
      

The DEFINE/KEY command defines PF1 as the SDA SHOW STACK command. The /TERMINATE qualifier causes SDA to execute the SHOW STACK command without waiting for you to press the Return key.

SDA> DEFINE/KEY/SET_STATE="GREEN" PF1 ""
SDA> DEFINE/KEY/TERMINATE/IF_STATE=GREEN PF3 "SHOW STACK"
SDA> [PF1] [PF3] SHOW STACK
Process stacks (on CPU 00)
-------------------------
Current operating stack (KERNEL):
   .
   .
   .
      

The first DEFINE/KEY command defines PF1 as a key that sets a command state GREEN. The trailing pair of quotation marks is required syntax, indicating that no command is to be executed when this key is pressed.

The second DEFINE command defines PF3 as the SHOW STACK command, but using the /IF_STATE qualifier, makes the definition valid only when the command state is GREEN. Thus, the user must press PF1 before pressing PF3 to issue the SHOW STACK command. The /TERMINATE qualifier causes the command to execute as soon as the PF3 key is pressed.

Computes and displays the value of the specified expression in both hexadecimal and decimal. Alternative evaluations of the expression are available with the use of the qualifiers defined for this command.

Format

EVALUATE [{/CONDITION_VALUE|/PS|/PTE|/SYMBOLS |/TIME}] expression

Parameter

expression

SDA expression to be evaluated. Chapter 2, Section 2.6.2 describes the components of SDA expressions.

Qualifiers

/CONDITION_VALUE

Displays the message that the $GETMSG system service obtains for the value of the expression.

/PS

Evaluates the specified expression in the format of a processor status.

/PTE

Interprets and displays the expression as a page table entry (PTE). The individual fields of the PTE are separated and an overall description of the PTE's type is provided.

/SYMBOLS

Specifies that all symbols known to be equal to the evaluated expression are to be listed in alphabetical order. The default behavior of the EVALUATE command displays only the first several symbols.

/TIME

Interprets and displays the expression as a 64-bit time value. Positive values are interpreted as absolute time; negative values are interpreted as delta time.

Description

If the expression is equal to the value of a symbol in the SDA symbol table, that symbol is displayed. If no symbol with this value is known, the next lower valued symbol is displayed with an appropriate offset unless the offset is extremely large. The DEFINE command adds symbols to the SDA symbol table but does not display the results of the computation. EVALUATE displays the result of the computation but does not add symbols to the SDA symbol table.

If no qualifier is specified, the EVALUATE command interprets and displays the expression as hexadecimal and decimal values.

Examples

SDA> EVALUATE -1
Hex = FFFFFFFF.FFFFFFFF   Decimal = -1           I              
      

The EVALUATE command evaluates a numeric expression, displays the value of that expression in hexadecimal and decimal notation, and displays a symbol that has been defined to have an equivalent value.

SDA> EVALUATE 1
Hex = 00000000.00000001   Decimal = 1  CHF$M_CALEXT_CANCEL
                                              CHF$M_FPREGS_VALID
                                              CHF$V_CALEXT_LAST
                                              IRP$M_BUFIO
                                              IRP$M_CLN_READY
                                                |
                           (remaining symbols suppressed by default)
      

The EVALUATE command evaluates a numeric expression and displays the value of that expression in hexadecimal and decimal notation. This example also shows the symbols that have the displayed value. A finite number of symbols are displayed by default.

SDA> DEFINE TEN = A
SDA> EVALUATE TEN
Hex = 00000000.0000000A   Decimal = 10  IRP$B_TYPE
                                             IRP$S_FMOD
                                             IRP$V_MBXIO
                                             TEN
                                             UCB$B_TYPE
                                             |
                           (remaining symbols suppressed by default)
      

This example shows the definition of a symbol named TEN. The EVALUATE command then shows the value of the symbol.

Note that A, the value assigned to the symbol by the DEFINE command, could be a symbol. When SDA evaluates a string that can be either a symbol or a hexadecimal numeral, it first searches its symbol table for a definition of the symbol. If SDA finds no definition for the string, it evaluates the string as a hexadecimal number.

SDA> EVALUATE (((TEN * 6) + (-1/4)) + 6)
Hex = 00000000.00000042      Decimal = 66
      

This example shows how SDA evaluates an expression of several terms, including symbols and rational fractions. SDA evaluates the symbol, substitutes its value in the expression, and then evaluates the expression. Note that the fraction -1/4 is truncated to 0.

SDA> EVALUATE/CONDITION 80000018
%SYSTEM-W-EXQUOTA, exceeded quota
      

This example shows the output of an EVALUATE/CONDITION command.

SDA> EVALUATE/PS  0B03
         MBZ SPAL      MBZ    IPL VMM MBZ CURMOD INT PRVMOD
         0   00   00000000000 0B  0   0   KERN   0   USER
         
      

SDA interprets the entered value 0B03 as though it were a processor status (PS) and displays the resulting field values.

SDA> EVALUATE/PTE 0BCDFFEE
 
 



  

    

      

      
 
  
 
  
3 3 2  2              2   1   1 1 
1 0 9  7              0   8   6 5               7 6           0 
+-+-+--+--------------+-+-+---+-+---------------+-+-----------+-+ 
|0|0|00|     005E     |0|X| 02|1|      FF       |X|    37     |0| 
+-+-+--+--------------+-+-+---+-+---------------+-+-----------+-+ 
|                            00000000                           | 
+---------------------------------------------------------------+ 
Global PTE:  Owner = S, Read Prot = KESU, Write Prot = KESU, CPY = 0 
                     GPT Index  = 00000000 




      

The EVALUATE/PTE command displays the expression ABCDFFEE as a page table entry (PTE) and labels the fields. It also describes the status of the page.

SDA>EVALUATE/TIME 009A9A4C.843DBA9F
10-OCT-1996 15:59:44.02
      

This example shows the use of the EVALUATE/TIME command.

Displays either the contents of a location or range of locations in physical memory, or the contents of a register. Use location parameters to display specific locations or use qualifiers to display entire process and system regions of memory.

Format

EXAMINE [/qualifier[,...]] [location]

Parameter

location

Location in memory to be examined. A location can be represented by any valid SDA expression. (See Chapter 2, Section 2.6.2 for additional information about expressions.) To examine a range of locations, the following syntax is used:

m:n	Range of locations to be examined, from m to n
m;n	Range of locations to be examined, starting at m and continuing for n bytes

The default location that SDA uses is initially 0 in the program region (P0) of the process that was executing at the time the system failed (if you are examining a crash dump) or your process (if you are examining the running system). Subsequent uses of the EXAMINE command with no parameter specified increase the last address examined by 8. Use of the /INSTRUCTION qualifier increases the default address by 4. To examine memory locations of other processes, you must use the SET PROCESS command.

Qualifiers

/ALL

Examines all the locations in the program, and control regions and parts of the writable system region, displaying the contents of memory in hexadecimal longwords. Do not specify parameters when you use this qualifier.

/CONDITION_VALUE

Examines the specified longword, displaying the message the $GETMSG system service obtains for the value in the longword.

/INSTRUCTION

Translates the specified range of memory locations into assembly instruction format. Each symbol in the EXAMINE expression that is defined as a procedure descriptor is replaced with the code entry point address of that procedure, unless you also specify the /NOPD qualifier.

/NOPD

Can be used with the /INSTRUCTION qualifier to override treating symbols as procedure descriptors. The qualifier can be placed immediately after the /INSTRUCTION qualifier, or following a symbol name.

For more details in using the /NOPD qualifier, see the description for the /PD qualifier.

/NOSUPPRESS

Inhibits the suppression of zeros when displaying memory with one of the following qualifiers: /ALL, /P0, /P1, /SYSTEM, or when a range is specified.

/P0

Displays the entire program region for the default process. Do not specify parameters when you use this qualifier.

/P1

Displays the entire control region for the default process. Do not specify parameters when you use this qualifier.

/PD

Causes the EXAMINE command to treat the location specified in the EXAMINE command as a procedure descriptor (PD). PD can also be used to qualify symbols.

The /PD and /NOPD qualifiers can be used with the /INSTRUCTION qualifier to override treating symbols as procedure descriptors. Placing the qualifier right after a symbol will override how the symbol is treated. /PD will force it to be a procedure descriptor, and /NOPD will force it to not be a procedure descriptor.

Only the /PD qualifier can be placed right after the /INSTRUCTION qualifier. It treats the calculated value as a process descriptor.

In the following examples, TEST_ROUTINE is a PD symbol. Its value is 500 and the code address in this procedure descriptor is 1000:

EXAMINE/INSTRUCTION TEST_ROUTINE/NOPD+20

displays instructions starting at 520

EXAMINE/INSTRUCTION TEST_ROUTINE+20

fetches code address from TEST_ROUTINE PD. Adds 20 and displays instructions at that address. In other words, it displays code starting at location 1020.

EXAMINE/INSTRUCTION/PD TEST_ROUTINE/NOPD+20

treates the address TEST_ROUTINE+20 as a procedure descriptor, so it fetches the code address out of a procedure descriptor at address 520. It then uses that address to display instructions.

/PHYSICAL

Examines physical addresses. The /PHYSICAL qualifier cannot be used in combination with the /P0, /P1, or /SYSTEM qualifiers.

/PS

Examines the specified quadword, displaying its contents in the format of a processor status. This qualifier must precede any parameters used in the command line.

/PTE

Interprets and displays the specified quadword as a page table entry (PTE). The display separates individual fields of the PTE and provides an overall description of the PTE's type.

/SYSTEM

Displays portions of the writable system region. Do not specify parameters when you use this qualifier.

/TIME

Examines the specified quadword, displaying its contents in the format of a system-date-and-time quadword.

Description

The following sections describe how to use the EXAMINE command.

Examining Locations

When you use the EXAMINE command to look at a location, SDA displays the location in symbolic notation (symbolic name plus offset), if possible, and its contents in hexadecimal and ASCII formats:

SDA> EXAMINE G6605C0 806605C0: 64646464.64646464 "dddddddd"

If the ASCII character that corresponds to the value contained in a byte is not printable, SDA displays a period (.). If the specified location does not exist in memory, SDA displays this message:

%SDA-E-NOTINPHYS, address : virtual data not in physical memory

To examine a range of locations, you can designate starting and ending locations separated by a colon. For example:

SDA> EXAMINE G40:G200

Alternatively, you can specify a location and a length, in bytes, separated by a semicolon. For example:

SDA> EXAMINE G400;16

When used to display the contents of a range of locations, the EXAMINE command displays six columns of information:

• Each of the first four columns represents a longword of memory, the contents of which are displayed in hexadecimal format.
• The fifth column lists the ASCII value of each byte in each longword displayed in the previous four columns.
• The sixth column contains the address of the first, or rightmost, longword in each line. This address is also the address of the first, or leftmost, character in the ASCII representation of the longwords. Thus, you read the hexadecimal dump display from right to left, and the ASCII display from left to right.

If a series of virtual addresses does not exist in physical memory, SDA displays a message specifying the range of addresses that were not translated.

If a range of virtual locations contains only zeros, SDA displays this message:

Zeros suppressed from 'loc1' to 'loc2'

Decoding Locations

You can translate the contents of memory locations into instruction format by using the /INSTRUCTION qualifier. This qualifier causes SDA to display the location in symbolic notation (if possible) and its contents in instruction format. The operands of decoded instructions are also displayed in symbolic notation. The location must be longword assigned.

Examining Memory Regions

You can display an entire region of virtual memory by using one or more of the qualifiers /ALL, /SYSTEM, /P0, and /P1 with the EXAMINE command.

Other Uses

Other uses of the EXAMINE command appear in the following examples.

Examples

SDA> EXAMINE/PS 7FF95E78
          MBZ SPAL      MBZ    IPL VMM MBZ CURMOD INT PRVMOD 
          0   00   00000000000 08  0   0   KERN   0   EXEC   
      

This example shows the display produced by the EXAMINE/PS command.

SDA>EXAMINE/PTE @^QMMG$GG_L1_BASE
      

3 3 2 2 2 1 1 1 1 0 9 7 0 8 6 5 7 6 0 +-+-+--+--------------+-+-+---+-+---------------+-+-----------+-+ |0|1|00| 0000 |0|X| 00|0| 11 |X| 04 |1| +-+-+--+--------------+-+-+---+-+---------------+-+-----------+-+ | 00000C37 | +---------------------------------------------------------------+ Valid PTE: Read Prot = K---, Write Prot = K--- Owner = K, Fault on = -E--, ASM = 00, Granularity Hint = 00 CPY = 00 PFN = 00000C37

---

Previous

Next

Contents

Index

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6549PRO_005.HTML