This command selects for display those tasks among the visible task and %TASK 3 that are in either the RUNNING or SUSPENDED state and have priority 7. 3 TERMINAL Identifies the current terminal screen height (page) and width being used to format output. NOTE This command is not available in the VSI DECwindows Motif for OpenVMS user interface to the debugger. Format SHOW TERMINAL 4 Description The current terminal screen height and width are the height and width last established by the SET TERMINAL command. By default, if you did not enter a SET TERMINAL command, the current height and width are the height and width known to the terminal driver, as displayed by the DCL command SHOW TERMINAL (usually 24 lines and 80 columns for VT-series terminals). Related commands: SET TERMINAL SHOW DISPLAY SHOW WINDOW 4 Example DBG> SHOW TERMINAL terminal width: 80 page: 24 wrap: 80 DBG> This command displays the current terminal screen width and height (page) as 80 columns and 24 lines, and the message wrap setting at column 80. 3 THREAD Displays information about the tasks of a multithread program (also called a tasking program). NOTE SET TASK and SET THREAD are synonymous commands. They perform identically. Format SHOW THREAD [task-spec[, . . . ]] 4 Parameters task-spec Specifies a task value. Use any of the following forms: o When the event facility is THREADS: - A task (thread) name 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 THREAD 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, 2), as indicated in a SHOW THREAD 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, /STATISTICS, or /TIME_SLICE. 4 Qualifiers /ALL Selects all existing tasks for display-namely, tasks that have been created and (in the case of Ada tasks) whose master has not yet terminated. /CALLS /CALLS[=n] Does a SHOW CALLS command for each task selected for display. This identifies the currently active routine calls (the call stack) for a task. /FULL When the event facility is THREADS, use the command. Displays additional information for each task selected for display. The additional information is provided if you use /FULL by itself or with /CALLS or /STATISTICS. 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. /HOLD /HOLD /NOHOLD (default) When the event facility is THREADS, use the PTHREAD tset -n thread-number command. Selects either tasks that are on hold, or tasks that are not on hold for display. If you do not specify a task, /HOLD selects all tasks that are on hold. If you specify a task list, /HOLD selects the tasks in the task list that are on hold. If you do not specify a task, /NOHOLD selects all tasks that are not on hold. If you specify a task list, /NOHOLD selects the tasks in the task list that are not on 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. /IMAGE Displays the image name for each active call on the call stack. Valid only with the /CALLS qualifier. /PRIORITY /PRIORITY=(n[, . . . ]) When the event facility is THREADS, use the PTHREAD tset -s thread-number command. If you do not specify a task, selects all tasks having any of the specified priorities, n, where n is a decimal integer from 0 to 15. If you specify a task list, selects the tasks in the task list that have any of the priorities specified. 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. /STATE /STATE=(state[, . . . ]) If you do not specify a task, selects all tasks that are in any of the specified states-RUNNING, READY, SUSPENDED, or TERMINATED. If you specify a task list, selects the tasks in the task list that are in any of the states specified. 4 Description A task can first appear in a SHOW THREAD display as soon as it is created. A task can no longer appear in a SHOW THREAD display if it is terminated or (in the case of an Ada tasking program) if its master is terminated. By default, the SHOW THREAD command displays one line of information for each task selected. When you specify the /IMAGE qualifier, the debugger first does a SET IMAGE command for each image that has debug information (that is, it was linked using the /DEBUG or /TRACEBACK qualifier). The debugger then displays the image name for each active call on the calls stack. The output display has been expanded and displays the image name in the first column. The debugger suppresses the share$image_name module name, because that information is provided by the /IMAGE qualifier. The SET IMAGE command lasts only for the duration of the SHOW THREAD/CALLS/IMAGE command. The debugger restores the set image state when the SHOW THREAD/CALLS/IMAGE command is complete. Related commands: DEPOSIT/TASK EXAMINE/TASK (SET, SHOW) EVENT_FACILITY SET TASK|THREAD 4 Examples 1.DBG> SHOW EVENT_FACILITY event facility is ADA . . . DBG> SHOW TASK/ALL task id pri hold state substate task object * %TASK 1 7 RUN 122624 %TASK 2 7 HOLD SUSP Accept H4.MONITOR %TASK 3 6 READY Entry call H4.CHECK_IN DBG> In this example, the SHOW EVENT_FACILITY command identifies ADA as the current event facility. The SHOW TASK/ALL command provides basic information about all the tasks that were created through Ada services and currently exist. One line is devoted to each task. The active task is marked with an asterisk (*). In this example, it is also the active task (the task that is in the RUN state). 2.DBG> SHOW TASK %ACTIVE_TASK,3,MONITOR This command selects the active task, 3, and task MONITOR for display. 3.DBG> SHOW TASK/PRIORITY=6 This command selects all tasks with priority 6 for display. 4.DBG> SHOW TASK/STATE=(RUN,SUSP) This command selects all tasks that are either running or suspended for display. 5.DBG> SHOW TASK/STATE=SUSP/NOHOLD This command selects all tasks that are both suspended and not on hold for display. 6.DBG> SHOW TASK/STATE=(RUN,SUSP)/PRIO=7 %VISIBLE_TASK, 3 This command selects for display those tasks among the visible task and %TASK 3 that are in either the RUNNING or SUSPENDED state and have priority 7. 3 TRACE Displays information about tracepoints. Format SHOW TRACE 4 Qualifiers /PREDEFINED Displays information about predefined tracepoints. /USER Displays information about user-defined tracepoints. 4 Description The SHOW TRACE command displays information about tracepoints that are currently set, including any options such as WHEN or DO clauses, /AFTER counts, and so on, and whether the tracepoints are deactivated. By default, SHOW TRACE displays information about both user- defined and predefined tracepoints (if any). This is equivalent to entering the SHOW TRACE/USER/PREDEFINED command. User-defined tracepoints are set with the SET TRACE command. Predefined tracepoints are set automatically when you start the debugger, and they depend on the type of program you are debugging. If you established a tracepoint using SET TRACE/AFTER:n, the SHOW TRACE command displays the current value of the decimal integer n, that is, the originally specified integer value minus 1 for each time the tracepoint location was reached. (The debugger decrements n each time the tracepoint location is reached until the value of n is 0, at which time the debugger takes trace action.) On Alpha systems, the SHOW TRACE command does not display individual instructions when the trace is on a particular class of instruction (as with SET TRACE/CALL or SET TRACE/RETURN). Related commands: (ACTIVATE, DEACTIVATE, SET, CANCEL) TRACE 4 Examples 1.DBG> SHOW TRACE tracepoint at routine CALC\MULT tracepoint on calls: RET RSB BSBB JSB BSBW CALLG CALLS DBG> In this VAX example, the SHOW TRACE command identifies all tracepoints that are currently set. This example indicates user-defined tracepoints that are triggered whenever execution reaches routine MULT in module CALC or one of the instructions RET, RSB, BSBB, JSB, BSBW, CALLG, or CALLS. 2.all> SHOW TRACE/PREDEFINED predefined tracepoint on program activation DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_ AT H1 SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC); SET DISP/DYN/REM/SIZE:64/PROC INST_ AT H1 INST (EXAM/INSTRUCTION .0\%PC)) predefined tracepoint on program termination all> This command identifies the predefined tracepoints that are currently set. The example shows the predefined tracepoints that are set automatically by the debugger for a multiprocess program. The tracepoint on program activation triggers whenever a new process comes under debugger control. The DO clause creates a process-specific source display named SRC_n and a process-specific instruction display named INST_n whenever a process activation tracepoint is triggered. The tracepoint on program termination triggers whenever a process does an image exit. 3 TYPE Identifies the current type for program locations that do not have a compiler-generated type or, if you specify /OVERRIDE, the current override type. Format SHOW TYPE 4 Qualifiers /OVERRIDE Identifies the current override type. 4 Description The current type for program locations that do not have a compiler-generated type is the type last established by the SET TYPE command. If you did not enter a SET TYPE command, the type for those locations is longword integer. The current override type for all program locations is the override type last established by the SET TYPE/OVERRIDE command. If you did not enter a SET TYPE/OVERRIDE command, the override type is "none". Related commands: CANCEL TYPE/OVERRIDE DEPOSIT EXAMINE (SET,SHOW,CANCEL) MODE (SET,SHOW,CANCEL) RADIX SET TYPE 4 Examples 1.DBG> SET TYPE QUADWORD DBG> SHOW TYPE type: quadword integer DBG> In this example, you set the type to quadword for locations that do not have a compiler-generated type. The SHOW TYPE command displays the current default type for those locations as quadword integer. This means that the debugger interprets and displays entities at those locations as quadword integers unless you specify otherwise (for example with a type qualifier on the EXAMINE command). 2.DBG> SHOW TYPE/OVERRIDE type/override: none DBG> This command indicates that no override type has been defined. 3 WATCH Displays information about watchpoints. Format SHOW WATCH 4 Description The SHOW WATCH command displays information about watchpoints that are currently set, including any options such as WHEN or DO clauses, /AFTER counts, and so on, and whether the watchpoints are deactivated. If you established a watchpoint using SET WATCH/AFTER:n, the SHOW WATCH command displays the current value of the decimal integer n, that is, the originally specified integer value minus 1 for each time the watchpoint location was reached. (The debugger decrements n each time the watchpoint location is reached until the value of n is 0, at which time the debugger takes watch action.) Related commands: (ACTIVATE,CANCEL,DEACTIVATE,SET) WATCH 4 Example DBG> SHOW WATCH watchpoint of MAIN\X watchpoint of SUB2\TABLE+20 DBG> This command displays two watchpoints: one at the variable X (defined in module MAIN), and the other at the location SUB2\TABLE+20 (20 bytes beyond the address denoted by the address expression TABLE). 3 WINDOW Identifies the name and screen position of predefined and user-defined screen-mode windows. NOTE This command is not available in the VSI DECwindows Motif for OpenVMS user interface to the debugger. Format SHOW WINDOW [window-name[, . . . ]] 4 Parameters windowname Specifies the name of a screen window definition. If you do not specify a name, or if you specify the asterisk (*) wildcard character by itself, all window definitions are listed. You can use the wildcard within a window name. Do not specify a window definition name with the /ALL qualifier. 4 Qualifiers /ALL Lists all window definitions. 4 Description Related commands: (SHOW,CANCEL) DISPLAY (SET,SHOW) TERMINAL (SET,CANCEL) WINDOW SHOW SELECT 4 Example DBG> SHOW WINDOW LH*,RH* window LH1 at (1,11,1,40) window LH12 at (1,23,1,40) window LH2 at (13,11,1,40) window RH1 at (1,11,42,39) window RH12 at (1,23,42,39) window RH2 at (13,11,42,39) DBG> This command displays the name and screen position of all screen window definitions whose names start with LH or RH. 2 SPAWN Creates a subprocess, enabling you to execute DCL commands without terminating a debugging session or losing your debugging context. NOTE This command is not available in the VSI DECwindows Motif for OpenVMS user interface to the debugger. Format SPAWN [DCL-command] 3 Parameters DCL-command Specifies a DCL command which is then executed in a subprocess. Control is returned to the debugging session when the DCL command terminates. If you do not specify a DCL command, a subprocess is created and you can then enter DCL commands. Either logging out of the spawned process or attaching to the parent process (with the DCL command ATTACH) returns you to your debugging session. If the DCL command contains a semicolon, you must enclose the command in quotation marks ("). Otherwise the semicolon is interpreted as a debugger command separator. To include a quotation mark in the string, enter two consecutive quotation marks (""). 3 Qualifiers /INPUT /INPUT=file-spec Specifies an input DCL command procedure containing one or more DCL commands to be executed by the spawned subprocess. The default file type is .COM. If you specify a DCL command string with the SPAWN command and an input file with /INPUT, the command string is processed before the input file. After processing of the input file is complete, the subprocess is terminated. Do not use the asterisk (*) wildcard character in the file specification. /OUTPUT /OUTPUT=file-spec Writes the output from the SPAWN operation to the specified file. The default file type is .LOG. Do not use the asterisk (*) wildcard character in the file specification. /WAIT /WAIT (default) /NOWAIT Controls whether the debugging session (the parent process) is suspended while the subprocess is running. The /WAIT qualifier (default) suspends the debugging session until the subprocess is terminated. You cannot enter debugger commands until control returns to the parent process. The /NOWAIT qualifier executes the subprocess in parallel with the debugging session. You can enter debugger commands while the subprocess is running. If you use /NOWAIT, you should specify a DCL command with the SPAWN command; the DCL command is then executed in the subprocess. A message indicates when the spawned subprocess completes. The kept debugger (that is, the debugger invoked with the DCL command DEBUG/KEEP) shares I/O channels with the parent process when it is run by a SPAWN/NOWAIT command. Therefore, in the VSI DECwindows Motif for OpenVMS user interface, you must press the Return key twice on the DECterm from which the debugger was run after the debugger version number has appeared in the command view. Optionally, you can execute the kept debugger in the following manner: $ DEFINE DBG$INPUT NL: $ SPAWN/NOWAIT RUN DEBUG/KEEP 3 Description The SPAWN command acts exactly like the DCL command SPAWN. You can edit files, compile programs, read mail, and so on without ending your debugging session or losing your current debugging context. In addition, you can spawn a DCL command SPAWN. DCL processes the second SPAWN command, including any qualifier specified with that command. Related command: ATTACH 3 Examples 1.DBG> SPAWN $ This example shows that the SPAWN command, without a parameter, creates a subprocess at DCL level. You can now enter DCL commands. Log out to return to the debugger prompt. 2.DBG> SPAWN/NOWAIT/INPUT=READ_NOTES/OUTPUT=0428NOTES This command creates a subprocess that is executed in parallel with the debugging session. This subprocess executes the DCL command procedure READ_NOTES.COM. The output from the spawned operation is written to the file 0428NOTES.LOG. 3.DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG @MYCOM This command creates a subprocess that is executed in parallel with the debugging session. This subprocess creates another subprocess to execute the DCL command procedure MYCOM.COM. The output from that operation is written to the file MYCOM.LOG. 2 START 3 HEAP_ANALYZER CLIENTS> STOP all> show process Number Name State Current PC 1 DBGK$$2727282C break SERVER main\main\%LINE 18834 2 USER1_2 interrupted 0FFFFFFFF800F7A20 * 3 USER1_3 interrupted 0FFFFFFFF800F7A20 all> This command sequence first shows all processes, then stops the processes in process set clients. The last SHOW PROCESS command shows the new process states. 2 SYMBOLIZE Converts a memory address to a symbolic representation, if possible. Format SYMBOLIZE address-expression[, . . . ] 3 Parameters address-expression Specifies an address expression to be symbolized. Do not use the asterisk (*) wildcard character. 3 Description If the address is a static address, it is symbolized as the nearest preceding symbol name, plus an offset. If the address is also a code address and a line number can be found that covers the address, the line number is included in the symbolization. If the address is a register address, the debugger displays all symbols in all set modules that are bound to that register. The full path name of each such symbol is displayed. The register name itself ("%R5", for example) is also displayed. If the address is a call stack location in the call frame of a routine in a set module, the debugger searches for all symbols in that routine whose addresses are relative to the frame pointer (FP) or the stack pointer (SP). The closest preceding symbol name plus an offset is displayed as the symbolization of the address. A symbol whose address specification is too complex is ignored. On Alpha processors, the commands SYMBOLIZE procedure-code-address and SYMBOLIZE procedure-descriptor-address both display the path name of the routine, entry point, or Ada package specified by these addresses. If the debugger cannot symbolize the address, a message is displayed. Related commands: EVALUATE/ADDRESS SET MODE [NO]LINE SET MODE [NO]SYMBOLIC (SET,SHOW) MODULE SHOW SYMBOL 3 Examples 1.DBG> SYMBOLIZE %R5 address PROG\%R5: PROG\X DBG> This example shows that the local variable X in routine PROG is located in register R5. 2.DBG> SYMBOLIZE %HEX 27C9E3 address 0027C9E3: MOD5\X DBG> This command directs the debugger to treat the integer literal 27C9E3 as a hexadecimal value and convert that address to a symbolic representation, if possible. The address converts to the symbol X in module MOD5. 2 TYPE Displays lines of source code. Format TYPE [[module-name\]line-number[:line-number] [,[module-name\]line-number[:line-number][, . . . ]]] 3 Parameters module-name Specifies the module that contains the source lines to be displayed. If you specify a module name along with the line numbers, use standard pathname notation: insert a backslash (\) between the module name and the line numbers. If you do not specify a module name, the debugger uses the current scope (as established by a previous SET SCOPE command, or the PC scope if you did not enter a SET SCOPE command) to find source lines for display. If you specify a scope search list with the SET SCOPE command, the debugger searches for source lines only in the module associated with the first named scope. line-number Specifies a compiler-generated line number (a number used to label a source language statement or statements). If you specify a single line number, the debugger displays the source code corresponding to that line number. If you specify a list of line numbers, separating each with a comma, the debugger displays the source code corresponding to each of the line numbers. If you specify a range of line numbers, separating the beginning and ending line numbers in the range with a colon (:), the debugger displays the source code corresponding to that range of line numbers. You can display all the source lines of a module by specifying a range of line numbers starting from 1 and ending at a number equal to or greater than the largest line number in the module. After displaying a single line of source code, you can display the next line of that module by entering a TYPE command without a line number (that is, by entering TYPE and then pressing the Return key). You can then display the next line and successive lines by repeating this sequence, in effect, reading through your source program one line at a time. 3 Description The TYPE command displays the lines of source code that correspond to the specified line numbers. The line numbers used by the debugger to identify lines of source code are generated by the compiler. They appear in a compiler-generated listing and in a screen-mode source display. If you specify a module name with the TYPE command, the module must be set. Use the SHOW MODULE command to determine whether a particular module is set. Then use the SET MODULE command, if necessary. In screen mode, the output of a TYPE command is directed at the current source display, not at an output or DO display. The source display shows the lines specified and any surrounding lines that fit in the display window. Related commands: EXAMINE/SOURCE SET (BREAK,TRACE,WATCH)/[NO]SOURCE SET MODE [NO]SCREEN (SET,SHOW,CANCEL) SCOPE SET STEP [NO]SOURCE STEP/[NO]SOURCE 3 Examples 1.DBG> TYPE 160 module COBOLTEST 160: START-IT-PARA. DBG> TYPE module COBOLTEST 161: MOVE SC1 TO ES0. DBG> In this example, the first TYPE command displays line 160, using the current scope to locate the module containing that line number. The second TYPE command, entered without specifying a line number, displays the next line in that module. 2.DBG> TYPE 160:163 module COBOLTEST 160: START-IT-PARA. 161: MOVE SC1 TO ES0. 162: DISPLAY ES0. 163: MOVE SC1 TO ES1. DBG> This command displays lines 160 to 163, using the current scope to locate the module. 3.DBG> TYPE SCREEN_IO\7,22:24 This command displays line 7 and lines 22 to 24 in module SCREEN_IO. 2 WAIT Causes the debugger to wait until the target processes have stopped before prompting for the next command. Format WAIT 3 Description When debugging multiprocess programs, the WAIT command causes the debugger to complete executing all process specified by the previous command before displaying a prompt to accept and execute another command. Related commands: STOP SET MODE [NO]INTERRUPT SET MODE [NO]WAIT 3 Example all> 2,3> GO;WAIT processes 2,3 break at CLIENT\main\%LINE 18814 18814: status = sys$qiow (EFN$C_ENF, mbxchan, IO$_READVBLKIO$M_WRITERCHECK, myiosb) process 1 break at SERVER\main\%LINE 18834 18834: if ((myiosb.iosb$w_status == SS$_NOREADER) && (pos_status != -1)) all> This command sequence executes the target processes (in this case, 2 and 3), and the debugger waits until both processes reach breakpoints before prompting for the next command. 2 WHILE Executes a sequence of commands while the language expression (Boolean expression) you have specified evaluates as true. Format WHILE Boolean-expression DO (command[; . . . ]) 3 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, separate the commands with semicolons (;). At each execution, the debugger checks the syntax of any expressions in the commands and then evaluates them. 3 Description The WHILE command evaluates a Boolean expression in the current language. If the value is true, the command list in the DO clause is executed. The command then repeats the sequence, reevaluating the Boolean expression and executing the command list until the expression is evaluated as false. If the Boolean expression is false, the WHILE command terminates. Related commands: EXITLOOP FOR REPEAT 3 Example DBG> WHILE (X .EQ. 0) DO (STEP/SILENT) This command directs the debugger to keep stepping through the program until X no longer equals 0 (Fortran example).