DBG$HELP.HLB  —  DEBUG  DISPLAY
    Creates a new screen display or modifies an existing display.

                                   NOTE

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

    Format

      DISPLAY  display-name [AT window-spec] [display-kind] [, . . . ]

1  –  Parameters

 display-name

    Specifies the display to be created or modified.

    If you are creating a new display, specify a name that is not
    already used as a display name.

    If you are modifying an existing display, you can specify any of
    the following entities:

    o  A predefined display:

          SRC
          OUT
          PROMPT
          INST
          REG
          FREG (Alpha and Integrity servers only)
          IREG

    o  A display previously created with the DISPLAY command

    o  A display built-in symbol:

          %CURDISP
          %CURSCROLL
          %NEXTDISP
          %NEXTINST
          %NEXTOUTPUT
          %NEXTSCROLL
          %NEXTSOURCE

    You must specify a display unless you use /GENERATE (parameter
    optional), or /REFRESH (parameter not allowed).

    You can specify more than one display, each with an optional
    window specification and display kind.

 window-spec

    Specifies the screen window at which the display is to be
    positioned. You can specify any of the following entities:

    o  A predefined window. For example, RH1 (right top half).

    o  A window definition previously established with the SET WINDOW
       command.

    o  A window specification of the form (start-line, line-count[,
       start-column, column-count]). The specification can include
       expressions which can be based on the built-in symbols %PAGE
       and %WIDTH (for example, %WIDTH/4).

    If you omit the window specification, the screen position depends
    on whether you are specifying an existing display or a new
    display:

    o  If you are specifying an existing display, the position of the
       display is not changed.

    o  If you are specifying a new display, it is positioned at
       window H1 or H2, alternating between H1 and H2 each time you
       create another display.

 display-kind

    Specifies the display kind. Valid keywords are as follows:

    DO                  Specifies an automatically updated output
    (command[; . . . ]) display. The commands are executed in the
                        order listed each time the debugger gains
                        control. Their output forms the contents of
                        the display. If you specify more than one
                        command, the commands must be separated by
                        semicolons.
    INSTRUCTION         Specifies an instruction display. If selected
                        as the current instruction display with the
                        SELECT/INSTRUCTION command, it displays the
                        output from subsequent EXAMINE/INSTRUCTION
                        commands.
    OUTPUT              Specifies an output display. If selected
                        as the current output display with the
                        SELECT/OUTPUT command, it displays any
                        debugger output that is not directed to
                        another display. If selected as the current
                        input display with the SELECT/INPUT command,
                        it echoes debugger input. If selected as the
                        current error display with the SELECT/ERROR
                        command, it displays debugger diagnostic
                        messages.
    REGISTER            Specifies an automatically updated register
                        display. The display is updated each time the
                        debugger gains control.
    SOURCE              Specifies a source display. If selected
                        as the current source display with the
                        SELECT/SOURCE command, it displays the
                        output from subsequent TYPE or EXAMINE/SOURCE
                        commands.
    SOURCE (command)    Specifies an automatically updated source
                        display. The command specified must be a
                        TYPE or EXAMINE/SOURCE command. The source
                        display is updated each time the debugger
                        gains control.

    You cannot change the display kind of the PROMPT display.

    If you omit the display-kind parameter, the display kind depends
    on whether you are specifying an existing display or a new
    display:

    o  If you specify an existing display, the display kind is not
       changed.

    o  If you specify a new display, an OUTPUT display is created.

2  –  Qualifiers

2.1    /CLEAR

    Erases the entire contents of a specified display. Do not use
    this qualifier with /GENERATE or when creating a new display.

2.2    /DYNAMIC

       /DYNAMIC (default)
       /NODYNAMIC

    Controls whether a display automatically adjusts its window
    dimensions proportionally when the screen height or width is
    changed by a SET TERMINAL command. By default (/DYNAMIC), all
    user-defined and predefined displays adjust their dimensions
    automatically.

