DBG$HELP.HLB  —  DEBUG  SET

1  –  ABORT_KEY

    Assigns the debugger's abort function to another Ctrl-key
    sequence. By default, Ctrl/C does the abort function.

                                   NOTE

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

    Format

      SET ABORT_KEY  = CTRL_character

1.1  –  Parameters

 character

    Specifies the key you press while holding down the Ctrl key. You
    can specify any alphabetic character.

1.2  –  Description

    By default, the Ctrl/C sequence, when entered within a debugging
    session, aborts the execution of a debugger command and
    interrupts program execution. The SET ABORT_KEY command enables
    you to assign the abort function to another Ctrl-key sequence.
    This might be necessary if your program has a Ctrl/C AST service
    routine enabled.

    Many Ctrl-key sequences have predefined functions, and the SET
    ABORT_KEY command enables you to override such definitions (see
    the OpenVMS User's Manual). Some of the Ctrl-key characters not
    used by the operating system are G, K, N, and P.

    The SHOW ABORT_KEY command identifies the Ctrl-key sequence
    currently in effect for the abort function.

    Do not use Ctrl/Y from within a debugging session. Instead, use
    either Ctrl/C or an equivalent Ctrl-key sequence established with
    the SET ABORT_KEY command.

    Related commands:

       Ctrl/C
       Ctrl/Y
       SHOW ABORT_KEY

1.3  –  Example

  DBG> SHOW ABORT_KEY
  Abort Command Key is CTRL_C
  DBG> GO
       . . .
      <Ctrl/C>
  DBG> EXAMINE/BYTE 1000:101000  !should have typed 1000:1010
  1000: 0
  1004: 0
  1008: 0
  1012: 0
  1016: 0
      <Ctrl/C>
  %DEBUG-W-ABORTED, command aborted by user request
  DBG> SET ABORT_KEY = CTRL_P
  DBG> GO
       . . .
      <Ctrl/P>
  DBG> EXAMINE/BYTE 1000:101000  !should have typed 1000:1010
  1000: 0
  1004: 0
  1008: 0
  1012: 0
  1016: 0
      <Ctrl/P>
  %DEBUG-W-ABORTED, command aborted by user request
  DBG>

      This example shows the following:

      o  Use of Ctrl/C for the abort function (default).

      o  Use of the SET ABORT_KEY command to reassign the abort
         function to Ctrl/P.

2  –  ATSIGN

    Establishes the default file specification that the debugger uses
    when searching for command procedures.

    Format

      SET ATSIGN  file-spec

2.1  –  Parameters

 file-spec

    Specifies any part of a file specification (for example, a
    directory name or a file type) that the debugger is to use
    by default when searching for a command procedure. If you do
    not supply a full file specification, the debugger assumes
    SYS$DISK:[]DEBUG.COM as the default file specification for any
    missing field.

    You can specify a logical name that translates to a search list.
    In this case, the debugger processes the file specifications
    in the order they appear in the search list until the command
    procedure is found.

2.2  –  Description

    When you invoke a debugger command procedure with the execute
    procedure (@) command, the debugger assumes, by default, that the
    command procedure file specification is SYS$DISK:[]DEBUG.COM. The
    SET ATSIGN command enables you to override this default.

    Related commands:

       @ (Execute Procedure)
       SHOW ATSIGN

2.3  –  Example

  DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
  DBG> @TEST

      In this example, when you use the @TEST command, the debugger
      looks for the file TEST.DBG in USER:[JONES.DEBUG].

3  –  BREAK

    Establishes a breakpoint at the location denoted by an address
    expression, at instructions of a particular class, or at the
    occurrence of specified events.

    Format

      SET BREAK  [address-expression[, . . . ]]

                 [WHEN(conditional-expression)]

                 [DO(command[; . . . ])]

3.1  –  Parameters

 address-expression

    Specifies an address expression (a program location) at which
    a breakpoint is to be set. With high-level languages, this
    is typically a line number, a routine name, or a label, and
    can include a path name to specify the entity uniquely. More
    generally, an address expression can also be a memory address or
    a register and can be composed of numbers (offsets) and symbols,
    as well as one or more operators, operands, or delimiters. For
    information about the operators that you can use in address
    expressions, see the Address_Expressions help topic.

    Do not specify the asterisk (*)  wildcard character. Do not
    specify an address expression with any of the following
    qualifiers:

       /ACTIVATING
       /BRANCH
       /CALL
       /EXCEPTION
       /HANDLER
       /INSTRUCTION
       /INTO
       /LINE
       /OVER
       /[NO]SHARE
       /[NO]SYSTEM
       /SYSEMULATE (Alpha only)
       /TERMINATING
       /UNALIGNED_DATA (Alpha and Integrity servers only)

    The /MODIFY and /RETURN qualifiers are used with specific kinds
    of address expressions.

    If you specify a memory address or an address expression whose
    value is not a symbolic location, check (with the EXAMINE
    command) that an instruction actually begins at the byte of
    memory so indicated. If an instruction does not begin at this
    byte, a run-time error can occur when an instruction including
    that byte is executed. When you set a breakpoint by specifying
    an address expression whose value is not a symbolic location, the
    debugger does not verify that the location specified marks the
    beginning of an instruction.

 conditional-expression

    Specifies a conditional expression in the currently set
    language that is to be evaluated whenever execution reaches the
    breakpoint. (The debugger checks the syntax of the expressions in
    the WHEN clause when execution reaches the breakpoint, not when
    the breakpoint is set.) If the expression is true, the debugger
    reports that a breakpoint has been triggered. If an action (DO
    clause) is associated with the breakpoint, it will occur at this
    time. If the expression is false, a report is not issued, the
    commands specified by the DO clause (if one was specified) are
    not executed, and program execution is continued.

 command

    Specifies a debugger command to be executed as part of the DO
    clause when break action is taken. The debugger checks the syntax
    of the commands in a DO clause when it executes the DO clause,
    not when the breakpoint is set.

3.2  –  Qualifiers

3.2.1    /ACTIVATING

    Causes the debugger to break when a new process comes under
    debugger control. The debugger prompt is displayed when the first
    process comes under debugger control. This enables you to enter
    debugger commands before the program has started execution. See
    also the /TERMINATING qualifier.

3.2.2    /AFTER

       /AFTER:n

    Specifies that break action not be taken until the nth time the
    designated breakpoint is encountered (n is a decimal integer).
    Thereafter, the breakpoint occurs every time it is encountered
    provided that conditions in the WHEN clause (if specified) are
    true. The SET BREAK/AFTER:1 command has the same effect as SET
    BREAK.

3.2.3    /BRANCH

    Causes the debugger to break on every branch instruction
    encountered during program execution. See also the /INTO and
    /OVER qualifiers.

3.2.4    /CALL

    Causes the debugger to break on every call instruction
    encountered during program execution, including the RET
    instruction. See also the /INTO and /OVER qualifiers.

3.2.5    /EVENT

       /EVENT=event-name

    Causes the debugger to break on the specified event (if that
    event is defined and detected by the current event facility).
    If you specify an address expression with /EVENT, causes the
    debugger to break whenever the specified event occurs for that
    address expression. You cannot specify an address expression with
    certain event names.

    Event facilities are available for programs that call Ada or SCAN
    routines or that use POSIX threads services. Use the SHOW EVENT_
    FACILITY command to identify the current event facility and the
    associated event names.

3.2.6    /EXCEPTION

    Causes the debugger to break whenever an exception is signaled.
    The break action occurs before any application-declared exception
    handlers are invoked.

    As a result of a SET BREAK/EXCEPTION command, whenever your
    program generates an exception, the debugger suspends program
    execution, reports the exception, and displays its prompt. When
    you resume execution from an exception breakpoint, the behavior
    is as follows:

    o  If you enter a GO command without an address-expression
       parameter, the exception is resignaled, thus allowing any
       application-declared exception handler to execute.

    o  If you enter a GO command with an address-expression
       parameter, program execution continues at the specified
       location, thus inhibiting the execution of any application-
       declared exception handler.

       On Alpha, you must explicitly set a breakpoint in the
       exception handler before entering a STEP or a GO command to
       get the debugger to suspend execution within the handler.

    o  If you enter a CALL command, the routine specified is
       executed.

    On Alpha processors, an exception might not be delivered (to
    the program or debugger) immediately after the execution of the
    instruction that caused the exception. Therefore, the debugger
    might suspend execution on an instruction beyond the one that
    actually caused the exception.

3.2.7    /HANDLER

    Causes the debugger to scan the call stack and attempt to set a
    breakpoint on every established frame-based handler whenever the
    program being debugged has an exception. The debugger does not
    discriminate between standard RTL handlers and user-established
    handlers.

    On Alpha and Integrity servers, most RTLs establish a jacket
    RTL handler on a frame where the user program has defined a
    handler. The RTL jacket performs setup, argument manipulation,
    and dispatch to the user written handlers. When processing the
    exception, the debugger can only set the breakpoint on the RTL
    jacket handler, because that is the address on the call stack. If
    the debugger suspends program execution in a jacket RTL handler,
    you can usually reach the user-defined handler by finding the
    dispatch point(s) via some number of STEP/CALLs followed by a
    STEP/INTO.

    See the OpenVMS Calling Standard for more information on frame-
    based handlers.

    If the jacket RTL handler is part of an installed shared image
    such as ALPHA LIBOTS, the debugger cannot set a breakpoint on it
    (no private user mode write access). In this case, activate ALL
    RTLs as private images via logical names. For example:

      $DEFINE LIBOTS SYS$SHARE:LIBOTS.EXE;

    Note that the trailing semicolon (;) is required. Note also that
    all (or none) of your shared installed RTLs should be activated
    privately. Use SHOW IMAGE/FULL data to realize the list of images
    with system space code sections and then define logicals for all
    of them and rerun your debug session.

3.2.8    /INSTRUCTION

       /INSTRUCTION
       /INSTRUCTION[=(opcode[, . . . ])]

    When you do not specify an opcode, causes the debugger to break
    on every instruction encountered during program execution.

    See also the /INTO and /OVER qualifiers.

3.2.9    /INTO

    (Default) Applies only to breakpoints set with the following
    qualifiers (that is, when an address expression is not explicitly
    specified):

       /BRANCH
       /CALL
       /INSTRUCTION
       /LINE

    When used with those qualifiers, /INTO causes the debugger to
    break at the specified points within called routines (as well as
    within the routine in which execution is currently suspended).
    The /INTO qualifier is the default and is the opposite of /OVER.

    When using /INTO, you can further qualify the break action with
    /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM.

3.2.10    /LINE

    Causes the debugger to break on the beginning of each source
    line encountered during program execution. See also the /INTO and
    /OVER qualifiers.

3.2.11    /MODIFY

    Causes the debugger to break on every instruction that writes to
    and modifies the value of the location indicated by the address
    expression. The address expression is typically a variable name.

    The SET BREAK/MODIFY command acts exactly like a SET WATCH
    command and operates under the same restrictions.

    If you specify an absolute address for the address expression,
    the debugger might not be able to associate the address with
    a particular data object. In this case, the debugger uses a
    default length of 4 bytes. You can change this length, however,
    by setting the type to either WORD (SET TYPE WORD, which changes
    the default length to 2 bytes) or BYTE (SET TYPE BYTE, which
    changes the default length to 1 byte). SET TYPE LONGWORD restores
    the default length of 4 bytes.

3.2.12    /OVER

    Applies only to breakpoints set with the following qualifiers
    (that is, when an address expression is not explicitly
    specified):

       /BRANCH
       /CALL
       /INSTRUCTION
       /LINE

    When used with those qualifiers, /OVER causes the debugger to
    break at the specified points only within the routine in which
    execution is currently suspended (not within called routines).
    The /OVER qualifier is the opposite of /INTO (which is the
    default).

3.2.13    /RETURN

    Causes the debugger to break on the return instruction of the
    routine associated with the specified address expression (which
    can be a routine name, line number, and so on). Breaking on the
    return instruction enables you to inspect the local environment
    (for example, obtain the values of local variables) while
    the routine is still active. Note that the view of a local
    environment may differ depending on your architecture. On Alpha
    processors, this qualifier can be applied to any routine.

    The address-expression parameter is an instruction address within
    a routine. It can simply be a routine name, in which case it
    specifies the routine start address. However, you can also
    specify another location in a routine, so you can see only those
    returns that are taken after a certain code path is followed.

    A SET BREAK/RETURN command cancels a previous SET BREAK if you
    specify the same address expression.

3.2.14    /SHARE

       /SHARE (default)
       /NOSHARE

    Qualifies /INTO. Use with /INTO and one of the following
    qualifiers:

       /BRANCH
       /CALL
       /INSTRUCTION
       /LINE

    The /SHARE qualifier permits the debugger to break within
    shareable image routines as well as other routines. The /NOSHARE
    qualifier specifies that breakpoints not be set within shareable
    images.

3.2.15    /SILENT

       /SILENT
       /NOSILENT (default)

    Controls whether the "break . . . " message and the source line
    for the current location are displayed at the breakpoint. The
    /NOSILENT qualifier specifies that the message is displayed. The
    /SILENT qualifier specifies that the message and the source line
    are not displayed. The /SILENT qualifier overrides /SOURCE. See
    also the SET STEP [NO]SOURCE command.

3.2.16    /SOURCE

       /SOURCE (default)
       /NOSOURCE

    Controls whether the source line for the current location is
    displayed at the breakpoint. The /SOURCE qualifier specifies that
    the source line is displayed. The /NOSOURCE qualifier specifies
    that no source line is displayed. The /SILENT qualifier overrides
    /SOURCE. See also the SET STEP [NO]SOURCE command.

3.2.17    /SYSEMULATE

       /SYSEMULATE[=mask]

    (Alpha only) Stops program execution and returns control to the
    debugger after the operating system emulates an instruction.
    The optional argument mask is an unsigned quadword with bits
    set to specify which emulated instruction groups shall cause
    breakpoints. The only emulated instruction group currently
    defined consists of the BYTE and WORD instructions. Select this
    instruction group by setting bit 0 of mask to 1.

    If mask is not specified or if mask = FFFFFFFFFFFFFFFF, the
    debugger stops program execution when the operating system
    emulates any instruction.

3.2.18    /SYSTEM

       /SYSTEM (default)
       /NOSYSTEM

    Qualifies /INTO. Use with /INTO and one of the following
    qualifiers:

       /BRANCH
       /CALL
       /INSTRUCTION
       /LINE

    The /SYSTEM qualifier permits the debugger to break within system
    routines (P1 space) as well as other routines. The /NOSYSTEM
    qualifier specifies that breakpoints not be set within system
    routines.

3.2.19    /TEMPORARY

    Causes the breakpoint to disappear after it is triggered (the
    breakpoint does not remain permanently set).

3.2.20    /TERMINATING

    Causes the debugger to break when a process does an image exit.
    The debugger gains control and displays its prompt when the
    last image of a one-process or multiprocess program exits. A
    process is terminated when the image has executed the $EXIT
    system service and all of its exit handlers have executed. See
    also the /ACTIVATING qualifier.

3.2.21    /UNALIGNED_DATA

    (Alpha and Integrity servers only) Causesthe debugger to break
    directly after any instruction that accesses unaligned data (for
    example, after a load word instruction that accesses data that is
    not on a word boundary).

3.3  –  Description

    When a breakpoint is triggered, the debugger takes the following
    actions:

    1. Suspends program execution at the breakpoint location.

    2. If you specified /AFTER when you set the breakpoint, checks
       the AFTER count. If the specified number of counts has not
       been reached, execution resumes and the debugger does not do
       the remaining steps.

    3. Evaluates the expression in a WHEN clause, if you specified
       one when you set the breakpoint. If the value of the
       expression is false, execution resumes and the debugger does
       not do the remaining steps.

    4. Reports that execution has reached the breakpoint location by
       issuing a "break . . . " message, unless you specified /SILENT.

    5. Displays the line of source code at which execution is
       suspended, unless you specified /NOSOURCE or /SILENT when
       you set the breakpoint or unless you previously entered SET
       STEP NOSOURCE.

    6. Executes the commands in a DO clause, if you specified one
       when you set the breakpoint. If the DO clause contains a GO
       command, execution continues and the debugger does not perform
       the next step.

    7. Issues the prompt.

    You set a breakpoint at a particular location in your program
    by specifying an address expression with the SET BREAK command.
    You set a breakpoint on consecutive source lines, classes of
    instructions, or events by specifying a qualifier with the SET
    BREAK command. Generally, you must specify either an address
    expression or a qualifier, but not both. Exceptions are /EVENT
    and /RETURN.

    The /LINE qualifier sets a breakpoint on each line of source
    code.

    The following qualifiers set breakpoints on classes of
    instructions. Using these qualifiers with /LINE causes the
    debugger to trace every instruction of your program as it
    executes and thus significantly slows down execution:

       /BRANCH
       /CALL
       /INSTRUCTION
       /RETURN

    The following qualifiers affect what happens at a routine call:

       /INTO
       /OVER
       /[NO]SHARE
       /[NO]SYSTEM

3.4  –  Description, Continued...

    The following qualifiers affect what output is displayed when a
    breakpoint is reached:

       /[NO]SILENT
       /[NO]SOURCE

    The following qualifiers affect the timing and duration of
    breakpoints:

       /AFTER:n
       /TEMPORARY

    Use the /MODIFY qualifier to monitor changes at program locations
    (typically changes in the values of variables).

    If you set a breakpoint at a location currently used as
    a tracepoint, the tracepoint is canceled in favor of the
    breakpoint, and vice versa.

    On OpenVMS Alpha and Integrity servers, the SET BREAK/UNALIGNED_
    DATA command calls the $START_ALIGN_FAULT_REPORT system service
    routine. Do not issue this command if the program you are
    debugging includes a call to the same $START_ALIGN_FAULT_REPORT
    routine. If you issue the command before the program call, the
    program call fails. If the program call occurs before you issue
    the command, unaligned breaks are not set.

    Breakpoints can be user defined or predefined. User-defined
    breakpoints are set explicitly with the SET BREAK command.
    Predefined breakpoints, which depend on the type of program you
    are debugging (for example, Ada or multiprocess), are established
    automatically when you start the debugger. Use the SHOW BREAK
    command to identify all breakpoints that are currently set. Any
    predefined breakpoints are identified as such.

    User-defined and predefined breakpoints are set and canceled
    independently. For example, a location or event can have both
    a user-defined and a predefined breakpoint. Canceling the user-
    defined breakpoint does not affect the predefined breakpoint, and
    conversely.

    Related commands:

       (ACTIVATE,DEACTIVATE,SHOW,CANCEL) BREAK
       CANCEL ALL
       GO
       (SET,SHOW) EVENT_FACILITY
       SET STEP [NO]SOURCE
       SET TRACE
       SET WATCH
       STEP

3.5  –  Examples

    1.DBG> SET BREAK SWAP\%LINE 12

      This command causes the debugger to break on line 12 of module
      SWAP.

    2.DBG> SET BREAK/AFTER:3 SUB2

      This command causes the debugger to break on the third and
      subsequent times that SUB2 (a routine) is executed.

    3.DBG> SET BREAK/NOSOURCE LOOP1 DO (EXAM D; STEP; EXAM Y; GO)

      This command causes the debugger to break at location LOOP1. At
      the breakpoint, the following commands are issued, in the order
      given: (1)  EXAMINE D, (2) STEP, (3)  EXAMINE Y, and (4)  GO.
      The /NOSOURCE qualifier suppresses the display of source code
      at the breakpoint.

    4.DBG> SET BREAK ROUT3 WHEN (X > 4) DO (EXAMINE Y)

      This command causes the debugger to break on routine ROUT3 when
      X is greater than 4. At the breakpoint, the EXAMINE Y command
      is issued. The syntax of the conditional expression in the WHEN
      clause is language-dependent.

    5.DBG> SET BREAK/TEMPORARY 1440
      DBG> SHOW BREAK
      breakpoint at 1440 [temporary]
      DBG>

      This command sets a temporary breakpoint at memory address
      1440. After that breakpoint is triggered, it disappears.

    6.DBG> SET BREAK/LINE

      This command causes the debugger to break on the beginning of
      every source line encountered during program execution.

    7.DBG> SET BREAK/LINE WHEN (X .NE. 0)
      DBG> SET BREAK/INSTRUCTION WHEN (X .NE. 0)

      These two commands cause the debugger to break when X is not
      equal to 0. The first command tests for the condition at the
      beginning of every source line encountered during execution.
      The second command tests for the condition at each instruction.
      The syntax of the conditional expression in the WHEN clause is
      language-dependent.

    8.DBG> SET BREAK/RETURN ROUT4

      This command causes the debugger to break whenever the return
      instruction of routine ROUT4 is about to be executed.

    9.DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS)

      This command causes the debugger to break whenever an exception
      is signaled. At the breakpoint, the SET MODULE/CALLS and SHOW
      CALLS commands are issued.

    10all> SET BREAK/ACTIVATING

      This command causes the debugger to break whenever a process of
      a multiprocess program is brought under debugger control.

