Library /sys$common/syshlp/DBG$HELP.HLB  —  DEBUG  EXAMINE  Description, Continued...
    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:

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

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

    o  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:

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

    o  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:

    o  NAME = name-string

    o  DISCRIMINANT = expression

    o  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 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
Close Help