HP OpenVMS Systems Documentation

Displays online help on debugger commands and selected topics.

Note This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Help on commands is available from the Help menu in a DECwindows debugger window.

Format

HELP topic [subtopic [...]]

Parameters

topic

Specifies the name of a debugger command or topic about which you want help. You can specify the asterisk (*) wildcard character, either singly or within a name.

subtopic

Specifies a subtopic, qualifier, or parameter about which you want further information. You can specify the asterisk wildcard (*), either singly or within a name.

Description

The debugger's online help facility provides the following information about any debugger command, including a description of the command, its format, explanations of any parameters that can be specified with the command, and explanations of any qualifiers that can be specified with the command.

To get information about a particular qualifier or parameter, specify it as a subtopic. If you want information about all qualifiers, specify "qualifier" as a subtopic. If you want information about all parameters, specify "parameter" as a subtopic. If you want information about all parameters, qualifiers, and any other subtopics related to a command, specify an asterisk (*) as a subtopic.

In addition to help on commands, you can get online help on various topics such as screen features, keypad mode, and so on. Topic keywords are listed along with the commands when you type HELP.

For summary information about new features with this release of the debugger, type HELP New_Features.

For help on the predefined keypad-key functions, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions.

Example

DBG> HELP GO
      

This command displays help for the GO command.

Executes a sequence of commands if a language expression (Boolean expression) is evaluated as true.

Format

IF Boolean-expression THEN (command[;...])
[ELSE (command[;...])]

Parameters

Boolean-expression

Specifies a language expression that evaluates as a Boolean value (true or false) in the currently set language.

command

Specifies a debugger command. If you specify more than one command, you must separate the commands with semicolons (;).

Description

The IF command evaluates a Boolean expression. If the value is true (as defined in the current language), the command list in the THEN clause is executed. If the expression is false, the command list in the ELSE clause (if any) is executed.

Related commands:

EXITLOOP
FOR
REPEAT
WHILE

Example

DBG> SET BREAK R DO (IF X .LT. 5 THEN (GO) ELSE (EXAMINE X))
      

This command causes the debugger to suspend program execution at location R (a breakpoint) and then resume program execution if the value of X is less than 5 (Fortran example). If the value of X is 5 or more, its value is displayed.

Displays the current value of a program variable or language expression in the monitor view of the Compaq DECwindows Motif for OpenVMS user interface.

Note Requires the Compaq DECwindows Motif for OpenVMS user interface.

Format

MONITOR expression

Parameters

expression

Specifies an entity to be monitored. With high-level languages, this is typically the name of a variable. Currently, MONITOR does not handle composite expressions (language expressions containing operators).

If you specify the name of an aggregate variable (a composite data structure such as an array or record structure), the monitor view lists "Aggregate" for the value of the variable. You can then double-click on the variable name to get the values of all the elements (see Section 10.5.4.1).

To specify an individual array element, array slice, or record component, follow the syntax of the current language.

Qualifiers

/ASCIC

/AC

Interprets each monitored entity as a counted ASCII string preceded by a 1-byte count field that gives the length of the string. The string is then displayed.

/ASCID

/AD

Interprets each monitored entity as the address of a string descriptor pointing to an ASCII string. 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.

/ASCII:n

Interprets and displays each monitored entity as an ASCII string of length n bytes (n characters). If you omit n, the debugger attempts to determine a length from the type of the address expression.

/ASCIW

/AW

Interprets each monitored entity as a counted ASCII string preceded by a 2-byte count field that gives the length of the string. The string is then displayed.

/ASCIZ

/AZ

Interprets each monitored entity as a zero-terminated ASCII string. The ending zero byte indicates the end of the string. The string is then displayed.

/BINARY

Displays each monitored entity as a binary integer.

/BYTE

Displays each monitored entity in the byte integer type (length 1 byte).

/D_FLOAT

(VAX only) Displays each monitored entity in the D_floating type (length 8 bytes).

/DATE_TIME

Interprets each monitored entity as a quadword integer (length 8 bytes) containing the internal OpenVMS representation of date and time. Displays the value in the format dd-mmm-yyyy hh:mm:ss.cc.

/DECIMAL

Displays each monitored entity as a decimal integer.

/DEFAULT

Displays each monitored entity in the default radix.

/EXTENDED_FLOAT

(Alpha only) Displays each monitored entity in the IEEE X_floating type (length 16 bytes).

/FLOAT

On VAX processors, displays each monitored entity in the F_floating type (length 4 bytes).

On Alpha processors, displays each monitored entity in the IEEE T_floating type (double precision, length 8 bytes).

/F_FLOAT