4  –  DEFINE

    Establishes a default qualifier (/ADDRESS, /COMMAND, /PROCESS_
    GROUP, or /VALUE) for the DEFINE command.

    Format

      SET DEFINE  define-default

4.1  –  Parameters

 define-default

    Specifies the default to be established for the DEFINE command.
    Valid keywords (which correspond to DEFINE command qualifiers)
    are as follows:

    ADDRESS          Subsequent DEFINE commands are treated as
                     DEFINE/ADDRESS. This is the default.
    COMMAND          Subsequent DEFINE commands are treated as
                     DEFINE/COMMAND.
    PROCESS_SET      Subsequent DEFINE commands are treated as
                     DEFINE/PROCESS_SET.
    VALUE            Subsequent DEFINE commands are treated as
                     DEFINE/VALUE.

4.2  –  Description

    The SET DEFINE command establishes a default qualifier for
    subsequent DEFINE commands. The parameters that you specify in
    the SET DEFINE command have the same names as the qualifiers for
    the DEFINE command. The qualifiers determine whether the DEFINE
    command binds a symbol to an address, a command string, a list of
    processes, or a value.

    You can override the current DEFINE default for the duration of
    a single DEFINE command by specifying another qualifier. Use the
    SHOW DEFINE command to identify the current DEFINE defaults.

    Related commands:

       DEFINE
       DEFINE/PROCESS_SET
       DELETE
       SHOW DEFINE
       SHOW SYMBOL/DEFINED

4.3  –  Example

  DBG> SET DEFINE VALUE

      The SET DEFINE VALUE command specifies that subsequent DEFINE
      commands are treated as DEFINE/VALUE.

5  –  EDITOR

    Establishes the editor that is started by the EDIT command.

    Format

      SET EDITOR  [command-line]

5.1  –  Parameters

 command-line

    Specifies a command line to start a particular editor on your
    system when you use the EDIT command.

    You need not specify a command line if you use /CALLABLE_EDT,
    /CALLABLE_LSEDIT, or /CALLABLE_TPU. If you do not use one of
    these qualifiers, the editor specified in the SET EDITOR command
    line is spawned to a subprocess when you enter the EDIT command.

    You can specify a command line with /CALLABLE_LSEDIT or
    /CALLABLE_TPU but not with /CALLABLE_EDT.

5.2  –  Qualifiers

5.2.1    /CALLABLE_EDT

    Specifies that the callable version of the EDT editor is started
    when you use the EDIT command. Do not specify a command line with
    this qualifier (a command line of "EDT" is used).

5.2.2    /CALLABLE_TPU

    Specifies that the callable version of the VSI Text Processing
    Utility (TPU) is started when you use the EDIT command. If you
    also specify a command line, it is passed to callable TPU. If
    you do not specify a command line, the default command line is
    TPU.

5.2.3    /START_POSITION

       /START_POSITION
       /NOSTART_POSITION (default)

    Controls whether the /START_POSITION qualifier is appended
    to the specified or default command line when you enter the
    EDIT command. Currently, only TPU and the VSI Language-
    Sensitive Editor (specified as TPU or /CALLABLE_TPU, and LSEDIT
    or /CALLABLE_LSEDIT, respectively) support this qualifier.

    The /START_POSITION qualifier affects the initial position of
    the editor's cursor. By default (/NOSTART_POSITION), the editor's
    cursor is placed at the beginning of source line 1, regardless
    of which line is centered in the debugger's source display or
    whether you specify a line number in the EDIT command. If you
    specify /START_POSITION, the cursor is placed either on the
    line whose number you specify in the EDIT command, or (if you
    do not specify a line number) on the line that is centered in the
    current source display.

5.3  –  Description

    The SET EDITOR command enables you to specify any editor that is
    installed on your system. In general, the command line specified
    as parameter to the SET EDITOR command is spawned and executed in
    a subprocess.

    On Alpha and Integrity servers, if you use EDT, LSEDIT, or
    TPU, you can start these editors in a more efficient way.
    You can specify /CALLABLE_EDT or /CALLABLE_TPU which causes the
    callable versions of EDT and TPU respectively, to be invoked
    by the EDIT command. In the case of TPU, you can also specify
    a command line that is executed by the callable editor.

    On Alpha processors, you can use /CALLABLE_EDT or /CALLABLE_TPU,
    but not /CALLABLE_LSEDIT.

    Related commands:

       EDIT
       (SET,SHOW,CANCEL) SOURCE
       SHOW DEFINE

5.4  –  Examples

    1.DBG> SET EDITOR '@MAIL$EDIT ""'

      This command causes the EDIT command to spawn the command line
      '@MAIL$EDIT ""', which starts the same editor as you use in
      MAIL.

    2.DBG> SET EDITOR/CALLABLE_TPU

      This command causes the EDIT command to start callable TPU
      with the default command line of TPU.

    3.DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI.TPU$SECTION

      This command causes the EDIT command to start callable TPU
      with the command line TPU/SECTION=MYSECINI.TPU$SECTION.

    4.DBG> SET EDITOR/CALLABLE_EDT/START_POSITION

      This command causes the EDIT command to start callable EDT
      with the default command line of EDT. Also the /START_POSITION
      qualifier is appended to the command line, so that the editing
      session starts on the source line that is centered in the
      debugger's current source display.

6  –  EVENT_FACILITY

    Establishes the current event facility.

    Event facilities are available for programs that call Ada or SCAN
    routines or that use POSIX threads services.

    Format

      SET EVENT_FACILITY  facility-name

6.1  –  Parameters

 facility-name

    Specifies an event facility. Valid facility-name keywords are as
    follows:

    ADA        If the event facility is set to ADA, the (SET,CANCEL)
               BREAK and (SET,CANCEL) TRACE commands recognize Ada-
               specific events as well as generic, low-level task
               events. (Ada events consist of task and exception
               events.)

               You can set the event facility to ADA only if the main
               program is written in Ada or if the program calls an
               Ada routine.
    THREADS    If the event facility is set to THREADS, the
               (SET,CANCEL) BREAK and (SET,CANCEL) TRACE commands
               recognize POSIX threads-specific as well as generic,
               low-level task events. All POSIX threads events are
               task (thread) events.

               You can set the event facility to THREADS only if
               the shareable image CMA$RTL is currently part of the
               program's process (if that image is listed in a SHOW
               IMAGE display).

6.2  –  Description

    The current event facility (ADA, THREADS, or SCAN) defines the
    eventpoints that you can set with the SET BREAK/EVENT and SET
    TRACE/EVENT commands.

    When started with a program that is linked with an event
    facility, the debugger automatically sets the facility in a
    manner appropriate for the type of program. For example, if the
    main program is written in Ada or SCAN, the event facility is set
    to ADA or SCAN, respectively.

    The SET EVENT_FACILITY command enables you to change the event
    facility and thereby change your debugging context. This is
    useful if you have a multilanguage program and want to debug
    a routine that is associated with an event facility but that
    facility is not currently set.

    Use the SHOW EVENT_FACILITY command to identify the event
    names associated with the current event facility. These are the
    keywords that you can specify with the (SET,CANCEL) BREAK/EVENT
    and (SET,CANCEL) TRACE/EVENT commands.

    Related commands:

       (SET,CANCEL) BREAK/EVENT
       (SET,CANCEL) TRACE/EVENT
       SHOW BREAK
       SHOW EVENT_FACILITY
       SHOW IMAGE
       SHOW TASK
       SHOW TRACE

6.3  –  Example

  DBG> SET EVENT_FACILITY THREADS

      This command establishes THREADS (POSIX threads) as the current
      event facility.

7  –  IMAGE

    Loads symbol information for one or more shareable images and
    establishes the current image.

    Format

      SET IMAGE  [image-name[, . . . ]]

7.1  –  Parameters

 image-name

    Specifies a shareable image to be set. Do not use the asterisk
    (*)  wildcard character. Instead, use the /ALL qualifier. Do not
    specify an image name with /ALL.

7.2  –  Qualifiers

7.2.1    /ALL

    Specifies that all shareable images are set.

7.3  –  Description

    The SET IMAGE command builds data structures for one or more
    specified images but does not set any modules within the images
    specified.

    The current image is the current debugging context: you have
    access to symbols in the current image. If you specify only one
    image with the SET IMAGE command, that image becomes the current
    image. If you specify a list of images, the last one in the list
    becomes the current image. If you specify /ALL, the current image
    is unchanged.

    Before an image can be set with the SET IMAGE command, it must
    have been linked with the /DEBUG or /TRACEBACK qualifier on the
    DCL command LINK. If an image was linked /NOTRACEBACK, no symbol
    information is available for that image and you cannot specify it
    with the SET IMAGE 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. When 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 available for all
    images.

    Related commands:

       SET MODE [NO]DYNAMIC
       (SET,SHOW,CANCEL) MODULE
       (SHOW,CANCEL) IMAGE

7.4  –  Example

  DBG> SET IMAGE SHARE1
  DBG> SET MODULE SUBR
  DBG> SET BREAK SUBR

      This sequence of commands shows how to set a breakpoint on
      routine SUBR in module SUBR of shareable image SHARE1. The SET
      IMAGE command sets the debugging context to SHARE1. The SET
      MODULE command loads the symbol records of module SUBR into
      the run-time symbol table (RST). The SET BREAK command sets a
      breakpoint on routine SUBR.

8  –  KEY

    Establishes the current key state.

                                   NOTE

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

    Format

      SET KEY

8.1  –  Qualifiers

8.1.1    /LOG

       /LOG (default)
       /NOLOG

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

8.1.2    /STATE

       /STATE[=state-name]
       /NOSTATE (default)

    Specifies a key state to be established as the current state.
    You can specify a predefined key state, such as GOLD, or
    a user-defined state. A state name can be any appropriate
    alphanumeric string. The /NOSTATE qualifier leaves the current
    state unchanged.

8.2  –  Description

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

    By default, the current key state is the DEFAULT state. When
    you define function keys, you can use the DEFINE/KEY /IF_STATE
    command to assign a specific state name to the key definition.
    If that state is not set when you press the key, the definition
    is not processed. The SET KEY/STATE command enables you to change
    the current state to the appropriate state.

    You can also change the current state 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
       DEFINE/KEY
       SHOW KEY

8.3  –  Example

  DBG> SET KEY/STATE=PROG3

      This command changes the key state to the PROG3 state. You
      can now use the key definitions that are associated with this
      state.

9  –  LANGUAGE

    Establishes the current language.

    Format

      SET LANGUAGE  language-name

9.1  –  Parameters

 language-name

    Specifies a language.

    On Integrity servers, you can specify one of the following
    keywords:

    AMACRO     BASIC     BLISS      C
    C++        COBOL     Fortran    PASCAL
    UNKNOWN

    On Alpha systems, you can specify one of the following keywords:

    ADA        AMACRO    BASIC      BLISS
    C          C++       COBOL      FORTRAN
    MACRO      MACRO64   PASCAL     UNKNOWN

    MACRO-32 must be compiled with the AMACRO compiler.

9.2  –  Description

    When you start the debugger, the current language is set to that
    in which the module containing the main program is written. This
    is usually the module containing the image transfer address. To
    debug a module written in a different source language from that
    of the main program, you can change the language with the SET
    LANGUAGE command.

    The current language setting determines how the debugger parses
    and interprets the names, operators, and expressions you specify
    in debugger commands, including things like the typing of
    variables, array and record syntax, the default radix for the
    entry and display of integer data, case sensitivity, and so on.
    The language setting also determines how the debugger formats and
    displays data associated with your program.

    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 default type for program locations that do not have a
    compiler-generated type is longword integer. This is appropriate
    for debugging 32-bit applications.

    It is advisable to change the default type to quadword for
    debugging applications that use the 64-bit address space (on
    OpenVMS Integrity server systems, the default type is quadword).
    Use the SET TYPE QUADWORD command.

    Use the SET LANGUAGE UNKNOWN command when debugging a program
    written in an unsupported language. To maximize the usability
    of the debugger with unsupported languages, SET LANGUAGE UNKNOWN
    causes the debugger to accept a large set of data formats and
    operators, including some that might be specific to only a few
    supported languages.

    Note that SET LANGUAGE UNKNOWN can be an easy, quick workaround
    for language-related problems because it uses the "loosest" set
    of rules.

    For information about debugger support for language-specific
    operators and constructs, see the Language_Support help topic.

    Related commands:

       EVALUATE
       EXAMINE
       DEPOSIT
       SET MODE
       SET RADIX
       SET TYPE
       SHOW LANGUAGE

9.3  –  Examples

    1.DBG> SET LANGUAGE COBOL

      This command establishes COBOL as the current language.

    2.DBG> SET LANGUAGE PASCAL

      This command establishes Pascal as the current language.

9.4    /DYNAMIC

    Toggles the state of automatic language setting.

    Format

      SET LANGUAGE/DYNAMIC

9.4.1  –  Description

    When you start the debugger, the current language is set to that
    in which the module containing the main program is written. This
    is usually the module containing the image transfer address. By
    default, when the scope of the program being executed changes to
    a module written in a different language, the debugger changes
    the current language to that of the module.

    You can prevent the debugger from automatically changing the
    current language with the SET LANGUAGE/NODYNAMIC command.

    Related commands:

       SET LANGUAGE
       SHOW LANGUAGE

