Document revision date: 30 March 2001

## OpenVMS Alpha System Analysis Tools Manual

Previous | Contents | Index

## DEFINE

> 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

#1
    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.

#2
    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.

#3
    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.

#4
    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).

## DEFINE/KEY

> 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
> PF2 | LK201, VT100
> PF3 | LK201, VT100
> 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

> #### /IF_STATE=state_list

> #### /NOIF_STATE

> Specifies a list of one or more states, one of which must be in effect for the key definition to work. The /NOIF_STATE qualifier has the same meaning as /IF_STATE=current_state. The state name is an alphanumeric string. States are established with the /SET_STATE qualifier. If you specify only one state name, you can omit the parentheses. By including several state names, you can define a key to have the same function in all the specified states.

> #### /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. The /KEY qualifier must be specified.

> #### /LOCK_STATE

> #### /NOLOCK_STATE

> Specifies that the state set by the /SET_STATE qualifier remains in effect until explicitly changed. By default, the /SET_STATE qualifier is in effect only for the next definable key you press or the next read-terminating character that you type. This qualifier can be specified only with the /SET_STATE qualifier.

> /NOLOCK_STATE is the default.

> #### /SET_STATE=state-name

> #### /NOSET_STATE

> Causes the key being defined to create a key state change instead of or in addition to issuing an SDA command. When you use the /SET_STATE qualifier, you supply the name of a key state to be used with the /IF_STATE qualifier in other key definitions.

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

> /NOSET_STATE is the default.

> #### /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 you specify the /TERMINATE qualifier.

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

#1
    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 you press the PF1 key, SDA displays the command and waits for you to press the Return key.

#2
    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.

#3
    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, you must press PF1 before pressing PF3 to issue the SHOW STACK command. The /TERMINATE qualifier causes the command to execute as soon as you press the PF3 key.

## DUMP

> Displays the contents of a range of memory formatted as a comma-separated variable (CSV) list, suitable for inclusion in a spreadsheet.

### Format

> DUMP range
> [/LONGWORD (default)|/QUADWORD]
> [/DECIMAL|/HEXADECIMAL (default)]
> [/FORWARD (default)|/REVERSE]
> [/RECORD_SIZE=size] (default = 512)
> [/INDEX_ARRAY [={ LONGWORD (default)|QUADWORD}] ]
> [/INITIAL_POSITION={ ADDRESS = address|RECORD = number}]
> [/COUNT = {ALL|records}] (default = all records)
> [/PHYSICAL]

### Parameter

> #### range

> The range of locations to be displayed. The range is specified in one of the following formats:

> m:n | Range from address m to address n inclusive
> m;n | Range from address m for n bytes

### Qualifiers

> #### /COUNT=[{ ALL|records}]

> Gives the number of records to be displayed. The default is to display all records.

> #### /DECIMAL

> Outputs data as decimal values.

> #### /FORWARD

> Causes SDA to display the records in the history buffer in ascending address order. This is the default.

> #### /HEXADECIMAL

> Outputs data as hexadecimal values. This is the default.

> #### /INDEX_ARRAY [={ LONGWORD (default)|QUADWORD}]

> Indicates to SDA that the range of addresses given is a vector of pointers to the records to be displayed. The vector can be a list of longwords (default) or quadwords. The size of the range must be an exact number of longwords or quadwords as appropriate.

> #### /INITIAL_POSITION = { ADDRESS = address|RECORD = number}

> Indicates to SDA which record is to be displayed first. The default is the lowest addressed record if /FORWARD is used, and the highest addressed record if /REVERSE is used. The initial position may be given as a record number within the range, or the address at which the record is located.

> #### /LONGWORD

> Outputs each data item as a longword. This is the default.

> #### /PHYSICAL

> Indicates to SDA that all addresses (range and/or start position) are physical addresses. By default, virtual addresses are assumed.

> #### /QUADWORD

> Outputs each data item as a quadword.

> #### /RECORD_SIZE=size