(VAX only) Displays each monitored entity in the F_floating type (length 4 bytes).

/G_FLOAT

Displays each monitored entity in the G_floating type (length 8 bytes).

/H_FLOAT

(VAX only) Displays each monitored entity in the H_floating type (length 16 bytes).

/HEXADECIMAL

Displays each monitored entity as a hexadecimal integer.

/INSTRUCTION

Displays each monitored entity as an assembly-language instruction (variable length, depending on the number of instruction operands and the kind of addressing modes used). See also the /OPERANDS qualifier.

/INT

Same as /LONGWORD qualifier.

/LONG_FLOAT

(Alpha only) Displays each monitored entity in the IEEE S_floating type (single precision, length 4 bytes).

/LONG_LONG_FLOAT

(Alpha only) Displays each monitored entity in the IEEE T_floating type (double precision, length 8 bytes).

/LONGWORD

/INT

/LONG

Displays each monitored entity in the longword integer type (length 4 bytes). This is the default type for program locations that do not have a compiler-generated type.

/OCTAL

Displays each monitored entity as an octal integer.

/OCTAWORD

Displays each monitored entity in the octaword integer type (length 16 bytes).

/QUADWORD

Displays each monitored entity in the quadword integer type (length 8 bytes).

/REMOVE

Removes a monitored item or items with the address expression specified from the Monitor View.

/SHORT

Same as /WORD qualfier.

/TASK

Applies to tasking (multithread) programs. Interprets each monitored entity as a task (thread) object and displays the task value (the name or task ID) of that task object. When monitoring a task object, use /TASK only if the programming language does not have built-in tasking services.

/WORD

/SHORT

Displays each monitored entity in the word integer type (length 2 bytes).

Description

You can use the MONITOR command only with the debugger's Compaq DECwindows Motif for OpenVMS user interface, because the output of that command is directed at the monitor view. With the command interface, you typically use the EVALUATE, EXAMINE or SET WATCH command instead.

The MONITOR command does the following:

1. Displays the monitor view (if it is not already displayed by a previous MONITOR command).
2. Puts the name of the specified variable or expression and its current value in the monitor view.

The debugger updates the monitor view whenever the debugger regains control from the program, regardless of whether the value of the variable or location you are monitoring has changed. (By contrast, a watchpoint halts execution when the value of the watched variable changes.)

For more information about the monitor view and the MONITOR command, see Section 10.5.4.

Related commands:

DEPOSIT
EVALUATE
EXAMINE
SET WATCH

Example

DBG> MONITOR COUNT
      

This command displays the name and current value of the variable COUNT in the monitor view of the debugger's Compaq DECwindows Motif for OpenVMS user interface. The value is updated whenever the debugger regains control from the program.

Moves a screen display vertically or horizontally across the screen.

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

Format

MOVE [display-name[,...]]

Parameters

display-name

Specifies a display to be moved. You can specify any of the following entities:

• A predefined display:

  SRC
  OUT
  PROMPT
  INST
  REG
  FREG (Alpha only)
  IREG

• A display previously created with the DISPLAY command
• A display built-in symbol:

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

If you do not specify a display, the current scrolling display, as established by the SELECT command, is chosen.

Qualifiers

/DOWN[:n]

Moves the display down by n lines (if n is positive) or up by n lines (if n is negative). If you omit n, the display is moved down by 1 line.

/LEFT[:n]

Moves the display to the left by n lines (if n is positive) or right by n lines (if n is negative). If you omit n, the display is moved to the left by 1 line.

/RIGHT[:n]

Moves the display to the right by n lines (if n is positive) or left by n lines (if n is negative). If you omit n, the display is moved to the right by 1 line.

/UP[:n]

Moves the display up by n lines (if n is positive) or down by n lines (if n is negative). If you omit n, the display is moved up by 1 line.

Description

You must specify at least one qualifier.

For each display specified, the MOVE command simply creates a window of the same dimensions elsewhere on the screen and maps the display to it, while maintaining the relative position of the text within the window.

The MOVE command does not change the order of a display on the display pasteboard. Depending on the relative order of displays, the MOVE command can cause the display to hide or uncover another display or be hidden by another display, partially or totally.

A display can be moved only up to the edge of the screen.

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

Related commands:

DISPLAY
EXPAND
SELECT/SCROLL
(SET,SHOW) TERMINAL

Examples

DBG> MOVE/LEFT
      

This command moves the current scrolling display to the left by 1 column.

DBG> MOVE/UP:3/RIGHT:5 NEW_OUT
      

This command moves display NEW_OUT up by 3 lines and to the right by 5 columns.

Passes a command to the POSIX Threads debugger for execution.

