Document revision date: 30 March 2001

## OpenVMS Debugger Manual

Previous | Contents | Index

## HELP

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

## IF

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

## MONITOR

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

## MOVE

> 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

#1
    DBG> MOVE/LEFT

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

#2
    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.

## PTHREAD

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

## QUIT

> 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

#1
    DBG> QUIT
    $

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

#2
    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.

Previous | Next | Contents | Index

| privacy and legal statement |
4538PRO_048.HTML