9.4.2  –  Examples

    1.DBG> SET LANGUAGE/NODYNAMIC

      This command prevents the debugger from changing the current
      language until you enter a SET LANGUAGE or SET LANGUAGE/DYNAMIC
      command.

10  –  LOG

    Specifies a log file to which the debugger writes after a SET
    OUTPUT LOG command has been entered.

    Format

      SET LOG  file-spec

10.1  –  Parameters

 file-spec

    Denotes the file specification of the log file. If you do
    not supply a full file specification, the debugger assumes
    SYS$DISK:[]DEBUG.LOG as the default file specification for any
    missing field.

    If you specify a version number and that version of the file
    already exists, the debugger writes to the file specified,
    appending the log of the debugging session onto the end of that
    file.

10.2  –  Description

    The SET LOG command determines only the name of a log file; it
    does not cause the debugger to create or write to the specified
    file. The SET OUTPUT LOG command accomplishes that.

    If you entered a SET OUTPUT LOG command but no SET LOG command,
    the debugger writes to the file SYS$DISK:[]DEBUG.LOG by default.

    If the debugger is writing to a log file and you specify another
    log file with the SET LOG command, the debugger closes the former
    file and begins writing to the file specified in the SET LOG
    command.

    Related commands:

       SET OUTPUT LOG
       SET OUTPUT SCREEN_LOG
       SHOW LOG

10.3  –  Examples

    1.DBG> SET LOG CALC
      DBG> SET OUTPUT LOG

      In this example, the SET LOG command specifies the debugger
      log file to be SYS$DISK:[]CALC.LOG. The SET OUTPUT LOG command
      causes user input and debugger output to be logged to that
      file.

    2.DBG> SET LOG [CODEPROJ]FEB29.TMP
      DBG> SET OUTPUT LOG

      In this example, the SET LOG command specifies the debugger
      log file to be [CODEPROJ]FEB29.TMP. The SET OUTPUT LOG command
      causes user input and debugger output to be logged to that
      file.

11  –  MARGINS

    Specifies the leftmost and rightmost source-line character
    position at which to begin and end display of a source line.

                                   NOTE

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

    Format

      SET MARGINS  rm

                   lm:rm

                   lm:

                   :rm

11.1  –  Parameters

 lm

    The source-line character position at which to begin display of
    the line of source code (the left margin).

 rm

    The source-line character position at which to end display of the
    line of source code (the right margin).

11.2  –  Description

    The SET MARGINS command affects only the display of source lines.
    It does not affect the display of other debugger output, as from
    an EXAMINE command.

    The SET MARGINS command is useful for controlling the display
    of source code when, for example, the code is deeply indented
    or long lines wrap at the right margin. In such cases, you can
    set the left margin to eliminate indented space in the source
    display, and you can decrease the right margin setting (from its
    default value of 255) to truncate lines and prevent them from
    wrapping.

    The SET MARGINS command is useful mostly in line (noscreen) mode.
    In line mode, the SET MARGINS command affects the display of
    source lines resulting from a TYPE, EXAMINE/SOURCE, SEARCH, or
    STEP command, or when a breakpoint, tracepoint, or watchpoint is
    triggered.

    In screen mode, the SET MARGINS command has no effect on
    the display of source lines in a source display, such as the
    predefined display SRC. Therefore it does not affect the output
    of a TYPE or EXAMINE/SOURCE command, since that output is
    directed at a source display. The SET MARGINS command affects
    only the display of any source code that might appear in an
    output or DO display (for example, after a STEP command has
    been executed). However, such source-code display is normally
    suppressed if you enable screen mode by pressing PF1-PF3, because
    that sequence issues the SET STEP NOSOURCE command as well as SET
    MODE SCREEN to eliminate redundant source display.

    By default, the debugger displays a source line starting at
    character position 1 of the source line. This is actually
    character position 9 on your terminal screen. The first eight
    character positions on the screen are reserved for the line
    number and cannot be manipulated by the SET MARGINS command.

    If you specify a single number, the debugger sets the left margin
    to 1 and the right margin to the number specified.

    If you specify two numbers, separated with a colon, the debugger
    sets the left margin to the number on the left of the colon and
    the right margin to the number on the right.

    If you specify a single number followed by a colon, the debugger
    sets the left margin to that number and leaves the right margin
    unchanged.

    If you specify a colon followed by a single number, the debugger
    sets the right margin to that number and leaves the left margin
    unchanged.

    Related commands:

       SET STEP [NO]SOURCE
       SHOW MARGINS

11.3  –  Examples

    1.DBG> SHOW MARGINS
      left margin: 1 , right margin: 255
      DBG> TYPE 14
      module FORARRAY
         14:        DIMENSION IARRAY(4:5,5), VECTOR(10), I3D(3,3,4)
      DBG>

      This example displays the default margin settings for a line of
      source code (1 and 255).

    2.DBG> SET MARGINS 39
      DBG> SHOW MARGINS
      left margin: 1 , right margin: 39
      DBG> TYPE 14
      module FORARRAY
         14:        DIMENSION IARRAY(4:5,5), VECTOR
      DBG>

      This example shows how the display of a line of source code
      changes when you change the right margin setting from 255 to
      39.

    3.DBG> SET MARGINS 10:45
      DBG> SHOW MARGINS
      left margin: 10 , right margin: 45
      DBG> TYPE 14
      module FORARRAY
         14: IMENSION IARRAY(4:5,5), VECTOR(10),
      DBG>

      This example shows the display of the same line of source code
      after both margins are changed.

    4.DBG> SET MARGINS :100
      DBG> SHOW MARGINS
      left margin: 10 , right margin: 100
      DBG>

      This example shows how to change the right margin setting while
      retaining the previous left margin setting.

    5.DBG> SET MARGINS 5:
      DBG> SHOW MARGINS
      left margin: 5 , right margin: 100
      DBG>

      This example shows how to change the left margin setting while
      retaining the previous right margin setting.

12  –  MODE

    Enables or disables a debugger mode.

    Format

      SET MODE  mode[, . . . ]

12.1  –  Parameters

 DYNAMIC

    (Default) Enables dynamic mode. When dynamic mode is enabled,
    the debugger sets modules and images automatically during program
    execution so that you typically do not have to enter the SET
    MODULE or SET IMAGE command. Specifically, whenever the debugger
    interrupts execution (whenever the debugger prompt is displayed),
    the debugger automatically sets the module and image that contain
    the routine in which execution is currently suspended. If the
    module or image is already set, dynamic mode has no effect
    on that module or image. The debugger issues an informational
    message when its sets a module or image automatically.

 NODYNAMIC

    Disables dynamic mode. Because additional memory is allocated
    when a module or image is set, you might want to disable dynamic
    mode if performance becomes a problem (you can also free up
    memory by canceling modules and images with the CANCEL MODULE
    and CANCEL IMAGE commands). When dynamic mode is disabled, you
    must set modules and images explicitly with the SET MODULE and
    SET IMAGE commands.

 G_FLOAT

    Specifies that the debugger interpret double-precision floating-
    point constants entered in expressions as G_FLOAT (does not
    affect the interpretation of variables declared in your program).

 NOG_FLOAT

    (Default) Specifies that the debugger interpret double-precision
    floating-point constants entered in expressions as D_FLOAT (does
    not affect the interpretation of variables declared in your
    program).

 INTERRUPT

    Useful when debugging a multiprocess program. Specifies that,
    when program execution is suspended in any process, the debugger
    interrupts execution in all other processes that were executing
    images and prompts for input.

 NOINTERRUPT

    (Default) Useful when debugging a multiprocess program. Specifies
    that, when program execution is suspended in any process, the
    debugger take no action with regard to other process.

 KEYPAD

                                   NOTE

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

    (Default) Enables keypad mode. When keypad mode is enabled,
    you can use the keys on the numeric keypad to perform certain
    predefined functions. Several debugger commands, especially
    useful in screen mode, are bound to the keypad keys. (See the
    Keypad_Definitions_CI help topic; also, use the SHOW KEY command
    to determine the current key definitions.) You can also redefine
    the key functions with the DEFINE/KEY command.

 NOKEYPAD

                                   NOTE

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

    Disables keypad mode. When keypad mode is disabled, the keys on
    the numeric keypad do not have predefined functions, nor can you
    assign debugger functions to those keys with DEFINE/KEY commands.

 LINE

    (Default) Specifies that the debugger display program locations
    in terms of line numbers, if possible.

 NOLINE

    Specifies that the debugger display program locations as routine-
    name + byte-offset rather than in terms of line numbers.

 OPERANDS[=keyword]

    Specifies that the EXAMINE command, when used to examine
    an instruction, display the address and contents of the
    instruction's operands in addition to the instruction and
    its operands. The level of information displayed about any
    nonregister operands depends on whether you use the keyword BRIEF
    or FULL. The default is OPERANDS=BRIEF.

 NOOPERANDS

    (Default) Specifies that the EXAMINE command, when used to
    examine an instruction, display only the instruction and its
    operands.

 SCREEN

                                   NOTE

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

    Enables screen mode. When screen mode is enabled, you can divide
    the terminal screen into rectangular regions, so different data
    can be displayed in different regions. Screen mode enables you to
    view more information more conveniently than the default, line-
    oriented, noscreen mode. You can use the predefined displays, or
    you can define your own.

 NOSCREEN

                                   NOTE

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

    (Default) Disables screen mode.

 SCROLL

                                   NOTE

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

    Enables scroll mode. When scroll mode is enabled, a screen-mode
    output or DO display is updated by scrolling the output line by
    line, as it is generated. SET MODE SCROLL is the default.

 NOSCROLL

                                   NOTE

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

    Disables scroll mode. When scroll mode is disabled, a screen-mode
    output or DO display is updated only once per command, instead
    of line by line as it is generated. Disabling scroll mode reduces
    the amount of screen updating that takes place and can be useful
    with slow terminals.

 SEPARATE

    (Applies only to workstations running VWS.) Specifies that a
    separate window be created for debugger input and output. This
    feature is useful when debugging screen-oriented programs,
    because it moves all debugger displays out of the window that
    contains the program's input and output. The separate window is
    created with a height of 24 lines and a width of 80 columns wide,
    emulating a VT-series terminal screen.

 NOSEPARATE

    (Applies only to workstations running VWS. Default.) Specifies
    that no separate window be created for debugger input and output.

 SYMBOLIC

    (Default) Enables symbolic mode. When symbolic mode is
    enabled, the debugger displays the locations denoted by address
    expressions symbolically (if possible) and displays instruction
    operands symbolically (if possible). EXAMINE/NOSYMBOLIC can be
    used to override SET MODE SYMBOLIC for the duration of an EXAMINE
    command.

 NOSYMBOLIC

    Disables symbolic mode. When symbolic mode is disabled, the
    debugger does not attempt to symbolize numeric addresses (it
    does not cause the debugger to convert numbers to names). This is
    useful if you are interested in identifying numeric addresses
    rather than their symbolic names (if symbolic names exist
    for those addresses). When symbolic mode is disabled, command
    processing might speed up somewhat, because the debugger does not
    need to convert numbers to names. EXAMINE/SYMBOLIC can be used
    to override SET MODE NOSYMBOLIC for the duration of an EXAMINE
    command.

 WAIT

    (Default) Enables wait mode. In wait mode the debugger waits
    until all processes under its control have stopped before
    prompting for a new command.

 NOWAIT

    Disable wait mode. In nowait mode, the debugger immediately
    prompts for new commands even if some or all processes are still
    running.

12.2  –  Description

    For details about the SET MODE command, see the parameter
    descriptions. The default values of these modes are the same
    for all languages.

    Related commands:

       EVALUATE
       EXAMINE
       DEFINE/KEY
       DEPOSIT
       DISPLAY
       (SET,SHOW,CANCEL) IMAGE
       (SET,SHOW,CANCEL) MODULE
       SET PROMPT
       (SET,SHOW,CANCEL) RADIX
       (SET,SHOW) TYPE
       (SHOW,CANCEL) MODE
       SYMBOLIZE

12.3  –  Example

  DBG> SET MODE SCREEN

      This command puts the debugger in screen mode.

13  –  MODULE

    Loads the symbol records of a module in the current image into
    the run-time symbol table (RST) of that image.

                                  NOTES

       The current image is either the main image (by default) or
       the image established as the current image by a previous SET
       IMAGE command.

       By default, the debugger automatically loads symbols in a
       module as needed. As such, this behavior makes the use of an
       explicit SET MODULE command optional. For more information,
       see SET MODE DYNAMIC.

    Format

      SET MODULE  [module-name[, . . . ]]

13.1  –  Parameters

 module-name

    Specifies a module of the current image whose symbol records
    are loaded into the RST. Do not use the asterisk (*)  wildcard
    character. Instead, use the /ALL qualifier. Do not specify a
    module name with /ALL or /CALLS.

13.2  –  Qualifiers

13.2.1    /ALL

    Specifies that the symbol records of all modules in the current
    image be loaded into the RST.

13.2.2    /CALLS

    Sets all the modules that currently have routines on the call
    stack. If a module is already set, /CALLS has no effect on that
    module.

13.2.3    /RELATED

       /RELATED (default)
       /NORELATED

    (Applies to Ada programs.) Controls whether the debugger loads
    into the RST the symbol records of a module that is related to a
    specified module through a with-clause or subunit relationship.
    Once loaded, you can reference names declared in related modules
    within debugger commands exactly as you reference them within the
    Ada source code.

13.3  –  Description

    The SET MODULE command loads the symbol records of a module in
    the current image into the run-time symbol table (RST) of that
    image. Symbol records must be present in the RST if the debugger
    is to recognize and properly interpret the symbols declared in
    your program. The process by which the symbol records of a module
    are loaded into the RST is called setting a module. This command
    also supports user-provided mixed-case and lowercase module names
    on Integrity and Alpha servers.

    At debugger startup, the debugger sets the module containing
    the transfer address (the main program). By default, dynamic
    mode is enabled (SET MODE DYNAMIC). Therefore, the debugger sets
    modules (and images) automatically as the program executes so
    that you can reference symbols as you need them. Specifically,
    whenever execution is suspended, the debugger sets the module
    and image containing the routine in which execution is suspended.
    In the case of Ada programs, as a module is set dynamically, its
    related modules are also set automatically, by default, to make
    the appropriate symbols accessible (visible).

    Dynamic mode makes accessible most of the symbols you might need
    to reference. If you need to reference a symbol in a module that
    is not already set, proceed as follows:

    o  If the module is in the current image, use the SET MODULE
       command to set the module where the symbol is defined or
       reference the symbol with a fully-qualified path name. For
       example:

       DBG>SET BREAK X\Y

    o  If the module is in another image, use the SET IMAGE command
       to make that image the current image, then use the SET MODULE
       command to set the module where the symbol is defined.

    If dynamic mode is disabled (SET MODE NODYNAMIC), only the module
    containing the transfer address is set automatically. You must
    set any other modules explicitly.

    If you use the SET IMAGE command to establish a new current
    image, all modules previously set remain set. However, only the
    symbols in the set modules of the current image are accessible.
    Symbols in the set modules of other images are temporarily
    inaccessible.

    When dynamic mode is enabled, memory is allocated automatically
    to accommodate the increasing size of the RST. If dynamic mode
    is disabled, the debugger automatically allocates more memory as
    needed when you set a module or an image.

    If a parameter in a SET SCOPE command designates a program
    location in a module that is not already set, the SET SCOPE
    command sets that module.

    For information specific to Ada programs, type Help
    Language_Support Ada.

    Related commands:

       (SET,SHOW,CANCEL) IMAGE
       SET MODE [NO]DYNAMIC
       (SHOW) MODULE

13.4  –  Examples

    1.DBG> SET MODULE SUB1

      This command sets module SUB1 (loads the symbol records of
      module SUB1 into the RST).

    2.DBG> SET IMAGE SHARE3
      DBG> SET MODULE MATH
      DBG> SET BREAK %LINE 31

      In this example, the SET IMAGE command makes shareable image
      SHARE3 the current image. The SET MODULE command sets module
      MATH in image SHARE3. The SET BREAK command sets a breakpoint
      on line 31 of module MATH.

    3.DBG> SHOW MODULE/SHARE
      module name           symbols   language   size

      FOO                   yes       MACRO       432
      MAIN                  no        FORTRAN     280
           . . .
      SHARE$DEBUG           no        Image         0
      SHARE$LIBRTL          no        Image         0
      SHARE$MTHRTL          no        Image         0
      SHARE$SHARE1          no        Image         0
      SHARE$SHARE2          no        Image         0

      total modules: 17.              bytes allocated: 162280.
      DBG> SET MODULE SHARE$SHARE2
      DBG> SHOW SYMBOL * IN SHARE$SHARE2

      In this example, the SHOW MODULE/SHARE command identifies all
      modules in the current image and all shareable images (the
      names of the shareable images are prefixed with SHARE$).
      The SET MODULE SHARE$SHARE2 command sets the shareable image
      module SHARE$SHARE2. The SHOW SYMBOL command identifies any
      universal symbols defined in the shareable image SHARE2. For
      more information, see the SHOW MODULE/SHARE command.

    4.DBG> SET BREAK X/Y:

      In this example, the debugger automatically loads the module
      information when you specify the module name in the command.
      Debugger ensures that the module information for module X is
      loaded, and then locates the information for the routine named
      Y.

