TOCPREVNEXTINDEX

Lund Performance Solutions


The AVATAR Tool
AVATAR’s decompiler capabilities include the ability to find, view, and modify the contents of any Native Mode program file, object file, executable library, or relocatable library. The AVATAR command set includes a variety of commands that simplify tasks like disassembling and modifying program files. Other features are geared towards deciphering header information in executable libraries and extracting portions of code into assembly language source.
Warning: AVATAR was designed to be used by experienced software engineers. In terms of how it is used, AVATAR is very similar in feel to Hewlett-Packard’s DEBUG. Therefore, if you are not comfortable using DEBUG you will not be comfortable using AVATAR. Proceed at your own risk, exercising appropriate caution.
AVATAR is more effectively used if you understand the following concepts:
  • HPPA assembly language
  • Procedure calling
  • Parameter passing conventions
  • Operation

    The primary use of AVATAR is to perform operations on SOMs. A SOM is a file that conforms to HP’s Standard Object Module conventions. There are four classes of files with which AVATAR is particularly familiar. Each of these four classes is easily identified by its filecode:

    NMPRG
    Native mode program files
    NMXL
    Native mode executable libraries
    NMRL
    Native mode relocatable libraries
    NMOBJ
    Native mode object files

    In addition to working on the file classes listed above, AVATAR can also be used as a binary editor to display and modify most other MPE files.
    When AVATAR is used as a decompiler, its output is displayed as assembly language and hexadecimal constants. To add symbolic information about register usage to the disassembled display, use AVATAR’s SYN command.
    A complete description of the assembly language can be found in HP’s Precision Architecture and Instruction Reference Manual. Another useful manual is HP’s Procedure Calling Convention Reference Manual, which describes how the general registers and stack frame are set up for procedure calls. Use the CSEQ tool to display the calling sequences for MPE intrinsics.
    After starting AVATAR, the AVATAR: prompt will be displayed. The next step is usually to OPEN a file. At that point, commands are entered to accomplish the task at hand. The general form for entering commands is:
    AVATAR: <command> [<expression>]
    The sections that follows describe the syntax and usage for all of AVATAR’s commands as well as the structure of an expression.

    Capabilities

    Program capabilities required include IA, BA, PM, DS, and PH. PM is required to run DEBUG.

    Usage

    AVATAR can be started from the supplied UDC or from a RUN statement. AVATAR does not use the INFO string or PARM.
    To start AVATAR, use one of the following methods:
  • UDC
  • :AVATAR
  • RUN
  • :RUN AVATAR.PUB.LPSTOOLS

    Expression Structure

    Expressions are used in many of the commands.
    Syntax:
    <expression> ::= <term> [ + | - <term> ]
    <term> ::= <factor> [ * | / <factor> ]
    <factor> ::= [ + | - ] <primary>
    <primary> ::= [ <expression> ]
    [` <assembler instruction> `]
    [ <number> ]
    [ SOM_HEADER ]
    [ LST_HEADER ]
    [ AUX_HEADER ]
    [ SPACE_DICT ]
    [ SUBSPACE_DICT ]
    [ LOADER_FIXUP ]
    [ SPACE_STRINGS ]
    [ INIT_ARRAY ]
    [ COMPILER_DICT ]
    [ SYMBOL_DICT ]
    [ FIXUP ]
    [ SYMBOL_STRINGS ]
    [ UNL_SPACE ]
    [ PROCTIME ]
    [ <symbol> ]
    [ " <symbol> " ]
    <assembler instruction>
    Is a valid assembler instruction. The instruction is enclosed in back-quotes.
    <number> ::=
    [ $ <hexadecimal digits> ]
    [ % <octal digits> ]
    [ # <decimal digits> ]
    [ <digits in current radix> ]
    <symbol>
    Is the value of any symbol defined in the current SOM. If the symbol is not enclosed in quotes, then it can not be one of the previously defined words (i.e. PROCTIME) and it can only contain characters from the set 'A'..'Z', 'a'..'z', '0'..'9', '_', '$', '#', '%'.
     
    If the name of the symbol is preceded with a ? then the value of a stub with that name is used.
     
    Strings are also used in many commands. Strings can be given as a simple string or as a compound string. A simple string is 'zero or more characters enclosed in double-quotes'. A compound string is a list of substrings, enclosed in braces ({}). A substring can be a string enclosed in double-quotes or a number representing the value of one byte. Example: "This is a string", while {"This is a string with a new-line character" $a}.

    Foundation Topic Discussions

    This section discusses concepts and terminology that you may find helpful in understanding the information presented about AVATAR. First, a brief background section introduces Standard Object Modules (SOMs), and then assembly language and mapped files are discussed in relation to how they are used in AVATAR.

    Standard Object Modules

    Standard Object Modules are the smallest unit which may be generated by a compiler. They correspond to a given order, regardless of the file type. For instance, the architecture of an NMPRG begins with header and procedural information that is important to the operating system. After this, data and code segments follow.
    A set of SOMs is defined as a library which may be either executable (NMXL) or relocatable (NMRL). Each library will contain library symbol table (LST) that describes its contents in terms of SOMs.
    Relocatable libraries contain one or more SOMs that must be linked (using LINKEDIT) with the SOM that references it. Executable libraries contain one or more SOMs that have already been linked and are ready to execute. The SOMs in an executable library are dynamically loaded by MPE/iX when referenced.
    Multiple SOMs can be stored in an object file, an executable library or a relocatable library. Once procedures are bound into a single SOM, they cannot be separated. AVATAR provides the capability to patch the assembler code of your compiled program. This means you now have the ability to support discontinued programs that may be important to your business or patch those almost-perfect programs when your vendor’s bug priority list doesn’t quite coincide with yours.
    A SOM can contain many procedures that have been combined into a single SOM. Normally, once a set of procedures has been combined by a compiler into a SOM, they are not easily separated from the SOM. AVATAR’s EXTRACT command breaks the SOM out into a separate ASCII file in assembler format that can be edited and assembled.

    Assembly Language

    Hewlett-Packard’s Precessions Architecture Assembly Language is a symbolic, more approachable, representation of MPE/iX machine language. Familiarity with assembly language may prove helpful in understanding AVATAR’s output, capabilities, and features.

    Mapped Files

    "Mapped Files" refers to the virtual address space used by files. This gives the operating system direct reference to all types of information in a manner that is reminiscent of disk-caching. Every byte of every opened file ha a unique virtual address. Portions of files are brought into real memory on demand, leaving behind other portions that are not yet required.

    NOTE Use the KLONDIKE tool from the System Manager’s Toolbox to view how much of a file is in real memory.

    MPE/iX’s treatment of virtual memory brings efficiency and flexibility to memory management that was non-existent with MPE V.

    Command Summary

    The following list provides a simple description of AVATAR commands that you can use to quickly locate the command that suits the task at hand. Detailed information on each command is provided in the next section.

    NOTE Portions of the Command Codes are printed in uppercase to denote the part of the command that AVATAR requires in order to distinguish one command from another. The commands themselves are not case-sensitive.

    Table 3.1 AVATAR Commands
    Command Code
    Description
    =
    Calculates a value from an expression
    ASM
    Shows the machine code for an assembler instruction
    AUX
    Prints the auxiliary headers
    CALCulate
    Evaluates an expression and displays the result
    CALLee
    Lists all calls to a given object from a code range
    CALLS
    Lists all call objects from a code range
    CHecksum
    Computes a new SOM checksum value
    CLose
    Closes a SOM file
    COmpiler
    Displays compiler information
    COUnt
    Counts all symbol types
    DC
    Displays data at a code address
    DD
    Displays data at a data address
    Debug
    Enters the system debugger
    DIsasm
    Shows the assembler instruction for a binary machine code
    DP
    Displays data starting at a procedure
    DR
    Displays real memory, use with extreme caution
    DV
    Displays data at a file offset
    Exit
    Terminates AVATAR
    EXtract
    Extracts a portion of code into an assembler source file
    Find
    Finds a symbol in the current SOM
    FINDAll
    Finds a symbol in all SOMs in the current SOM file
    FIXup
    Displays fixup information
    FORMAT
    Format data at a file offset
    HELP
    Invokes AVATAR help
    Init
    Displays initialization record information
    Look
    Looks at a symbols attributes
    LSt
    Lists all module names in SOM
    MC
    Modifies data at a code address
    MD
    Modifies data at a data address
    MV
    Modifies data at a file offset
    Next
    Displays more data, after a DC, DD, DP or DV command
    Open
    Opens a SOM file for processing
    Quit
    Exits the program
    Radix
    Changes the default radix
    Search
    Search for a value in the SOM file
    SPace
    Displays space header information
    STatistics
    Displays SOM file statistics
    STRIP
    Remove symbolic information from SOM
    SUbspace
    Displays subspace header information
    SYMFormat
    Format options for SYMOS information display
    SYMOpen
    Opens a SYMOS file for examination
    SYn
    Sets up synonyms for registers
    UNCALLED
    Displays entry points that are never called
    UNWIND
    Displays unwind descriptors
    Most commands may be abbreviated somewhat.
    Although most of the AVATAR commands require that a SOM file be open, the DV and MV commands can be used after OPENing any kind of file.

    Command Definitions

    This section describes AVATAR commands in detail.

    =

    This command has the following syntax:
    = <expression>
    The equal sign (=) operator when followed by an expression can be used to calculate the value of the expression.
    Example 1: = 5+3
    Example 2: = ’nop’

    ASM

    This command has the following syntax:
    ASM <assembler instruction>
    The ASM (assemble) command shows the binary machine code for an assembler instruction.
    <assembler instruction> = a valid assembler instruction.
    Example1: ASM ldo 1(0),31
    Example 2: ASM bl $$lr_unk_unk,31

    AUX

    The AUX command prints all the auxiliary headers from the current SOM. The format will depend on the actual header type of each header. Each auxiliary header is constructed of 6 fields:

    MANDATORY
    The MANDATORY field is used to indicate if this SOM contains information that the linker must understand.
    COPY
    The COPY field is used to indicate that this auxiliary header should be copied without change to any new SOM created from this SOM.
    APPEND
    The APPEND field is used to indicate entries with the same TYPE and APPEND fields should be merged together.
    IGNORE
    The IGNORE field is used to indicate this auxiliary header should be ignored if its TYPE field is unknown.
    TYPE
    The TYPE field is a numeric field that is used to describe the contents of this auxiliary header. The list of known values are provided next.
    LENGTH
    See the following table.

    Known values for the Type field are shown in the following table:
    Table 3.2 TYPE field values
    Value
    Meaning
    Associated Auxiliary Header
    0
    NULL
     
    1
    LINK information
    LINK aux header
    2,7
    HP Program
    HP Program aux header
    3
    DEBUG
    DEBUG aux header
    4
    HP-UX aux header
    HP-UX aux header
    5
    IPL aux header
    IPL aux header
    6
    User string aux header
    User string aux header
    8
    SOM
    HP SOM aux header
    The LENGTH field contains the number of bytes in the auxiliary header less 4 bytes.
    Auxiliary Header Definitions
    The various headers that can be used with the AUX command are described below:

    LINK
    This auxiliary header is used to record the last time the linker modified the SOM. The four elements in this header include:
    aux header id
    linker version id
    linker product id
    link time
    HP Program
    This auxiliary header contains information that is used by the operating system to load an executable. The seven elements in this header include:
    aux header id
    unsat names
    capabilities
    max stacksize
    entry name
    search list
    max heapsize
     
    DEBUG
    This auxiliary header is used to record the last time that the debugger modified the SOM. The four elements in this header include:
    aux header id
    debugger version id
    debugger product id
    debug time
    HP-UX
    This auxiliary header contains information that is used by the UX loader. The eleven elements in this header include:
    aux header id
    execute code size
    execute code offset memory
    execute code offset SOM
    execute data size
    execute data offset memory
    execute data offset SOM
    execute uninitialized data size
    execute start entry
    execute initialized data
    execute loader flags
    IPL
    This auxiliary header contains information that is used for loading bootable utilities. The six elements in this header include:
    aux header id
    physical address destination
    bbs size
    file length
    entry offset
    checksum
    User String
    This auxiliary header is used to store user definable strings. Typically the user-definable strings are defined through compiler directives like VERSION and COPYRIGHT. The three elements in this header are:
    aux header id
    string length
    string
     
    HP SOM
    This auxiliary header contains information necessary to load executable SOMs. The seven elements of this header are:
    aux header id
    num of XRTs
    unwind end
    ecover end
    SOM flag
    unwind start
    recover start








    Figure 3.1 AUX Example

    CALCulate

    This command has the following syntax:
    CALCulate <expression>
    The CALCULATE command will evaluate will evaluate an expression and display the resultant value in hexadecimal and decimal.

    <expression>
    An arithmetic expression

    All calculations are done using 32-bit integer arithmetic.
    Example1: =5+20-$15
    Example 2: =FOPEN

    CALLee

    This command has the following syntaxes:
    CALLee <calleename> <procedurename>
    or
    CALLee <calleename> <startoffset> <endoffset>

    <calleename>
    The name of the callee to be searched.
    <procedurename>
    The procedure in which the calls must occur.
    If neither a procedure name nor a range is given, then the whole SOM will be searched.
    <startoffset>
    The staring point from where searching begins.
    <endoffset>
    The ending point of the search.

    This command is used to locate all calls to a given procedure calleename over the specified range. The calleename can be any symbol found in the currently selected SOM. The calleename cannot contain any wildcards and is case-sensitive. Ranges are specified in one of the three ways: by procedurename, by an explicit offset range, or not specified. An unspecified range forces a search of the entire SOM. The range specifiers can be constructed using any valid expression.
    Example 1: CALLEE fwrite
    Example 2: CALLEE fwrite myprocedure
    Example 3: CALLEE fwrite myprocedure+$b myprocedure+1000

    CALLS

    This command has the following syntaxes:
    CALLS <procedurename>
    or
    CALLS <startoffset> <endoffset>

    <procedurename>
    The procedure in which the calls must occur.
    If neither a procedure name nor a range is given, then the whole SOM will be searched.
    <startoffset>
    The staring point from where searching begins.
    <endoffset>
    The ending point of the search.

    This command is used to locate calls to a given procedure over the specified range. Ranges are specified in one of the three ways: by procedurename, by an explicit offset range, or not specified. The latter forces a search of the entire SOM. The range specifiers can be constructed using any valid expression.
    Example 1: CALLS
    Example 2: CALLS myprocedure
    Example 3: CALLS myprocedure+$b myprocedure+1000

    CHecksum

    This command has no parameters. It works with the currently opened SOM. The SOM header is constructed of 124 bytes. The CHECKSUM entry is the last word in the header and is not included in its calculation. Anytime AVATAR changes part of the SOM header the CHECKSUM command should be used to recalculate the CHECKSUM. The CHECKSUM word is created by exclusive "OR-ing" all of the words in the SOM header. This provides a simple, quick way of determining if the SOM contains a valid header. The CHECKSUM command will calculate the checksum for the currently opened SOM file and replace the existing value with the new one. This is necessary if you have modified the first 124 bytes of the SOM file.

    CLose

    This command will close the currently opened SOM file. This really is not necessary because the OPEN command will close any opened SOM file.

    COmpiler

    This command has no parameters. Output from this command provides general information about the SOM, as well as information specific to each module within the SOM. For example, a compiled C module could contain the following information. For a NMOBJ file on a Spectrum machine, general information items (numbers in hexadecimal) are:

    system id = 20B
    Spectrum architecture
    magic# = 106
    Relocatable SOM
    version id = 5124000
    The ending point of the search.

    SOM-specific information:

    source file name
    = C2SPL
    language name
    = HP-C
    product id
    = HP31506
    version id
    = C/XL Compiler Version A.01.22

    Other magic numbers that might be generated for a NMOBJ file on a Spectrum machine include the following:
    These two entries have Library Symbol Table headers
    $104 = executable library (NMXL)
    $619 = relocatable library (NMRL)
    These entries have SOM headers.
    $106 = relocatable SOM
    $107 = non-shareable, executable SOM
    $108 = shareable, executable SOM
    $10B = shareable, demand-loaded executable SOM

    COUnt

    This command is used to display the symbol type and corresponding scopes for all symbols in the current SOM in tabular format. Provided in the following list is a complete listing and short definition of each symbol type for a SOM. Following the symbol types list is a similar list for symbol scopes.
    Table 3.3 SOM Symbol Types
    Symbol
    Description
    NULL
    Invalid symbol record
    ABSOLUTE
    Absolute constant
    DATA
    Normal initialized data
    CODE
    Unspecified code, resolved at link time
    PRI_PROG
    Primary program entry point
    SEC_PROG
    Secondary program entry point
    ENTRY
    Code entry point symbols
    STORAGE
    Storage requirement; known length, unknown value
    STUB
    External call stub, or relocation stub
    MODULE
    Source module name
    SYM_EXT
    Extension record of the current entry
    ARG_EXT
    Extension record of the current entry
    MILLICODE
    Name of a millicode subroutine
    PLABEL
    Procedure label
    OCT_DIS
    Used by OCT (Object Code Translator)
    MILLI_EXT
    Address of an external millicode subroutine
    Table 3.4 SOM Symbol Scopes
    Symbol
    Description
    UNSAT
    Unsatisfied import request
    EXTRN
    Import request to a symbol in another SOM
    LOCAL
    Private symbol
    UNIVERSAL
    Symbol to be exported outside the SOM
    SCOPE
    TYPE
    UNSAT
    LOCAL
    EXTERNAL
    UNIVERSAL
    NULL
     
     
     
     
    ABSOLUTE
    X
    X
     
    X
    DATA
    X
    X
     
    X
    CODE
     
     
     
    X
    PRI_PROG
     
     
     
    X
    SEC_PROG
     
     
     
    X
    ENTRY
     
    X
     
    X
    STORAGE
    X
    X
     
    X
    STUB
     
    X
    X
     
    MODULE
     
    X
     
    X
    SYM_EXT
     
     
     
     
    ARG_EXT
     
     
     
     
    MILLICODE
    X
    X
     
    X
    PLABEL
     
    X
     
     
    OCT_DIS
     
    X
     
    X
    MILLI_EXT
     
     
     
    X

    DC

    This command has the following syntax:
    DC <code offset> [<display format>] [<numlines>]
    The DC command will display data at a given code address. The data will be displayed in assembler format by default, but other formats may be specified.

    <code offset>
    An expression giving the offset to the start of the current code module, where data to display starts.
    <display format>
    Either C or D. Default is C. If D is specified then data is displayed in hex and ascii format. If C is specified then data is displayed as disassembled code.
    <numlines>
    A decimal number, indicating the number of lines to show.

    Example 1: DC my_procedure_name
    Example 2: DC proc + $15 D 12

    DD

    This command has the following syntax:
    DD <data offset> [<display format>] [<numlines>]
    The DD command will display values (data) from an initialized block within the current module of the opened SOM file. Data will be displayed in hexadecimal and ASCII formats by default.

    <data offset>
    An expression giving the start within an initialized block, where display starts.
    <display format>
    Either C or D. Default is D. If D is specified then data is displayed in hex and ascii format. If C is specified then data is displayed as disassembled code.
    <numlines>
    A decimal number, indicating the number of lines to show.
    The default value is to keep on displaying until the next control-y or '/' reply.

    Example 1: DD $40000008
    Example 2: DD dl_area 20

    Debug

    This command invokes the system debug program, DEBUG. There are no parameters for this command.


    Figure 3.2 DEBUG Command
    See the System Debug Reference Manual for details on using DEBUG.

    DIsasm

    This command has the following syntax:
    DIsasm <expression>
    The DISASM command shows the assembler instruction corresponding to a machine code defined by expression.
    Example 1: DISASM $8000240
    Example 2: DISASM ’nop’

    NOTE The assembler instruction is enclosed in back-quotes.

    DP

    This command has the following syntax:
    DP <procedure name>
    The DP command will display code for a given procedure. The data will be displayed in assembler format.

    <procedure name>
    Any procedure that has been defined in the current module of the opened SOM file.

    Example: DP my_procedure_name

    DR

    This command has the following syntax:
    DR <expression>
    The DR command will display real memory starting at the physical address given by the expression.
    Example: AVATAR DR $4000 (see Figure 3.22)

    DV

    This command has the following syntax:
    DV <data offset> [<display format>] [<numlines>]
    The DV command will display values (data) from within the current SOM file. Data will be displayed in hexadecimal and ASCII formats by default.

    <data offset>
    An expression giving the offset from the start of the file, where display starts.
    <display format>
    Either C or D. Default is D. If D is specified then data is displayed in hex and ascii format. If C is specified then data is displayed as disassembled code.
    <numlines>
    A decimal number, indicating the number of lines to show. The default value is to keep on displaying until the next control-y or '/' reply.

    Example 1: DV $100 Displays data starting at address hex 100
    Example 2: DV 5+20-$15 C Display lines at address 4, disassembled as code
    To dump the SOM header for a NMOBJ, try the following:


    Figure 3.3 Dumping the SOM

    Exit

    The EXIT command terminates AVATAR.

    EXtract

    This command has the following syntax:
    EXtract <file name> <start> [<end>]
    The EXTRACT command extracts a portion of code into an ASCII file. This file can be used as input to the ASSEMBLER.

    <file name>
    The name of a file to be created. The file may not exist.
    <start>
    The starting point from which extraction begins.
    <end>
    The last instruction to be extracted. If omitted, AVATAR tries to extract to the end of the procedure referred to in <start>.

    Example 1: EXTRACT file1 $1000 $2000
    Example 2: EXTRACT file2 my_proc my_proc+1000
    Example 3: EXTRACT foo fopen_nm

    Find

    This command has the following syntax:
    Find <string> <filter> | <symbol> <filter>
    The FIND command will find all entries in the symbol dictionary that have a name that matches or partially matches the provided string. Entries in the symbol dictionary include all procedures, global data items, intrinsics, etc. The search is limited to the current module of the opened SOM file. The FINDALL command searches through all modules.
    <string>
    Any string of ASCII characters enclosed in double quotes.
    <symbol>
    Any string of valid symbol characters.
    <filter>
    A symbol type to be filtered out. The default is that all symbols are listed. The possible filter values are listed below:
    Filter Types

    ABSOLUTE
    EXTERNAL
    NULL
    STORAGE
    ARG_EXT
    LOCAL
    OCT_DIS
    STUB
    CODE
    MILLICODE
    PLABEL
    SYM_EXT
    DATA
    MILLI_EXT
    PRI_PROG
    UNIVERSAL
    ENTRY
    MODULE
    SEC_PROG
    UNSAT


    NOTE To display all symbols, pass a Null string to the FIND command.

    Example 1: FIND time Find any entries that includes the strings time in the name.
    Example 2: FIND $$divoI millicode

    FINDAll

    This command has the following syntax:
    FINDAll <string> <filter> | <symbol> <filter>
    The FINDALL command will find all entries in the symbol dictionary that have a name that matches or partially matches the provided string. Entries in the symbol dictionary include all procedures, global data items, intrinsics, etc. The search will include all modules in the currently opened SOM file, unlike the FIND command (which searches only the current module).
    This is extremely helpful when looking through an XL or even NL.PUB.SYS!

    <string>
    Any string of ASCII characters.
    <symbol>
    Any string of valid symbol characters.
    <filter>
    A symbol type to be filtered out. The default is that all symbols are listed.

    The possible filter values are noted in the Filter Types list for the FIND command. See the section on "Filter Types" for a complete list.

    FIXup

    The FIXUP command displays the fixup records from an object file. Currently only fixups generated by the ASSEMBLER are correctly recognized.
    Key to FIXUP Output
    Symbol_type

    ABSOLUTE
    Absolute constant
    ARG_EXT
    Extension record of the current entry
    CODE
    Unspecified code, resolved at link time
    DATA
    Normal initialized data
    ENTRY
    Code entry point symbols
    MILLICODE
    Name of a millicode subroutine
    MILLI_EXT
    Address of an external millicode subroutine
    MODULE
    Source module name
    NULL
    Invalid symbol record
    OCT_DIS
    Used by OCT (Object Code Translator)
    PLABEL
    Procedure label
    PRI_PROG
    Primary program entry point
    SEC_PROG
    Secondary program entry point
    STORAGE
    Storage requirement with known length & unknown value
    STUB
    External call stub, or relocation stub
    SYM_EXT
    Extension record of the current entry

    Symbol_scope

    EXTERNAL
    Import request to a symbol in another SOM
    LOCAL
    Private symbol
    UNIVERSAL
    Symbol to be exported outside the SOM
    UNSAT
    Unsatisfied import request

    Check_level
    Determines the type checking error level that the linker uses while binding external references to procedures and global variables. All object modules indicate a checking level for each reference and each definition of a procedure or a global variable. When binding an external reference to a definition, the linker compares the type information at the lower of the two checking levels specified by the reference and the definition. If a type mismatch is found, the linker reports it as either a warning or an error.
    The values for check_level are:

    0
    All type mismatches are warnings.
    1
    Mismatches of the procedures, function, or variable type are errors; all other mismatches are warnings.
    2
    Mismatches of the procedures, function, or variable type, and mismatches of the number of arguments for procedures or functions are errors; all other mismatches (i.e., parameter types) are warnings.
    3
    All type mismatches are errors.

    Must_qualify
    Used to indicate if more than one entry has the same symbol name.

    0
    Multiple symbol not present
    1
    Multiple symbol present

    Initially_frozen
    Code using this symbol will be locked into physical memory when the operating system is booted.

    0
    Not frozen
    1
    Frozen

    Memory_resident
    Indicates that the code that will use the symbol is frozen in memory. This provides a way for frozen procedures to communicate.

    0
    Not in memory
    1
    In memory

    Is_common
    Used to indicate if a symbol is in an initialized common data area.

    0
    Not in common
    1
    In common

    Duplicate_common
    Used to indicate if the source language allows duplicate initialization.

    0
    No allowed
    1
    Allowed

    Xleast
    Execution level that is required to call this entry point.

    0:
     
    1:
     
    2:
     
    3:
     

    Argument Relocation
    This fixup information is used to communicate the locations of the first four parameters, and the function return parameter. The linker used this information to match up exported symbol information with fixup references. The four possible values for this field are:

    0
    "Do not relocate"
    1
    "Argument register"
    2
    "Floating point coprocessor register, low"
    3
    "Floating point coprocessor register, high"

    Code offset
    Offset into the SOM where "symbol name" code begins.
    Privilege_level
    Determines the privilege level used by the executable program file. This parameter changes the privilege level of all procedures in the symbol and export tables (of the relocatable object file) that were set during compilation. The values for this field are:

    0
    System level access
    1
    Unused
    2
    Privileged level access
    3
    User level access

    FORMAT

    This command has the following syntax:
    FORMAT <data offset> <format> <count>
    The FORMAT command allows to display data relative to the start of the SOM file in one of many different formats.

    <data offset>
    An expression giving the offset from the start of the file, where formatting starts.
    <format>
    The format specifier. The valid format specifiers are listed below. The composition of each format is detailed in the "Format Specifier Definitions".
    <count>
    An integer giving the number of elements to format.

    Format Specifier List

    AUX_HEADER_ID
    LST_HEADER
    SYMBOL_DICT_REC
    ARG_DESCRIPTOR
    LST_SYMBOL
    SYMDICT_ARG_REC
    COMPILER_REC
    SOM_HEADER
    SYMDICT_EXT_REC
    FIXUP_BITS
    SPACE_REC
    UNWIND_DESCRIPT
    FIXUP_REC
    SUBSPACE_BITS
    UNWIND_ENTRY
    INIT_REC
    SUBSPACE_REC
     
    LST_BITS
    SYMBOL_DICT_BITS
     

    Sample output using the format specifier SOM_HEADER:


    Figure 3.4 SOM_HEADER Format
    Sample output using the format specifier LST_HEADER:


    Figure 3.5 LST_HEADER Format
    Format Specifier Definitions
    The LST_HEADER is composed of the following elements:

    system_id
    module_limit
    string_loc
    a_magic
    dir_loc
    string_size
    version_id
    export_loc
    free_list
    file_time
    export_count
    file_end
    hash_loc
    import_loc
    checksum
    hash_size
    aux_loc
     
    module_count
    aux_size
     

    The LST_BITS is composed of the following elements:

    hidden
    must_qualify
    duplicate_common
    symbol_type
    initially_frozen
    xleast
    symbol_scope
    memory_resident
    arg_relocation
    check_level
    is_common
     

    The LST_SYMBOL is composed of the following elements:

    ls_bits
    symbol_descriptor
    som_index
    symbol_name_ptr
    max_num_args
    symbol_key
    qualifier_name_ptr
    min_num_args
    next_entry
    symbol_info
    num_args
     

    The SOM_HEADER is composed of the following elements:

    system_id
    presumed_dp
    compiler_dictionary_location
    a_magic
    space_dictionary_location
    compiler_dictionary_total
    version_id
    space_dictionary_total
    symbol_dictionary_location
    file_time_a
    subspace_dictionary_location
    symbol_dictionary_total
    file_time_b
    subspace_dictionary_total
    fixup_request_location
    entry_space
    loader_fixup_location
    fixup_request_total
    entry_subspace
    loader_fixup_total
    symbol_strings_location
    entry_offset
    space_strings_location
    symbol_strings_size
    aux_header_location
    space_strings_size
    unloadable_space_location
    aux_header_size
    init_array_location
    unloadable_space_size
    som_length
    init_array_total
    checksum

    The AUX_HEADER_ID is composed of the following elements:

    mandatory
    append
    type
    copy
    ignore
    length

    The SPACE_REC is composed of the following elements:

    name_pointer
    subspace_index
    init_pointer_index
    access_bits
    subspace_quantity
    init_pointer_quantity
    sort_key
    loader_fixup_index
     
    number
    loader_fixup_quantity
     

    The SUBSPACE_BITS is composed of the following elements:

    acb
    is_loadable
    sort_key
    memory_resident
    quadrant
    replicate_init
    duplicate_common
    initially_frozen
    continuation
    is_common
    code_only
     

    The SUBSPACE_REC is composed of the following elements:

    space_index
    startfixup_request_qty
    name_pointer
    bits
    length
    fixup_request_index
    file_loc
    reserved
     
    init_length
    alignment
     

    The COMPILER_REC is composed of the following elements:

    name
    product_id
    compile_time
    language_name
    version_id
    source_time

    The FIXUP_BITS is composed of the following elements:

    need_data_reference
    expression_type
    fixup_format
    arg_relocation
    execution_level
    fixup_field

    The FIXUP_REC is composed of the following elements:

    bits
    symbol_index_one
    fixup_constant
    space_offset
    symbol_index_two
     

    The INIT_REC is composed of the following elements:

    space_index
    access_control
    new_locality
    file_location
    has_data
    length
    memory_resident
    offset
    initially_frozen

    The SYMBOL_DICT_BITS is composed of the following elements:

    bits
    symbol_name_ptr
    qualifier_name_ptr
    symbol_info
    symbol_value
     

    The ARG_DESCRIPTOR is composed of the following elements:

    packing
    alignment
    mode
    structure
    hash
    data_type

    The SYMBOL_DICT_REC is composed of the following elements:

    bits
    symbol_name_ptr
    qualifier_name_ptr
    symbol_info
    symbol_value
     

    The SYMDICT_EXT_REC is composed of the following elements:

    type
    num_args
    arg_descriptor[2]
    max_num_args
    symbol_descriptor
    arg_descriptor[3]
    min_num_args
    arg_descriptor[1]
     

    The SYMDICT_ARG_REC is composed of the following elements:

    type
    arg_descriptor[2]
    arg_descriptor[4]
    arg_descriptor[1]
    arg_descriptor[3]
     

    The UNWIND_DESCRIPT is composed of the following elements:

    cannot_unwind
    entry_gr
    save_mrp_in_frame
    millicode
    args_stored
    cleanup_defined
    millicode_save_sr0
    call_fr
    hpe_interrupt_marker
    region_description
    call_gr
    hpux_interrupt_marker
    save_srs
    save_sp
    large_frame_r3
    entry_fr
    save_rp
    total_framesize

    The UNWIND_ENTRY is composed of the following elements:

    starting_offset
     
     
    ending_offset
     
     

    Example: FORMAT LST_HEADER LST_HEADER
    The first LST_HEADER is an expression, giving an offset in the file to where the LST HEADER starts, While the second one is a format specifier.

    HELP

    The HELP command invokes AVATAR Help.

    Init

    The INIT command will display all the compiler init entries for the current module of the opened SOM file. This information comes from the INIT_REC portion of the SOM.


    Figure 3.6 INIT Command

    Space
    =
    index into the space dictionary
    Acc
    =
    access control bits, valid value from 0-7
    0: read only data page
    1: normal data page
    2: normal code page
    3: dynamic code page
    4: gateway to PL0
    5: gateway to PL1
    6: gateway to PL2
    7: gateway to PL3
    DRFN
    =
    bit encoded flag
    D: data defined in SOM for this space
    R: this subspace is locked into physical memory once the subspace goes into execution
    F: this subspace is locked into physical memory when the operating system is booted
    N: initialization pointers starts a new locality set
    File-loc
    =
    if ’D’ (data defined in SOM), then this entry points at the data to initialize one or more subspaces. Otherwise this field contains a 32-bit value used to initialize one or more subspaces.
    Length
    =
    if ’D’, then this field contains the byte length of the area to initialize. Otherwise it is undefined.
    Offset
    =
    byte offset where initialization is to start, relative to the start of the space.

    Look

    This command has the following syntax:
    Look <string>
    <symbol>
    The LOOK command will display all the available information about a given entry in the symbol dictionary. See the FIND command. For example, this command can be used to find the argument types and order for any procedure, anywhere. Parameters for this command are case- sensitive.

    <string>
    Any string of ASCII characters.
    <symbol>
    Any string of valid symbol characters.

    Example: LOOK HPFOPEN
    Displays all information for the intrinsic HPFOPEN (See Figure 3.7)




    Figure 3.7 LOOK HPFOPEN



    Figure 3.8 LOOK QUIT

    LSt

    The LST command will display all the available modules in the currently opened SOM file and allow you to select a module. When a SOM with multiple entries is OPENed, the LST command is automatically invoked.
    Example: Only SOMs with multiple entries require the use of the LST command.








    Figure 3.9 LST Command

    MC

    This command has the following syntax:
    MC <expression> <value>
    The MC command will modify data at a given code address. The address can be specified as any valid expression for the current SOM. The new value can be any valid value for the code space, including assembler instructions.

    <expression>
    Is an arithmetic expression that represents an offset to the start of the current module.
    <value>
    Is an expression representing the new data.

    Example 1: MC my_proc+$100 `LDW -4(0,30),2`
    Example 2: MC my_proc + $200 `BL FOPEN,2`
    Example 3: MC $1200 8004000
    Example 4: mc test_while_for "BL FOPEN,2" (See Figure 3.10)


    Figure 3.10 MC Command

    MD

    This command has the following syntax:
    MD <expression> <value>
    The MD command will modify values from an initialized block within the current module of the opened SOM file.

    <expression>
    Is an arithmetic expression that represents an offset into the initialized data area in the current SOM.
    <value>
    Is an expression representing the new data.

    Example 1: MD db_area+#100 $5078
    Example 2: md _db_area+123 (See Figure 3.11)
    Figure 3.11 MD Command

    MV

    This command has the following syntax:
    MV <expression> <value>
    The MV command will modify values (data) within the current SOM file.

    <expression>
    Is an arithmetic expression that represents an offset to the start of the current file.
    <value>
    Is an expression representing the new data.

    Example 1: MV $100 $5078
    Change the data at address hex 100 to hex 5078.
    Example 2: mv 0 100 (See Figure 3.12)
    Example 3: mv 0 $dc (See Figure 3.12)
    Figure 3.12 MV Command

    Next

    The NEXT command repeats the last DV, DC or DD command starting from the point where it left off.

    NOTE MC, MV or MD command will reposition the pointer as well. The NEXT command is optional, a mere <cr> will do.

    Open

    This command has the following syntax:
    OPEN filename [READ]
    The OPEN command opens an NMPRG or an NMXL.
    filename must be a valid MPE/iX file descriptor (no wildcards). If the specified file is a Native Mode executable file (SOM) and it contains more than one LST entry, then the user is asked to select which LST entry to analyze. If the specified file is nor an SOM, then the file is mapped into virtual memory where the user is restricted to basic operations, such as displaying and modifying memory. If READ is specified, then the SOM file is opened for Read-Access only. The MC, MV and MD commands are then disabled. The default is read/write access.
    Example 1: OPEN myprog
    Example 2: OPEN myprog READ

    Quit

    The QUIT command exits the program.

    Radix

    This command has the following syntax:
    Radix <mnemonic>
    The RADIX command will change the default radix, which is the base that all input is assumed to be.

    <mnemonic>=
    [DECIMAL]
    [HEX]
    [OCTAL]

    Example 1: RADIX HEX
    Example 2: RADIX DECIMAL
    Example 3: RADIX OCTAL

    Search

    This command has the following syntax:
    SEARCH <expression>
    <string>
    The SEARCH command will search the entire opened SOM file an look for a given value. If the value is found, a line of data is displayed.

    <expression>
    An expression that result in an integer value to be searched in the file.
    <string>
    A quoted string to be searched in the file.

    Example 1: SEARCH $8861
    Example 2: SEARCH "A string"
    Example 3: SEARCH `LDIL $1000,0`
    Searching an ASCII file:


    Figure 3.13 SEARCH Command
    Searching a Native Mode program file:


    Figure 3.14 SEARCH a Native Mode Program

    SPace

    The SPACE command will display the space and subspace information about the current module of the opened SOM file.


    Figure 3.15 SPACE Command

    STatistics

    The STATISTICS command displays SOM file statistics.


    Figure 3.16 STATISTICS Command

    STRIP

    The STRIP command will remove symbolic information from SOM.


    Figure 3.17 STRIP Command

    SUbspace

    The SUBSPACE command will display the subspace information about the current module of the opened SOM file.


    Figure 3.18 SUBSPACE Command

    SYMformat

    This command has the following syntax:
    SYMformat <HEADER | GNTT | LNTT | SLT | VT>
    The SYMFORMAT command is used to format and display various portions of a SYMOS file. Using this command requires an expert-level knowledge of the MPE/iX operating system.

    HEADER
    is used to format and display header information.
    GNTT
    not implemented
    LNTT
    is used to format and display LNTT information.
    SLT
    is used to format and display SLT information.
    VT
    is used to format and display VT information.

    SYMOpen

    This command has the following syntax:
    SYMOpen <symos filename>
    The SYMOPEN command is used to open a SYMOS file for examination. Using this command requires an expert-level knowledge of the MPE/iX operating system.
    SYM-based Examples
    These Examples illustrate usage for SYMOPEN, SYMFORMAT HEADER, SYMFORMAT VT, and SYMFORMAT LNTT.




    Figure 3.19 SYMOPEN/SYMFORMAT: LNTT, VT

    SYn

    This command has the following syntax:
    SYn SPLASH
    SYSTEM
    NONE
    R
    REG <general register number> <synonym>
    CR <control register number> <synonym>
    The SYN command sets up synonyms for the general registers and the special registers. These synonyms will be shown in the disassembled format of any instruction.

    SPLASH
    Sets synonyms to reflect the normal SPLash! usage for synonyms.
    SYSTEM
    Sets synonyms to reflect the normal system usage for registers.
    NONE
    Resets all synonyms.
    R
    Precedes every register number by the letter 'r' in generated assembly language.
    <general register number>
    Is a number between 0 and 31 inclusive, designating the general register for which a synonym is set up.
    <special register number>
    Is a number between 0 and 31 inclusive, designating the special register for which a synonym is set up.
    <synonym>
    Is any name, to be used as a synonym.

    UNCALLED

    This command has the following syntax:
    UNCALLED [<expression>]
    The UNCALLED command lists all code entry points that are called less than a specified number of times from within the same SOM.

    <expression>
    The maximum number of times that an entry point may be called to be listed. Default is 0.

    Example: UNCALLED 0


    Figure 3.20 UNCALLED Command

    UNWind

    The UNWIND commands produces a formatted listing of the unwind descriptor entries from the current SOM.


    Figure 3.21 UNWIND Command

    AVATAR Examples

    Figure 3.22 uses the DR command.
    Figure 3.23 uses the FIND command to locate external procedure calls. Remember, most symbol parameters are case-sensitive.


    Figure 3.22 DR Command








    Figure 3.23 FIND Command (External)
    Occasionally, you may want to know what external procedures a program calls. The FIND command can easily locate all external procedure calls.
    Figure 3.24 uses the LOOK command to determine parameter types.
    Because the parameter to the LOOK command was entered in lower case type, we know immediately that it is not an intrinsic call but rather an external procedure. There are six parameters for this procedure and we can see that the first 3 parameters are simple variables while the last 3 are array (or record) parameters.




    Figure 3.24 LOOK Command (direcfind)
    Figure 3.25 shows how the EXTRACT command is used.
    Figure 3.25 EXTRACT Command

    AVATAR Error Messages

    Each AVATAR error message is described in the following table.
    Table 3.5 AVATAR Error Messages
    Message
    Cause
    Action
    Expected "D" or "C" as data type
    DISPLAY command expects known data type modified.
    Use only the "D" (hex/ASCII dump) or "C" (disassemble) data type modifiers.
    Invalid primary
    User entered unknown AVATAR command or option.
    Review command syntax.
    Invalid start address
    EXTRACT command start address must be within procedure.
    Use AVATAR to review the address range for the procedure being extracted.
    Invalid type
    User entered invalid symbol type for lookup symbol command.
    Review symbol types. The valid types are: ABSOLUTE, DATA, CODE, PRI_PROG, SEC_PROG, ENTRY, STORAGE, STUB, MODULE, SYM_EXT, ARG_EXT, MILLICODE, PLABEL, OCT_DIS, MILLI_EXT.
    Start must be less then end.
    EXTRACT command expects and offset to be larger than beginning offset.
    Review EXTRACT command syntax.

    Lund Performance Solutions
    www.lund.com
    Voice: (541) 812-7600
    Fax: (541) 81207611
    info@lund.com
    TOCPREVNEXTINDEX