Note This command is valid only when the event facility is THREADS and the program is running POSIX Threads 3.13 or later.

Format

PTHREAD command

Parameters

command

A POSIX Threads debugger command.

Description

Passes a command to the POSIX Threads debugger for execution. The results appear in the command view. Once the POSIX Threads debugger command has been completed, control is returned to the OpenVMS debugger. You can get help on POSIX Threads debugger commands by typing PTHREAD HELP .

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

Related commands:

• SET EVENT FACILITY
• SET TASK|THREAD
• SHOW EVENT FACILITY
• SHOW TASK|THREAD

Example

DBG_1> PTHREAD HELP
    conditions [-afhwqrs] [-N <n>] [id]...: list condition variables
    exit: exit from DECthreads debugger
    help [topic]: display help information
    keys [-v] [-N <n>] [id]...: list keys
    mutexes [-afhilqrs] [-N <n>] [id]...: list mutexes
    quit: exit from DECthreads debugger
    show [-csuv]: show stuff
    squeue [-c <n>] [-fhq] [-t <t>] [a]: format queue
    stacks [-fs] [sp]...: list stacks
    system: show system information
    threads [-1] [-N <n>] [-abcdfhklmnor] [-s <v>] [-tz] [id]...: list threads
    tset [-chna] [-s <v>] <id>: set state of thread
    versions: display versions
    write <st>: write a string
All keywords may be abbreviated: if the abbreviation is ambiguous,
the first match will be used. For more help, type 'help <topic>'.
DBG_1>

      

This command invokes the POSIX Threads debugger help file, then returns control to the OpenVMS debugger. To get specific help on a POSIX Threads debugger Help topic, type PTHREAD HELP topic .

Ends a debugging session, or terminates one or more processes of a multiprocess program (similar to EXIT), but without allowing any application-declared exit handlers to run. If used within a command procedure or DO clause and no process is specified, it exits the command procedure or DO clause at that point.

Format

QUIT [process-spec[,...]]

Parameters

process-spec

(Kept debugger only.) Specifies a process currently under debugger control. Use any of the following forms:

[%PROCESS_NAME] process-name	The process name, if that name does not contain spaces or lowercase characters. The process name can include the asterisk (*) wildcard character.
[%PROCESS_NAME] " process-name"	The process name, if that name contains 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] process-number (or %PROC process-number)	The number assigned to a process when it comes under debugger control. A new number is assigned sequentially, 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 all processes.

Description

The QUIT command is simlar to the EXIT command, except that QUIT does not cause your program to execute and, therefore, does not execute any application-declared exit handlers in your program.

Ending a Debugging Session

To end a debugging session, enter the QUIT command at the debugger prompt without specifying any parameters. This causes orderly termination of the session: the debugger exit handler is executed (closing log files, restoring the screen and keypad states, and so on), and control is returned to DCL level. You cannot then continue to debug your program by entering the DCL command DEBUG or CONTINUE (you must restart the debugger).

Using the QUIT Command in Command Procedures and DO Clauses

When the debugger executes a QUIT command (without any parameters) in a command procedure, control returns to the command stream that invoked the command procedure. A command stream can be the terminal, an outer (containing) command procedure, or a DO clause in a command or screen display definition. For example, if the command procedure was invoked from within a DO clause, control returns to that DO clause, where the debugger executes the next command (if any remain in the command sequence).

When the debugger executes a QUIT command (without any parameters) in a DO clause, it ignores any remaining commands in that clause and displays its prompt.

Terminating Specified Processes

If you are debugging a multiprocess program, you can use the QUIT command to terminate specified processes without ending the debugging session. The same techniques and behavior apply, whether you enter the QUIT command at the prompt or use it within a command procedure or DO clause.

To terminate one or more processes, enter the QUIT command, specifying these processes as parameters. This causes orderly termination of the images in these processes without executing any application-declared exit handlers associated with these images. Subsequently, the specified processes are no longer identified in a SHOW PROCESS/ALL display.

In contrast to the EXIT command, the QUIT command does not cause any process to start execution.

Related commands:

DISCONNECT
@ (Execute Procedure)
Ctrl/C
Ctrl/Y
Ctrl/Z
EXIT
RERUN
RUN
SET ABORT_KEY
SET PROCESS

Examples

DBG> QUIT
$
      

This command ends the debugging session and returns you to DCL level.

all> QUIT %NEXT_PROCESS, JONES_3, %PROC 5
all>
      

This command causes orderly termination of three processes of a multiprocess program: the process after the visible process on the process list, process JONES_3, and process 5. Control is returned to the debugger after the specified processes have exited.