14  –  OUTPUT

    Enables or disables a debugger output option.

    Format

      SET OUTPUT  output-option[, . . . ]

14.1  –  Parameters

 output-option

    Specifies an output option to be enabled or disabled. Valid
    keywords are as follows:

    LOG          Specifies that debugger input and output be recorded
                 in a log file. If you specify the log file by
                 the SET LOG command, the debugger writes to that
                 file; otherwise, by default the debugger writes to
                 SYS$DISK[]:DEBUG.LOG.
    NOLOG        (Default) Specifies that debugger input and output
                 not be recorded in a log file.
    SCREEN_LOG   Specifies that, while in screen mode, the screen
                 contents be recorded in a log file as the screen is
                 updated. To log the screen contents, you must also
                 specify SET OUTPUT LOG. See the description of the
                 LOG option regarding specifying the log file.
    NOSCREEN_    (Default) Specifies that the screen contents, while
    LOG          in screen mode, not be recorded in a log file.
    TERMINAL

                                           NOTE

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

                 (Default) Specifies that debugger output be
                 displayed at the terminal.
    NOTERMINAL

                                           NOTE

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

                 Specifies that debugger output, except diagnostic
                 messages, not be displayed at the terminal.
    VERIFY       Specifies that the debugger echo, on the current
                 output device, each input command string that it is
                 executing from a command procedure or DO clause. The
                 current output device is by default SYS$OUTPUT (your
                 terminal) but can be redefined with the logical name
                 DBG$OUTPUT.
    NOVERIFY     (Default) Specifies that the debugger not display
                 each input command string that it is executing from
                 a command procedure or DO clause.

14.2  –  Description

    Debugger output options control the way in which debugger
    responses to commands are displayed and recorded. For details
    about the SET OUTPUT command, see the parameter descriptions.

    Related commands:

       @ (Execute Procedure)
       (SET,SHOW) ATSIGN
       (SET,SHOW) LOG
       SET MODE SCREEN
       SHOW OUTPUT

14.3  –  Example

  DBG> SET OUTPUT VERIFY,LOG,NOTERMINAL

      This command specifies that the debugger take the following
      actions:

      o  Output each command string that it is executing from a
         command procedure or DO clause (VERIFY)

      o  Record debugger output and user input in a log file (LOG)

      o  Not display output at the terminal, except diagnostic
         messages (NOTERMINAL)

15  –  PROCESS

    Establishes the visible process or enables/disables dynamic
    process setting.

    Used only when debugging multiprocess programs (kept debugger
    only).

    Format

      SET PROCESS  [process-spec[, . . . ]]

15.1  –  Parameters

 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.

    You can also use the asterisk (*)  wildcard character to specify
    process set all.

    Do not specify a process with the /[NO]DYNAMIC qualifier.

15.2  –  Qualifiers

15.2.1    /DYNAMIC

       /DYNAMIC (default)
       /NODYNAMIC

    Controls whether dynamic process setting is enabled or disabled.
    When dynamic process setting is enabled (/DYNAMIC), whenever the
    debugger suspends execution and displays its prompt, the process
    in which execution is suspended automatically becomes the visible
    process. When dynamic process setting is disabled (/NODYNAMIC),
    the visible process remains unchanged until you specify another
    process with the SET PROCESS/VISIBLE command.

15.2.2    /VISIBLE

    Makes the specified process the visible process. This switches
    your debugging context to the specified process, so that symbol
    lookups and the setting of breakpoints, and so on, are done
    in the context of that process. When using /VISIBLE, you must
    specify one process.

15.3  –  Description

    The SET PROCESS command establishes the visible process, defines
    the current process set, or defines the visible process.

    By default, commands are executed in the context of the visible
    process (the process that is your current debugging context).
    Symbol lookups, the setting of breakpoints, and so on, are done
    in the context of the visible process.

    Dynamic process setting is enabled by default and is controlled
    with /[NO]DYNAMIC. When dynamic process setting is enabled,
    whenever the debugger suspends program execution and displays
    its prompt, the process in which execution is suspended becomes
    the visible process automatically.

    Related commands:

       CALL
       EXIT
       GO
       QUIT
       SHOW PROCESS
       STEP

15.4  –  Example

  all> SET PROCESS TEST_Y
  all> SHOW PROCESS
   Number   Name         State     Current PC
  *    2 TEST_Y          break     PROG\%LINE 71
  all>

      The SET PROCESS TEST_Y command makes process TEST_Y the visible
      process. The SHOW PROCESS command displays information about
      the visible process by default.

16  –  PROMPT

    Changes the debugger prompt string to your personal preference.

    Format

      SET PROMPT  [prompt-parameter]

16.1  –  Parameters

 prompt-parameter

    Specifies the new prompt string. If the string contains spaces,
    semicolons (;),  or lowercase characters, you must enclose it in
    quotation marks (")  or apostrophes ('). If you do not specify a
    string, the current prompt string remains unchanged.

    By default, the prompt string is DBG> when debugging a single
    process program.

    By default, when debuggging a multiprocess program, the prompt
    string is the name of the current process set followed by a right
    angle bracket (>). You should not use the SET PROMPT command when
    debugging multiprocess programs.

16.2  –  Qualifiers

16.2.1    /POP

       /POP
       /NOPOP (default)

    (Applies only to workstations running VWS.) The /POP qualifier
    causes the debugger window to pop over other windows and become
    attached to the keyboard when the debugger prompts for input. The
    /NOPOP qualifier disables this behavior (the debugger window is
    not popped over other windows and is not attached to the keyboard
    automatically when the debugger prompts for input).

16.3  –  Description

    The SET PROMPT command enables you to tailor the debugger prompt
    string to your individual preference.

    If you are debugging a multiprocess program, you should not use
    the SET PROMPT command.

    If you are using the debugger at a workstation, /[NO]POP enables
    you to control whether the debugger window is popped over other
    windows whenever the debugger prompts for input.

    Related commands:

       (SET,SHOW) PROCESS

16.4  –  Examples

    1.DBG> SET PROMPT "$ "
      $ SET PROMPT "d b g : "
      d b g : SET PROMPT "DBG> "
      DBG>

      In this example, the successive SET PROMPT commands change the
      debugger prompt from "DBG>" to "$", to "d b g :", then back to
      "DBG>".

17  –  RADIX

    Establishes the radix for the entry and display of integer data.
    When used with /OVERRIDE, it causes all data to be displayed as
    integer data of the specified radix.

    Format

      SET RADIX  radix

17.1  –  Parameters

 radix

    Specifies the radix to be established. Valid keywords are as
    follows:

    BINARY      Sets the radix to binary.
    DECIMAL     Sets the radix to decimal. This is the default for
                all languages except BLISS, MACRO-32, and MACRO-64
                (Alpha and Integrity servers only).
    DEFAULT     Sets the radix to the language default.
    OCTAL       Sets the radix to octal.
    HEXADECIMAL Sets the default radix to hexadecimal. This is the
                default for BLISS, MACRO-32, and MACRO-64 (Alpha and
                Integrity servers only).

17.2  –  Qualifiers

17.2.1    /INPUT

    Sets only the input radix (the radix for entering integer data)
    to the specified radix.

17.2.2    /OUTPUT

    Sets only the output radix (the radix for displaying integer
    data) to the specified radix.

17.2.3    /OVERRIDE

    Causes all data to be displayed as integer data of the specified
    radix.

17.3  –  Description

    The current radix setting influences how the debugger interprets
    and displays integer data in the following contexts:

    o  Integer data that you specify in address expressions or
       language expressions.

    o  Integer data that is displayed by the EXAMINE and EVALUATE
       commands.

    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 SET RADIX command enables you to specify a new radix
    for data entry or display (the input radix and output radix,
    respectively).

    If you do not specify a qualifier, the SET RADIX command
    changes both the input and output radix. If you specify /INPUT
    or /OUTPUT, the command changes the input or output radix,
    respectively.

    Using SET RADIX/OVERRIDE changes only the output radix but causes
    all data (not just data that has an integer type) to be displayed
    as integer data of the specified radix.

    Except when used with /OVERRIDE, the SET RADIX command does not
    affect the interpretation or display of noninteger values (such
    as real or enumeration type values).

    The EVALUATE, EXAMINE, and DEPOSIT commands have radix
    qualifiers (/BINARY, /HEXADECIMAL, and so on) which enable you to
    override, for the duration of that command, any radix previously
    established with SET RADIX or SET RADIX/OVERRIDE.

    You can also use the built-in symbols %BIN, %DEC, %HEX, and %OCT
    in address expressions and language expressions to specify that
    an integer literal should be interpreted in binary, decimal,
    hexadecimal, or octal radix.

    Related commands:

       DEPOSIT
       EVALUATE
       EXAMINE
       (SET,SHOW,CANCEL) MODE
       (SHOW,CANCEL) RADIX

17.4  –  Examples

    1.DBG> SET RADIX HEX

      This command sets the radix to hexadecimal. This means that,
      by default, integer data is interpreted and displayed in
      hexadecimal radix.

    2.DBG> SET RADIX/INPUT OCT

      This command sets the radix for input to octal. This means
      that, by default, integer data that is entered is interpreted
      in octal radix.

    3.DBG> SET RADIX/OUTPUT BIN

      This command sets the radix for output to binary. This means
      that, by default, integer data is displayed in binary radix.

    4.DBG> SET RADIX/OVERRIDE DECIMAL

      This command sets the override radix to decimal. This means
      that, by default, all data (not just data that has an integer
      type) is displayed as decimal integer data.

18  –  SCOPE

    Establishes how the debugger looks up symbols (variable names,
    routine names, line numbers, and so on) when a path-name prefix
    is not specified.

    Format

      SET SCOPE  location[, . . . ]

18.1  –  Parameters

 location

    Denotes a program region (scope) to be used for the
    interpretation of symbols that you specify without a path-name
    prefix. A location can be any of the following, unless you
    specify /CURRENT or /MODULE.

    path-name      Specifies the scope denoted by the path-name
    prefix         prefix. A path-name prefix consists of the
                   names of one or more nesting program elements
                   (module, routine, block, and so on), with each
                   name separated by a backslash character (\).
                   When a path-name prefix consists of more than
                   one name, list a nesting element to the left of
                   the backslash and a nested element to the right of
                   the backslash. A common path-name prefix format is
                   module\routine\block\.

                   If you specify only a module name and that name is
                   the same as the name of a routine, use /MODULE;
                   otherwise, the debugger assumes that you are
                   specifying the routine.
    n              Specifies the scope denoted by the routine which
                   is n levels down the call stack (n is a decimal
                   integer). A scope specified by an integer changes
                   dynamically as the program executes. The value 0
                   denotes the routine that is currently executing,
                   the value 1 denotes the caller of that routine,
                   and so on down the call stack. The default scope
                   search list is 0,1,2, . . . ,n, where n is the
                   number of calls in the call stack.
    \              Specifies the global scope-that is, the set of
    (backslash)    all program locations in which a global symbol is
                   known. The definition of a global symbol and the
                   way it is declared depends on the language.

    When you specify more than one location parameter, you establish
    a scope search list. If the debugger cannot interpret the symbol
    using the first parameter, it uses the next parameter, and
    continues using parameters in order of their specification until
    it successfully interprets the symbol or until it exhausts the
    parameters specified.

18.2  –  Qualifiers

18.2.1    /CURRENT

    Establishes a scope search list that is like the default search
    list (0,1,2, . . . ,n), numeric scope specified as the command
    parameter. Scope 0 is the PC scope, and n is the number of calls
    in the call stack.

    When using SET SCOPE/CURRENT, note the following conventions and
    behavior:

    o  The default scope search list must be in effect when the
       command is entered. To restore the default scope search list,
       enter the CANCEL SCOPE command.

    o  The command parameter specified must be one (and only one)
       decimal integer from 0 to n.

    o  In screen mode, the command updates the predefined source,
       instruction, and register displays SRC, INST, and REG,
       respectively, to show the routine on the call stack in which
       symbol searches are to start.

    o  The default scope search list is restored when program
       execution is resumed.

18.2.2    /MODULE

    Indicates that the name specified as the command parameter is a
    module name and not a routine name. You need to use /MODULE only
    if you specify a module name as the command parameter and that
    module name is the same as the name of a routine.

18.3  –  Description

    By default, the debugger looks up a symbol specified without a
    path-name prefix according to the scope search list 0,1,2, . . .
    ,n, where n is the number of calls in the call stack. This
    scope search list is based on the current PC value and changes
    dynamically as the program executes. The default scope search
    list specifies that a symbol lookup such as EXAMINE X first looks
    for X in the routine that is currently executing (scope 0, also
    known as the PC scope); if no X is visible there, the debugger
    looks in the caller of that routine (scope 1), and so on down the
    call stack; if X is not found in scope n, the debugger searches
    the rest of the run-time symbol table (RST)-that is, all set
    modules and the global symbol table (GST), if necessary.

    In most cases, this default scope search list enables you
    to resolve ambiguities in a predictable, natural way that is
    consistent with language rules. But if you cannot access a symbol
    that is defined multiple times, use either of the following
    techniques:

    o  Specify the symbol with a path-name prefix. The path-name
       prefix consists of any nesting program units (for example,
       module\routine\block) that are necessary to specify the symbol
       uniquely. For example:

       DBG> EXAMINE MOD4\ROUT3\X
       DBG> TYPE MOD4\27

    o  Establish a new default scope (or a scope search list) for
       symbol lookup by using the SET SCOPE command. You can then
       specify the symbol without using a path-name prefix. For
       example:

       DBG> SET SCOPE MOD4\ROUT3
       DBG> EXAMINE X
       DBG> TYPE 27

18.4  –  Description, Continued...

    The SET SCOPE command is useful in those cases where otherwise
    you would need to use a path name repeatedly to specify symbols.

    SET SCOPE changes the debugger's language setting to the language
    of the specified scope.

    To restore the default scope search list, use the CANCEL SCOPE
    command.

    When the default scope search list is in effect, you can use the
    SET SCOPE/CURRENT command to specify that symbol searches start
    at a numeric scope other than scope 0, relative to the call stack
    (for example, scope 2).

    When you use the SET SCOPE command, the debugger searches only
    the program locations you specify explicitly, unless you specify
    /CURRENT. Also, the scope or scope search list established with a
    SET SCOPE command remains in effect until you restore the default
    scope search list or enter another SET SCOPE command. However, if
    you specify /CURRENT, the default scope search list is restored
    whenever program execution is resumed.

    The SET SCOPE command updates a screen-mode source or instruction
    display only if you specify /CURRENT.

    If a name you specify in a SET SCOPE command is the name of
    both a module and a routine, the debugger sets the scope to the
    routine. In such cases, use the SET SCOPE/MODULE command if you
    want to set the scope to the module.

    If you specify a module name in a SET SCOPE command, the debugger
    sets that module if it is not already set. However, if you want
    only to set a module, use the SET MODULE command rather than the
    SET SCOPE command, to avoid the possibility of disturbing the
    current scope search list.

    For information specific to Ada programs, type Help Language_
    Support Ada.

    Related commands:

       CANCEL ALL
       SEARCH
       SET MODULE
       (SHOW,CANCEL) SCOPE
       SHOW SYMBOL
       SYMBOLIZE
       TYPE

18.5  –  Examples

    1.DBG> EXAMINE Y
      %DEBUG-W-NOUNIQUE, symbol 'Y' is not unique
      DBG> SHOW SYMBOL Y
          data CHECK_IN\Y
          data INVENTORY\COUNT\Y
      DBG> SET SCOPE INVENTORY\COUNT
      DBG> EXAMINE Y
      INVENTORY\COUNT\Y: 347.15
      DBG>

      In this example, the first EXAMINE Y command indicates that
      symbol Y is defined multiple times and cannot be resolved from
      the current scope search list. The SHOW SYMBOL command displays
      the different declarations of symbol Y. The SET SCOPE command
      directs the debugger to look for symbols without path-name
      prefixes in routine COUNT of module INVENTORY. The subsequent
      EXAMINE command can now interpret Y unambiguously.

19  –  SEARCH

    Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or
    /STRING) for the SEARCH command.

    Format

      SET SEARCH  search-default[, . . . ]

19.1  –  Parameters

 search-default

    Specifies a default to be established for the SEARCH command.
    Valid keywords (which correspond to SEARCH command qualifiers)
    are as follows:

    ALL        Subsequent SEARCH commands are treated as SEARCH/ALL,
               rather than SEARCH/NEXT.
    IDENTIFIER Subsequent SEARCH commands are treated as
               SEARCH/IDENTIFIER, rather than SEARCH/STRING.
    NEXT       (Default) Subsequent SEARCH commands are treated as
               SEARCH/NEXT, rather than SEARCH/ALL.
    STRING     (Default) Subsequent SEARCH commands are treated as
               SEARCH/STRING, rather than SEARCH/IDENTIFIER.

