DBG$HELP.HLB  —  DEBUG  DEFINE
    Assigns a symbolic name to an address expression, command, or
    value.

    Format

      DEFINE  symbol-name=parameter [,symbol-name=parameter[, . . . ]]

1  –  Parameters

 symbol-name

    Specifies a symbolic name to be assigned to an address, command,
    or value. The symbolic name can be composed of alphanumeric
    characters and underscores. The debugger converts lowercase
    alphabetic characters to uppercase. The first character must not
    be a number. The symbolic name must be no more than 31 characters
    long.

 parameter

    Depends on the qualifier specified.

2  –  Qualifiers

2.1    /ADDRESS

    (Default) Specifies that the defined symbol is an abbreviation
    for an address expression. In this case, parameter is an address
    expression.

2.2    /COMMAND

    Specifies that the defined symbol is treated as a new debugger
    command. In this case, parameter is a quoted character string.
    This qualifier provides, in simple cases, essentially the same
    capability as the following DCL command:

    $ symbol := string

    To define complex commands, you might need to use command
    procedures with formal parameters. For more information about
    declaring parameters to command procedures, see the DECLARE
    command.

2.3    /LOCAL

    Specifies that the definition is valid only in the command
    procedure in which it is defined. The defined symbol is not
    visible at debugger command level. By default, a symbol defined
    within a command procedure is visible outside that procedure.

2.4    /VALUE

    Specifies that the defined symbol is an abbreviation for a value.
    In this case, parameter is a language expression in the current
    language.

3  –  Description

    The DEFINE/ADDRESS command assigns a symbolic name to an
    address expression in a program. You can define a symbol for a
    nonsymbolic program location or for a symbolic program location
    having a long path-name prefix. You can then refer to that
    program location with the symbolic name. The /ADDRESS qualifier
    is the default.

    The DEFINE/COMMAND command enables you to define abbreviations
    for debugger commands or even define new commands, either from
    the debugger command level or from command procedures.

    The DEFINE/VALUE command enables you to assign a symbolic name to
    a value (or the result of evaluating a language expression).

    The DEFINE/LOCAL command confines symbol definitions to command
    procedures. By default, defined symbols are global (visible
    outside the command procedure).

    To enter several DEFINE commands with the same qualifier, first
    use the SET DEFINE command to establish a new default qualifier
    (for example, SET DEFINE COMMAND makes subsequent DEFINE commands
    behave like DEFINE/COMMAND). You can override the current default
    qualifier for a single DEFINE command by specifying another
    qualifier.

    In symbol translation, the debugger searches symbols you define
    during the debugging session first. So if you define a symbol
    that already exists in your program, the debugger translates the
    symbol according to its defined definition, unless you specify a
    path-name prefix.

    If a symbol is redefined, the previous definition is canceled,
    even if you used different qualifiers with the DEFINE command.

    Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE
    commands are available only when the image in whose context
    they were created is the current image. If you use the SET IMAGE
    command to establish a new current image, these definitions are
    temporarily unavailable. However, definitions created with the
    DEFINE/COMMAND and DEFINE/KEY commands are always available for
    all images.

    Use the SHOW SYMBOL/DEFINED command to determine the equivalence
    value of a symbol.

    Use the DELETE command to cancel a symbol definition.

    Related commands:

       DECLARE
       DELETE
       SET IMAGE
       SHOW DEFINE
       SHOW SYMBOL/DEFINED

4  –  Examples

    1.DBG> DEFINE/VALUE COUNTER=0
      DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1)

      In this example, the DEFINE/VALUE command assigns a value of
      0 to the symbol COUNTER. The SET TRACE command causes the
      debugger to increment the value of the symbol COUNTER by 1
      whenever address R is encountered. In other words, this example
      counts the number of calls to R.

    2.DBG> DEFINE/COMMAND BRE = "SET BREAK"

      This command assigns the symbol BRE to the debugger command SET
      BREAK.

5    /KEY

    Assigns a string to a function key.

                                   NOTE

       This command is not available in the VSI DECwindows Motif for
       OpenVMS user interface to the debugger.

    Format

      DEFINE/KEY  key-name "equivalence-string"