2.3    /GENERATE

    Regenerates the contents of a specified display. Only
    automatically generated displays are regenerated. These include
    DO displays, register displays, source (cmd-list) displays, and
    instruction (cmd-list) displays. The debugger automatically
    regenerates all these kinds of displays before each prompt. If
    you do not specify a display, it regenerates the contents of all
    automatically generated displays. Do not use this qualifier with
    /CLEAR or when creating a new display.

2.4    /HIDE

    Places a specified display at the bottom of the display
    pasteboard (same as /PUSH). This hides the specified display
    behind any other displays that share the same region of the
    screen. You cannot hide the PROMPT display.

2.5    /MARK_CHANGE

       /MARK_CHANGE
       /NOMARK_CHANGE (default)

    Controls whether the lines that change in a DO display each time
    it is automatically updated are marked. Not applicable to other
    kinds of displays.

    When you use /MARK_CHANGE, any lines in which some contents
    have changed since the last time the display was updated are
    highlighted in reverse video. This qualifier is particularly
    useful when you want any variables in an automatically updated
    display to be highlighted when they change.

    The /NOMARK_CHANGE qualifier (default) specifies that any lines
    that change in DO displays are not to be marked. This qualifier
    cancels the effect of a previous /MARK_CHANGE on the specified
    display.

2.6    /POP

       /POP (default)
       /NOPOP

    Controls whether a specified display is placed at the top of the
    display pasteboard, ahead of any other displays but behind the
    PROMPT display. By default (/POP), the display is placed at the
    top of the pasteboard and hides any other displays that share the
    same region of the screen, except the PROMPT display.

    The /NOPOP qualifier preserves the order of all displays on the
    pasteboard (same as /NOPUSH).