19.2  –  Description

    The SET SEARCH command establishes default qualifiers for
    subsequent SEARCH commands. The parameters that you specify with
    SET SEARCH have the same names as the qualifiers for the SEARCH
    command. The qualifiers determine whether the SEARCH command:
    (1)  searches for all occurrences of a string (ALL) or only the
    next occurrence (NEXT); and (2)  displays any occurrence of the
    string (STRING) or only those occurrences in which the string is
    not bounded on either side by a character that can be part of an
    identifier in the current language (IDENTIFIER).

    You can override the current SEARCH default for the duration of
    a single SEARCH command by specifying other qualifiers. Use the
    SHOW SEARCH command to identify the current SEARCH defaults.

    Related commands:

       SEARCH
       (SET,SHOW) LANGUAGE
       SHOW SEARCH

19.3  –  Example

  DBG> SHOW SEARCH
  search settings: search for next occurrence, as a string

  DBG> SET SEARCH IDENTIFIER
  DBG> SHOW SEARCH
  search settings: search for next occurrence, as an identifier

  DBG> SET SEARCH ALL
  DBG> SHOW SEARCH
  search settings: search for all occurrences, as an identifier
  DBG>

      In this example, the SET SEARCH IDENTIFIER command directs
      the debugger to search for an occurrence of the string in
      the specified range but display the string only if it is not
      bounded on either side by a character that can be part of an
      identifier in the current language.

      The SET SEARCH ALL command directs the debugger to search for
      (and display) all occurrences of the string in the specified
      range.

20  –  SOURCE

    Specifies a directory search list, a directory search method, or
    both a list and a method for source files.

    Format

      SET SOURCE  directory-spec[, . . . ]

20.1  –  Parameters

 directory-spec

    Specifies any part of an OpenVMS file specification (typically
    a device/directory) that the debugger is to use by default
    when searching for a source file. For any part of a full file
    specification that you do not supply, the debugger uses the file
    specification stored in the module's symbol record (that is, the
    file specification that the source file had at compile time).

    If you specify more than one directory in a single SET SOURCE
    command, you create a source directory search list (you can
    also specify a search list logical name that is defined at your
    process level). In this case, the debugger locates the source
    file by searching the first directory specified, then the second,
    and so on, until it either locates the source file or exhausts
    the list of directories.

20.2  –  Qualifiers

20.2.1    /DISPLAY

    Specifies the directory search list used when the debugger
    displays source code. The default display search directory is
    the compilation directory.

20.2.2    /EDIT

    Specifies the directory search list used during execution of the
    debugger's EDIT command. The default edit search directory is the
    compilation directory.

20.2.3    /EXACT

       /EXACT (default)

    Specifies the directory search method used. In this case, the
    debugger searches for the exact version of the source file, as
    indicated in the debugger symbol table.

20.2.4    /LATEST

    Specifies the directory search method used. In this case, the
    debugger searches for the latest version of the source file, that
    is, the highest-numbered version in your directory.

20.2.5    /MODULE

       /MODULE=module-name

    Specifies the directory search list used only for the designated
    module. You can append one or more of the qualifiers listed above
    to the SET SOURCE/MODULE command.

20.2.6    /ORIGINAL

    (Applies to STDL programs only. Requires installation of the
    Correlation Facility (a separate layered product) and invocation
    of the kept debugger.) Specifies that the debugger display the
    original STDL source file, rather than the intermediate files
    produced during STDL compilation.

20.3  –  Description

    By default, the debugger expects a source file to be in the same
    directory it was in at compile time. If a source file has been
    moved to a different directory since compile time, use the SET
    SOURCE command to specify a directory search list and search
    method to locate the file.

    Specifying the Directory Search List

    A complete ODS-2 OpenVMS file specification has the following
    format:

    node::device:[directory]file-name.file-type;version-number

    This format reflects the DECnet node name functionality used in
    DECnet Phase IV that shipped with the OpenVMS operating system.
    For more information, see the DECnet for OpenVMS Networking
    Manual.

    On OpenVMS systems running Version 6.1 or later and DECnet-
    Plus for OpenVMS, a complete file specification can include
    expanded node designations, called full names. Full names are
    hierarchically structured DECnet-Plus for OpenVMS node names that
    can be stored in a DECdns naming service. Full names can be a
    maximum of 255 bytes long, in the following format:

    namespace:.directory ... .directory.node-name

    In this syntax statement, namespace identifies the global naming
    service, directory ... .directory defines the hierarchical
    directory path within the naming service, and node-name is the
    specific object defining the DECnet node.

    For information on full names and suggestions for setting up a
    system of names, see the VSI OpenVMS System Manager's Manual. For
    information on DECnet-Plus for OpenVMS, see the DECnet-Plus for
    OpenVMS Introduction and User's Guide.

    If the full file specification of a source file exceeds 255
    characters, the debugger cannot locate the file. You can work
    around this problem by first defining a logical name "X" (at DCL
    level) to expand to your long file specification, and then using
    the SET SOURCE X command.

    A SET SOURCE command with neither the /DISPLAY nor the /EDIT
    qualifier changes both the display and edit search directories.

    When compiling a program with the /DEBUG qualifier, if you use
    a rooted-directory logical name to specify the location of the
    source file, make sure that it is a concealed rooted-directory
    logical name. If it is not concealed and you move the source file
    to another directory after compilation, you cannot then use the
    debugger SET SOURCE command to specify the new location of the
    source file.

    To create a concealed rooted-directory logical name, use the DCL
    command DEFINE with the /TRANSLATION_ATTR=CONCEALED qualifier.

20.4  –  Description, Continued...

    Specifying the Directory Search Method

    When you issue a SET SOURCE command, be aware that one of the
    two qualifiers -/LATEST or /EXACT-will always be active. These
    qualifiers affect the debugger search method. The /LATEST
    qualifier directs the debugger to search for the version last
    created (the highest-numbered version in your directory). The
    /EXACT qualifier directs the debugger to search for the version
    last compiled (the version recorded in the debugger symbol table
    created at compile time). For example, a SET SOURCE/LATEST
    command might search for SORT.FOR;3 while a SET SOURCE/EXACT
    command might search for SORT.FOR;1.

    If the debugger locates this version using the directory search
    list, it checks that the creation or revision date and time,
    file size, record format, and file organization are the same as
    the original compile-time source file. If these characteristics
    match, the debugger concludes that the original source file has
    been located in its new directory.

    If the debugger cannot locate this version using the directory
    search list, it identifies the file that has the closest revision
    date and time (if such a file exists in that directory) and
    issues a NOTORIGSRC message ("original version of source file
    not found") when first displaying the source code.

    Specifying the /EDIT Qualifier

    The /EDIT qualifier is needed when the files used for the display
    of source code are different from the files to be edited by
    using the EDIT command. This is the case with Ada programs. For
    Ada programs, the (SET, SHOW, CANCEL) SOURCE commands affect
    the search of files used for source display (the "copied"
    source files in Ada program libraries); the (SET,SHOW,CANCEL)
    SOURCE/EDIT commands affect the search of the source files you
    edit when using the EDIT command. If you use /MODULE with /EDIT,
    the effect of /EDIT is further qualified by /MODULE.

    For information specific to Ada programs, see the
    Language_Support Ada help topic.

    Specifying the /ORIGINAL Qualifier

    Before you can use the /ORIGINAL qualifier in a SET SOURCE
    command, the Correlation Facility (a separate layered product)
    must be installed on your system. Refer to Correlation Facility
    documentation for information on creating a correlation library
    before debugging.

    Then, invoke the kept debugger and issue the SET SOURCE/ORIGINAL
    command as follows:

    $   DEBUG/KEEP
    DBG> SET SOURCE/ORIGINAL
    DBG> RUN filename.EXE

    After issuing these commands, you can debug STDL source code in
    the same way you debug any other supported language program.

    Related commands:

       (SHOW,CANCEL) SOURCE

20.5  –  Examples

    1.DBG> SHOW SOURCE
        no directory search list in effect
      DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC]
      DBG> SHOW SOURCE
          source directory list for all modules,
          match the latest source file version:
              [PROJA]
              [PROJB]
              [PETER.PROJC]

      In this example, the SET SOURCE command specifies that the
      debugger should search directories [PROJA], [PROJB], and
      [PETER.PROJC], in that order, for the latest version of source
      files.

    2.DBG> SET SOURCE /EXACT
      DBG> SHOW SOURCE
          no directory search list in effect,
           match the exact source file
      DBG> SET SOURCE [JONES]
      DBG> SHOW SOURCE
          source directory list for all modules,
           match the exact source file version:
               [JONES]
      DBG> CANCEL SOURCE /EXACT
      DBG> SHOW SOURCE
           source directory list for all modules,
           match the latest source file version:
               [JONES]

      In this example, the SET SOURCE/EXACT command establishes a
      search method (exact version) that remains in effect for the
      SET SOURCE [JONES] command. The CANCEL SOURCE/EXACT command not
      only cancels SET SOURCE/EXACT command, but also affects the SET
      SOURCE [JONES] command.

21  –  STEP

    Establishes default qualifiers (/LINE, /INTO, and so on) for the
    STEP command.

    Format

      SET STEP  step-default[, . . . ]

21.1  –  Parameters

 BRANCH

    Subsequent STEP commands are treated as STEP/BRANCH (step to the
    next branch instruction).

 CALL

    Subsequent STEP commands are treated as STEP/CALL (step to the
    next call instruction).

 EXCEPTION

    Subsequent STEP commands are treated as STEP/EXCEPTION (step to
    the next exception).

 INSTRUCTION

    Subsequent STEP commands are treated as STEP/INSTRUCTION (step to
    the next instruction).

    On VAX processors, you can also specify one or more instructions
    (opcode[, . . . ]). The debugger then steps to the next
    instruction in the specified list.

    On VAX processors, if you specify a vector instruction, do not
    include an instruction qualifier (/UNALIGNED_DATA, /MODIFY, /0,
    or /1)) with the instruction mnemonic.

 INTO

    Subsequent STEP commands are treated as STEP/INTO (step into
    called routines) rather than STEP/OVER (step over called
    routines). When INTO is in effect, you can qualify the types
    of routines to step into by using the [NO]JSB, [NO]SHARE,
    and [NO]SYSTEM parameters, or by using the STEP/[NO]JSB,
    STEP/[NO]SHARE, and STEP/[NO]SYSTEM command/qualifier
    combinations (the latter three take effect only for the immediate
    STEP command).

 LINE

    (Default) Subsequent STEP commands are treated as STEP/LINE (step
    to the next line).

 OVER

    (Default) Subsequent STEP commands are treated as STEP/OVER (step
    over all called routines) rather than STEP/INTO (step into called
    routines).

 RETURN

    Subsequent STEP commands are treated as STEP/RETURN (step to the
    return instruction of the routine that is currently executing-
    that is, up to the point just prior to transferring control back
    to the calling routine).

 SEMANTIC_EVENT

    (Alpha only) Subsequent STEP commands are treated as
    STEP/SEMANTIC_EVENT (step to the next semantic event).

 SHARE

    (Default) If INTO is in effect, subsequent STEP commands
    are treated as STEP/INTO/SHARE (step into called routines in
    shareable images as well as into other called routines).

 NOSHARE

    If INTO is in effect, subsequent STEP commands are treated as
    STEP/INTO/NOSHARE (step over called routines in shareable images,
    but step into other routines).

 SILENT

    Subsequent STEP commands are treated as STEP/SILENT (after a
    step, do not display the "stepped to . . . " message or the source
    line for the current location).

 NOSILENT

    (Default) Subsequent STEP commands are treated as STEP/NOSILENT
    (after a step, display the "stepped to . . . " message).

 SOURCE

    (Default) Subsequent STEP commands are treated as STEP/SOURCE
    (after a step, display the source line for the current location).
    Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands
    are treated as SET BREAK/SOURCE, SET TRACE/SOURCE, and SET
    WATCH/SOURCE, respectively (at a breakpoint, tracepoint, or
    watchpoint, display the source line for the current location).

 NOSOURCE

    Subsequent STEP commands are treated as STEP/NOSOURCE (after a
    step, do not display the source line for the current location).
    Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands
    are treated as SET BREAK/NOSOURCE, SET TRACE/NOSOURCE, and
    SET WATCH/NOSOURCE, respectively (at a breakpoint, tracepoint,
    or watchpoint, do not display the source line for the current
    location).

 SYSTEM

    (Default) If INTO is in effect, subsequent STEP commands are
    treated as STEP/INTO/SYSTEM (step into called routines in system
    space (P1 space) as well as into other called routines).

 NOSYSTEM

    If INTO is in effect, subsequent STEP commands are treated as
    STEP/INTO/NOSYSTEM (step over called routines in system space,
    but step into other routines).

21.2  –  Description

    The SET STEP command establishes default qualifiers for
    subsequent STEP commands. The parameters that you specify in
    the SET STEP command have the same names as the qualifiers for
    the STEP command. The following parameters affect where the STEP
    command suspends execution after a step:

       BRANCH
       CALL
       EXCEPTION
       INSTRUCTION
       LINE
       RETURN
       SEMANTIC_EVENT (Alpha only)

    The following parameters affect what output is seen when a STEP
    command is executed:

       [NO]SILENT
       [NO]SOURCE

    The following parameters affect what happens at a routine call:

       INTO
       OVER
       [NO]SHARE
       [NO]SYSTEM

    You can override the current STEP defaults for the duration of a
    single STEP command by specifying other qualifiers. Use the SHOW
    STEP command to identify the current STEP defaults.

    Enabling screen mode by pressing PF1-PF3 enters the SET STEP
    NOSOURCE command as well as the SET MODE SCREEN command.
    Therefore, any display of source code in output and DO displays
    that would result from a STEP command or from a breakpoint,
    tracepoint, or watchpoint being triggered is suppressed, to
    eliminate redundancy with the source display.

    Related commands:

       SHOW STEP
       STEP

21.3  –  Examples

    1.DBG> SET STEP INSTRUCTION,NOSOURCE

      This command causes the debugger to execute the program to the
      next instruction when a STEP command is entered, and not to
      display lines of source code with each STEP command.

    2.DBG> SET STEP LINE,INTO,NOSYSTEM,NOSHARE

      This command causes the debugger to execute the program to
      the next line when a STEP command is entered, and to step into
      called routines in user space only. The debugger steps over
      routines in system space and in shareable images.

22  –  TASK

    Changes characteristics of one or more tasks of a tasking program
    (also called a multithread program).

                                   NOTE

       SET TASK and SET THREAD are synonymous commands. They
       perform identically.

    Format

      SET TASK  [task-spec[, . . . ]]

22.1  –  Parameters

 task-spec

    Specifies a task value. Use any of the following forms:

    o  When the event facility is THREADS:

       -  A task (thread) ID number as declared in the program, or a
          language expression that yields a task ID number.

       -  A task ID number (for example, 2), as indicated in a SHOW
          TASK display.

    o  When the event facility is ADA:

       -  A task (thread) name as declared in the program, or a
          language expression that yields a task value. You can use a
          path name.

       -  A task ID (for example, %TASK 2), as indicated in a SHOW
          TASK display.

    o  One of the following task built-in symbols:

       %ACTIVE_TASK    The task that runs when a GO, STEP, CALL, or
                       EXIT command executes.
       %CALLER_TASK    (Applies only to Ada programs.) When an accept
                       statement executes, the task that called the
                       entry associated with the accept statement.
       %NEXT_TASK      The task after the visible task in the
                       debugger's task list. The ordering of tasks
                       is arbitrary but consistent within a single
                       run of a program.
       %PREVIOUS_      The task previous to the visible task in the
       TASK            debugger's task list.
       %VISIBLE_TASK   The task whose call stack and register set are
                       the current context for looking up symbols,
                       register values, routine calls, breakpoints,
                       and so on.

    Do not use the asterisk (*)  wildcard character. Instead, use the
    /ALL qualifier. Do not specify a task with /ALL or /TIME_SLICE.
    If you do not specify a task or /ALL with /ABORT, /[NO]HOLD,
    /PRIORITY, or /RESTORE, the visible task is selected.

22.2  –  Qualifiers

22.2.1    /ABORT

    Marks the specified tasks for termination. Termination occurs
    at the next allowable point after a specified task resumes
    execution.

    For HP Ada tasks, the effect is identical to executing an Ada
    abort statement for the tasks specified and causes these tasks
    to be marked as abnormal. Any dependent tasks are also marked for
    termination.

    For POSIX threads threads, use the following command:

    PTHREAD tset -c thread-number

    You can get help on POSIX threads debugger commands by typing
    PTHREAD HELP.

    See the Guide to the POSIX Threads Library for more information
    about using the POSIX threads debugger.

22.2.2    /ACTIVE

    Makes the specified task the active task, which is the task that
    runs when a STEP, GO, CALL, or EXIT command executes. This causes
    a task switch to the new active task and makes that task the
    visible task. The specified task must be in either the RUNNING or
    READY state. When using /ACTIVE, you must specify one task.

    For POSIX threads programs or HP Ada on Alpha programs, use
    one of the following alternatives:

    o  For query-type actions, use the SET TASK/VISIBLE command.

    o  To gain control of execution, use a strategic placement of
       breakpoints.

    o  Use the PTHREAD tset -a thread-number command.

    You can get help on POSIX threads debugger commands by typing
    PTHREAD HELP.

    See the Guide to the POSIX Threads Library for more information
    about using the POSIX threads debugger.