> Indicates the size of each record within the history buffer, the default being 512 bytes. Note that this size must exactly divide into the total size of the address range to be displayed, unless /INDEX_ARRAY is specified.

> #### /REVERSE

> Causes SDA to display the records in the history buffer in descending address order.

### Description

> The DUMP command displays the contents of a range of memory formatted as a comma-separated variable (CSV) list, suitable for inclusion in a spreadsheet. It is intended for use with a "history" buffer containing records of information of which the most recently written entry is in the middle of the memory range.

> Note See SET OUTPUT/NOHEADER for related information.

### Examples

#1
    SDA> DUMP dump g;200/initial_position=record=5/record_size=20/reverse
    05,A77B0010,A79B0008,6B9C4001,47FF041F,A03E0000,47DF041C,201F0016,083
    04,A03E0000,47DF041C,201F0058,083,A77B0010,A79B0008,6B9C4001,47FF041F
    03,A03E0000,47DF041C,201F0075,083,A03E0000,47DF041C,201F001B,083
    02,A77B0010,A79B0008,6B9C4001,47FF041F,A03E0000,47DF041C,201F0074,083
    01,43E05120,083,6BFA8001,47FF041F,A77B0010,A79B0008,6B9C4001,47FF041F
    0,201F0104,6BFA8001,47FF041F,47FF041F,201F0001,6BFA8001,47FF041F,47FF041F
    0F,A03E0000,47DF041C,201F0065,083,A03E0000,47DF041C,201F0006,083
    0E,A03E0000,47DF041C,201F001C,083,A03E0000,47DF041C,201F001A,083
    0D,A03E0000,47DF041C,201F0077,083,A03E0000,47DF041C,201F0057,083
    0C,A03E0000,47DF041C,201F002B,083,A03E0000,47DF041C,201F003A,083
    0B,A03E0000,47DF041C,201F007D,083,A77B0010,A79B0008,6B9C4001,47FF041F
    0A,A03E0000,47DF041C,201F005A,083,A03E0000,47DF041C,201F0078,083
    09,A03E0000,47DF041C,201F0002,082,A03E0000,47DF041C,201F0037,083
    08,A03E0000,47DF041C,201F0035,083,A03E0000,47DF041C,201F007A,083
    07,A03E0000,47DF041C,201F0019,083,A03E0000,47DF041C,201F0034,083
    06,A77B0010,A79B0008,6B9C4001,47FF041F,A03E0000,47DF041C,201F0018,083

> This example shows the dump of an area of memory treated as 16 records of 32 bytes each, beginning at record 5, and dumped in reverse order. Note the record number in the first field, and that the dump wraps to the end of the memory area once the first record has been output.

#2
    SDA> examine SMP$GL_CPU_DATA;80
    00000000 00000000 8FE26000 8FE14000 00000000 00000000 8FE02000 811FE000  ...
    00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000  ...
    00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000  ...
    00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000  ...
    SDA> dump SMP$GL_CPU_DATA;80/index_array/record_size=20/count=5
    0,810C17C0,8EC7C180,026A09C0,02,0,FFFFFFFF,0,0
    01,810C17C0,8EC7C400,026A09C0,02,0,FFFFFFFF,0,01
    04,810C17C0,8EC7CB80,026A09C0,02,0,FFFFFFFF,0,04

> This example shows the contents of the CPU database vector, then dumps the first 32 bytes of each CPU database entry. Note that only the first five entries in the array are requested, and those containing zero are ignored.

## EVALUATE

> 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 five 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 you do not specify a qualifier, the EVALUATE command interprets and displays the expression as hexadecimal and decimal values. In addition, 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. (See Section 2.6.2.4 for a description of how SDA displays symbols and offsets.) 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.

###

#### Examples

#1
    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.

#2
    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 maximum of five symbols are displayed by default.

#3
    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.

#4
    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.

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

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

#6
    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.

#7

    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 0BCDFFEE as a page table entry (PTE) and labels the fields. It also describes the status of the page.

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

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

Previous | Next | Contents | Index

| privacy and legal statement |
6549PRO_005.HTML