5.1  –  Parameters

 key-name

    Specifies a function key to be assigned a string. Valid key names
    are as follows:

    Key       LK201
    Name      Keyboard      VT100-type    VT52-type

    PF1       PF1           PF1           Blue
    PF2       PF2           PF2           Red
    PF3       PF3           PF3           Black
    PF4       PF4           PF4
    KP0-KP9   Keypad 0-9    Keypad 0-9    Keypad 0-9
    PERIOD    Keypad        Keypad
              period (.)    period (.)
    COMMA     Keypad comma  Keypad comma
              (,)           (,)
    E1        Find
    E2        Insert Here
    E3        Remove
    E4        Select
    E5        Prev Screen
    E6        Next Screen
    HELP      Help
    DO        Do
    F6-F20    F6-F20

    On LK201 keyboards:

    o  You cannot define keys F1 to F5 or the arrow keys (E7 to E10).

    o  You can define keys F6 to F14 only if you have first entered
       the DCL command SET TERMINAL/NOLINE_EDITING. In that case, the
       line-editing functions of the left and right arrow keys (E8
       and E9) are disabled.

 equivalence-string

    Specifies the string to be processed when you press the specified
    key. Typically, this is one or more debugger commands. If the
    string includes any space or nonalphanumeric characters (for
    example, a semicolon separating two commands), enclose the string
    in quotation marks (").

5.2  –  Qualifiers

5.2.1    /ECHO

       /ECHO (default)
       /NOECHO

    Controls whether the command line is displayed after the key has
    been pressed. Do not use /NOECHO with /NOTERMINATE.

5.2.2    /IF_STATE

       /IF_STATE=(state-name[, . . . ])
       /NOIF_STATE (default)

    Specifies one or more states to which a key definition applies.
    The /IF_STATE qualifier assigns the key definition to the
    specified states. You can specify predefined states, such as
    DEFAULT and GOLD, or user-defined states. A state name can be
    any appropriate alphanumeric string. The /NOIF_STATE qualifier
    assigns the key definition to the current state.

5.2.3    /LOCK_STATE

       /LOCK_STATE
       /NOLOCK_STATE (default)

    Controls how long the state set by /SET_STATE remains in effect
    after the specified key is pressed. The /LOCK_STATE qualifier
    causes the state to remain in effect until it is changed
    explicitly (for example, with a SET KEY/STATE command). The
    /NOLOCK_STATE qualifier causes the state to remain in effect
    only until the next terminator character is typed, or until the
    next defined function key is pressed.

5.2.4    /LOG

       /LOG (default)
       /NOLOG

    Controls whether a message is displayed indicating that the key
    definition has been successfully created. The /LOG qualifier
    displays the message. The /NOLOG qualifier suppresses the
    message.

5.2.5    /SET_STATE

       /SET_STATE=state-name
       /NOSET_STATE (default)

    Controls whether pressing the key changes the current key state.
    The /SET_STATE qualifier causes the current state to change to
    the specified state when you press the key. The /NOSET_STATE
    qualifier causes the current state to remain in effect.

5.2.6    /TERMINATE

       /TERMINATE
       /NOTERMINATE (default)

    Controls whether the specified string is terminated (processed)
    when the key is pressed. The /TERMINATE qualifier causes the
    string to be terminated when the key is pressed. The /NOTERMINATE
    qualifier enables you to press other keys before terminating the
    string by pressing the Return key.

5.3  –  Description

    Keypad mode must be enabled (SET MODE KEYPAD) before you can use
    this command. Keypad mode is enabled by default.

    The DEFINE/KEY command enables you to assign a string to a
    function key, overriding any predefined function that was bound
    to that key. When you then press the key, the debugger enters
    the currently associated string into your command line. The
    DEFINE/KEY command is like the DCL command DEFINE/KEY.

    For a list of the predefined key functions, see the Keypad_
    Definitions_CI online help topic.

    On VT52- and VT100-series terminals, the function keys you can
    use include all of the numeric keypad keys. Newer terminals and
    workstations have the LK201 keyboard. On LK201 keyboards, the
    function keys you can use include all of the numeric keypad keys,
    the nonarrow keys of the editing keypad (Find, Insert Here, and
    so on), and keys F6 to F20 at the top of the keyboard.

    A key definition remains in effect until you redefine the key,
    enter the DELETE/KEY command for that key, or exit the debugger.
    You can include key definitions in a command procedure, such as
    your debugger initialization file.

    The /IF_STATE qualifier enables you to increase the number of
    key definitions available on your terminal. The same key can be
    assigned any number of definitions as long as each definition is
    associated with a different state.

    By default, the current key state is the DEFAULT state. The
    current state can be changed with the SET KEY/STATE command,
    or by pressing a key that causes a state change (a key that was
    defined with DEFINE/KEY/LOCK_STATE/SET_STATE).

    Related commands:

       DELETE/KEY
       (SET,SHOW) KEY

5.4  –  Examples

    1.DBG> SET KEY/STATE=GOLD
      %DEBUG-I-SETKEY, keypad state has been set to GOLD
      DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX"
      %DEBUG-I-DEFKEY, GOLD key KP9 has been defined

      In this example, the SET KEY command establishes GOLD as
      the current key state. The DEFINE/KEY command assigns the
      SET RADIX/OVERRIDE HEX command to keypad key 9 (KP9) for the
      current state (GOLD). The command is processed when you press
      the key.

    2.DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK %LINE "
      %DEBUG-I-DEFKEY, BLUE key KP9 has been defined

      This command assigns the unterminated command string "SET BREAK
      %LINE" to keypad key 9 for the BLUE state. After pressing BLUE-
      KP9, you can enter a line number and then press the Return key
      to terminate and process the SET BREAK command.

    3.DBG> SET KEY/STATE=DEFAULT
      %DEBUG-I-SETKEY, keypad state has been set to DEFAULT
      DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 ""
      %DEBUG-I-DEFKEY, DEFAULT key F12 has been defined

      In this example, the SET KEY command establishes DEFAULT as
      the current state. The DEFINE/KEY command makes the F12 key
      (on an LK201 keyboard) a state key. Pressing F12 while in
      the DEFAULT state causes the current state to become RED. The
      key definition is not terminated and has no other effect (a
      null string is assigned to F12). After pressing F12, you can
      enter "RED" commands by pressing keys that have definitions
      associated with the RED state.

6    /PROCESS_SET

    Assigns a symbolic name to a list of process specifications.

    Format

      DEFINE/PROCESS_SET  process-set-name =process-spec[, . . . ]

6.1  –  Parameters

 process-set-name

    Specifies a symbolic name to be assigned to a list of process
    specifications. The symbolic name can be composed of alphanumeric
    characters and underscores. The debugger converts lowercase
    alphabetic characters to uppercase. The first character must not
    be a number. The symbolic name must be no more than 31 characters
    long.

 process-spec

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

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

    If you do not specify a process, the symbolic name is created but
    contains no process entries.

6.2  –  Description

    The DEFINE/PROCESS_SET command assigns a symbol to a list of
    process specifications. You can then use the symbol in any
    command where a list of process specifications is allowed.

    The DEFINE/PROCESS_SET command does not verify the existence of a
    specified process. This enables you to specify processes that do
    not yet exist.

    To identify a symbol that was defined with the DEFINE/PROCESS_SET
    command, use the SHOW SYMBOL/DEFINED command. To delete a symbol
    that was defined with the DEFINE/PROCESS_SET command, use the
    DELETE command.

    Related commands:

       DELETE
       (SET,SHOW) DEFINE
       SHOW SYMBOL/DEFINED

6.3  –  Examples

    1.all> DEFINE/PROCESS_SET SERVERS=FILE_SERVER,NETWORK_SERVER
      all> SHOW PROCESS SERVERS
       Number  Name               State   Current PC
      *    1 FILE_SERVER          step    FS_PROG\%LINE 37
           2 NETWORK_SERVER       break   NET_PROG\%LINE 24
      all>

      This DEFINE/PROCESS_SET command assigns the symbolic name
      SERVERS to the process set consisting of FILE_SERVER and
      NETWORK_SERVER. The SHOW PROCESS SERVERS command displays
      information about the processes that make up the set SERVERS.

    2.all> DEFINE/PROCESS_SET G1=%PROCESS_NUMBER 1,%VISIBLE_PROCESS
      all> SHOW SYMBOL/DEFINED G1
      defined G1
          bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS"
          was defined /process_set
      all> DELETE G1

      This DEFINE/PROCESS_SET command assigns the symbolic name G1 to
      the process set consisting of process 1 and the visible process
      (process 3). The SHOW SYMBOL/DEFINED G1 command identifies the
      defined symbol G1. The DELETE G1 command deletes the symbol
      from the DEFINE symbol table.

    3.all> DEFINE/PROCESS_SET A = B,C,D
      all> DEFINE/PROCESS_SET B = E,F,G
      all> DEFINE/PROCESS_SET E = I,J,A
      %DEBUG-E-NORECSYM, recursive PROCESS_SET symbol definition
           encountered at or near "A"

      This series of DEFINE/PROCESS_SET commands illustrate valid and
      invalid uses of the command.
Close Help