22.2.3    /ALL

    Applies the SET TASK command to all tasks.

22.2.4    /HOLD

       /HOLD
       /NOHOLD (default)

    When the event facility is THREADS, use the
    PTHREAD tset -h thread-number or the PTHREAD tset -n thread-num
    command.

    Controls whether a specified task is put on hold. The /HOLD
    qualifier puts a specified task on hold.

    Putting a task on hold prevents a task from entering the RUNNING
    state. A task put on hold is allowed to make other state
    transitions; in particular, it can change from the SUSPENDED
    to the READY state.

    Putting a task on hold prevents a task from entering the RUNNING
    state. A task put on hold is allowed to make other state
    transitions; in particular, it can change from the SUSPENDED
    to the READY state.

    A task already in the RUNNING state (the active task) can
    continue to execute as long as it remains in the RUNNING state,
    even though it is put on hold. If the task leaves the RUNNING
    state for any reason (including expiration of a time slice, if
    time slicing is enabled), it will not return to the RUNNING state
    until released from the hold condition.

    You can override the hold condition and force a task into the
    RUNNING state with the SET TASK/ACTIVE command even if the task
    is on hold.

    The /NOHOLD qualifier releases a specified task from hold.

    You can get help on POSIX threads debugger commands by typing
    PTHREAD HELP.

    See the Guide to the POSIX Threads Library for more information
    about using the POSIX threads debugger.

22.2.5    /PRIORITY

       /PRIORITY=n

    When the event facility is THREADS, use the PTHREAD
    tset -s thread-number command.

    Sets the priority of a specified task to n, where n is a decimal
    integer from 0 to 15. This does not prevent the priority from
    later changing in the course of execution, for example, while
    executing an Ada rendezvous or

    Sets the priority of a specified task to n, where n is a decimal
    integer from 0 to 15. This does not prevent the priority from
    later changing in the course of execution, for example, while
    executing an Ada rendezvous or POSIX threads synchronization
    event. This qualifier does not affect a task's scheduling policy.

    You can get help on POSIX threads debugger commands by typing
    PTHREAD HELP.

    See the Guide to the POSIX Threads Library for more information
    about using the POSIX threads debugger.

22.2.6    /VISIBLE

    Makes the specified task the visible task, which is the task
    whose call stack and register set are the current context for
    looking up symbols, register values, routine calls, breakpoints,
    and so on. Commands such as EXAMINE are directed at the visible
    task. The /VISIBLE qualifier does not affect the active task.
    When using /VISIBLE, you must specify one task.

22.3  –  Description

    The SET TASK command enables you to establish the visible task
    and the active task, control the execution of tasks, and cause
    task state transitions, directly or indirectly.

    To determine the current state of a task, use the SHOW TASK
    command. The possible states are RUNNING, READY, SUSPENDED, and
    TERMINATED.

    Related commands:

       DEPOSIT/TASK
       EXAMINE/TASK
       SET BREAK/EVENT
       SET TRACE/EVENT
       (SET, SHOW) EVENT_FACILITY
       SHOW TASK|THREAD

22.4  –  Examples

    1.DBG> SET TASK/ACTIVE %TASK 3

      (Event facility = ADA) This command makes task 3 (task ID = 3)
      the active task.

    2.DBG> PTHREAD tset -a 3

      (Event facility = THREADS) This command makes task 3 (task ID =
      3) the active task.

    3.DBG> SET TASK %NEXT_TASK

      This command makes the next task in the debugger's task list
      the visible task. (The /VISIBLE qualifier is a default for the
      SET TASK command.)

    4.DBG> SET TASK/HOLD/ALL
      DBG> SET TASK/ACTIVE %TASK 1
      DBG> GO
           . . .
      DBG> SET TASK/ACTIVE %TASK 3
      DBG> STEP
           . . .

      In this example, the SET TASK/HOLD/ALL command freezes
      the state of all tasks except the active task. Then, SET
      TASK/ACTIVE is used selectively (along with the GO and STEP
      commands) to observe the behavior of one or more specified
      tasks in isolation.

23  –  TERMINAL

    Sets the terminal-screen height or width that the debugger uses
    when it formats screen and other output.

                                   NOTE

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

    Format

      SET TERMINAL

23.1  –  Qualifiers

23.1.1    /PAGE

       /PAGE:n

    Specifies that the terminal screen height should be set to n
    lines. You can use any value from 18 to 100.

23.1.2    /WIDTH

       /WIDTH:n

    Specifies that the terminal screen width should be set to n
    columns. You can use any value from 20 to 255. For a VT100-,
    VT200-, or VT300 series terminal, n is typically either 80 or
    132.

23.1.3    /WRAP

    Tells the debugger to wrap output text in predefined display
    OUT at the column specified by the /WIDTH qualifier. If you do
    not specify /WIDTH in the current command, /WRAP defaults to the
    %WIDTH setting.

23.2  –  Description

    The SET TERMINAL command enables you to define the portion of
    the screen that the debugger has available for formatting screen
    output.

    This command is useful with VT100-, VT200-, or VT300-series
    terminals, where you can set the screen width to typically 80 or
    132 columns. It is also useful with workstations, where you can
    modify the size of the terminal-emulator window that the debugger
    uses.

    You must specify at least one qualifier. You can specify all. The
    /PAGE and /WIDTH qualifiers each require a value.

    When you enter the SET TERMINAL command, all display window
    definitions are automatically adjusted to reflect the new screen
    dimensions. For example, RH1 changes dimensions proportionally to
    remain in the top right half of the screen.

    Similarly, all "dynamic" display windows are automatically
    adjusted to maintain their relative proportions. Note that
    all display windows are dynamic unless referenced with the
    DISPLAY/NODYNAMIC command. In that case, the display window
    retains its current dimensions after subsequent SET TERMINAL
    commands. However, you can use the DISPLAY command to reconfigure
    the display window (you can also use keypad-key combinations,
    such as BLUE-MINUS, to enter predefined DISPLAY commands).

    Related commands:

       DISPLAY/[NO]DYNAMIC
       EXPAND
       (SET,SHOW,CANCEL) WINDOW
       SHOW TERMINAL

23.3  –  Example

  DBG> SET TERMINAL/WIDTH:132

      This command specifies that the terminal screen width be set to
      132 columns.

24  –  THREAD

    Changes characteristics of one or more tasks of a tasking program
    (also called a multithread program).

                                   NOTE

       SET TASK and SET THREAD are synonymous commands. They
       perform identically.

    Format

      SET TASK  [task-spec[, . . . ]]

24.1  –  Parameters

 task-spec

    Specifies a task value. Use any of the following forms:

    o  When the event facility is THREADS:

       -  A task (thread) ID number as declared in the program, or a
          language expression that yields a task ID number.

       -  A task ID number (for example, 2), as indicated in a SHOW
          TASK display.

    o  When the event facility is ADA:

       -  A task (thread) name as declared in the program, or a
          language expression that yields a task value. You can use a
          path name.

       -  A task ID (for example, %TASK 2), as indicated in a SHOW
          TASK display.

    o  One of the following task built-in symbols:

       %ACTIVE_TASK    The task that runs when a GO, STEP, CALL, or
                       EXIT command executes.
       %CALLER_TASK    (Applies only to Ada programs.) When an accept
                       statement executes, the task that called the
                       entry associated with the accept statement.
       %NEXT_TASK      The task after the visible task in the
                       debugger's task list. The ordering of tasks
                       is arbitrary but consistent within a single
                       run of a program.
       %PREVIOUS_      The task previous to the visible task in the
       TASK            debugger's task list.
       %VISIBLE_TASK   The task whose call stack and register set are
                       the current context for looking up symbols,
                       register values, routine calls, breakpoints,
                       and so on.

    Do not use the asterisk (*)  wildcard character. Instead, use the
    /ALL qualifier. Do not specify a task with /ALL or /TIME_SLICE.
    If you do not specify a task or /ALL with /ABORT, /[NO]HOLD,
    /PRIORITY, or /RESTORE, the visible task is selected.

24.2  –  Qualifiers

24.2.1    /ABORT

    Marks the specified tasks for termination. Termination occurs
    at the next allowable point after a specified task resumes
    execution.

    For HP Ada tasks, the effect is identical to executing an Ada
    abort statement for the tasks specified and causes these tasks
    to be marked as abnormal. Any dependent tasks are also marked for
    termination.

    For POSIX threads threads, use the following command:

    PTHREAD tset -c thread-number

    You can get help on POSIX threads debugger commands by typing
    PTHREAD HELP.

    See the Guide to the POSIX Threads Library for more information
    about using the POSIX threads debugger.

24.2.2    /ACTIVE

    Makes the specified task the active task, which is the task that
    runs when a STEP, GO, CALL, or EXIT command executes. This causes
    a task switch to the new active task and makes that task the
    visible task. The specified task must be in either the RUNNING or
    READY state. When using /ACTIVE, you must specify one task.

    For POSIX threads programs or HP Ada on Alpha programs, use
    one of the following alternatives:

    o  For query-type actions, use the SET TASK/VISIBLE command.

    o  To gain control of execution, use a strategic placement of
       breakpoints.

    o  Use the PTHREAD tset -a thread-number command.

    You can get help on POSIX threads debugger commands by typing
    PTHREAD HELP.

    See the Guide to the POSIX Threads Library for more information
    about using the POSIX threads debugger.

24.2.3    /ALL

    Applies the SET TASK command to all tasks.

24.2.4    /HOLD

       /HOLD
       /NOHOLD (default)

    When the event facility is THREADS, use the
    PTHREAD tset -h thread-number or the PTHREAD tset -n thread-num
    command.

    Controls whether a specified task is put on hold. The /HOLD
    qualifier puts a specified task on hold.

    Putting a task on hold prevents a task from entering the RUNNING
    state. A task put on hold is allowed to make other state
    transitions; in particular, it can change from the SUSPENDED
    to the READY state.

    Putting a task on hold prevents a task from entering the RUNNING
    state. A task put on hold is allowed to make other state
    transitions; in particular, it can change from the SUSPENDED
    to the READY state.

    A task already in the RUNNING state (the active task) can
    continue to execute as long as it remains in the RUNNING state,
    even though it is put on hold. If the task leaves the RUNNING
    state for any reason (including expiration of a time slice, if
    time slicing is enabled), it will not return to the RUNNING state
    until released from the hold condition.

    You can override the hold condition and force a task into the
    RUNNING state with the SET TASK/ACTIVE command even if the task
    is on hold.

    The /NOHOLD qualifier releases a specified task from hold.

    You can get help on POSIX threads debugger commands by typing
    PTHREAD HELP.

    See the Guide to the POSIX Threads Library for more information
    about using the POSIX threads debugger.

24.2.5    /PRIORITY

       /PRIORITY=n

    When the event facility is THREADS, use the PTHREAD
    tset -s thread-number command.

    Sets the priority of a specified task to n, where n is a decimal
    integer from 0 to 15. This does not prevent the priority from
    later changing in the course of execution, for example, while
    executing an Ada rendezvous or

    Sets the priority of a specified task to n, where n is a decimal
    integer from 0 to 15. This does not prevent the priority from
    later changing in the course of execution, for example, while
    executing an Ada rendezvous or POSIX threads synchronization
    event. This qualifier does not affect a task's scheduling policy.

    You can get help on POSIX threads debugger commands by typing
    PTHREAD HELP.

    See the Guide to the POSIX Threads Library for more information
    about using the POSIX threads debugger.

24.2.6    /VISIBLE

    Makes the specified task the visible task, which is the task
    whose call stack and register set are the current context for
    looking up symbols, register values, routine calls, breakpoints,
    and so on. Commands such as EXAMINE are directed at the visible
    task. The /VISIBLE qualifier does not affect the active task.
    When using /VISIBLE, you must specify one task.

24.3  –  Description

    The SET TASK command enables you to establish the visible task
    and the active task, control the execution of tasks, and cause
    task state transitions, directly or indirectly.

    To determine the current state of a task, use the SHOW TASK
    command. The possible states are RUNNING, READY, SUSPENDED, and
    TERMINATED.

    Related commands:

       DEPOSIT/TASK
       EXAMINE/TASK
       SET BREAK/EVENT
       SET TRACE/EVENT
       (SET, SHOW) EVENT_FACILITY
       SHOW TASK|THREAD

24.4  –  Examples

    1.DBG> SET TASK/ACTIVE %TASK 3

      (Event facility = ADA) This command makes task 3 (task ID = 3)
      the active task.

    2.DBG> PTHREAD tset -a 3

      (Event facility = THREADS) This command makes task 3 (task ID =
      3) the active task.

    3.DBG> SET TASK %NEXT_TASK

      This command makes the next task in the debugger's task list
      the visible task. (The /VISIBLE qualifier is a default for the
      SET TASK command.)

    4.DBG> SET TASK/HOLD/ALL
      DBG> SET TASK/ACTIVE %TASK 1
      DBG> GO
           . . .
      DBG> SET TASK/ACTIVE %TASK 3
      DBG> STEP
           . . .

      In this example, the SET TASK/HOLD/ALL command freezes
      the state of all tasks except the active task. Then, SET
      TASK/ACTIVE is used selectively (along with the GO and STEP
      commands) to observe the behavior of one or more specified
      tasks in isolation.

25  –  TRACE

    Establishes a tracepoint at the location denoted by an address
    expression, at instructions of a particular class, or at the
    occurrence of specified events.

    Format

      SET TRACE  [address-expression[, . . . ]]

                 [WHEN(conditional-expression)]

                 [DO(command[; . . . ])]

25.1  –  Parameters

 address-expression

    Specifies an address expression (a program location) at which
    a tracepoint is to be set. With high-level languages, this
    is typically a line number, a routine name, or a label, and
    can include a path name to specify the entity uniquely. More
    generally, an address expression can also be a memory address or
    a register and can be composed of numbers (offsets) and symbols,
    as well as one or more operators, operands, or delimiters. For
    information about the operators that you can use in address
    expressions, type Help Address_Expressions.

    Do not specify the asterisk (*)  wildcard character. Do not
    specify an address expression with the following qualifiers:

       /ACTIVATING
       /BRANCH
       /CALL
       /EXCEPTION
       /INSTRUCTION
       /INTO
       /LINE
       /OVER
       /[NO]SHARE
       /[NO]SYSTEM
       /TERMINATING

    The /MODIFY and /RETURN qualifiers are used with specific kinds
    of address expressions.

    If you specify a memory address or an address expression whose
    value is not a symbolic location, check (with the EXAMINE
    command) that an instruction actually begins at the byte of
    memory so indicated. If an instruction does not begin at this
    byte, a run-time error can occur when an instruction including
    that byte is executed. When you set a tracepoint by specifying
    an address expression whose value is not a symbolic location, the
    debugger does not verify that the location specified marks the
    beginning of an instruction.

 conditional-expression

    Specifies a conditional expression in the currently set
    language that is to be evaluated whenever execution reaches the
    tracepoint. (The debugger checks the syntax of the expressions in
    the WHEN clause when execution reaches the tracepoint, not when
    the tracepoint is set.) If the expression is true, the debugger
    reports that a tracepoint has been triggered. If an action (DO
    clause) is associated with the tracepoint, it will occur at this
    time. If the expression is false, a report is not issued, the
    commands specified by the DO clause (if one was specified) are
    not executed, and program execution is continued.

 command

    Specifies a debugger command to be executed as part of the DO
    clause when trace action is taken. The debugger checks the syntax
    of the commands in a DO clause when it executes the DO clause,
    not when the tracepoint is set.

25.2  –  Qualifiers

25.2.1    /ACTIVATING

    Causes the debugger to trace when a new process comes under
    debugger control. See also the /TERMINATING qualifier.

25.2.2    /AFTER

       /AFTER:n

    Specifies that trace action not be taken until the nth time the
    designated tracepoint is encountered (n is a decimal integer).
    Thereafter, the tracepoint occurs every time it is encountered
    provided that conditions in the WHEN clause (if specified) are
    true. The SET TRACE/AFTER:1 command has the same effect as SET
    TRACE.

25.2.3    /BRANCH

    Causes the debugger to trace every branch instruction encountered
    during program execution. See also the /INTO and /OVER
    qualifiers.

25.2.4    /CALL

    Causes the debugger to trace every call instruction encountered
    during program execution, including the return instruction. See
    also the /INTO and /OVER qualifiers.

25.2.5    /EVENT

       /EVENT=event-name

    Causes the debugger to trace the specified event (if that event
    is defined and detected by the current event facility). If you
    specify an address expression with /EVENT, causes the debugger
    to trace whenever the specified event occurs for that address
    expression. You cannot specify an address expression with certain
    event names.

    Event facilities are available for programs that call Ada or
    SCAN routines or that use POSIX threads services. To identify the
    current event facility and the associated event names, use the
    SHOW EVENT_FACILITY command.