2.7    /PROCESS

       /PROCESS[=(process-spec)]
       /NOPROCESS (default)

    Used only when debugging multiprocess programs (kept debugger
    only). Controls whether the specified display is process specific
    (that is, whether the specified display is associated only with a
    particular process). The contents of a process-specific display
    are generated and modified in the context of that process. You
    can make any display process specific, except the PROMPT display.

    The /PROCESS=(process-spec) qualifier causes the specified
    display to be associated with the specified process. You must
    include the parentheses. Use any of the following process-spec
    forms:

    [%PROCESS_NAME] proc-     The process name, if that name contains
    name                      no space or lowercase characters. The
                              process name can include the asterisk
                              (*)  wildcard character.
    [%PROCESS_NAME] "proc-    The process name, if that name contains
    name"                     space or lowercase characters. You can
                              also use apostrophes (') instead of
                              quotation marks (").
    %PROCESS_PID proc-id      The process identifier (PID, a
                              hexadecimal number).
    %PROCESS_NUMBER proc-     The number assigned to a process when
    number                    it comes under debugger control.
    (or %PROC proc-number)    Process numbers appear in a SHOW
                              PROCESS display.
    proc-group-name           A symbol defined with the
                              DEFINE/PROCESS_GROUP command to
                              represent a group of processes. Do not
                              specify a recursive symbol definition.
    %NEXT_PROCESS             The 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 call stack, register
                              set, and images are the current context
                              for looking up symbols, register
                              values, routine calls, breakpoints,
                              and so on.

    The /PROCESS qualifier causes the specified display to be
    associated with the process that was the visible process when
    the DISPLAY/PROCESS command was executed.

    The /NOPROCESS qualifier (which is the default) causes the
    specified display to be associated with the visible process,
    which might change during program execution.

    If you do not specify /PROCESS, the current process-specific
    behavior (if any) of the specified display remains unchanged.

2.8    /PUSH

       /PUSH
       /NOPUSH

    The /PUSH qualifier has the same effect as /HIDE. The /NOPUSH
    qualifier preserves the order of all displays on the pasteboard
    (same as /NOPOP).

2.9    /REFRESH

    Refreshes the terminal screen. Do not specify any command
    parameters with this qualifier. You can also use Ctrl/W to
    refresh the screen.

2.10    /REMOVE

    Marks the display as being removed from the display pasteboard,
    so it is not shown on the screen unless you explicitly request
    it with another DISPLAY command. Although a removed display is
    not visible on the screen, it still exists and its contents are
    preserved. You cannot remove the PROMPT display.

2.11    /SIZE

       /SIZE:n

    Sets the maximum size of a display to n lines. If more than n
    lines are written to the display, the oldest lines are lost as
    the new lines are added. If you omit this qualifier, the maximum
    size of the display is as follows:

    o  If you specify an existing display, the maximum size is
       unchanged.

    o  If you are creating a display, the default size is 64 lines.

    For an output or DO display, /SIZE:n specifies that the display
    should hold the n most recent lines of output. For a source or
    instruction display, n gives the number of source lines or lines
    of instructions that can be placed in the memory buffer at any
    one time. However, you can scroll a source display over the
    entire source code of the module whose code is displayed (source
    lines are paged into the buffer as needed). Similarly, you can
    scroll an instruction display over all of the instructions of
    the routine whose instructions are displayed (instructions are
    decoded from the image as needed).

3  –  Description

    You can use the DISPLAY command to create a display or to modify
    an existing display.

    To create a display, specify a name that is not already used as
    a display name (the SHOW DISPLAY command identifies all existing
    displays).

    By default, the DISPLAY command places a specified display on
    top of the display pasteboard, ahead of any other displays but
    behind the PROMPT display, which cannot be hidden. The specified
    display thus hides the portions of other displays (except the
    PROMPT display) that share the same region of the screen.

    For a list of the key definitions associated with the DISPLAY
    command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY
    command to determine the current key definitions.

    Related commands:

       Ctrl/W
       EXPAND
       MOVE
       SET PROMPT
       (SET,SHOW) TERMINAL
       (SET,SHOW,CANCEL) WINDOW
       SELECT
       (SHOW,CANCEL) DISPLAY

4  –  Examples

    1.DBG> DISPLAY REG

      This command shows the predefined register display, REG, at its
      current window location.

    2.DBG> DISPLAY/PUSH INST

      This command pushes display INST to the bottom of the display
      pasteboard, behind all other displays.

    3.DBG> DISPLAY NEWDISP AT RT2
      DBG> SELECT/INPUT NEWDISP

      In this example, the DISPLAY command shows the user-defined
      display NEWDISP at the right middle third of the screen. The
      SELECT/INPUT command selects NEWDISP as the current input
      display. NEWDISP now echoes debugger input.

    4.DBG> DISPLAY DISP2 AT RS45
      DBG> SELECT/OUTPUT DISP2

      In this example, the DISPLAY command creates a display named
      DISP2 essentially at the right bottom half of the screen, above
      the PROMPT display, which is located at S6. This is an output
      display by default. The SELECT/OUTPUT command then selects
      DISP2 as the current output display.

    5.DBG> SET WINDOW TOP AT (1,8,45,30)
      DBG> DISPLAY NEWINST AT TOP INSTRUCTION
      DBG> SELECT/INST NEWINST

      In this example, the SET WINDOW command creates a window named
      TOP starting at line 1 and column 45, and extending down for
      8 lines and to the right for 30 columns. The DISPLAY command
      creates an instruction display named NEWINST to be displayed
      through TOP. The SELECT/INST command selects NEWINST as the
      current instruction display.

    6.DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS)

      This command creates a DO display named CALLS at window Q3.
      Each time the debugger gains control from the program, the
      SHOW CALLS command is executed and the output is displayed in
      display CALLS, replacing any previous contents.

    7.DBG> DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C)

      This command creates a DO display named EXAM at window Q2.
      The display shows the current values of variables A, B, and C
      whenever the debugger prompts for input. Any changed values are
      highlighted.

    8.all> DISPLAY/PROCESS OUT_X AT S4

      This command makes display OUT_X specific to the visible
      process (process 3) and puts the display at window S4.
Close Help