25.2.6    /EXCEPTION

    Causes the debugger to trace every exception that is signaled.
    The trace action occurs before any application-declared exception
    handlers are invoked.

    As a result of a SET TRACE/EXCEPTION command, whenever your
    program generates an exception, the debugger reports the
    exception and resignals the exception, thus allowing any
    application-declared exception handler to execute.

25.2.7    /INSTRUCTION

    When you do not specify an opcode, causes the debugger to trace
    every instruction encountered during program execution.

    See also the /INTO and /OVER qualifiers.

25.2.8    /INTO

    (Default) Applies only to tracepoints set with the following
    qualifiers (that is, when an address expression is not explicitly
    specified):

       /BRANCH
       /CALL
       /INSTRUCTION
       /LINE

    When used with those qualifiers, /INTO causes the debugger to
    trace the specified points within called routines (as well as
    within the routine in which execution is currently suspended).
    The /INTO qualifier is the default and is the opposite of /OVER.

    When using /INTO, you can further qualify the trace action with
    the /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers.

25.2.9    /LINE

    Causes the debugger to trace the beginning of each source line
    encountered during program execution. See also the /INTO and
    /OVER qualifiers.

25.2.10    /MODIFY

    Causes the debugger to trace when an instruction writes to and
    changes the value of a location indicated by a specified address
    expression. The address expression is typically a variable name.

    The SET TRACE/MODIFY X command is equivalent to SET WATCH X
    DO(GO). The SET TRACE/MODIFY command operates under the same
    restrictions as SET WATCH.

    If you specify an absolute address for the address expression,
    the debugger might not be able to associate the address with
    a particular data object. In this case, the debugger uses a
    default length of 4 bytes. You can change this length, however,
    by setting the type to either WORD (SET TYPE WORD, which changes
    the default length to 2 bytes) or BYTE (SET TYPE BYTE, which
    changes the default length to 1 byte). The SET TYPE LONGWORD
    command restores the default length of 4 bytes.

25.2.11    /OVER

    Applies only to tracepoints set with the following qualifiers
    (that is, when an address expression is not explicitly
    specified):

       /BRANCH
       /CALL
       /INSTRUCTION
       /LINE

    When used with those qualifiers, /OVER causes the debugger to
    trace the specified points only within the routine in which
    execution is currently suspended (not within called routines).
    The /OVER qualifier is the opposite of /INTO (which is the
    default).

25.2.12    /RETURN

    Causes the debugger to break on the return instruction of the
    routine associated with the specified address expression (which
    can be a routine name, line number, and so on). Breaking on the
    return instruction enables you to inspect the local environment
    (for example, obtain the values of local variables) while
    the routine is still active. Note that the view of a local
    environment may differ depending on your architecture. On Alpha
    processors, this qualifier can be applied to any routine.

    The address-expression parameter is an instruction address within
    a routine. It can simply be a routine name, in which case it
    specifies the routine start address. However, you can also
    specify another location in a routine, so you can see only those
    returns that are taken after a certain code path is followed.

    A SET TRACE/RETURN command cancels a previous SET TRACE if you
    specify the same address expression.

25.2.13    /SHARE

       /SHARE (default)
       /NOSHARE

    Qualifies /INTO. Use with /INTO and one of the following
    qualifiers:

       /BRANCH
       /CALL
       /INSTRUCTION
       /LINE

    The /SHARE qualifier permits the debugger to set tracepoints
    within shareable image routines as well as other routines. The
    /NOSHARE qualifier specifies that tracepoints not be set within
    shareable images.

25.2.14    /SILENT

       /SILENT
       /NOSILENT (default)

    Controls whether the "trace . . . " message and the source line
    for the current location are displayed at the tracepoint. The
    /NOSILENT qualifier specifies that the message is displayed. The
    /SILENT qualifier specifies that the message and source line are
    not displayed. The /SILENT qualifier overrides /SOURCE.

25.2.15    /SOURCE

       /SOURCE
       /NOSOURCE (default)

    Controls whether the source line for the current location is
    displayed at the tracepoint. The /SOURCE qualifier specifies that
    the source line is displayed. The /NOSOURCE qualifier specifies
    that the source line is not displayed. The /SILENT qualifier
    overrides /SOURCE. See also the SET STEP [NO]SOURCE command.

25.2.16    /SYSTEM

       /SYSTEM (default)
       /NOSYSTEM

    Qualifies /INTO. Use with /INTO and one of the following
    qualifiers:

       /BRANCH
       /CALL
       /INSTRUCTION
       /LINE

    The /SYSTEM qualifier permits the debugger to set tracepoints
    within system routines (P1 space) as well as other routines. The
    /NOSYSTEM qualifier specifies that tracepoints not be set within
    system routines.

25.2.17    /TEMPORARY

    Causes the tracepoint to disappear after it is triggered (the
    tracepoint does not remain permanently set).

25.2.18    /TERMINATING

    (Default) Causes the debugger to trace when a process does an
    image exit. The debugger gains control and displays its prompt
    when the last image of a one-process or multiprocess program
    exits. See also the /ACTIVATING qualifier.

25.3  –  Description

    When a tracepoint is triggered, the debugger takes the following
    actions:

    1. Suspends program execution at the tracepoint location.

    2. If you specified /AFTER when you set the tracepoint, checks
       the AFTER count. If the specified number of counts has not
       been reached, execution is resumed and the debugger does not
       perform the remaining steps.

    3. Evaluates the expression in a WHEN clause, if you specified
       one when you set the tracepoint. If the value of the
       expression is false, execution is resumed and the debugger
       does not perform the remaining steps.

    4. Reports that execution has reached the tracepoint location by
       issuing a "trace . . . " message, unless you specified /SILENT.

    5. Displays the line of source code corresponding to the
       tracepoint, unless you specified /NOSOURCE or /SILENT when
       you set the tracepoint or entered a previous SET STEP NOSOURCE
       command.

    6. Executes the commands in a DO clause, if you specified one
       when you set the tracepoint.

    7. Resumes execution.

    You set a tracepoint at a particular location in your program
    by specifying an address expression with the SET TRACE command.
    You set a tracepoint on consecutive source lines, classes of
    instructions, or events by specifying a qualifier with the SET
    TRACE command. Generally, you must specify either an address
    expression or a qualifier, but not both. Exceptions are /EVENT
    and /RETURN.

    The /LINE qualifier sets a tracepoint on each line of source
    code.

    The following qualifiers set tracepoints on classes of
    instructions. Using these qualifiers and /LINE causes the
    debugger to trace every instruction of your program as it
    executes and thus significantly slows down execution.

       /BRANCH
       /CALL
       /INSTRUCTION
       /RETURN
       /SYSEMULATE (Alpha only)

    The following qualifiers set tracepoints on classes of events:

       /ACTIVATING
       /EVENT=event-name
       /EXCEPTION
       /TERMINATING

25.4  –  Description (Continued...)

    The following qualifiers affect what happens at a routine call:

       /INTO
       /OVER
       /[NO]SHARE
       /[NO]SYSTEM

 The following qualifiers affect what output is displayed when a
 tracepoint is reached:

       /[NO]SILENT
       /[NO]SOURCE

    The following qualifiers affect the timing and duration of
    tracepoints:

       /AFTER:n
       /TEMPORARY

    Use the /MODIFY qualifier to monitor changes at program locations
    (typically changes in the values of variables).

    If you set a tracepoint at a location currently used as
    a breakpoint, the breakpoint is canceled in favor of the
    tracepoint, and conversely.

    Tracepoints can be user defined or predefined. User-defined
    tracepoints are set explicitly with the SET TRACE command.
    Predefined tracepoints, which depend on the type of program you
    are debugging (for example, Ada or multiprocess), are established
    automatically when you start the debugger. Use the SHOW TRACE
    command to identify all tracepoints that are currently set. Any
    predefined tracepoints are identified as such.

    User-defined and predefined tracepoints are set and canceled
    independently. For example, a location or event can have both
    a user-defined and a predefined tracepoint. Canceling the user-
    defined tracepoint does not affect the predefined tracepoint, and
    conversely.

    Related commands:

       (ACTIVATE,DEACTIVATE,SHOW,CANCEL) TRACE
       CANCEL ALL
       GO
       SET BREAK
       (SET,SHOW) EVENT_FACILITY
       SET STEP [NO]SOURCE
       SET WATCH

25.5  –  Examples

    1.DBG> SET TRACE SUB3

      This command causes the debugger to trace the beginning of
      routine SUB3 when that routine is executed.

    2.DBG> SET TRACE/BRANCH/CALL

      This command causes the debugger to trace every BRANCH
      instruction and every CALL instruction encountered during
      program execution.

    3.DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM

      This command causes the debugger to trace the beginning of
      every source line, including lines in called routines (/INTO)
      but not in shareable image routines (/NOSHARE) or system
      routines (/NOSYSTEM).

    4.DBG> SET TRACE/NOSOURCE TEST5\%LINE 14 WHEN (X .NE. 2) DO (EXAMINE Y)

      This command causes the debugger to trace line 14 of module
      TEST5 when X is not equal to 2. At the tracepoint, the EXAMINE
      Y command is issued. The /NOSOURCE qualifier suppresses the
      display of source code at the tracepoint. The syntax of
      the conditional expression in the WHEN clause is language-
      dependent.

    5.DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0)

      This command causes the debugger to trace when X is not equal
      to 0. The condition is tested at each instruction encountered
      during execution. The syntax of the conditional expression in
      the WHEN clause is language-dependent.

    6.DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)

      This command causes the debugger to trace the beginning of
      routine SUB2 during execution. At the tracepoint, the DO
      clause sets a watchpoint on variable K. The /SILENT qualifier
      suppresses the "trace . . . " message and the display of source
      code at the tracepoint. This example shows a convenient way
      of setting a watchpoint on a nonstatic (stack or register)
      variable. A nonstatic variable is defined only when its
      defining routine (SUB2, in this case) is active (on the call
      stack).

    7.DBG> SET TRACE/RETURN ROUT4 DO (EXAMINE X)

      This command causes the debugger to trace the return
      instruction of routine ROUT4 (that is, just before execution
      returns to the calling routine). At the tracepoint, the DO
      clause issues the EXAMINE X command. This example shows a
      convenient way of obtaining the value of a nonstatic variable
      just before execution leaves that variable's defining routine.

    8.DBG> SET TRACE/EVENT=TERMINATED

      This command causes the debugger to trace the point at which
      any task makes a transition to the TERMINATED state.

26  –  TYPE

    Establishes the default type to be associated with program
    locations that do not have a symbolic name (and, therefore, do
    not have an associated compiler-generated type). When used with
    /OVERRIDE, it establishes the default type to be associated with
    all locations, overriding any compiler-generated types.

    Format

      SET TYPE  type-keyword

26.1  –  Parameters

 ASCIC

    Sets the default type to counted ASCII string with a 1-byte count
    field that precedes the string and gives its length. AC is also
    accepted as a keyword.

 ASCID

    Sets the default type to ASCII string descriptor. The CLASS and
    DTYPE fields of the descriptor are not checked, but the LENGTH
    and POINTER fields provide the character length and address
    of the ASCII string. The string is then displayed. AD is also
    accepted as a keyword.

 ASCII:n

    Sets the default type to ASCII character string (length n bytes).
    The length indicates both the number of bytes of memory to be
    examined and the number of ASCII characters to be displayed. If
    you do not specify a value for n, the debugger uses the default
    value of 4 bytes. The value n is interpreted in decimal radix.

 ASCIW

    Sets the default type to counted ASCII string with a 2-byte count
    field that precedes the string and gives its length. This data
    type occurs in PASCAL and PL/I. AW is also accepted as a keyword.

 ASCIZ

    Sets the default type to zero-terminated ASCII string. The ending
    zero byte indicates the end of the string. AZ is also accepted as
    a keyword.

 BYTE

    Sets the default type to byte integer (length 1 byte).

 D_FLOAT

    Sets the default type to D_floating (length 8 bytes).

 DATE_TIME

    Sets the default type to date and time. This is a quadword
    integer (length 8 bytes) containing the internal representation
    of date and time. Values are displayed in the format dd-mmm-yyyy
    hh:mm:ss.cc. Specify an absolute date and time as follows:

    [dd-mmm-yyyy[:]] [hh:mm:ss.cc]

 EXTENDED_FLOAT

    (Alpha only) Sets the default type to IEEE X_floating (length 16
    bytes).

 G_FLOAT

    Sets the default type to G_floating (length 8 bytes).

 INSTRUCTION

    Sets the default type to instruction (variable length, depending
    on the number of instruction operands and the kind of addressing
    modes used).

 LONG_FLOAT

    (Alpha only) Sets the default type to IEEE S_Floating type
    (single precision, length 4 bytes).

 LONG_LONG_FLOAT

    (Alpha only) Sets the default type to IEEE T_Floating type
    (double precision, length 8 bytes).

 LONGWORD

    Sets the default type to longword integer (length 4 bytes). This
    is the default type for program locations that do not have a
    symbolic name (do not have a compiler-generated type).

 OCTAWORD

    Sets the default type to octaword integer (length 16 bytes).

 PACKED:n

    Sets the default type to packed decimal. The value of n is the
    number of decimal digits. Each digit occupies one nibble (4
    bits).

 QUADWORD

    Sets the default type to quadword integer (length 8 bytes).

 TYPE=expression

    Sets the default type to the type denoted by expression (the name
    of a variable or data type declared in the program). This enables
    you to specify an application-declared type.

 S_FLOAT

    (Alpha only) Sets the default type to IEEE S_Floating type
    (single precision, length 4 bytes).

 T_FLOAT

    On Alpha systems, sets the default type to IEEE T_Floating type
    (double precision, length 8 bytes).

 X_FLOAT

    On Alpha systems, sets the default type to IEEE X_floating type
    (length 16 bytes).

 WORD

    Sets the default type to word integer (length 2 bytes).

26.2  –  Qualifiers

26.2.1    /OVERRIDE

    Associates the type specified with all program locations, whether
    or not they have a symbolic name (whether or not they have an
    associated compiler-generated type).

26.3  –  Description

    When you use EXAMINE, DEPOSIT, or EVALUATE commands, the default
    types associated with address expressions affect how the debugger
    interprets and displays program entities.

    The debugger recognizes the compiler-generated types associated
    with symbolic address expressions (symbolic names declared in
    your program), and it interprets and displays the contents of
    these locations accordingly. For program locations that do not
    have a symbolic name and, therefore, no associated compiler-
    generated type, the default type in all languages is longword
    integer, which is appropriate for debugging 32-bit applications.

    The default data type for untyped storage locations has been
    changed from longword (32 bits) to quadword (64 bits).

    On Alpha systems, when debugging applications that use the 64-bit
    address space, you should use the SET TYPE QUADWORD command.

    The SET TYPE command enables you to change the default type
    associated with locations that do not have a symbolic name.
    The SET TYPE/OVERRIDE command enables you to set a default type
    for all program locations, both those that do and do not have a
    symbolic name.

    The EXAMINE and DEPOSIT commands have type qualifiers (/ASCII,
    /BYTE, /G_FLOAT, and so on) which enable you to override, for the
    duration of a single command, the type previously associated with
    any program location.

    Related commands:

       CANCEL TYPE/OVERRIDE
       DEPOSIT
       EXAMINE
       (SET,SHOW,CANCEL) RADIX
       (SET,SHOW,CANCEL) MODE
       SHOW TYPE

26.4  –  Examples

    1.DBG> SET TYPE ASCII:8

      This command establishes an 8-byte ASCII character string as
      the default type associated with untyped program locations.

    2.DBG> SET TYPE/OVERRIDE LONGWORD

      This command establishes longword integer as the default type
      associated with both untyped program locations and program
      locations that have compiler-generated types.

    3.DBG> SET TYPE D_FLOAT

      This command establishes D_Floating as the default type
      associated with untyped program locations.

    4.DBG> SET TYPE TYPE=(S_ARRAY)

      This command establishes the type of the variable S_ARRAY as
      the default type associated with untyped program locations.

27  –  WATCH

    Establishes a watchpoint at the location denoted by an address
    expression.

    Format

      SET WATCH  address-expression[, . . . ]

                 [WHEN(conditional-expression)]

                 [DO(command[; . . . ])]

27.1  –  Parameters

 address-expression

    Specifies an address expression (a program location) at which
    a watchpoint is to be set. With high-level languages, this is
    typically the name of a program variable and can include a path
    name to uniquely specify the variable. More generally, an address
    expression can also be a memory address or a register and can
    be composed of numbers (offsets) and symbols, as well as one or
    more operators, operands, or delimiters. For information about
    the operators that you can use in address expressions, see the
    Address_Expressions online help topic.

    Do not specify the asterisk (*)  wildcard character.

 conditional-expression

    Specifies a conditional expression in the currently set language;
    the expression is to be evaluated whenever execution reaches the
    watchpoint. (The debugger checks the syntax of the expressions in
    the WHEN clause when execution reaches the watchpoint, not when
    the watchpoint is set.) If the expression is true, the debugger
    reports that a watchpoint has been triggered. If an action (DO
    clause) is associated with the watchpoint, it will occur at this
    time. If the expression is false, a report is not issued, the
    commands specified by the DO clause (if one was specified) are
    not executed, and program execution is continued.

 command

    Specifies a debugger command to be executed as part of the DO
    clause when watch action is taken. The debugger checks the syntax
    of the commands in a DO clause when it executes the DO clause,
    not when the watchpoint is set.

27.2  –  Qualifiers

27.2.1    /AFTER

       /AFTER:n

    Specifies that watch action not be taken until the nth time the
    designated watchpoint is encountered (n is a decimal integer).
    Thereafter, the watchpoint occurs every time it is encountered
    provided that conditions in the WHEN clause are true. The SET
    WATCH/AFTER:1 command has the same effect as SET WATCH.

27.2.2    /INTO

    Specifies that the debugger is to monitor a nonstatic variable
    by tracing instructions not only within the defining routine, but
    also within a routine that is called from the defining routine
    (and any other such nested calls). The SET WATCH/INTO command
    enables you to monitor nonstatic variables within called routines
    more precisely than SET WATCH/OVER; but the speed of execution
    within called routines is faster with SET WATCH/OVER.

27.2.3    /OVER

    Specifies that the debugger is to monitor a nonstatic variable
    by tracing instructions only within the defining routine, not
    within a routine that is called by the defining routine. As a
    result, the debugger executes a called routine at normal speed
    and resumes tracing instructions only when execution returns
    to the defining routine. The SET WATCH/OVER command provides
    faster execution than SET WATCH/INTO; but if a called routine
    modifies the watched variable, execution is interrupted only upon
    returning to the defining routine. When you set watchpoints on
    nonstatic variables, SET WATCH/OVER is the default.

27.2.4    /SILENT

       /SILENT
       /NOSILENT (default)

    Controls whether the "watch . . . " message and the source line
    for the current location are displayed at the watchpoint. The
    /NOSILENT qualifier specifies that the message is displayed. The
    /SILENT qualifier specifies that the message and source line are
    not displayed. The /SILENT qualifier overrides /SOURCE.

27.2.5    /SOURCE

       /SOURCE (default)
       /NOSOURCE

    Controls whether the source line for the current location is
    displayed at the watchpoint. The /SOURCE qualifier specifies that
    the source line is displayed. The /NOSOURCE qualifier specifies
    that the source line is not displayed. The /SILENT qualifier
    overrides /SOURCE. See also the SET STEP [NO]SOURCE command.

27.2.6    /STATIC

       /STATIC
       /NOSTATIC

    Enables you to override the debugger's default determination of
    whether a specified variable (watchpoint location) is static or
    nonstatic. The /STATIC qualifier specifies that the debugger
    should treat the variable as a static variable, even though
    it might be allocated in P1 space. This causes the debugger
    to monitor the location by using the faster write-protection
    method rather than by tracing every instruction. The /NOSTATIC
    qualifier specifies that the debugger should treat the variable
    as a nonstatic variable, even though it might be allocated in P0
    space, and causes the debugger to monitor the location by tracing
    every instruction. Be careful when using these qualifiers.

27.2.7    /TEMPORARY

    Causes the watchpoint to disappear after it is triggered (the
    watchpoint does not remain permanently set).

27.3  –  Description

    When an instruction causes the modification of a watchpoint
    location, the debugger takes the following actions:

    1. Suspends program execution after that instruction has
       completed execution.

    2. If you specified /AFTER when you set the watchpoint, checks
       the AFTER count. If the specified number of counts has not
       been reached, execution continues and the debugger does not
       perform the remaining steps.

    3. Evaluates the expression in a WHEN clause, if you specified
       one when you set the watchpoint. If the value of the
       expression is false, execution continues and the debugger
       does not perform the remaining steps.

    4. Reports that execution has reached the watchpoint location
       ("watch of . . . ") unless you specified /SILENT.

    5. Reports the old (unmodified) value at the watchpoint location.

    6. Reports the new (modified) value at the watchpoint location.

    7. Displays the line of source code at which execution is
       suspended, unless you specified /NOSOURCE or /SILENT when
       you set the watchpoint or entered a previous SET STEP NOSOURCE
       command.

    8. Executes the commands in a DO clause, if you specified one
       when you set the watchpoint. If the DO clause contains a GO
       command, execution continues and the debugger does not perform
       the next step.

    9. Issues the prompt.

    For high-level language programs, the address expressions you
    specify with the SET WATCH command are typically variable names.
    If you specify an absolute memory address that is associated
    with a compiler-generated type, the debugger symbolizes the
    address and uses the length in bytes associated with that type
    to determine the length in bytes of the watchpoint location. If
    you specify an absolute memory address that the debugger cannot
    associate with a compiler-generated type, the debugger watches 4
    bytes of memory (by default), beginning at the byte identified by
    the address expression. You can change this length, however, by
    setting the type to either WORD (SET TYPE WORD, which changes the
    default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes
    the default length to 1 byte). SET TYPE LONGWORD restores the
    default length of 4 bytes.

    You can set a watchpoint on a range, for example,

    SET WATCH 30000:300018

    The debugger establishes a series of longword watches that cover
    the range.

    You can set watchpoints on aggregates (that is, entire arrays
    or records). A watchpoint set on an array or record triggers
    if any element of the array or record changes. Thus, you do not
    need to set watchpoints on individual array elements or record
    components. Note, however, that you cannot set an aggregate
    watchpoint on a variant record.

    You can also set a watchpoint on a record component, on an
    individual array element, or on an array slice (a range of array
    elements). A watchpoint set on an array slice triggers if any
    element within that slice changes. When setting the watchpoint,
    follow the syntax of the current language.

27.4  –  Description, Continued...

    The following qualifiers affect what output is seen when a
    watchpoint is reached:

       /[NO]SILENT
       /[NO]SOURCE

    The following qualifiers affect the timing and duration of
    watchpoints:

       /AFTER:n
       /TEMPORARY

    The following qualifiers apply only to nonstatic variables:

       /INTO
       /OVER

    The following qualifier overrides the debugger's determination of
    whether a variable is static or nonstatic:

       /[NO]STATIC

                                   NOTE

       Related commands:

          (ACTIVATE,DEACTIVATE,SHOW,CANCEL) WATCH
          MONITOR
          SET BREAK
          SET STEP [NO]SOURCE
          SET TRACE

27.5  –  Static and Nonstatic Watchpoints

    Static and Nonstatic Watchpoints

    The technique for setting a watchpoint depends on whether the
    variable is static or nonstatic.

    A static variable is associated with the same memory address
    throughout execution of the program. You can always set a
    watchpoint on a static variable throughout execution.

    A nonstatic variable is allocated on the call stack or in a
    register and has a value only when its defining routine is active
    (on the call stack). Therefore, you can set a watchpoint on a
    nonstatic variable only when execution is currently suspended
    within the scope of the defining routine (including any routine
    called by the defining routine). The watchpoint is canceled when
    execution returns from the defining routine. With a nonstatic
    variable, the debugger traces every instruction to detect any
    changes in the value of a watched variable or location.

    Another distinction between static and nonstatic watchpoints
    is speed of execution. To watch a static variable, the debugger
    write-protects the page containing the variable. If your program
    attempts to write to that page, an access violation occurs and
    the debugger handles the exception, determining whether the
    watched variable was modified. Except when writing to that page,
    the program executes at normal speed.

    To watch a nonstatic variable, the debugger traces every
    instruction in the variable's defining routine and checks the
    value of the variable after each instruction has been executed.
    Since this significantly slows execution, the debugger issues a
    message when you set a nonstatic watchpoint.

    As explained in the next paragraphs, /[NO]STATIC, /INTO, and
    /OVER enable you to exercise some control over speed of execution
    and other factors when watching variables.

    The debugger determines whether a variable is static or nonstatic
    by checking how it is allocated. Typically, a static variable is
    in P0 space (0 to 3FFFFFFF, hexadecimal); a nonstatic variable is
    in P1 space (40000000 to 7FFFFFFF) or in a register. The debugger
    issues a warning if you try to set a watchpoint on a variable
    that is allocated in P1 space or in a register when execution is
    not currently suspended within the scope of the defining routine.

    The /[NO]STATIC qualifiers enable you to override this default
    behavior. For example, if you have allocated nonstack storage
    in P1 space, use /STATIC when setting a watchpoint on a variable
    that is allocated in that storage area. This enables the debugger
    to use the faster write-protection method of watching the
    location instead of tracing every instruction. Conversely, if,
    for example, you have allocated your own call stack in P0 space,
    use /NOSTATIC when setting a watchpoint on a variable that is
    allocated on that call stack. This enables the debugger to treat
    the watchpoint as a nonstatic watchpoint.

    You can also control the execution speed for nonstatic
    watchpoints in called routines by using /INTO and /OVER.

    On Alpha processors, both static and nonstatic watchpoints are
    available. With static watchpoints, the debugger write-protects
    the page of memory in which the watched variable is stored.
    Static watchpoints, therefore, would interfere with the system
    service itself if not for the debugger's use of system service
    interception (SSI).

    If a static watchpoint is in effect then, through system service
    interception, the debugger deactivates the static watchpoint,
    asynchronous traps (ASTs), and thread switching, just before the
    system service call. The debugger reactivates them just after
    the system service call completes, putting the watchpoint, AST
    enabling, and thread switching back to their original state
    and, finally, checking for any watchpoint hits. This behavior
    is designed to allow the system service to run as it normally
    would (that is, without write-protected pages) and to prevent
    the AST code or a different thread from potentially changing the
    watchpointed location while the watchpoint is deactivated. Be
    aware of this behavior if, for example, your application tests to
    see if ASTs are enabled.

    An active static watchpoint can cause a system service to fail,
    likely with an ACCVIO status, if the system service is not
    supported by the system service interception (SSI) vehicle (
    SYS$SSISHR on OpenVMS Alpha systems). Any system service that is
    not in SYS$PUBLIC_VECTORS is unsupported by SSI, including User
    Written System Services (UWSS) and any loadable system services,
    such as $MOUNT.

    When a static watchpoint is active, the debugger write-protects
    the page containing the variable to be watched. A system service
    call not supported by SSI can fail if it tries to write to that
    page of user memory.

    To avoid this failure, do either of the following:

    o  Deactivate the static watchpoint before the service call.
       When the call completes, check the watchpoint manually and
       reactivate it.

    o  Use nonstatic watchpoints. Note that nonstatic watchpoints can
       slow execution.

    If a watched location changes during a system service routine,
    you will be notified, as usual, that the watchpoint occurred.
    Note that, on rare occasions, stack may show one or more debugger
    frames on top of the frame or frames for your program. To work
    around this problem, enter one or more STEP/RETURN commands to
    get back to your program.

    System service interception is on by default, but on Alpha
    processors only, you can disable interception prior to a
    debugging session by issuing the following command:

    $  DEFINE SSI$AUTO_ACTIVATE OFF

    To reenable system service interception, issue one of the
    following commands:

    $  DEFINE SSI$AUTO_ACTIVATE ON
    $  DEASSIGN SSI$AUTO_ACTIVATE

27.6  –  Global Section Watchpoints

    On Alpha processors, you can set watchpoints on variables or
    arbitrary program locations in global sections. A global section
    is a region of memory that is shared among all processes of a
    multiprocess program. A watchpoint that is set on a location in
    a global section (a global section watchpoint) triggers when any
    process modifies the contents of that location.

    You set a global section watchpoint just as you would set a
    watchpoint on a static variable. However, because of the way the
    debugger monitors global section watchpoints, note the following
    point. When setting watchpoints on arrays or records, performance
    is improved if you specify individual elements rather than the
    entire structure with the SET WATCH command.

    If you set a watchpoint on a location that is not yet mapped to
    a global section, the watchpoint is treated as a conventional
    static watchpoint. When the location is subsequently mapped
    to a global section, the watchpoint is automatically treated
    as a global section watchpoint and an informational message is
    issued. The watchpoint is then visible from each process of the
    multiprocess program.

    Examples

    1.DBG> SET WATCH MAXCOUNT

    This command establishes a watchpoint on the variable MAXCOUNT.

    2.DBG> SET WATCH ARR
      DBG> GO
           . . .
      watch of SUBR\ARR at SUBR\%LINE 12+8
         old value:
          (1):         7
          (2):         12
          (3):         3
         new value:
          (1):         7
          (2):         12
          (3):         28

      break at SUBR\%LINE 14
      DBG>

    In this example, the SET WATCH command sets a watchpoint on
    the three-element integer array, ARR. Execution is then resumed
    with the GO command. The watchpoint triggers whenever any array
    element changes. In this case, the third element changed.

    3.DBG> SET WATCH ARR(3)

    This command sets a watchpoint on element 3 of array ARR (Fortran
    array syntax). The watchpoint triggers whenever element 3
    changes.

    4.DBG> SET WATCH P_ARR[3:5]

    This command sets a watchpoint on the array slice consisting
    of elements 3 to 5 of array P_ARR (Pascal array syntax). The
    watchpoint triggers whenever any of these elements change.

    5.DBG> SET WATCH P_ARR[3]:P_ARR[5]

    This command sets a separate watchpoint on each of elements 3 to
    5 of array P_ARR (Pascal array syntax). Each watchpoint triggers
    whenever its target element changes.

    6.DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)

    In this example, variable K is a nonstatic variable and is
    defined only when its defining routine, SUB2, is active (on
    the call stack). The SET TRACE command sets a tracepoint on
    SUB2. When the tracepoint is triggered during execution, the
    DO clause sets a watchpoint on K. The watchpoint is then canceled
    when execution returns from routine SUB2. The /SILENT qualifier
    suppresses the "trace . . . " message and the display of source
    code at the tracepoint.

    7.DBG> g
      %DEBUG-I-ASYNCSSWAT, possible asynchronous system service and static
      watchpoint collision break at LARGE_UNION\main\%LINE 24192+60
      DBG> sho call
      module name      routine name     line        rel PC             abs PC
      *LARGE_UNION     main             24192   00000000000003A0    00000000000303A0
      *LARGE_UNION     __main           24155   0000000000000110    0000000000030110
                                                FFFFFFFF80B90630    FFFFFFFF80B90630
      DBG> ex/sour %line 24192
      module LARGE_UNION
      24192:    sstatus = sys$getsyi (EFN$C_ENF, &sysid, 0, &syi_ile, &myiosb, 0, 0);

    In this example, an asynchronous write by SYS$QIO to its IOSB
    output parameter fails if that IOSB is being watched directly
    or even if it simply lives on the same page as an active static
    watchpoint.

    Debugger notices this problem and warns the user about potential
    collisions between static watchpoints and asynchronous system
    services.

28  –  WINDOW

    Creates a screen window definition. This command is not available
    in the VSI DECwindows Motif for OpenVMS user interface to the
    debugger.

    Format

      SET WINDOW  window-name

                  AT (start-line,line-count

                  [,start-column,column-count])

28.1  –  Parameters

 window-name

    Specifies the name of the window you are defining. If a window
    definition with that name already exists, it is canceled in favor
    of the new definition.

 start-line

    Specifies the starting line number of the window. This line
    displays the window title, or header line. The top line of the
    screen is line 1.

 line-count

    Specifies the number of text lines in the window, not counting
    the header line. The value must be at least 1. The sum of start-
    line and line-count must not exceed the current screen height.

 start-column

    Specifies the starting column number of the window. This is the
    column at which the first character of the window is displayed.
    The leftmost column of the screen is column 1.

 column-count

    Specifies the number of characters per line in the window. The
    value must be at least 1. The sum of start-column and column-
    count must not exceed the current screen width.

28.2  –  Description

    A screen window is a rectangular region on the terminal screen
    through which you can view a display. The SET WINDOW command
    establishes a window definition by associating a window name
    with a screen region. You specify the screen region in terms of a
    starting line and height (line count) and, optionally, a starting
    column and width (column count). If you do not specify the
    starting column and column count, the starting column defaults
    to column 1 and the column count defaults to the current screen
    width.

    You can specify a window region in terms of expressions that use
    the built-in symbols %PAGE and %WIDTH.

    You can use the names of any windows you have defined with the
    SET WINDOW command in a DISPLAY command to position displays on
    the screen.

    Window definitions are dynamic-that is, window dimensions expand
    and contract proportionally when a SET TERMINAL command changes
    the screen width or height.

    Related commands:

       DISPLAY
       (SHOW,CANCEL) DISPLAY
       (SET,SHOW) TERMINAL
       (SHOW,CANCEL) WINDOW

28.3  –  Examples

    1.DBG> SET WINDOW ONELINE AT (1,1)

      This command defines a window named ONELINE at the top of the
      screen. The window is one line deep and, by default, spans the
      width of the screen.

    2.DBG> SET WINDOW MIDDLE AT (9,4,30,20)

      This command defines a window named MIDDLE at the middle of the
      screen. The window is 4 lines deep starting at line 9, and 20
      columns wide starting at column 30.

    3.DBG> SET WINDOW FLEX AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)

      This command defines a window named FLEX that occupies a region
      around the middle of the screen and is defined in terms of the
      current screen height (%PAGE) and width (%WIDTH).
Close Help