1 DEBUG The Debugger Command Dictionary contains detailed reference information about all debugger commands, organized as follows: o Command Format explains how to enter debugger commands. o Commands Disabled in DECwindows lists commands that are disabled in the command/message view of the debugger's Compaq DECwindows Motif for OpenVMS user interface. o Messages gives general information about debugger diagnostic messages. The Debugger Command Dictionary contains detailed reference information about the debugger commands. 2 New_Features For more information, see the OpenVMS Debugger Manual. This section describes the following new OpenVMS Debugger features: o New commands for examining process dumps o Multiprocess debugging o New /VARIANT qualifier to the EXAMINE command 3 New_Process_Dump_Tools_(Alpha_only) The OpenVMS Version 7.3 debugger contains new comands for processing dump files. Note that these new-style process dump and process dump analysis tools are not compatible with the old- style process dumps. That is, if you have a problem you want to analyze with the new tools, you must generate a new process dump using the new process dump image. The following subtopics describe the new tools. 4 Debugger_ANALYZE_PROCESS_DUMP_Command The debugger has a new command: ANALYZE/PROCESS_DUMP/IMAGE_PATH[=directory-spec] dumpfile. This command is available only in the kept debugger. The kept debugger is the image you invoke with the command DEBUG/KEEP, which allows you to run and rerun programs from the same debugging session. The qualifier /PROCESS_DUMP is required, and distinguishes this command from the one that invokes the System Dump Debugger (SDD), ANALYZE/CRASH_DUMP. For more information, see the OpenVMS Debugger Manual 4 Debugger_SDA_Command The new debugger SDA command invokes the System Dump Analyzer (SDA) from within the OpenVMS debugger. You can then use SDA for additional process dump analysis. For example: DBG> SDA OpenVMS (TM) Alpha process dump analyzer SDA> .. . . SDA> EXIT DBG> This allows you to use SDA for additional analysis of a system dump without terminating a debugger session. For more information, see the OpenVMS Debugger Manual 3 Multiprocess_Debugging_Enhanced For Version 7.3, debugger support for multiprocess programs has been extensively overhauled. Bugs have been fixed and the user- interface has been improved. The multiprocess debugging enhancements include the following features: o Greater control over individual process and groups of processes, including: Execution of processes (or groups of processes) Suspension of processes (or groups of processes) Exiting processes (or groups of processes), with or without exit handler execution o Ability to create user-defined groups of processes o Simpler to start a multiprocess debugging session; the default configuration of the kept debugger is for a multiprocess session o Applications that use $HIBER WAIT (LIB$WAIT, $SCHDWH, and so on) can now be debugged using normal debugger configurations These enhancements make it much easier to debug multiprocess programs. For more detailed information, refer to the OpenVMS Debugger Manual. 3 EXAMINE/VARIANT_Command The EXAMINE command has a new /VARIANT qualifier that enables the debugger to display the correct item when it encounters an anonymous variant. In a C program, a union contains members, only one of which is valid at any one time. When displaying a union, the debugger does not know which member is currently valid. In a PASCAL program, a record with a variant part contains variants, only one of which is valid at any one time. When displaying a record with an anonymous variant part, the debugger does not know which variant is currently valid, and displays all variants by default. You can use the /VARIANT qualifier to select which member of a union (C program) or anonymous variant (PASCAL program) to display. The format is as follows: DBG> EXAMINE /VARIANT=var-selector address-exp DBG> EXAMINE /VARIANT=(var-selector,...) address-exp The variant selector var-selector specifies a name, a discriminant (PASCAL only), or a position; that is, one of the following: o NAME = name-string o DISCRIMINANT = expression o POSITION = expression For more information, see the EXAMINE topic. 2 Address_Expressions Several debugger commands require that you specify an address expression. An address expression is an entity that denotes a memory address or a register. Commands for which you specify address expressions are: (SET,ACTIVATE,DEACTIVATE,CANCEL) BREAK (SET,ACTIVATE,DEACTIVATE,CANCEL) TRACE (SET,ACTIVATE,DEACTIVATE,CANCEL) WATCH EVALUATE/ADDRESS EXAMINE DEPOSIT (at the left of the equal sign) In general, you can specify address expressions using the syntax of the currently set language. For example: DBG> EXAMINE A(1) ! FORTRAN DBG> SET WATCH A[1] ! Pascal DBG> EXAMINE C OF R ! COBOL In addition, you can specify address expressions numerically, and you can also use the built-in symbols %LINE and %LABEL to refer to code locations: DBG> EXAMINE 512 DBG> SET BREAK %LINE 10 You can also use the following operators to specify addresses that you might not be able to access by name (nonsymbolic addresses): + - * Arithmetic operators / @ or . Indirection Select bit field For example, examine the instruction 3 bytes after line 10: DBG> EXAMINE %LINE 10 + 3 Examine the location pointed to by P: DBG> EXAMINE @P Do not confuse an address expression with a language expression, which denotes a value rather than a program location. The following examples show how the same command parameter is treated either as an address expression or as a language expression depending on the command: Show the address of the variable X (address expression): DBG> EVALUATE/ADDR X 512 Show the current value of X (address expression): DBG> EXAMINE X X: 0 Evaluate X (language expression): DBG> EVALUATE X 0 Evaluate X+1 (language expression): DBG> EVALUATE X+1 1 Show value at location X plus 1 byte (address expression): DBG> EXAMINE X+1 513: 0 3 Using_Symbols_and_Operators_in_Address_Expressions The symbols and operators that can be used in address expressions are listed below. A unary operator has one operand. A binary operator has two operands. Symbol Description %LABEL Specifies that the numeric literal that follows is a program label (for languages like FORTRAN that have numeric program labels). You can qualify the label with a path-name prefix that specifies the containing module. %LINE Specifies that the numeric literal that follows is a line number in your program. You can qualify the line number with a path-name prefix that specifies the containing module. Backslash (\) When used within a path name, delimits each element of the path name. In this context, the backslash cannot be the leftmost element of the complete path name. When used as the prefix to a symbol, specifies that the symbol is to be interpreted as a global symbol. In this context, the backslash must be the leftmost element of the symbol's complete path name. At sign (@) Unary operators. In an address expression, the Period (.) at sign (@) and period (.) each function as a "contents-of" operator. The "contents-of" operator causes its operand to be interpreted as a memory address and thus requests the contents of (or value residing at) that address. Bit field Unary operator. You can apply bit field selection to an address-expression. To select a bit field, you supply a bit offset (p), a bit length (s), and a sign extension bit (e), which is optional. Plus sign (+) Unary or binary operator. As a unary operator, indicates the unchanged value of its operand. As a binary operator, adds the preceding operand and succeeding operand together. Minus sign (-) Unary or binary operator. As a unary operator, indicates the negation of the value of its operand. As a binary operator, subtracts the succeeding operand from the preceding operand. Multiplication Binary operator. Multiplies the preceding sign (*) operand by the succeeding operand. Division sign Binary operator. Divides the preceding operand (/) by the succeeding operand. The examples in the additional topics illustrate the use of built-in symbols and operators in address expressions. 4 %LINE_and_%LABEL_Operators The following command sets a tracepoint at line 26 of the module in which execution is currently suspended: DBG> SET TRACE %LINE 26 The next command displays the source line associated with line 47: DBG> EXAMINE/SOURCE %LINE 47 module MAIN 47: procedure SWAP(X,Y: in out INTEGER) is DBG> The next command sets a breakpoint at label 10 of module MOD4: DBG> SET BREAK MOD4\%LABEL 10 4 Path-Name_Operators The following command displays the value of the variable COUNT that is declared in routine ROUT2 of module MOD4. The backslash (\) path-name delimiter separates the path-name elements: DBG> EXAMINE MOD4\ROUT2\COUNT MOD4\ROUT2\COUNT: 12 DBG> The following command sets a breakpoint on line 26 of the module QUEUMAN: DBG> SET BREAK QUEUMAN\%LINE 26 The following command displays the value of the global symbol X: DBG> EXAMINE \X 4 Arithmetic_Operators The order in which the debugger evaluates the elements of an address expression is similar to that used by most programming languages. The order is determined by the following three factors, listed in decreasing order of precedence (first listed have higher precedence): 1. The use of delimiters (usually parentheses or brackets) to group operands with particular operators 2. The assignment of relative priority to each operator 3. Left-to-right priority of operators The debugger operators are listed in decreasing order of precedence as follows: 1. Unary operators ((.), (@), (+), (-)) 2. Multiplication and division operators ((*), (/)) 3. Addition and subtraction operators ((+), (-)) For example, when evaluating the following expression, the debugger first adds the operands within parentheses, then divides the result by 4, then subtracts the result from 5. 5--(T+5)/4 The following command displays the value contained in the memory location X + 4 bytes: DBG> EXAMINE X + 4 4 Contents-of_Operator The following examples illustrate use of the contents-of operator. In the next example, the instruction at the current PC value is obtained (the instruction whose address is contained in the PC and which is about to execute): DBG> EXAMINE .%PC MOD\%LINE 5: PUSHL S^#8 DBG> In the next example, the source line at the PC value one level down the call stack is obtained (at the call to routine SWAP): DBG> EXAMINE/SOURCE .1\%PC module MAIN MAIN\%LINE 134: SWAP(X,Y); DBG> For the next example, assume that the value of pointer variable PTR is 7FF00000 hexadecimal, the address of an entity that you want to examine. Assume further that the value of this entity is 3FF00000 hexadecimal. The following command shows how to examine the entity: DBG> EXAMINE/LONG .PTR 7FF00000: 3FF00000 DBG> In the next example, the contents-of operator (at sign or period) is used with the current location operator (period) to examine a linked list of three quadword-integer pointer variables (identified as L1, L2, and L3 in the illustration that follows). P is a pointer to the start of the list. The low longword of each pointer variable contains the address of the next variable; the high longword of each variable contains its integer value (8, 6, and 12, respectively). +------+ P: | 9B40 |--+ L1 L2 L3 +------+ | +------+ +------+ +------+ +-->| 9BDA |--->| 9BF4 |--->| 0000 | |------| |------| |------| | 8 | | 6 | | 12 | +------+ +------+ +------+ DBG> SET TYPE QUADWORD; SET RADIX HEX DBG> EXAMINE .P ! Examine the entity whose address ! is contained in P. 00009BC2: 00000008 00009BDA ! High word has value 8, low word ! has address of next entity (9BDA). DBG> EXAMINE @. ! Examine the entity whose address ! is contained in the current entity. 00009BDA: 00000006 00009BF4 ! High word has value 6, low word ! has address of next entity (9BF4). DBG> EXAMINE .. ! Examine the entity whose address ! is contained in the current entity. 00009BF4: 0000000C 00000000 ! High word has value 12 (dec.), low word ! has address 0 (end of list). 4 Bit-Field_Operator The following example shows how to use the bit-field operator. For example, to examine the address expression X_NAME starting at bit 3 with a length of 4 bits and no sign extension, you would enter the following command: DBG> EXAMINE X_NAME <3,4,0> 2 Built_in_Symbols The debugger built-in symbols provide options for specifying program entities and values in debugger commands, as follows: Function Symbols Specify %Rn, %R31, %AP, %FP, %SP, %PC, %PSL, %Vn, %VCR, Alpha %VLR, %VMR, %Fn, %F31 and VAX registers %LANGUAGE Specify the current language %NAME Construct identifiers %PARCNT Count parameters passed in command procedures %BIN, %DEC, Control radix %HEX, %OCT %CURLOC, Specify consecutive program locations and the %NEXTLOC, current value of an entity %PREVLOC, %CURVAL %LABEL, Specify numeric labels and line numbers %LINE %ADDR, Specify the argument passing mechanism for the %DESCR, CALL command %REF, %VAL Specify %ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME, %EXC_ processes, NUM, %EXC_SEVERITY, %PROCESS_NAME, %PROCESS_PID, tasks, or %PROCESS_NUMBER, %NEXT_PROCESS, %PREVIOUS_PROCESS, information %VISIBLE_PROCESS, %ACTIVE_TASK, %CALLER_TASK, about %NEXT_TASK, %TASK. %VISIBLE_TASK exceptions Specify %PAGE, %WIDTH, %DECWINDOWS, %CURDISP, %CURSCROLL, information %NEXTDISP, %NEXTINST, %NEXTOUTPUT, %NEXTSCROLL, about the %NEXTSOURCE, %SOURCE_SCOPE, %INST_SCOPE, %CURRENT_ interface SCOPE_ENTRY, %NEXT_SCOPE_ENTRY, %PREVIOUS_SCOPE_ ENTRY 3 %Rn On VAX systems, specifies the VAX general purpose registers %R0 through %R11. On Alpha systems, specifies the Alpha integer registers %R0 through %R28. Example: DBG> DEPOSIT %R1 = 23 3 %AP On VAX systems, specifies the VAX argument pointer register (%R12). 3 %FP On VAX systems, specifies the VAX frame pointer register (%R13). On Alpha systems, specifies the Alpha stack frame base register (%R29). 3 %SP On VAX systems, specifies the VAX stack pointer register (%R14). On Alpha systems, specifies the Alpha stack pointer register (%R30). 3 %PC Specifies the VAX or Alpha program counter register. The PC contains the address of the next instruction to be executed by the processor. VAX Examples: DBG> EXAMINE %PC ! Display the value in the PC MOD3\%PC: 1554 ! address of next instruction to execute DBG> EXAMINE %PC ! Display the value at the address in the PC MOD3\%LINE 12: MOVL B^12(R11),R1 ! next instruction to execute 3 %PSL On VAX systems, specifies the VAX processor status longword. 3 %Vn On VAX systems, specifies the VAX vector registers %V0 through %V15. 3 %VCR On VAX systems, specifies the VAX vector count register (%VCR). The VCR specifies the length of the offset vector generated by the IOTA instruction. 3 %VLR On VAX systems, specifies the VAX vector length register (%VLR). The VLR limits the highest element of a vector register that is processed by a vector instruction. 3 %VMR On VAX systems, specifies the VAX vector mask register (%VMR). The VMR specifies a mask (a bit pattern) that a vector instruction uses in order to operate on only certain elements of a vector register operand. 3 %R31 On Alpha systems, specifies the ReadAsZero/Sink register. This register is permanently assigned the value zero. 3 %PS On Alpha systems, specifies the Alpha processor status register. 3 %Fn On Alpha systems, specifies the Alpha floating-point registers %F0 through %F30. 3 %F31 On Alpha systems, specifies the ReadAsZero/Sink floating-point register. This register is permanently assigned the value zero. 3 %LANGUAGE Specifies the current language. The current language is the language last established with the SET LANGUAGE command. BY default, if you did not enter a SET LANGUAGE command, the current language is the language of the module containing the main program (image transfer address). Example: DBG> EVALUATE %LANGUAGE 'FORTRAN' DBG> SET LANGUAGE ADA DBG> EVALUATE %LANGUAGE "ADA" 3 %NAME Enables you to constuct identifiers that are not ordinarily legal in the current language. Format: %NAME id-char-string %NAME 'any-char-string' Examples: DBG> EXAMINE %NAME 12 ! Examine variable nameD '12' DBG> EXAMINE %NAME 'P.AAA' ! Examine generated label P.AAA 3 %PARCNT Specifies the number of actual parameters to the current command procedure. Use %PARCNT in command procedures that can take a variable number of actual parameters. You can use %PARCNT only inside command procedures; it is not defined when commands are entered from the terminal. For example, suppose the command procedure ABC is executed with the command @ABC 111,222,333. Inside ABC, %PARCNT then has the value 3 because there are three parameters on this particular call to ABC. Example: EVALUATE %PARCNT FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) 3 %BIN Specifies that a following numeric literal (or all numeric literals in a following parenthesized expression) be interpreted in binary radix. Examples: DBG> EVALUATE/DEC %BIN 10 2 DBG> EVALUATE/DEC %BIN (10 + 10) 4 3 %DEC Specifies that a following numeric literal (or all numeric literals in a following parenthesized expression) be interpreted in decimal radix. Examples: DBG> EVALUATE/HEX %DEC 10 0A DBG> EVALUATE/HEX %DEC (10 + 10) 14 3 %HEX Specifies that a following numeric literal (or all numeric literals in a following parenthesized expression) be interpreted in hexadecimal radix. Examples: DBG> EVALUATE/HEX %DEC 10 16 DBG> EVALUATE/DEC %HEX (10 + 10) 32 3 %OCT Specifies that a following numeric literal (or all numeric literals in a following parenthesized expression) be interpreted in octal radix. Examples: DBG> EVALUATE/DEC %OCT 10 8 DBG> EVALUATE/DEC %OCT (10 + 10) 16 3 %CURLOC Specifies the current logical entity (that is, the program location last referenced by an EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command). You can also use the period character (.) for this purpose. Example: DBG> EXAMINE RADIUS CIRCLE\RADIUS: 0.0000000E+00 DBG> DEPOSIT %CURLOC = 1 ! Set RADIUS to 1 DBG> DEPOSIT . = 2 ! Set RADIUS to 2 3 %NEXTLOC Specifies the logical successor of the current entity (that is, the program location that logically follows the location last referenced by an EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command). The EXAMINE command without a parameter is equivalent to EXAMINE %NEXTLOC. Example: DBG> EXAMINE PRIMES(4) SIEVE\PRIMES(4): 7 DBG> EXAMINE %NEXTLOC SIEVE\PRIMES(5): 11 DBG> EXAMINE ! Equivalent to EXAMINE %NEXTLOC SIEVE\PRIMES(6): 13 3 %PREVLOC Specifies the logical predecessor of the current entity (that is, the program location that logically precedes the location last referenced by an EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command). You can also use the circumflex character (^) for this purpose. Examples: DBG> EXAMINE PRIMES(6) SIEVE\PRIMES(6): 13 DBG> EXAMINE %PREVLOC SIEVE\PRIMES(5): 11 DBG> EXAMINE ^ ! Equivalent to EXAMINE %PREVLOC SIEVE\PRIMES(4): 7 3 %CURVAL Specifies the value last displayed by an EVALUATE or EXAMINE command, or deposited by a DEPOSIT command. You can also use the backslash character (\) for this purpose. These two symbols are not affected by an EVALUATE/ADDRESS command. Example: DBG> EXAMINE RADIUS CIRCLE\RADIUS: 0.0000000E+00 DBG> EVALUATE %CURVAL 0.0000000E+00 3 %LABEL %LABEL n is the debugger syntax for referring to label n in your program. This is intended for languages like FORTRAN which have numeric program labels. You can qualify the label with a path name specifying the containing module. Example: DBG> SET BREAK MODULENAME\%LABEL 10 The old syntax of %LABEL MODULENAME\n is no longer accepted. 3 %LINE %LINE n is the debugger syntax for referring to line n in your program. You can qualify the line number with a path name specifying the containing module. Example: DBG> SET BREAK MODULENAME\%LINE 10 The old syntax of %LINE MODULENAME\n is no longer accepted. 3 %PAGE Specifies the current height of the screen, in lines, as used by the debbuger. For example, the following command defines a screen mode window named MIDDLE that occupies a region around the middle of the screen: DBG> SET WINDOW MIDDLE AT - _DBG> (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2) 3 %WIDTH Specifies the current width of the screen, in columns, as used by the debugger. For example, the following command defines a screen mode window named MIDDLE that occupies a region around the middle of the screen: DBG> SET WINDOW MIDDLE AT - _DBG> (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2) 3 %DECWINDOWS Enables you to determine whether you are using the debugger's command interface or Compaq DECwindows Motif for OpenVMS user interface. With the Compaq DECwindows Motif for OpenVMS user interface, the value of %DECWINDOWS is 1 (TRUE). With the command interface, the value is 0 (FALSE). For example: DBG> EVALUATE %DECWINDOWS 0 The following example shows how to use %DECWINDOWS in a debugger initialization file to position the debugger source window, SRC, at debugger startup: IF %DECWINDOWS THEN ! DECwindows Motif (workstation) syntax: (DISPLAY SRC AT (100,300,100,700)) ELSE ! Screen-mode (terminal) syntax: (DISPLAY SRC AT (AT H1)) 3 %ADDR (Default) Used with the CALL command to specify the argument passing mechanism. The %ADDR symbol specifies that the argument is passed by address. See the CALL command. 3 %DESCR Used with the CALL command to specify the argument passing mechanism. The %DESCR symbol specifies that the argument is passed by descriptor. See the CALL command. 3 %REF Used with the CALL command to specify the argument passing mechanism. The %REF symbol specifies that the argument is passed by reference. See the CALL command. 3 %VAL Used with the CALL command to specify the argument passing mechanism. The %VAL symbol specifies that the argument is passed by value. See the CALL command. 3 %CURDISP Specifies the current display (screen mode). This is the display most recently referenced with a DISPLAY command (that is, the least occluded display.) Example: DBG> SELECT/SCROLL %CURDISP 3 %CURSCROLL Specifies the current (screen mode) scrolling display. This is the default display for the SCROLL, MOVE, and EXPAND commands, as well as for the associated keypad keys (KP2, KP4, KP6, and KP8). Example: DBG> EXPAND/DOWN:5 %CURSCROLL 3 %NEXTDISP Specifies the next display after the current display in the screen-mode display list. The next display is the display that follows the topmost display. Because the display list is circular, this is the display at the bottom of the pasteboard (the most occluded display). Example: DBG> DISPLAY/POP %NEXTDISP 3 %NEXTINST Specifies the next instruction display after the current instruction display in the screen-mode display list. The current instruction display is the display that receives the output from EXAMINE/INSTRUCTION commands. Example: DBG> DISPLAY/REMOVE %NEXTINST 3 %NEXTOUTPUT Specifies the next output display after the current output display in the screen-mode display list. An output display receives debugger output that is not already directed to another display. Example: DBG> EXTRACT %NEXTOUTPUT OUT4.TXT 3 %NEXTSCROLL Specifies the next display after the current scrolling display in the screen-mode display list. Example: DBG> SELECT/SCROLL %NEXTSCROLL 3 %NEXTSOURCE Specifies the next source display after the current source display in the screen-mode display list. The current source display is the display which receives the output from TYPE and EXAMINE/SOURCE commands. Example: DBG> SELECT/SOURCE %NEXTSOURCE 3 %SOURCE_SCOPE Specifies the scope, relative to the call stack, for which source code is displayed in a screen-mode source display. If source code is not available for display in that scope, the debugger displays source code for the next level down the call stack for which it is available. The %SOURCE_SCOPE symbol is used in the definition of the predefined screen-mode source display SRC: DBG> DISPLAY SRC AT H1 SOURCE - _DBG> (EXAMINE/SOURCE .%SOURCE_SCOPE\%PC) 3 %INST_SCOPE Specifies the scope, relative to the call stack, for which decoded instructions are displayed in a screen-mode instruction display. The %INST_SCOPE symbol is used in the definition of the predefined screen-mode instruction display INST: DBG> DISPLAY INST AT H1 INSTRUCTION - _DBG> (EXAMINE/INST .%INST_SCOPE\%PC) 3 %CURRENT_SCOPE_ENTRY Specifies the call frame that the debugger is currently using as reference when displaying source code or decoded instructions, or when searching for symbols. By default, this is call frame 0. The %CURRENT_SCOPE_ENTRY symbol returns an integer value that denotes a call frame on the call stack. Call frame 0 denotes the routine at the top of the call stack, where execution is suspended. Call frame 1 denotes the calling routine, and so on. 3 %NEXT_SCOPE_ENTRY Specifies the next frame down the call stack from the call frame denoted by %CURRENT_SCOPE_ENTRY. The %NEXT_SCOPE_ENTRY symbol returns an integer value that denotes a call frame on the call stack. Call frame 0 denotes the routine at the top of the call stack, where execution is suspended. Call frame 1 denotes the calling routine, and so on. 3 %PREVIOUS_SCOPE_ENTRY Specifies the next frame up the call stack from the call frame denoted by %CURRENT_SCOPE_ENTRY. The %PREVIOUS_SCOPE_ENTRY symbol returns an integer value that denotes a call frame on the call stack. Call frame 0 denotes the routine at the top of the call stack, where execution is suspended. Call frame 1 denotes the calling routine, and so on. 3 %PROCESS_NAME When specifying a process name in a debugger command string, you can optionally precede the name with the symbol %PROCESS_NAME. Example: all> EXIT %PROCESS_NAME JONES_4 3 %PROCESS_PID When specifying a process identifier (PID) in a debugger command string, you must precede the PID with the symbol %PROCESS_PID. Example: all> CONNECT %PROCESS_PID 258001B6 3 %PROCESS_NUMBER When specifying a debugger-assigned process number in a debugger command string, you can precede the number with %PROCESS_NUMBER (or the abbreviation %PROC). Example: all> SHOW PROCESS %PROC 3 3 %NEXT_PROCESS Specifies the next process in the debugger's process list after the visible process. Example: all> SET PROCESS %NEXT_PROCESS 3 %PREVIOUS_PROCESS Specifies the previous process in the debugger's process list before the visible process. Example: all> SHOW PROCESS/FULL %PREVIOUS_PROCESS 3 %VISIBLE_PROCESS Specifies the visible process. This is the process whose stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on. Example: all> %VISIBLE_PROCESS,%NEXT_PROCESS > EXAMINE X 3 %ADAEXC_NAME A special form of %EXC_NAME for Ada programs. In Ada, an exception can be raised with syntax such as "raise XXX;". In this case, the exception name in the operating system sense is just "EXCEPTION," which is what %E returns. The Ada exception name ("XXX") is returned by %ADAEXC_NAME. Example: DBG> SET BREAK/EXCEPTION WHEN - _DBG> (%ADAEXC_NAME = "XXX") 3 %EXC_FACILITY Gives you the facility of the current exception. This provides a way of qualifying exception breaks. Example: DBG> EVALUATE %EXC_FACILITY "SYSTEM" DBG> SET BREAK/EXCEPTION WHEN - _DBG> (%EXC_FAC = "SYSTEM") 3 %EXC_NAME Gives you the name of the current exception. This provides a way of qualifying exception breaks. Example: DBG> EVALUATE %EXC_NAME "FLTDIV_F" DBG> SET BREAK/EXCEPTION WHEN (%EXC_NAME = "FLTDIV_F") 3 %EXC_NUM Gives you the current exception number. This provides a way of qualifying exception breaks. Example: DBG> EVALUATE %EXC_NUM 12 DBG> EVALUATE/COND %EXC_NUM %SYSTEM-F-ACCVIO, access violation at PC !XL, virtual address !XL DBG> SET BREAK/EXCEPTION WHEN (%EXC_NUM = 12) 3 %EXC_SEVERITY Gives you the severity code of the current exception. This provides a way of qualifying exception breaks. Example: DBG> EVALUATE %EXC_SEVERITY "F" DBG> SET BREAK/EXCEPTION WHEN (%EXC_SEV = "F") 3 %ACTIVE_TASK (Applies only to tasking programs.) Gives you the currently active task (the one that was running when the debugger last took control). See the SET TASK/ACTIVE command. Example: DBG> EVALUATE %ACTIVE_TASK %TASK 2 3 %CALLER_TASK (Applies only to Ada tasking programs.) Gives you the task which is the entry caller of the active task during a task rendezvous. If the active task (%ACTIVE_TASK) is not currently executing an accept statement (that is, a rendezvous is not in progress), %CALLER_TASK returns %TASK 0. Example: The following command sets a breakpoint within an accept statement. The breakpoint is triggered only when %TASK 3 is the task making the entry call of the rendezvous. DBG> TYPE 51:53 module SAMPLE 51: accept RENDEZVOUS do 52: PUT_LINE("Beginning the rendezvous"); 53: end RENDEZVOUS; DBG> SET BREAK %LINE 52 WHEN (%CALLER_TASK = %TASK 3) 3 %NEXT_TASK (Applies only to tasking programs.) Gives you the next task after the one currently visible (%VISIBLE_TASK). "Next" in this context is just an internal ordering that cycles through all the tasks. This lets you set up command procedures that cycle through all tasks. Example: DBG> WHILE %NEXT NEQ %ACTIVE DO - _DBG> (SET TASK %NEXT; SHOW CALLS) 3 %TASK (Applies only to tasking programs.) %TASK n (where n is a positive decimal integer) is the debugger syntax for referring to a task by its task ID. The task ID is a unique number associated with a task at the time the task is created. The task number n can be obtained using the SHOW TASK/ALL command or by examining task objects. Example: DBG> EXAMINE T1 T1: %TASK 2 DBG> SET TASK %TASK 2 3 %VISIBLE_TASK (Applies only to tasking programs.) Gives you the task that the debugger is using to do symbol lookups. This is the default task assumed by debugging commands when you do not (or cannot) specify a task. For example, the EXAMINE %R0 command displays register 0 of the visible task. This is normally the same as %ACTIVE_TASK but can be changed using the SET TASK command. Example: DBG> SET TASK %TASK 2 DBG> EVALUATE %VISIBLE %TASK 2 2 Client-Server_Interface The OpenVMS Debugger has an optional client/server configuration that allows you to access the debugger and its functions from a PC or a workstation. The debugger client/server retains the functionality of the OpenVMS kept debugger, but splits the debugger into two components, the debug server and the debug client. The interface of the Compaq DECwindows Motif for OpenVMS debug client is similar to the Motif interface of the standalone debugger. The debug server runs on an OpenVMS system, similar to the kept debugger without the user interface. The debug client contains the user interface, and runs on an OpenVMS system using Compaq DECwindows Motif for OpenVMS, or on a PC running Microsoft Windows 95 or Microsoft Windows NT. The following table shows the systems on which the debug client and the debug server run: Debug Debug Client Server System X X OpenVMS VAX X X OpenVMS Alpha X Microsoft Windows 95 Intel X Microsoft Windows 98 Intel X Microsoft Windows NT Alpha X Microsoft Windows NT Intel The OpenVMS client-server configuration allows the following: o Remote access to OpenVMS Debug Servers from other OpenVMS systems or from PCs running Windows 95 or Windows NT Version 3.51 or later o Client access to multiple servers, each running on the same or different OpenVMS nodes o Multiple clients on different nodes to simultaneously connect to the same server for teaching or team debugging o Debugging of multi-tier client/server applications that are distributed among several mixed-platform systems 3 Required_Software The Compaq DECwindows Motif for OpenVMS debug client requires the following system software: OpenVMS Version 7.0 or later (VAX or Alpha) Compaq DECwindows Motif for OpenVMS Version 1.2 or later The debug server requires OpenVMS Version 7.0 or later running on a VAX or Alpha node. The OpenVMS debugger client/server configuration also requires that the following be installed on the OpenVMS node running the server and any nodes running the Compaq DECwindows Motif for OpenVMS client: o A TCP/IP stack o DCE RPC NOTE If you are running TCP/IP Services for OpenVMS (UCX) Version 4.1, you must have ECO2 installed. You can also run a later version of UCX. The client and server communicate using DCE RPC over one of the following transports: TCP/IP UDP DECnet 3 Starting_the_Debug_Server You can start the debug server after logging in directly to the OpenVMS system. You can also log in remotely with a product such as eXcursion, or a terminal emulator such as Telnet. Note that you can run Telnet directly from the Microsoft Windows client. To start the server on an OpenVMS node, enter the following command: $ DEBUG/SERVER The server displays its network binding strings, which allow Compaq DECwindows Motif for OpenVMS and Microsoft Windows clients to specify this server for connection. For example: $ DEBUG/SERVER %DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: YES %DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.138[1034] %DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:19.10[RPC224002690001] %DEBUG-I-WATCH: Network Binding: ncadg_ip_udp:16.32.16.138[1045] %DEBUG-I-AWAIT: Ready for client connection... To connect to the server, you must know the nodename of the node running the server, and the port number. The port number is displayed in the square brackets of the network binding string. The following table matches the network binding string prefix with its associated network transport: Network Transport NetworK Binding String Prefix TCP/IP ncacn_ip_tcp DECnet ncacn_dnet_nsp: UDP ncadg_ip_udp NOTE You must hold the DBG$ENABLE_SERVER identifier in the rights database to be able to run the debug server. Exercise care when using the debug server. Once a debug server is running, anyone on the network has the ability to connect to the debug server. Before granting the DBG$ENABLE_SERVER identifier, the system manager must create it by entering the command DEBUG/SERVER from an account with write access to the rights database. The system manager needs to do this only once. The system manager can then run the Authorize utility to grant the DBG$ENABLE_SERVER identifier to the user's account in the rights database. 3 Starting_the_Motif_Debug_Client Once the debug server is running, start the Motif debug client. To do so, enter the following command: $ DEBUG/CLIENT The debugger displays the Server Connection dialog. From the Server Connection dialog, you can o Select a session for connection o Select a network transport protocol o Specify the number of secondary clients allowed o Connect to a selected server to begin and activate a new session or reactivate an existing session o Disconnect from a session o Test whether a server is available o Stop the server o Cancel a connection operation and dismiss the dialog NOTE Messages and program output appear by default in the window in which you start the server. You can redirect program output to another window as required. 3 Primary_Clients_and_Secondary_Clients The primary client is the first client to connect to the server. A secondary client is an additional client that has connected to the same server. The primary client controls whether or not any secondary clients can connect to the server through the Server Options dialog. Click Options on the Server Connection dialog to display the Server Options dialog. 3 Establishing_a_Server_Session A session is the connection between a particular client and a particular server. Each session is identified within the client by the network binding string the client used to connect to the server. When you start the client, the debugger displays the Server Connection dialog, to let you specify the server, the network transport protocol, and the number of secondary clients allowed. In the Server Connection dialog the Connection [local]: dialog bar contains the default network binding string. This string is based on the last string you entered, or the node on which the client is running. There is not necessarily a server associated with the default binding string. To specify the server, you can accept the default, or you can enter the node name of the OpenVMS node running the debug server and the port number. For example: NODNAM[1234] To specify the network transport protocol and the number of secondary clients allowed, perform the following steps: 1. Click Options to display the Server Options dialog. 2. In the Server Options dialog, click on the network transport: TCP/IP, DECnet, or UDP. 3. In the Server Options dialog, enter the number of secondary clients (0-30) to be allowed. 4. Click OK to dismiss the Server Options dialog. Click Connect to connect the client to the server. 3 Switching_Between_Sessions Each time you connect to a server and initiate a session, the session is listed in the Active Sessions dialog bar in the Server Connection dialog. You can switch back and forth between sessions. Each time you switch to a new session, the debugger updates the contents of any open debugger displays with the new context. To switch to a different session, perform the following steps: 1. Open the File menu. 2. Click Server Connection. 3. Click the Active Sessions dialog bar to display the list of active sessions. 4. Double click the required session in the Active Sessions list. This selects the session as the current session, dismisses the Server Connection dialog, and updates the debugger displays with the current context. Note that you cannot change the number of secondary clients allowed on a session while that session is active. To change the number of clients allowed on a session, you must be the primary client, and perform the following steps: 1. Open the File menu. 2. Specify the network binding string of the session. 3. Click Disconnect. 4. Click Options. 5. In the Server Options dialog, click on the network transport: TCP/IP, DECnet, or UDP. 6. In the Server Options dialog, select the number of secondary clients (0-31) to be allowed. 7. Click OK to dismiss the Server Options dialog. 8. In the Server Connection dialog, click Connect. 3 Closing_a_Client/Server_Session Click on Exit Debug? from the File menu to invoke the Confirm Exit dialog. Once you have invoked the Confirm Exit dialog, perform one of the following: o To terminate both the client and the server (default) click OK. o To dismiss the Confirm Exit dialog without taking any action, click Cancel. o To terminate only the debug client, perform the following steps: o Click Exit Server. o Click OK. o To terminate only the debug server, perform the following steps: o Click Exit Client. o Click OK. If you do not terminate the debug server, you can connect to the server from another debug client. If you do not terminate the client, you can connect to another server for which you know the network binding string. 2 Command_Format You can enter debugger commands interactively at the keyboard or store them within a command procedure to be executed later with the execute procedure (@) command. 3 General_Rules A command string is the complete specification of a debugger command. Although you can continue a command on more than one line, the term command string is used to define an entire command that is passed to the debugger. A debugger command string consists of a verb and, possibly, parameters and qualifiers. The verb specifies the command to be executed. Some debugger command strings might consist of only a verb or a verb pair. For example: DBG> GO DBG> SHOW IMAGE A parameter specifies what the verb acts on (for example, a file specification). A qualifier describes or modifies the action taken by the verb. Some command strings might include one or more parameters or qualifiers. In the following examples, COUNT, I, J, and K, OUT2, and PROG4.COM are parameters (@ is the execute procedure command); /SCROLL and /OUTPUT are qualifiers. DBG> SET WATCH COUNT DBG> EXAMINE I,J,K DBG> SELECT/SCROLL/OUTPUT OUT2 DBG> @PROG4.COM Some commands accept optional WHEN or DO clauses. DO clauses are also used in some screen display definitions. A WHEN clause consists of the keyword WHEN followed by a conditional expression (within parentheses) that evaluates to true or false in the current language. A DO clause consists of the keyword DO followed by one or more command strings (within parentheses) that are to be executed in the order that they are listed. You must separate multiple command strings with semicolons (;). These points are illustrated in the next example. The following command string sets a breakpoint on routine SWAP. The breakpoint is triggered whenever the value of J equals 4 during execution. When the breakpoint is triggered, the debugger executes the two commands SHOW CALLS and EXAMINE I,K, in the order indicated. DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I,K) The debugger checks the syntax of the commands in a DO clause when it executes the DO clause. You can nest commands within DO clauses. 3 Interactive_Input_Rules When entering a debugger command interactively at the keyboard, you can abbreviate a keyword (verb, qualifier, parameter) to as few characters as are needed to make it unique within the set of all debugger keywords. However, some commonly used commands (for example, EXAMINE, DEPOSIT, GO, STEP) can be abbreviated to their first characters. Also, in some cases, the debugger interprets nonunique abbreviations correctly on the basis of context. Pressing the Return key terminates the current line, causing the debugger to process it. To continue a long command string on another line, type a hyphen (-) before pressing Return. As a result, the debugger prompt is prefixed with an underscore character (_DBG>), indicating that the command string is still being accepted. You can enter more than one command string on one line by separating command strings with semicolons (;). To enter a comment (explanatory text recorded in a debugger log file but otherwise ignored by the debugger), precede the comment text with an exclamation point (!). If the comment wraps to another line, start that line with an exclamation point. The command line editing functions that are available at the DCL prompt ($) are also available at the debugger prompt (DBG>), including command recall with the up arrow and down arrow keys. For example, pressing the left arrow and right arrow keys moves the cursor one character to the left and right, respectively; pressing Ctrl/H or Ctrl/E moves the cursor to the start or end of the line, respectively; pressing Ctrl/U deletes all the characters to the left of the cursor, and so on. To interrupt a command that is being processed by the debugger, press Ctrl/C. See the Ctrl/C command. 3 Command_Procedure_Rules To maximize legibility, it is best not to abbreviate command keywords in a command procedure. Do not abbreviate command keywords to less than four significant characters (not counting the negation /NO . . . ), to avoid potential conflicts in future releases. Start a debugger command line at the left margin. (Do not start a command line with a dollar sign ($) as you do when writing a DCL command procedure.) The beginning of a new line ends the previous command line (the end-of-file character also ends the previous command line). To continue a command string on another line, type a hyphen (-) before starting the new line. You can enter more than one command string on one line by separating command strings with semicolons (;). To enter a comment (explanatory text that does not affect the execution of the command procedure), precede the comment text with an exclamation point (!). If the comment wraps to another line, start that line with an exclamation point. 2 Command_Summary The additional topics list all the debugger commands and any related DCL commands in functional groupings, along with brief descriptions. 3 Starting_and_Ending_a_Debugging_Session The commands listed below are used to start the debugger, bring a program under debugger control, and interrupt and end a debugging session. Except where otherwise specified, all commands are debugger commands. DEBUG/KEEP (DCL) Starts the debugger RUN filespec Brings a program under debugger control RERUN Reruns the program currently under debugger control RUN filespec (DCL) If the specified image was linked using LINK/DEBUG, starts the debugger and also brings the image under debugger control. When you start the debugger in this manner, you cannot then use the debugger RUN or RERUN commands. You can use the /[NO]DEBUG qualifiers with the RUN command to control whether the debugger is started when the program is executed. EXIT, Ctrl/Z Ends a debugging session, executing all exit handlers QUIT Ends a debugging session without executing any exit handlers declared in the program Ctrl/C Aborts program execution or a debugger command without interrupting the debugging session (SET,SHOW) ABORT_KEY (Assigns, identifies) the default Ctrl/C abort function to another Ctrl- key sequence, identifies the Ctrl-key sequence currently defined for the abort function Ctrl/Y-DEBUG (DCL) Interrupts a program that is running without debugger control and starts the debugger; not supported in the Kept Debugger configuration ATTACH Passes control of your terminal from the current process to another process SPAWN Creates a subprocess, enabling you to execute DCL commands without ending a debugging session or losing your debugging context 3 Controlling_and_Monitoring_Program_Execution The following commands are used to control and monitor program execution: GO Starts or resumes program execution STEP Executes the program up to the next line, instruction, or specified instruction (SET,SHOW) STEP (Establishes, displays) the default qualifiers for the STEP command (SET,SHOW,CANCEL) (Sets, displays, cancels) breakpoints BREAK (ACTIVATE,DEACTIVATE) (Activates, deactivates) previously set BREAK breakpoints (SET,SHOW,CANCEL) (Sets, displays, cancels) tracepoints TRACE (ACTIVATE,DEACTIVATE) (Activates, deactivates) previously set TRACE tracepoints (SET,SHOW,CANCEL) (Sets, displays, cancels) watchpoints WATCH (ACTIVATE,DEACTIVATE) (Activates, deactivates) previously set WATCH watchpoints SHOW CALLS Identifies the currently active routine calls SHOW STACK Gives additional information about the currently active routine calls CALL Calls a routine 3 Examining_and_Manipulating_Data The following commands are used to examine and manipulate data: EXAMINE Displays the value of a variable or the contents of a program location SET MODE [NO]OPERANDS Controls whether the address and contents of the instruction operands are displayed when you examine an instruction DEPOSIT Changes the value of a variable or the contents of a program location DUMP Displays the contents of memory in a manner similar to the DCL command DUMP. EVALUATE Evaluates a language or address expression MONITOR (Applies only to the debugger's Compaq DECwindows Motif for OpenVMS user interface). Displays the current value of a variable or language expression in the Monitor View of the Compaq DECwindows Motif for OpenVMS user interface. 3 Type_Selection_and_Radix The following commands are used to control type selection and radix: (SET,SHOW,CANCEL) (Establishes, displays, restores) the RADIX radix for data entry and display (SET,SHOW,CANCEL) (Establishes, displays, restores) the TYPE type for program locations that are not associated with a compiler-generated type SET MODE [NO]G_FLOAT Controls whether double-precision floating-point constants are interpreted as G_FLOAT or D_FLOAT 3 Symbol_Searches_and_Symbolization The following commands are used to control symbol searches and symbolization: SHOW SYMBOL Displays symbols in your program (SET,SHOW,CANCEL) Sets a module by loading its symbol MODULE information into the debugger's symbol table, identifies, cancels a set module (SET,SHOW,CANCEL) Sets a shareable image by loading data IMAGE structures into the debugger's symbol table, identifies, cancels a set image SET MODE [NO]DYNAMIC Controls whether or not modules and shareable images are set automatically when the debugger interrupts execution (SET,SHOW,CANCEL) (Establishes, displays, restores) the SCOPE scope for symbol searches SYMBOLIZE Converts a memory address to a symbolic address expression SET MODE [NO]LINE Controls whether program locations are displayed in terms of line numbers or routine-name + byte offset SET MODE [NO]SYMBOLIC Controls whether program locations are displayed symbolically or in terms of numeric addresses 3 Displaying_Source_Code The following commands are used to control the display of source code: TYPE Displays lines of source code EXAMINE/SOURCE Displays the source code at the location specified by the address expression SEARCH Searches the source code for the specified string (SET,SHOW) SEARCH (Establishes, displays) the default qualifiers for the SEARCH command SET STEP [NO]SOURCE Enables/disables the display of source code after a STEP command has been executed or at a breakpoint, tracepoint, or watchpoint (SET,SHOW) MARGINS (Establishes, displays) the left and right margin settings for displaying source code (SET,SHOW,CANCEL) (Creates, displays, cancels) a source SOURCE directory search list 3 Screen_Mode The following commands are used to control screen mode and screen displays: SET MODE [NO]SCREEN Enables/disables screen mode DISPLAY Creates or modifies a display SCROLL Scrolls a display EXPAND Expands or contracts a display MOVE Moves a display across the screen (SHOW,CANCEL) DISPLAY (Identifies, deletes) a display (SET,SHOW,CANCEL) (Creates, identifies, deletes) a window WINDOW definition SELECT Selects a display for a display attribute SHOW SELECT Identifies the displays selected for each of the display attributes SAVE Saves the current contents of a display into another display EXTRACT Saves a display or the current screen state into a file (SET,SHOW) TERMINAL (Establishes, displays) the terminal screen height and width that the debugger uses when it formats displays and other output SET MODE [NO]SCROLL Controls whether an output display is updated line by line or once per command Ctrl/W Refreshes the screen DISPLAY/REFRESH 3 Editing_Source_Code The following commands are used to control source editing from a debugging session: EDIT Starts an editor during a debugging session (SET,SHOW) EDITOR (Establishes, identifies) the editor started by the EDIT command 3 Defining_Symbols The following commands are used to define and delete symbols for addresses, commands, or values: DEFINE Defines a symbol as an address, command, or value DELETE Deletes symbol definitions (SET,SHOW) DEFINE (Establishes, displays) the default qualifier for the DEFINE command SHOW SYMBOL/DEFINED Identifies symbols that have been defined with the DEFINE command 3 Keypad_Mode The following commands are used to control keypad mode and key definitions: SET MODE [NO]KEYPAD Enables/disables keypad mode DEFINE/KEY Creates key definitions DELETE/KEY Deletes key definitions SET KEY Establishes the key definition state SHOW KEY Displays key definitions 3 Command_Files__Log_Files__Initialization_Files_ The following commands are used with command procedures and log files: @ (Execute Procedure) Executes a command procedure (SET,SHOW) ATSIGN (Establishes, displays) the default file specification that the debugger uses to search for command procedures DECLARE Defines parameters to be passed to command procedures (SET,SHOW) LOG (Specifies, identifies) the debugger log file SET OUTPUT [NO]LOG Controls whether a debugging session is logged SET OUTPUT Controls whether, in screen mode, the [NO]SCREEN_LOG screen contents are logged as the screen is updated SET OUTPUT [NO]VERIFY Controls whether debugger commands are displayed as a command procedure is executed SHOW OUTPUT Identifies the current output options established by the SET OUTPUT command 3 Control_Structures The following commands are used to establish conditional and looping structures for debugger commands: FOR Executes a list of commands while incrementing a variable IF Executes a list of commands conditionally REPEAT Executes a list of commands a specified number of times WHILE Executes a list of commands while a condition is true EXITLOOP Exits an enclosing WHILE, REPEAT, or FOR loop 3 Multiprocess_Programs The following commands are used to debug multiprocess programs. Note that these commands are specific to multiprocess programs. Many of the commands listed under other categories have qualifiers or parameters that are specific to multiprocess programs (for example, SET BREAK/ACTIVATING, EXIT process-spec, DISPLAY/PROCESS=). CONNECT Brings a process under debugger control DISCONNECT Release a process from debugger control DEFINE/PROCESS_SET Assigns a symbolic name to a list of process specifications SET MODE Controls whether execution is interrupted [NO]INTERRUPT in other processes when it is paused in some process SET MODE [NO]WAIT Controls whether the debugger waits for all processes to stop executing before it prompts for another command (SET,SHOW) PROCESS Modifies the multiprocess debugging environment, displays process information WAIT Controls whether the debugger waits until all processes have stopped before prompting for another command. 3 Additional_Commands The following commands are used for miscellaneous purposes: HELP Displays online help on debugger commands and selected topics (DISABLE,ENABLE,SHOW) (Disables, enables) the delivery of AST ASTs in the program, identifies whether delivery is enabled or disabled (SET,SHOW) EVENT_ (Establishes, identifies) the current run- FACILITY time facility for Ada, POSIX Threads, and SCAN events (SET,SHOW) LANGUAGE (Establishes, identifies) the current language SET MODE [NO]SEPARATE Controls whether the debugger, when used on a workstation running VWS, creates a separate window for debugger input and output SET OUTPUT Controls whether debugger output, except [NO]TERMINAL for diagnostic messages, is displayed or suppressed SET PROMPT Specifies the debugger prompt (SET,SHOW) TASK Modifies the tasking environment, displays task information (SET,SHOW) VECTOR_ Enables or disables a debugger vector mode MODE option, identifies the current vector mode option (for vectorized programs). SHOW EXIT_HANDLERS Identifies the exit handlers declared in the program SHOW MODE Identifies the current debugger modes established by the SET MODE command (for example, screen mode, step mode) SHOW OUTPUT Identifies the current output options established by the SET OUTPUT command SYNCHRONIZE VECTOR_ Forces immediate synchronization between MODE the scalar and vector processors (for vectorized programs) 2 Process_Relationships The debugger consists of two parts: A main debugger image (DEBUGSHR.EXE) that contains most of the debugger code and a smaller kernel debugger image (DEBUG.EXE). This separation reduces potential interference between the debugger and the program being debugged and also makes it possible to have a multiprocess debugging configuration. When you start the debugger, a process is created to run the main debugger. Regardless of the configuration (default or multiprocess), the presence of a main debugger running in some process establishes a unique debugging session. When you bring a program under debugger control, the main debugger spawns a subprocess to run the program along with the kernel debugger. In the multiprocess configuration, the program being debugged runs in several processes. Each process that is running one or more images under debugger control is also running a local copy of the kernel debugger. The main debugger, running in its own process, communicates with the other processes through their kernel debuggers. Although all processes of a multiprocess configuration must be in the same job, they do not have to be related in a particular process/subprocess hierarchy. Moreover, the program images running in separate processes do not have to communicate with each other. 2 Compaq_DECwindows_Interface The debugger has a Compaq DECwindows Motif for OpenVMS user interface for workstations. When using this interface, you interact with the debugger by using a mouse and pointer to choose items from menus, click on buttons, select names in windows, and so on. The default DECwindows interface provides the basic debugging and convenience features that you will need most of the time. You can customize the Compaq DECwindows Motif for OpenVMS user interface with many of the special features of the command interface by modifying the control-panel buttons and their associated commands or by adding new buttons. You can customize other Compaq DECwindows Motif for OpenVMS user interface features by modifying the debugger resource file (DECW$USER_ DEFAULTS:VMSDEBUG.DAT). Occasionally, you may find you prefer to disable the Compaq DECwindows Motif for OpenVMS user interface, in order to use the somewhat faster command-line interface. If you redefine the DBG$DECW$DISPLAY logical name, as follows, you can use the debugger command-line interface while retaining a windows interface for your application: $ DEFINE DBG$DECW$DISPLAY " " For complete information about the Compaq DECwindows Motif for OpenVMS user interface, see the OpenVMS Debugger Manual. 3 Invocation To invoke the debugger's Compaq DECwindows Motif for OpenVMS user interface from the DCL command line, issue the following command: $ DEBUG/KEEP 3 Online_Help To access online help within the Compaq DECwindows Motif for OpenVMS user interface, choose one of the following items from the Help menu on the debugger's main window: o On Context: context-sensitive help. o On Window: task-oriented help. o On Help: how to use online help. o On Version: copyright and version information. o On Commands: debugger command help. o On Commands, Messages item: diagnostic message help. 3 DBG$DECW$DISPLAY_Logical_Name Specifies the debugger interface (Compaq DECwindows Motif for OpenVMS or command) or the display device (if you are displaying the interface on a workstation). By default, DBG$DECW$DISPLAY is either undefined or has the same definition as the application-wide logical name DECW$DISPLAY (see help on Logical_Names). The Compaq DECwindows Motif for OpenVMS user interface is the default on workstations. To display the command interface instead of the Compaq DECwindows Motif for OpenVMS user interface, enter the following definition before starting the debugger: $ DEFINE DBG$DECW$DISPLAY " " For complete information about the Compaq DECwindows Motif for OpenVMS user interface, see the debugger's Compaq DECwindows Motif for OpenVMS documentation. 2 Commands_Disabled_in_DECwindows The following commands are disabled in the debugger's Compaq DECwindows Motif for OpenVMS user interface. Many of them are relevant only to the command interface's screen mode. ATTACH SELECT CANCEL MODE (SET,SHOW) ABORT_KEY CANCEL WINDOW (SET,SHOW) KEY DEFINE/KEY (SET,SHOW) MARGINS DELETE/KEY SET MODE [NO]KEYPAD DISPLAY SET MODE [NO]SCREEN EXAMINE/SOURCE SET MODE [NO]SCROLL EXPAND SET OUTPUT [NO]TERMINAL EXTRACT (SET,SHOW) TERMINAL HELP (SET,SHOW) WINDOW MOVE (SHOW,CANCEL) DISPLAY SAVE SHOW SELECT SCROLL SPAWN The debugger issues an error message if you try to enter any of these disabled commands at the command prompt or when the debugger executes a command procedure containing any of these commands. The MONITOR command works only with the Compaq DECwindows Motif for OpenVMS user interface (because the command uses the Monitor View). 2 Keypad_Definitions_CI This help topic describes the keypad definitions in the debugger's command interface. For information on keypad definitions in the graphical user interface (GUI), type HELP Keypad_Definitions_GUI. On Digital VT-series terminals and MicroVAX workstations, you can use the numeric keypad to enter debugger commands provided you are in "keypad mode." Keypad mode is enabled by default, but can be disabled and enabled by the SET MODE [NO]KEYPAD commands. In keypad mode, keypad keys are bound to commonly used debugger commands such as STEP, GO and EXAMINE. Most keys are bound to screen mode commands, to help you manipulate the predefined screen displays efficiently. Some keys are "terminated": the corresponding command is executed immediately. Others are not: you can enter additional parameters to the command before terminating it with a carriage return or the Enter key. Also, some keys echo on the terminal while others do not, depending on the key. You can define your own keypad definitions with the DEFINE/KEY command. 3 DEFAULT Keypad definitions when +--------+--------+--------+--------+ you do not use the GOLD | | Help | Set | | or BLUE key. | GOLD | Keypad | Mode | BLUE | | | Default| Screen | | For more information +--------+--------+--------+--------+ see help on: | Src LH1| | | Disp | |Inst RH1| Scroll | Disp | next | KEYPAD BLUE | Out S45| Up | next | S12345 | KEYPAD GOLD +--------+--------+--------+--------+ KEYPAD STATE_KEYS | Exam | | | | | Scroll | Source | Scroll | Go | Ctrl/W does a | Left | .0\%PC | Right | | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. | | | Select | | | Exam | Scroll | Scroll | E | | | Down | next | N | +--------+--------+--------+ T | | | | E | | Step | Reset | R | | | | | +-----------------+--------+--------+ 3 GOLD Keypad definitions when +--------+--------+--------+--------+ you press the GOLD key. | | Help |Set Mode| | | GOLD | Keypad | No | BLUE | Reset cancels the | | Gold | Screen | | GOLD key. +--------+--------+--------+--------+ |Inst LH1| | Set | | For more information, | Reg RH1| Scroll | Process| | see help on: | Out S45| Top | next | | +--------+--------+--------+--------+ KEYPAD BLUE | Scroll | | Scroll | Select | KEYPAD DEFAULT | Left | Show | Right | Source | KEYPAD STATE_KEYS | 255 | Calls | 255 | next | +--------+--------+--------+--------+ Ctrl/W does a | Exam | | Select | | DISPLAY/REFRESH | prev | Scroll | Output | E | in screen mode. | | Bottom | next | N | +--------+--------+--------+ T | | | | E | | Step/Into | Reset | R | | | | | +-----------------+--------+--------+ 3 BLUE Keypad definitions when +--------+--------+--------+--------+ you press the BLUE key. | | Help | | | | GOLD | Keypad | Disp | BLUE | "..." means you must | | Blue | Gener | | type more input after +--------+--------+--------+--------+ pressing the key. |2 SRC Qn| Scroll | 2 SRC | Disp | | 2 INST | Up | at | Src H1 | Reset cancels the | at RQn | ... | Q1,Q2 | Out S45| BLUE key. +--------+--------+--------+--------+ | Scroll | Show | Scroll | Select | For more information, | Left | Calls | Right | Inst | see help on: | ... | 3 | ... | next | +--------+--------+--------+--------+ KEYPAD DEFAULT |3 SRC Sn| Scroll | 3 SRC | | KEYPAD GOLD | 3 INST | Down | at | E | KEYPAD STATE_KEYS | at RSn | ... |S1,S2,S3| N | +--------+--------+--------+ T | Ctrl/W does a | | | E | DISPLAY/REFRESH | Step/Over | Reset | R | in screen mode. | | | | +-----------------+--------+--------+ 3 MOVE Keypad definitions in +--------+--------+--------+--------+ the MOVE state when you | | Help | Set | | do not use GOLD or BLUE. | GOLD | Keypad | Mode | BLUE | | | Move | Screen | | For more information, +--------+--------+--------+--------+ see help on: | Src LH1| | | Disp | |Inst RH1| Move | Disp | next | KEYPAD BLUE | Out S45| Up | next | S12345 | KEYPAD GOLD +--------+--------+--------+--------+ KEYPAD STATE_KEYS | | Exam | | | | Move | Source | Move | Go | Ctrl/W does a | Left | .0\%PC | Right | | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. | | | Select | | | Exam | Move | Scroll | E | | | Down | next | N | +--------+--------+--------+ T | | | | E | | Step | Reset | R | | | | | +-----------------+--------+--------+ 3 EXPAND Keypad definitions in +--------+--------+--------+--------+ the EXPAND state when | | Help | Set | | you do not use the GOLD | GOLD | Keypad | Mode | BLUE | or BLUE key. | | Expand | Screen | | +--------+--------+--------+--------+ For more information, | Src LH1| | | Disp | see help on: |Inst RH1| Expand | Disp | next | | Out S45| Up | next | S12345 | KEYPAD BLUE +--------+--------+--------+--------+ KEYPAD GOLD | | Exam | | | KEYPAD STATE_KEYS | Expand | Source | Expand | Go | | Left | .0\%PC | Right | | Ctrl/W does a +--------+--------+--------+--------+ DISPLAY/REFRESH | | | Select | | in screen mode. | Exam | Expand | Scroll | E | | | Down | next | N | +--------+--------+--------+ T | | | | E | | Step | Reset | R | | | | | +-----------------+--------+--------+ 3 CONTRACT Keypad definitions in +--------+--------+--------+--------+ the CONTRACT state when | | Help | Set | | you do not use the GOLD | GOLD | Keypad | Mode | BLUE | or BLUE key. | |Contract| Screen | | +--------+--------+--------+--------+ For more information, | Src LH1| Expand | | Disp | see help on: |Inst RH1| Up= | Disp | next | | Out S45| -1 | next | S12345 | KEYPAD BLUE +--------+--------+--------+--------+ KEYPAD GOLD | Expand | Exam | Expand | | KEYPAD STATE_KEYS | Left= | Source | Right= | Go | | -1 | .0\%PC | -1 | | Ctrl/W does a +--------+--------+--------+--------+ DISPLAY/REFRESH | | Expand | Select | | in screen mode. | Exam | Down= | Scroll | E | | | -1 | next | N | +--------+--------+--------+ T | | | | E | | Step | Reset | R | | | | | +-----------------+--------+--------+ 3 MOVE_GOLD Keypad definitions in +--------+--------+--------+--------+ the MOVE state when | | Help |Set Mode| | you press the GOLD key. | GOLD | Keypad | No | BLUE | | |MoveGold| Screen | | For more information, +--------+--------+--------+--------+ see help on: |Inst LH1| Move | Set | | | Reg RH1| Up= | Process| | KEYPAD BLUE | Out S45| 999 | next | | KEYPAD DEFAULT +--------+--------+--------+--------+ KEYPAD STATE_KEYS | Move | | Move | Select | | Left= | Show | Right= | Source | Ctrl/W does a | 999 | Calls | 999 | next | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. | Exam | Move | Select | | | prev | Down= | Output | E | | | 999 | next | N | +--------+--------+--------+ T | | | | E | | Step/Into | Reset | R | | | | | +-----------------+--------+--------+ 3 EXPAND_GOLD Keypad definitions in +--------+--------+--------+--------+ the EXPAND state when | | Help |Set Mode| | you press the GOLD key. | GOLD | Keypad | No | BLUE | | |ExpaGold| Screen | | For more information, +--------+--------+--------+--------+ see help on: |Inst LH1| Expand | Set | | | Reg RH1| Up= | Process| | KEYPAD BLUE | Out S45| 999 | next | | KEYPAD DEFAULT +--------+--------+--------+--------+ KEYPAD STATE_KEYS | Expand | | Expand | Select | | Left= | Show | Right= | Source | Ctrl/W does a | 999 | Calls | 999 | next | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. | Exam | Expand | Select | | | prev | Down= | Output | E | | | 999 | next | N | +--------+--------+--------+ T | | | | E | | Step/Into | Reset | R | | | | | +-----------------+--------+--------+ 3 CONTRACT_GOLD Keypad definitions in +--------+--------+--------+--------+ the CONTRACT state when | | Help |Set Mode| | you press the GOLD key. | GOLD | Keypad | No | BLUE | | |CntrGold| Screen | | For more information, +--------+--------+--------+--------+ see help on: |Inst LH1| Expand | Set | | | Reg RH1| Up= | Process| | KEYPAD BLUE | Out S45| -999 | next | | KEYPAD DEFAULT +--------+--------+--------+--------+ KEYPAD STATE_KEYS | Expand | | Expand | Select | | Left= | Show | Right= | Source | Ctrl/W does a | -999 | Calls | -999 | next | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. | Exam | Expand | Select | | | prev | Down= | Output | E | | | -999 | next | N | +--------+--------+--------+ T | | | | E | | Step/Into | Reset | R | | | | | +-----------------+--------+--------+ 3 MOVE_BLUE Keypad definitions in +--------+--------+--------+--------+ the MOVE state when | | Help | | | you press the BLUE key. | GOLD | Keypad | Disp | BLUE | | |MoveBlue| Gener | | For more information +--------+--------+--------+--------+ see help on: |2 SRC Qn| | 2 SRC | Disp | | 2 INST | Move | at | Src H1 | KEYPAD DEFAULT | at RQn | Up=5 | Q1,Q2 | Out S45| KEYPAD GOLD +--------+--------+--------+--------+ KEYPAD STATE_KEYS | | Show | | Select | | Move | Calls | Move | Inst | Ctrl/W does a | Left=10| 3 |Right=10| next | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. |3 SRC Sn| | 3 SRC | | | 3 INST | Move | at | E | | at RSn | Down=5 |S1,S2,S3| N | +--------+--------+--------+ T | | | | E | | Step/Over | Reset | R | | | | | +-----------------+--------+--------+ 3 EXPAND_BLUE Keypad definitions in +--------+--------+--------+--------+ the EXPAND state when | | Help | | | you press the BLUE key. | GOLD | Keypad | Disp | BLUE | | |ExpaBlue| Gener | | For more information +--------+--------+--------+--------+ see help on: |2 SRC Qn| | 2 SRC | Disp | | 2 INST | Expand | at | Src H1 | KEYPAD DEFAULT | at RQn | Up=5 | Q1,Q2 | Out S45| KEYPAD GOLD +--------+--------+--------+--------+ KEYPAD STATE_KEYS | | Show | | Select | | Expand | Calls | Expand | Inst | Ctrl/W does a | Left=10| 3 |Right=10| next | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. |3 SRC Sn| | 3 SRC | | | 3 INST | Expand | at | E | | at RSn | Down=5 |S1,S2,S3| N | +--------+--------+--------+ T | | | | E | | Step/Over | Reset | R | | | | | +-----------------+--------+--------+ 3 CONTRACT_BLUE Keypad definitions in +--------+--------+--------+--------+ the CONTRACT state when | | Help | | | you press the BLUE key. | GOLD | Keypad | Disp | BLUE | | |CntrBlue| Gener | | For more information, +--------+--------+--------+--------+ see help on: |2 SRC Qn| Expand | 2 SRC | Disp | | 2 INST | Up= | at | Src H1 | KEYPAD DEFAULT | at RQn | -5 | Q1,Q2 | Out S45| KEYPAD GOLD +--------+--------+--------+--------+ KEYPAD STATE_KEYS | Expand | Show | Expand | Select | | Left= | Calls | Right= | Inst | Ctrl/W does a | -10 | 3 | -10 | next | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. |3 SRC Sn| Expand | 3 SRC | | | 3 INST | Down= | at | E | | at RSn | -5 |S1,S2,S3| N | +--------+--------+--------+ T | | | | E | | Step/Over | Reset | R | | | | | +-----------------+--------+--------+ 3 State_Keys You can use the four scrolling keys (KP8, KP2, KP4, and KP6) to expand, contract, and move displays, depending on the keypad state in effect. Thus, the keys do a SCROLL/UP, /DOWN, /LEFT, or /RIGHT, or a corresponding MOVE. You can press the GOLD key to make the operation to advance more than one line or column. The commands apply to the current scrolling display. Pressing KP3 selects the current scrolling display from the display circular list. Four keys on the LK201 keyboard let you set the keypad state to DEFAULT, MOVE, EXPAND, or CONTRACT. The keypad state changes the definitions of KP8, KP2, KP4, and KP6. The meaning of all other keys remains unchanged. If you do not have an LK201 keyboard with the F17-F20 keys on it, you can get the same effect by typing the corresponding command: F17 F18 F19 F20 SET KEY/STATE=DEFAULT or +--------+--------+--------+--------+ SET KEY/STATE=MOVE | | | | | SET KEY/STATE=EXPAND | DEFAULT| MOVE | EXPAND |CONTRACT| SET KEY/STATE=CONTRACT | | | | | +--------+--------+--------+--------+ For example, in the MOVE state (key F18), pressing KP2 moves the default scrolling display down by one character position, and pressing GOLD-KP2 moves the display down by a larger increment. The keypad remains in the MOVE state until you select another state, such as the DEFAULT state (key F17). 3 Summary Summary of debugger +--------+--------+--------+--------+ keypad definitions. | | | | | | GOLD | Help | Screen | BLUE | For more information, | | | Mode | | see help on: +--------+--------+--------+--------+ | Select | | | Disp | KEYPAD BLUE | Screen | Up | Disp | next | KEYPAD DEFAULT | Layout | | next | at FS | KEYPAD GOLD +--------+--------+--------+--------+ KEYPAD STATE_KEYS | | | | | | Left | Where | Right | Go | Ctrl/W does a | | am I? | | | DISPLAY/REFRESH +--------+--------+--------+--------+ in screen mode. | | | | | | Exam | Down | Select | E | | | | next | N | +--------+--------+--------+ T | | | | E | | Step | Reset | R | | | | | +-----------------+--------+--------+ 2 Keypad_Definitions_GUI This section describes the keypad definitions in the debugger's graphical user interface. For information on the keypad definitions in the command interface, type HELP Keypad_ Definitions_CI. On workstations running the debugger's GUI, you can use the numeric keypad to enter predefined debugger commands, as follows: Key Predefined Command KP0 Step/Line KP1 Examine KPcomma Go GOLD-KP0 Step/Into BLUE-KP0 Step/Over GOLD-KP1 Examine^ KP5 Show Calls GOLD-KP5 Show Calls 3 To issue one of these commands, press the key indicated, followed by the Enter key on the keypad. You can change the commands represented by each key, or map commands to other keys on your keyboard, by customizing the EnterCmdOnCmdLine entry in the debugger resource file. For more information, see the OpenVMS Debugger Manual. If you are mapping to other keys, you also need to consult the key designations listed in the KeySym Encoding chapter of the X and Motif Quick Reference Guide. Users of the debugger's command interface keypad definitions should note that you do not need to be in keypad mode to use keypad definitions in the GUI. 2 Language_Support On VAX processors, you can use the debugger with programs written in the following Compaq languages: Ada BASIC BLISS C C++ COBOL DIBOL Fortran MACRO-32 Pascal PL-I RPG II SCAN On Alpha processors, you can use the debugger with programs written in the following Compaq languages: Ada BASIC BLISS C C++ COBOL Fortran MACRO-32 MACRO-64 Pascal PL/I 3 Overview The debugger recognizes the syntax, data typing, and scoping rules of each language. It also recognizes each language's operators and expression syntax. Therefore, when using debugger commands you can specify variables and other program entities as you might in the source code of the program. You can also compute the value of a source-language expression using the syntax of that language. This appendix describes debugging techniques that are common to most of the supported languages. The help topics provide further information specific to each language: o Supported operators in language expressions o Supported constructs in language expressions and address expressions o Supported data types o Any other language-specific information, including restrictions in debugger support, if any For more information about language-specific debugger support, refer to the documentation furnished with a particular language. If your program is written in more than one language, you can change the debugging context from one language to another during a debugging session. Use the SET LANGUAGE command with the keyword corresponding to your language choice. On VAX processors, you can specify one of the following keywords: ADA BASIC BLISS C C++ COBOL DIBOL FORTRAN MACRO PASCAL PLI RPG SCAN UNKNOWN On Alpha processors, you can specify one of the following keywords: ADA AMACRO BASIC BLISS C C++ COBOL FORTRAN MACRO MACRO64 PASCAL UNKNOWN When you are debugging a program written in an unsupported language, enter the SET LANGUAGE UNKNOWN command. To maximize the usability of the debugger with unsupported languages, this setting 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. For information about the operators and constructs that are recognized when the language is set to UNKNOWN, type Help Language_UNKNOWN. 3 Ada The following subtopics describe debugger support for Ada. For information specific to Ada tasking programs, see also the debugger manual. 4 Ada_Names_and_Symbols The following subtopics describe debugger support for Ada names and symbols, including predefined attributes. Note that parts of names may be language expressions-for example, attributes such as 'FIRST or 'POS. This affects how you use the EXAMINE, EVALUATE, and DEPOSIT commands with such names. For examples of enumeration types, type Help Specifying_Attributes_ with_Enumeration_Types. 5 Ada_Names Supported Ada names follow: Kind of Name Debugger Support Lexical Full support for Ada rules for the syntax of elements identifiers. Function designators that are operator symbols (for example, + and *) rather than identifiers must be prefixed with %NAME. Also, the operator symbol must be enclosed in quotation marks. Full support for Ada rules for numeric literals, character literals, string literals, and reserved words. The debugger accepts signed integer literals in the range -2147483648 to 2147483647. Depending on context and architecture, the debugger interprets floating-point types as F_ floating, D_floating, G_floating, H_floating, S_ floating, or T_floating. Indexed Full support. components Slices You can examine and evaluate an entire slice or an indexed component of a slice. You can deposit only to an indexed component of a slice. You cannot deposit an entire slice. Selected Full support, including use of the keyword all in components .all. Literals Full support, including the keyword null. Boolean Full support (TRUE, FALSE). symbols Aggregates You can examine the entire record and array objects with the EXAMINE command. You can deposit a value in a component of an array or record. You cannot use the DEPOSIT command with aggregates, except to deposit character string values. 5 Predefined_Attributes Supported Ada predefined attributes follow. Note that the debugger SHOW SYMBOL/TYPE command provides the same information that is provided by the P'FIRST, P'LAST, P'LENGTH, P'SIZE, and P'CONSTRAINED attributes. Attribute Debugger Support P'CONSTRAINEDFor a prefix P that denotes a record object with discriminants. The value of P'CONSTRAINED reflects the current state of P (constrained or unconstrained). P'FIRST For a prefix P that denotes an enumeration type or a subtype of an enumeration type. Yields the lower bound of P. P'FIRST For a prefix P that is appropriate for an array type, or that denotes a constrained array subtype. Yields the lower bound of the first index range. P'FIRST(N) For a prefix P that is appropriate for an array type, or that denotes a constrained array subtype. Yields the lower bound of the Nth index range. P'LAST For a prefix P that denotes an enumeration type, or a subtype of an enumeration type. Yields the upper bound of P. P'LAST For a prefix P that is appropriate for an array type, or that denotes a constrained array subtype. Yields the upper bound of the first index range. P'LAST(N) For a prefix P that is appropriate for an array type, or that denotes a constrained array subtype. Yields the upper bound of the Nth index range. P'LENGTH For a prefix P that is appropriate for an array type, or that denotes a constrained array subtype. Yields the number of values of the first index range (zero for a null range). P'LENGTH(N) For a prefix P that is appropriate for an array type, or that denotes a constrained array subtype. Yields the number of values of the Nth index range (zero for a null range). P'POS(X) For a prefix P that denotes an enumeration type or a subtype of an enumeration type. Yields the position number of the value X. The first position is 0. P'PRED(X) For a prefix P that denotes an enumeration type or a subtype of an enumeration type. Yields the value of type P which has a position number one less than that of X. P'SIZE For a prefix P that denotes an object. Yields the number of bits allocated to hold the object. P'SUCC(X) For a prefix P that denotes an enumeration type or a subtype of an enumeration type. Yields the value of type P which has a position number one more than that of X. P'VAL(N) For a prefix P that denotes an enumeration type or a subtype of an enumeration type. Yields the value of type P which has the position number N. The first position is 0. 6 Specifying_Attributes_with_Enumeration_Types Consider the following declarations: type DAY is (MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY,SUNDAY); MY_DAY : DAY; The following examples show the use of attributes with enumeration types. Note that you cannot use the EXAMINE command to determine the value of attributes, because attributes are not variable names. You must use the EVALUATE command instead. For the same reason, attributes can appear only on the right of the := operator in a DEPOSIT command. DBG> EVALUATE DAY'FIRST MON DBG> EVALUATE DAY'POS(WEDNESDAY) 2 DBG> EVALUATE DAY'VAL(4) FRI DBG> DEPOSIT MY_DAY := TUESDAY DBG> EVALUATE DAY'SUCC(MY_DAY) WED DBG> DEPOSIT . := DAY'PRED(MY_DAY) DBG> EXAMINE . EXAMPLE.MY_DAY: MONDAY DBG> EVALUATE DAY'PRED(MY_DAY) %DEBUG-W-ILLENUMVAL, enumeration value out of legal range 6 Resolving_Overloaded_Enumeration_Literals Consider the following declarations: type MASK is (DEC,FIX,EXP); type CODE is (FIX,CLA,DEC); MY_MASK : MASK; MY_CODE : CODE; In the following example, the qualified expression CODE'(FIX) resolves the overloaded enumeration literal FIX, which belongs to both type CODE and type MASK: DBG> DEPOSIT MY_CODE := FIX %DEBUG-W-NOUNIQUE, symbol 'FIX' is not unique DBG> SHOW SYMBOL/TYPE FIX data EXAMPLE.FIX enumeration type (CODE, 3 elements), size: 1 byte data EXAMPLE.FIX enumeration type (MASK, 3 elements), size: 1 byte DBG> DEPOSIT MY_CODE := CODE'(FIX) DBG> EXAMINE MY_CODE EXAMPLE.MY_CODE: FIX 4 Operators_and_Expressions The following sections describe debugger support for Ada operators and language expressions. 5 Operators_in_Language_Expressions Supported Ada operators in language expressions include: Kind Symbol Function Prefix + Unary plus (identity) Infix + Addition Infix * Multiplication Infix / Division Infix MOD Modulus Infix REM Remainder Infix ** Exponentiation (VAX specific) Prefix ABS Absolute value Infix & Concatenation (only string types) Infix = Equality (only scalar and string types) Infix /= Inequality (only scalar and string types) Infix > Greater than (only scalar and string types) Infix >= Greater than or equal (only scalar and string types) Infix < Less than (only scalar and string types) Infix <= Less than or equal (only scalar and string types) Prefix NOT Logical NOT Infix AND Logical AND (not for bit arrays) Infix OR Logical OR (not for bit arrays) Infix XOR Logical exclusive OR (not for bit arrays) The debugger does not support the following items: o Operations on entire arrays or records o The short-circuit control forms: and then, or else o The membership tests: in, not in o User-defined operators 5 Language_Expressions Supported Ada expressions include: Kind of Expression Debugger Support Type No support for any of the explicit type conversions conversions specified in Ada. However, the debugger performs certain implicit type conversions between numeric types during the evaluation of expressions. The debugger converts lower-precision types to higher-precision types before evaluating expressions involving types of different precision: o If integer and floating-point types are mixed, the integer type is converted to floating-point type. o If integer and fixed-point types are mixed, the integer type is converted to fixed-point type. o If integer types of different sizes are mixed (for example, byte-integer and word-integer), the one with the smaller size is converted to the larger size. Subtypes Full support. Note that the debugger denotes subtypes and types that have range constraints as "subrange" types. Qualified Supported as required to resolve overloaded expressions enumeration literals (literals that have the same identifier but belong to different enumeration types). The debugger does not support qualified expressions for any other purpose. Allocators No support for any operations with allocators. Universal No support. expressions 4 Data_Types Supported Ada data types follow: Ada Data Type Operating System Data Type Name INTEGER Longword Integer (L) SHORT_INTEGER Word Integer (W) SHORT_SHORT_INTEGER Byte Integer (B) SYSTEM.UNSIGNED_QUADWORD Quadword Unsigned (QU) SYSTEM.UNSIGNED_LONGWORD Longword Unsigned (LU) SYSTEM.UNSIGNED_WORD Word Unsigned (WU) SYSTEM.UNSIGNED_BYTE Byte Unsigned (BU) FLOAT F_Floating (F) SYSTEM.F_FLOAT F_Floating (F) SYSTEM.D_FLOAT D_Floating (D) LONG_FLOAT D_Floating (D), if pragma LONG_FLOAT (D_FLOAT) is in effect. G_Floating (G), if pragma LONG_FLOAT (G_FLOAT) is in effect. SYSTEM.G_FLOAT G_Floating (G) SYSTEM.H_FLOAT H_Floating (H) (VAX specific) LONG_LONG_FLOAT H_Floating (H) (VAX specific) IEEE_SINGLE_FLOAT S_Floating (FS) (Alpha specific) IEEE_DOUBLE_FLOAT T_Floating (FT) (Alpha specific) Fixed (None) STRING ASCII Text (T) BOOLEAN Aligned Bit String (V) BOOLEAN Unaligned Bit String (VU) Enumeration For any enumeration type whose value fits into an unsigned byte or word: Byte Unsigned (BU) or Word Unsigned (WU), respectively. Otherwise: No corresponding operating system data type. Arrays (None) Records (None) Access (pointers) (None) Tasks (None) 4 Compiling_and_Linking The Ada predefined units in the ADA$PREDEFINED program library on your system have been compiled with the /NODEBUG qualifier. Before using the debugger to refer to names declared in the predefined units, you must first copy the predefined unit source files using the ACS EXTRACT SOURCE command. Then, you must compile the copies into the appropriate library with the /DEBUG qualifier, and relink the program with the /DEBUG qualifier. If you use the /NODEBUG qualifier with one of the Ada compilation commands, only global symbol records are included in the modules for debugging. Global symbols in this case are names that the program exports to modules in other languages by means of the Ada export pragmas: EXPORT_PROCEDURE EXPORT_VALUED_PROCEDURE EXPORT_FUNCTION EXPORT_OBJECT EXPORT_EXCEPTION PSECT_OBJECT The /DEBUG qualifier on the ACS LINK command causes the linker to include all debugging information in the closure of the specified unit in the executable image. 4 Source_Display Source code may not be available for display for the following reasons that are specific to Ada programs: o Execution is paused within Ada initialization or elaboration code, for which no source code is available. o The copied source file is not in the program library where the unit was originally compiled. o The external source file is not where it was when the unit was originally compiled. o The source file has been modified since the executable image was generated, and the original copied source file or external source file no longer exists. The following paragraphs explain how to control the display of source code with Ada programs. If the compiler command's /COPY_SOURCE qualifier (the default) was in effect when you compiled your program, the debugger obtains the displayed Ada source code from the copied source files located in the program library where the program was originally compiled. If you compiled your program with the /NOCOPY_SOURCE qualifier, the debugger obtains the displayed Ada source code from the external source files associated with your program's compilation units. The file specifications of the copied or external source files are embedded in the associated object files. For example, if you have used the ACS COPY UNIT command to copy units, or the DCL command COPY or BACKUP to copy an entire library, the debugger still searches the original program library for copied source files. If, after copying, the original units have been modified or the original library has been deleted, the debugger may not find the original copied source files. Similarly, if you have moved the external source files to another disk or directory, the debugger may not find them. In such cases, use the SET SOURCE command to locate the correct files for source display. You can specify a search list of one or more program library or source code directories. For example (ADA$LIB is the logical name that the program library manager equates to the current program library): DBG> SET SOURCE ADA$LIB,DISK:[SMITH.SHARE.ADALIB] The SET SOURCE command does not affect the search list for the external source files that the debugger fetches when you use the debugger EDIT command. To tell the EDIT command where to look for your source files, use the SET SOURCE/EDIT command. 4 EDIT_Command With Ada programs, by default the debugger EDIT command fetches the external source file that was compiled to produce the compilation unit in which execution is currently paused. You do not edit the copied source file, in the program library, that the debugger uses for source display. The file specifications of the source files you edit are embedded in the associated object files during compilation (unless you specify /NODEBUG). If some source files have been relocated after compilation, the debugger may not find them. In such cases, you can use the debugger SET SOURCE/EDIT command to specify a search list of one or more directories where the debugger should look for source files. For example: DBG> SET SOURCE/EDIT [],USER:[JONES.PROJ.SOURCES] The SET SOURCE/EDIT command does not affect the search list for copied source files that the debugger uses for source display. The SHOW SOURCE/EDIT command displays the source-file search list currently being used for the EDIT command. The CANCEL SOURCE/EDIT command cancels the source-file search list currently being used for the EDIT command and restores the default search mode. 4 GO_and_STEP_Commands Note the following points about using the GO and STEP commands with Ada programs: o When starting a debugging session, use the GO command rather than the STEP command to avoid stepping through compiler- generated initialization code. - Use the GO command to go directly to the preset breakpoint at the start of the main program, past the initialization and package elaboration code. - Use the GO command and breakpoints to suspend execution at the start of the elaboration of library packages, before execution reaches the main program. For information on how to monitor the package elaboration phase, type Help Debugging_Ada_Library_Packages. o If a line contains more than one statement, a STEP command executes all the statements on that line as part of a single step. o Ada task entry calls are not the same as subprogram calls because task entry calls are queued and may not execute right away. If you use the STEP command to move execution into a task entry call, the results might not be what you expect. 4 Debugging_Ada_Library_Packages When an Ada main program (or a non-Ada main program that calls Ada code) is executed, initialization code is executed for the Ada run-time library and elaboration code for all library units that the program depends on. The elaboration code causes the library units to be elaborated in appropriate order before the main program is executed. Library specifications, bodies, and some of their subunits are also elaborated by this process. The elaboration of library packages accomplishes the following operations: o Causes package declarations to take effect o Initializes any variables whose declaration includes initialization code o Executes any sequence of statements that appear between the begin and end statements of package bodies When you bring an Ada program under debugger control, execution is paused initially before the initialization code is executed and before the elaboration of library units. For example: DBG> RUN FORMS Language: ADA, Module: FORMS Type GO to reach main program DBG> At that point, before typing GO to get to the start of the main program, you can step through and examine parts of the library packages by setting breakpoints at the package specifications or bodies you are interested in. You then use the GO command to get to the start of each package. To set a breakpoint on a package body, specify the package unit name with the SET BREAK command. To set a breakpoint on a package specification, specify the package unit name followed by a trailing underscore character (_). Even if you have set a breakpoint on a package body, the break will not occur if the debugger module for that body is not set. If the module is not set, the break will occur at the package specification. This effect occurs because the debugger automatically sets modules for the specifications of packages named in with clauses; it does not automatically set modules for the associated package bodies (see the Language_Support Ada subtopic Setting_Modules). Also, to set a breakpoint on a subprogram declared in a package specification, you must set the module for the package body. Note that the compiler generates unique names for subprograms declared in library packages that are or could be overloaded names. The debugger uses these unique names in its output, and requires them in commands where the names would otherwise be ambiguous. For more information on resolving overloaded names and symbols, see the Language_Support Ada subtopic Resolving_ Overloaded_Names_and_Symbols. 4 Predefined_Breakpoints When you start the debugger with an Ada program (or a non-Ada program that calls Ada code), two breakpoints that are associated with Ada tasking exception events are automatically established. These breakpoints are established automatically during debugger initialization when the Ada run-time library is present. When you enter a SHOW BREAK command under these conditions, the following breakpoints are displayed: DBG> SHOW BREAK Predefined breakpoint on ADA event "EXCEPTION_TERMINATED" for any value Predefined breakpoint on ADA event "DEPENDENTS_EXCEPTION" for any value DBG> 4 Monitoring_Exceptions The debugger recognizes three kinds of exceptions in Ada programs: o A user-defined exception-an exception declared with the Ada reserved word exception in an Ada compilation unit o An Ada predefined exception, such as PROGRAM_ERROR or CONSTRAINT_ERROR o Any other (non-Ada) exception or condition The following subtopics explain how to monitor such exceptions. 5 Monitoring_Any_Exception The SET BREAK/EXCEPTION command enables you to set a breakpoint on any exception or condition. This includes certain conditions that are signaled internally within the Ada run-time library. These conditions are an implementation mechanism; they do not represent program failures, and they cannot be handled by Ada exception handlers. If these conditions appear while you are debugging your program, you may want to consider specifying the kind of exceptions when setting breakpoints. The following example shows a tracepoint occurring for an Ada CONSTRAINT_ERROR exception as the result of a SET TRACE/EXCEPTION command: DBG> SET TRACE/EXCEPTION DBG> GO . . . %ADA-F-CONSTRAINT_ERRO, CONSTRAINT_ERROR -ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000A7C trace on exception preceding ADA$RAISE\ADA$RAISE_CONDITION.%LINE 333+12 . . . In the next example, the SHOW CALLS command displays a traceback of the calls leading to the subprogram where the exception occurred or to which the exception was raised: DBG> SET BREAK/EXCEPTION DO (SHOW CALLS) DBG> GO . . . %SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=000008AF, PSL=03C000A2 break on exception preceding SYSTEM_OPS.DIVIDE.%LINE 17+6 17: return X/Y; module name routine name line rel PC abs PC *SYSTEM_OPS DIVIDE 17 00000015 000008AF *PROCESSOR PROCESSOR 19 000000AE 00000BAD *ADA$ELAB_PROCESSOR ADA$ELAB_PROCESSOR 00000009 00000809 LIB$INITIALIZE 00000054 00000C36 SHARE$ADARTL 00000000 000398BE *ADA$ELAB_PROCESSOR ADA$ELAB_PROCESSOR 0000001B 0000081B LIB$INITIALIZE 0000002F 00000C21 In this example, the condition SS$_INTDIV is raised at line 17 of the subprogram DIVIDE in the package SYSTEM_OPS. The example shows an important effect: some conditions (such as SS$_ INTDIV) are treated as being equivalent to some Ada predefined exceptions. The matching of a condition and an Ada predefined exception is performed by the condition handler provided by Ada for any frame that includes an exception part. Therefore, when an exception breakpoint or tracepoint is triggered by a condition that has an equivalent Ada exception name, the message displays only the system condition code name, and not the name of the corresponding Ada exception. 5 Monitoring_Specific_Exceptions Whenever an exception is raised, the debugger sets the following built-in symbols. You can use them to qualify exception breakpoints or tracepoints so that they trigger only on certain exceptions. %EXC_ A string that names the facility that issued the FACILITY exception. The facility name for Ada predefined exceptions and user-defined exceptions is ADA. %EXC_NAME An uppercase string that names the exception. If the exception raised is an Ada predefined exception, its name is truncated if it exceeds 15 characters. For example, CONSTRAINT_ERROR is truncated to CONSTRAINT_ERRO. If the exception is a user-defined exception, %EXC_NAME contains the string "EXCEPTION", and the name of the user-defined exception is contained in %ADAEXC_NAME. %ADAEXC_ If the exception raised is user-defined, %ADAEXC_ NAME NAME contains a string that names the exception, and %EXC_NAME contains the string "EXCEPTION". If the exception is not user-defined, %ADAEXC_NAME contains a null string, and the name of the exception is contained in %EXC_NAME. %EXC_NUM The number of the exception. %EXC_ A string that gives the exception severity level (F, SEVERITY E, W, I, S, or ?). 5 Monitoring_Handled_Exceptions_and_Exception_Handlers The SET BREAK/EVENT and SET TRACE/EVENT commands let you set breakpoints and tracepoints on exceptions that are about to be handled by Ada exception handlers. These commands let you observe the execution of each Ada exception handler that gains control. You can specify two event names with these commands: HANDLED Triggers when an exception is about to be handled in an Ada exception handler (includes HANDLED_ OTHERS events). HANDLED_ Triggers only when an exception is about to be OTHERS handled in an Ada exception handler choice others. For example, the following command sets a breakpoint that triggers whenever an exception is about to be handled by an Ada exception handler: DBG> SET BREAK/EVENT=HANDLED When the breakpoint triggers, the debugger identifies the exception that is about to be handled and the exception handler that is about to be executed. You can then use that information to set a breakpoint on a particular handler, or you can enter the GO command, and see which Ada handler next attempts to handle the exception. For example: DBG> GO . . . break on Ada event HANDLED task %TASK 1 is about to handle an exception The Ada exception handler is at: PROCESSOR.%LINE 21 %ADA-F-CONSTRAINT_ERRO, CONSTRAINT_ERROR -ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000A7C DBG> SET BREAK PROCESSOR.%LINE 21; GO 4 Examining_and_Manipulating_Data When examining and manipulating data, note the following considerations: o Before you can examine or deposit into a nonstatic variable (any variable not declared in a library package), its defining subprogram, task, and so on, must be active on the call stack. o Before you can examine, deposit, or evaluate an Ada subprogram formal parameter or an Ada variable, the parameter or variable must be elaborated. In other words, you should step or otherwise move execution past the parameter or variable's declaration. The value contained in any variable or formal parameter whose declaration has not been elaborated might be invalid. In most cases, the debugger enables you to specify variables and expressions in debugger commands exactly as you would specify them in the source code of the program, including use of qualified expressions. The following subtopics discuss some additional points about debugger support for records and access types. 5 Records Note the following points about debugger support for records: o With certain Ada record variables, the debugger fails to show the record components correctly (possibly with a NOACCESSR error message) when the type declaration is in a different scope than the record (symbol) declaration. o With variant records, the debugger lets you examine or assign a value to a component of a variant part that is not active. But because this is an illegal action in Ada, the debugger also issues an informational message. For example, assume that record REC1 has a variant field named STATUS and that the value of STATUS is such that REC1.COMP3 is inactive: DBG> EXAMINE REC1.COMP3 %DEBUG-I-BADDISCVAL, incorrect value of 1 in discriminant field STATUS MAIN.REC1.COMP3: 438 5 Access_Types Note the following points about debugger support for access types: o The debugger does not support allocators, so you cannot create new access objects with the debugger. o When you specify the name of an access object with the EXAMINE command, the debugger displays the memory location of the object it designates. o To examine the value of a designated object, you must use selected component notation, specifying .ALL. For example, to examine the value of a record access object designated by A: DBG> EXAMINE A.ALL EXAMPLE.A.ALL NAME(1..10): "John Doe " AGE : 6 NEXT: 1462808 o To examine one component of a designated object, you can omit .ALL from the selected component syntax. For example: DBG> EXAMINE A.NAME EXAMPLE.A.ALL.NAME(1..10): "John Doe " The following example shows the debugger support for incomplete types. Consider the following declarations: package P is type T is private; private type T_TYPE; type T is access T_TYPE; end P; package body P is type T_TYPE is record A: NATURAL := 5; B: NATURAL := 4; end record; T_REC: T_TYPE; T_PTR: T := new T_TYPE'(T_REC); end P; with P; use P; procedure INCOMPLETE is VAR: T; begin . . . end INCOMPLETE; The debugger does not have complete information about the type T, so you cannot manipulate the variable VAR. However, the debugger does have information about objects declared in the package body P. Thus, you can manipulate the variables T_PTR and T_REC. 4 Module_Names_and_Path_Names The names of Ada debugger modules are the same as the names of the corresponding compilation units, with the following provision. To eliminate ambiguity, an underscore character (_) is appended to a specification name to distinguish it from its body name. For example, TEST (body), TEST_ (specification). To determine the exact names of the modules in your program, use the SHOW MODULE command. In most cases when you specify a path name, the debugger can distinguish body names and specification names from the context. Therefore, use this naming convention only if needed to resolve an ambiguity. When the debugger language is set to Ada, the debugger generally constructs pathnames that follow the Ada rules, using selected component notation to separate path name elements (with other languages, a backslash is used to separate elements). For example: TEST_.A1 ! A1 is declared in the package ! specification of unit TEST TEST.B1 ! B1 is declared in the package ! body of unit TEST The maximum length that you can specify for a subunit path name (expanded name) is 247 characters. When a use clause makes a symbol declared in a package directly visible outside the package, you do not need to specify an expanded name (package-name.symbol) to refer to the symbol, either in the program itself or in debugger commands. The SHOW SYMBOL/USE_CLAUSE command identifies any package (library or otherwise) that a specified block, subprogram, or package mentions in a use clause. If the entity specified is a package (library or otherwise), the command also identifies any block, subprogram, package, and so on, that names the specified module in a use clause. For example: DBG> SHOW SYMBOL/USE_CLAUSE B_ package spec B_ used by: F uses: A_ If a label has been assigned to a loop statement or declare block in the source code, the debugger displays the label; otherwise, the debugger displays LOOP$n for a loop statement or BLOCK$n for a declare block, where n is the line number at which the statement or block begins. 4 Symbol_Lookup_Conventions For Ada programs, when you do not specify a path name (including an Ada expanded name), the debugger searches the run-time symbol table as follows. 1. The debugger looks for the symbol within the block or routine surrounding the current PC value (where execution is currently paused). 2. If the symbol is not found, the debugger then searches any package that is mentioned in a use clause. The debugger does not distinguish between a library package and a package whose declaration is in the same module as the current scope region. If the same symbol is declared in two or more packages that are visible, the symbol is not unique (according to Ada rules), and the debugger issues a message similar to the following: %DEBUG-E-NOUNIQUE, symbol 'X' is not unique 3. If the symbol is still not found, the debugger searches the call stack and other scopes, as for other languages. 4 Setting_Modules When you or the debugger sets an Ada module, by default the debugger also sets any "related" module (that is, any module whose symbols should be visible within the module being set). Such modules are related to the one being set through either a with-clause or a subunit relationship. Related module setting takes place as follows. If M1 is the module that is being set, then the following modules are considered related and are also set: o If M1 is a library body, the debugger also sets the associated library specification, if any. o If M1 is a subunit, the debugger also sets its parent unit and, therefore, any parent of the parent. o If M1 mentions a library package P1 in a with clause, the debugger also sets P1's specification. Neither the body of P1 nor any possible subunits of P1 are set, because symbols declared within them should not be visible outside. If P1's specification mentions a package P2 in a with clause, the debugger also sets P2's specification. Likewise, if P2's specification mentions a package P3 in a with clause, the debugger also sets P3's specification, and so on. The specifications of all such library packages are set so that you can access data components (for example, record components) that may have been declared in other packages. o If M1 mentions a library subprogram in a with clause, the debugger does not set the subprogram. Only the subprogram name needs to be visible in M1 (no declaration within a library subprogram should be visible outside the subprogram). Therefore, the debugger inserts the name of the library subprogram into the RST when M1 is set. If debugger performance becomes a problem as more modules are set, use the SET MODE NODYNAMIC command, which disables related module setting as well as dynamic module setting. You must then set individual modules explicitly with the SET MODULE command. By default, the SET MODULE command sets related modules simultaneously with the module specified in the command. The SET MODULE/NORELATED command sets only the modules you specify explicitly. However, if you use SET MODULE/NORELATED, you may find that a symbol that is declared in another unit and that should be visible at the point of execution is no longer visible or that a symbol which should be hidden by a redeclaration of that same symbol is now visible. The CANCEL MODULE/NORELATED command deletes from the RST only the modules you specify explicitly. This command, which is the default, deletes related modules in a manner consistent with the intent of Ada's scope and visibility rules. The exact effect depends on module relationships. The distinction between related and directly related for subunits is analogous to that for library packages. 5 Setting_Modules_for_Package_Bodies Modules for package bodies are not automatically set by the debugger. You may need to set the modules for library package bodies yourself so that you can debug the package body or debug subprograms declared in the corresponding package specification. 4 Resolving_Overloaded_Names_and_Symbols When you encounter overloaded names and symbols, the debugger issues a message like the following: %DEBUG-E-NOTUNQOVR, symbol 'ADD' is overloaded use SHOW SYMBOL to find the unique symbol names If the overloaded symbol is an enumeration literal, you can use qualified expressions to resolve the overloadings. If the overloaded symbol represents a subprogram or task accept statement, you can use the unique name generated by the compiler for the debugger. The compiler always generates unique names for subprograms declared in library package specifications, because the names might later be overloaded in the package body. Unique names are generated for task accept statements and subprograms declared in other places only if the task accept statements or subprograms are actually overloaded. Overloaded task accept statement names and subprogram names are distinguished by a suffix consisting of two underscores followed by an integer that uniquely identifies the given symbol. You must use the unique naming notation in debugger commands to uniquely specify a subprogram whose name is overloaded. However, if there is no ambiguity, you do not need to use the unique name, even though one was generated. 4 CALL_Command With Ada programs, you can use the CALL command reliably only with a subprogram that has been exported. An exported subprogram must be a library subprogram or must be declared in the outermost declarative part of a library package. The CALL command does not check whether or not the subprogram can be exported, nor does it check the parameter-passing mechanisms that you specify. Note that you cannot use the CALL command to modify the value of a parameter. A CALL command may result in a deadlock if it is entered when the Ada run-time library is executing. The run-time library routines acquire and release internal locks that allow the routines to operate in a tasking environment. Deadlock can result if a subprogram called from the CALL command requires a resource that has been locked by an executing run-time library routine. To avoid this situation in a nontasking program, enter the CALL command immediately before or after an Ada statement has been executed. However, this approach is not sufficient to assure that deadlock will not occur in a tasking program, as some other task may be executing a run-time library routine at the time of the call. If you must use the CALL command in a tasking program, you can avoid deadlock if the called subprogram does not do any tasking or input-output operations. 3 BASIC The following subtopics describe debugger support for BASIC. 4 Operators_in_Language_Expressions Supported BASIC operators in language expressions include: Kind Symbol Function Prefix + Unary plus Infix + Addition, String concatenation Infix * Multiplication Infix / Division Infix ** Exponentiation Infix ^ Exponentiation Infix = Equal to Infix <> Not equal to Infix >< Not equal to Infix > Greater than Infix >= Greater than or equal to Infix => Greater than or equal to Infix < Less than Infix <= Less than or equal to Infix =< Less than or equal to Prefix NOT Bit-wise NOT Infix AND Bit-wise AND Infix OR Bit-wise OR Infix XOR Bit-wise exclusive OR Infix IMP Bit-wise implication Infix EQV Bit-wise equivalence 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for BASIC follow: Symbol Construct ( ) Subscripting :: Record component selection 4 Data_Types Supported BASIC data types follow: BASIC Data Type Operating System Data Type Name BYTE Byte Integer (B) WORD Word Integer (W) LONG Longword Integer (L) SINGLE F_Floating (F) DOUBLE D_Floating (D) GFLOAT G_Floating (G) HFLOAT (VAX specific) H_Floating (H) DECIMAL Packed Decimal (P) STRING ASCII Text (T) RFA (None) RECORD (None) Arrays (None) 4 Compiling_for_Debugging If you make changes to a program in the BASIC environment and attempt to compile the program with the /DEBUG qualifier without first saving or replacing the program, BASIC signals the error "Unsaved changes, no source line debugging available." To avoid this problem, save or replace the program, and then recompile the program with the /DEBUG qualifier. 4 Constants BASIC constants of the form [radix]"numeric-string"[type] (such as "12.34"GFLOAT) or the form n% (such as 25% for integer 25) are not supported in debugger expressions. 4 Evaluating_Expressions Expressions that overflow in the BASIC language do not necessarily overflow when evaluated by the debugger. The debugger tries to compute a numerically correct result, even when the BASIC rules call for overflows. This difference is particularly likely to affect DECIMAL computations. 4 Line_Numbers The sequential line numbers that you refer to in a debugging session and that are displayed in a source code display are those generated by the compiler. When a BASIC program includes or appends code from another file, the included lines of code are also numbered in sequence by the compiler. 4 Stepping_into_Routines The STEP/INTO command is useful for examining external functions. However, if you use this command to stop execution at an internal subroutine or a DEF, the debugger initially steps into run-time library (RTL) routines, providing you with no useful information. In the following example, execution is paused at line 8, at a call to Print_routine: . . . -> 8 GOSUB Print_routine 9 STOP . . . 20 Print_routine: 21 IF Competition = Done 22 THEN PRINT "The winning ticket is #";Winning_ticket 23 ELSE PRINT "The game goes on." 24 END IF 25 RETURN A STEP/INTO command would cause the debugger to step into the relevant RTL code and would inform you that no source lines are available for display. On the other hand, a STEP command alone would cause the debugger to proceed directly to source line 9, past the call to Print_routine. To examine the source code of subroutines or DEF functions, set a breakpoint on the routine label (for example, enter the SET BREAK PRINT_ROUTINE command). You can then suspend execution exactly at the start of the routine (line 20, in this example) and then step directly into the code. 4 Symbolic_References All variable and label names within a single BASIC program must be unique. Otherwise the debugger cannot resolve the symbol ambiguity. 4 Watchpoints In BASIC, you can set a watchpoint only on variables that are declared in COMMON or MAP statements (static variables). You cannot set watchpoints on variables explicitly declared with the DECLARE statement. 3 BLISS The following subtopics describe debugger support for BLISS. 4 Operators_in_Language_Expressions Supported BLISS operators in language expressions include: Kind Symbol Function Prefix . Indirection Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix MOD Remainder Infix ^ Left shift Infix EQL Equal to Infix EQLU Equal to Infix EQLA Equal to Infix NEQ Not equal to Infix NEQU Not equal to Infix NEQA Not equal to Infix GTR Greater than Infix GTRU Greater than unsigned Infix GTRA Greater than unsigned Infix GEQ Greater than or equal to Infix GEQU Greater than or equal to unsigned Infix GEQA Greater than or equal to unsigned Infix LSS Less than Infix LSSU Less than unsigned Infix LSSA Less than unsigned Infix LEQ Less than or equal to Infix LEQU Less than or equal to unsigned Infix LEQA Less than or equal to unsigned Prefix NOT Bit-wise NOT Infix AND Bit-wise AND Infix OR Bit-wise OR Infix XOR Bit-wise exclusive OR Infix EQV Bit-wise equivalence 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for BLISS follow: Symbol Construct [ ] Subscripting [fldname] Field selection Bit field selection 4 Data_Types Supported BLISS data types follow: BLISS Data Type Operating System Data Type Name BYTE Byte Integer (B) WORD Word Integer (W) LONG Longword Integer (L) QUAD (Alpha specific) Quadword (Q) BYTE UNSIGNED Byte Unsigned (BU) WORD UNSIGNED Word Unsigned (WU) LONG UNSIGNED Longword Unsigned (LU) QUAD UNSIGNED (Alpha Quadword Unsigned (QU) specific) VECTOR (None) BITVECTOR (None) BLOCK (None) BLOCKVECTOR (None) REF VECTOR (None) REF BITVECTOR (None) REF BLOCK (None) REF BLOCKVECTOR (None) 3 CC The following subtopics describe debugger support for C. 4 Operators_in_Language_Expressions Supported C operators in language expressions include: Kind Symbol Function Prefix * Indirection Prefix & Address of Prefix sizeof size of Infix + Addition Infix * Multiplication Infix / Division Infix % Remainder Infix << Left shift Infix >> Right shift Infix == Equal to Infix != Not equal to Infix > Greater than Infix >= Greater than or equal to Infix < Less than Infix <= Less than or equal to Prefix ~ Bit-wise NOT (tilde) Infix & Bit-wise AND Infix | Bit-wise OR Infix ^ Bit-wise exclusive OR Prefix ! Logical NOT Infix && Logical AND Infix || Logical OR Because the exclamation point (!) is an operator in C, it cannot be used as the comment delimiter. When the language is set to C, the debugger instead accepts /* as the comment delimiter. The comment continues to the end of the current line. (A matching */ is neither needed nor recognized.) To permit debugger log files to be used as debugger input, the debugger still recognizes an exclamation point (!) as a comment delimiter if it is the first nonspace character on a line. The debugger accepts the prefix asterisk (*) as an indirection operator in both C language expressions and debugger address expressions. In address expressions, prefix "*" is synonymous to prefix "." or "@" when the language is set to C. The debugger does not support any of the assignment operators in C (or any other language) in order to prevent unintended modifications to the program being debugged. Hence such operators as =, +=, ++, and -- are not recognized. To alter the contents of a memory location, you must use an explicit DEPOSIT command. 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for C follow: Symbol Construct [ ] Subscripting . Structure component selection (period) -> Pointer dereferencing 4 Data_Types Supported C data types follow: C Data Type Operating System Data Type Name __int64 (Alpha specific) Quadword Integer (Q) unsigned __int64 (Alpha Quadword Unsigned (QU) specific) __int32 (Alpha specific) Longword Integer (L) unsigned __int32 (Alpha Longword Unsigned (LU) specific) int Longword Integer (L) unsigned int Longword Unsigned (LU) __int16 (Alpha specific) Word Integer (W) unsigned __int16 (Alpha Word Unsigned (WU) specific) short int Word Integer (W) unsigned short int Word Unsigned (WU) char Byte Integer (B) unsigned char Byte Unsigned (BU) float F_Floating (F) __f_float (Alpha F_Floating (F) specific) double D_Floating (D) double G_Floating (G) __g_float (Alpha G_Floating (G) specific) float (Alpha specific) IEEE S_Floating (FS) __s_float (Alpha IEEE S_Floating (FS) specific) double (Alpha specific) IEEE T_Floating (FT) __t_float (Alpha IEEE T_Floating (FT) specific) enum (None) struct (None) union (None) Pointer Type (None) Array Type (None) Floating-point numbers of type float may be represented by F_ Floating or IEEE S_Floating, depending on compiler switches. Floating-point numbers of type double may be represented by IEEE T_Floating, D_Floating, or G_Floating, depending on compiler switches. 4 Case_Sensitivity Symbol names are case sensitive for language C, meaning that uppercase and lowercase letters are treated as different characters. 4 Static_and_Nonstatic_Variables Variables of the following storage classes are allocated statically: static, globaldef, globalref, and extern. Variables of the following storage classes are allocated nonstatically (on the stack or in registers): auto and register. Such variables can be accessed only when their defining routine is active (on the call stack). 4 Scalar_Variables You can specify scalar variables of any C type in debugger commands exactly as you would specify them in the source code of the program. The following paragraphs provide additional information about char variables and pointers. The char variables are interpreted by the debugger as byte integers, not ASCII characters. To display the contents of a char variable ch as a character, you must use the /ASCII qualifier: DBG> EXAMINE/ASCII ch SCALARS\main\ch: "A" You also must use the /ASCII qualifier when depositing into a char variable, to translate the byte integer into its ASCII equivalent. For example: DBG> DEPOSIT/ASCII ch = 'z' DBG> EXAMINE/ASCII ch SCALARS\main\ch: "z" The following example shows use of pointer syntax with the EXAMINE command. Assume the following declarations and assignments: static long li = 790374270; static int *ptr = &li; DBG> EXAMINE *ptr *SCALARS\main\ptr: 790374270 4 Arrays The debugger handles C arrays as for most other languages. That is, you can examine an entire array aggregate, a slice of an array, or an individual array element, using array syntax (for example EXAMINE arr[3]). And you can deposit into only one array element at a time. 4 Character_Strings Character strings are implemented in C as null-terminated ASCII strings (ASCIZ strings). To examine and deposit data in an entire string, use the /ASCIZ (or /AZ) qualifier so that the debugger can interpret the end of the string properly. You can examine and deposit individual characters in the string using the C array subscripting operators ([ ]). When you examine and deposit individual characters, use the /ASCII qualifier. Assume the following declarations and assignments: static char *s = "vaxie"; static char **t = &s; The EXAMINE/AZ command displays the contents of the character string pointed to by *s and **t: DBG> EXAMINE/AZ *s *STRING\main\s: "vaxie" DBG> EXAMINE/AZ **t **STRING\main\t: "vaxie" The DEPOSIT/AZ command deposits a new ASCIZ string in the variable pointed to by *s. The EXAMINE/AZ command displays the new contents of the string: DBG> DEPOSIT/AZ *s = "DEC C" DBG> EXAMINE/AZ *s, **t *STRING\main\s: "DEC C" **STRING\main\t: "DEC C" You can use array subscripting to examine individual characters in the string and deposit new ASCII values at specific locations within the string. When accessing individual members of a string, use the /ASCII qualifier. A subsequent EXAMINE/AZ command shows the entire string containing the deposited value: DBG> EXAMINE/ASCII s[3] [3]: " " DBG> DEPOSIT/ASCII s[3] = "-" DBG> EXAMINE/AZ *s, **t *STRING\main\s: "VAX-C" **STRING\main\t: "VAX-C" 4 Structures_and_Unions You can examine structures in their entirety or on a member-by- member basis, and deposit data into structures one member at a time. To reference members of a structure or union, use the usual C syntax for such references. That is, if variable p is a pointer to a structure, you can reference member y of that structure with the expression p ->y. If variable x refers to the base of the storage allocated for a structure, you can refer to a member of that structure with the x.y expression. The debugger uses C type-checking rules to reference members of a structure or union. For example, in the case of x.y, y need not be a member of x; it is treated as an offset with a type. When such a reference is ambiguous-when there is more than one structure with a member y-the debugger attempts to resolve the reference according to the following rules. The same rules for resolving the ambiguity of a reference to a member of a structure or union apply to both x.y and p ->y. o If only one of the members, y, belongs in the structure or union, x, that is the one that is referenced. o If only one of the members, y, is in the same scope as x, then that is the one that is referenced. You can always give a path name with the reference to x to narrow the scope that is used and to resolve the ambiguity. The same path name is used to look up both x and y. 3 C++_V5.5_and_Later (Alpha only.) On Alpha systems, the OpenVMS debugger provides enhanced support for debugging C++ modules compiled with the Version 5.5 compiler or later (Alpha only). The debugger supports the following C++ features: o C++ names and expressions, including: - Explicit and implicit this pointer to refer to class members - Scope resolution operator (::) - Member access operators: period (.) and right arrow (->) - Template instantiations o Setting breakpoints in: - Member functions, including static and virtual functions - Overloaded functions - Constructors and destructors - Template instantiations - Operators o Calling functions, including overloaded functions o Debugging programs containing a mixture of C++ code and code in other languages The following subtopics describe debugger support for C++ (Compiler Version 5.5 (Alpha only)). 4 Operators_in_Language_Expressions Supported C++ operators in language expressions follow: Kind Symbol Function Prefix * Indirection Prefix & Address of Prefix sizeof size of Prefix - Unary minus (negation) Infix + Addition Infix - Subtraction Infix * Multiplication Infix / Division Infix % Remainder Infix << Left shift Infix >> Right shift Infix == Equal to Infix != Not equal to Infix > Greater than Infix >= Greater than or equal to Infix < Less than Infix <= Less than or equal to Prefix ~ Bit-wise NOT (tilde) Infix & Bit-wise AND Infix | Bit-wise OR Infix ^ Bit-wise exclusive OR Prefix ! Logical NOT Infix && Logical AND Infix || Logical OR Because the exclamation point (!) is an operator, it cannot be used in C++ programs as a comment delimiter. However, to permit debugger log files to be used as debugger input, the debugger interprets ! as a comment delimiter when it is the first nonspace character on a line. In C++ language mode, the debugger also interprets /* or // as preceding a comment that continues to the end of the current line. The debugger accepts the asterisk (*) prefix as an indirection operator in both C++ language expressions and debugger address expressions. In address expressions, the * prefix is synonymous with either the period (.) prefix or at sign (@) prefix when the debugger is in C++ language mode. To prevent unintended modifications to the program being debugged, the debugger does not support any of the assignment operators in C++ (or any other language). Thus, such operators as =, +=, -=, ++, and -- are not recognized in debugger commands. To alter the contents of a memory location, you must use the debugger DEPOSIT command. 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for C++ follow: Symbol Construct [ ] Subscripting . Structure component selection (period) -> Pointer dereferencing :: Scope resolution 4 Data_Types Supported C++ data types follow: C++ Data Type Operating System Data Type Name __int64 (Alpha) Quadword Integer (Q) unsigned __int64 (Alpha) Quadword Unsigned (QU) __int32 (Alpha) Longword Integer (L) unsigned __int32 (Alpha) Longword Unsigned (LU) int Longword Integer (L) unsigned int Longword Unsigned (LU) __int16 (Alpha) Word Integer (W) unsigned __int16 (Alpha) Word Unsigned (WU) short int Word Integer (W) unsigned short int Word Unsigned (WU) char Byte Integer (B) unsigned char Byte Unsigned (BU) float F_Floating (F) __f_float (Alpha) F_Floating (F) double D_Floating (D) double G_Floating (G) __g_float (Alpha) G_Floating (G) float (Alpha) IEEE S_Floating (FS) __s_float (Alpha) IEEE S_Floating (FS) double (Alpha) IEEE T_Floating (FT) __t_float (Alpha) IEEE T_Floating (FT) enum (None) struct (None) class (None) union (None) Pointer Type (None) Array Type (None) Floating-point numbers of type float may be represented by F_ Floating or IEEE S_Floating, depending on compiler switches. Floating-point numbers of type double may be represented by IEEE T_Floating, D_Floating, or G_Floating, depending on compiler switches. 4 Case_Sensitivity Symbol names are case sensitive in C++. This means that uppercase and lowercase letters are treated as different characters. 4 Displaying_Information_About_a_Class Use the command SHOW SYMBOL to display static information about a class declaration. Use the command EXAMINE to view dynamic information about class objects (see Displaying Information About an Object). The command SHOW SYMBOL/FULL displays the class type declaration, including: Data members (including static data members) Member functions (including static member functions) Constructors and destructors Base classes and derived classes For example: dbg> SHOW SYMBOL /TYPE C type C struct (C, 13 components), size: 40 bytes overloaded name C instance C::C(void) instance C::C(const C &) dbg> SHOW SYMBOL /FULL C type C struct (C, 13 components), size: 40 bytes inherits: B1, size: 24 bytes, offset: 0 bytes B2, size: 24 bytes, offset: 12 bytes contains the following members: overloaded name C::g instance C::g(int) instance C::g(long) instance C::g(char) j : longword integer, size: 4 bytes, offset: 24 bytes s : longword integer, size: 4 bytes, address: # [static] overloaded name C int ==(C &) C & =(const C &) void h(void) [virtual] ~C(void) __vptr : typed pointer type, size: 4 bytes, offset: 4 bytes __bptr : typed pointer type, size: 4 bytes, offset: 8 bytes structure has been padded, size: 4 bytes, offset: 36 bytes overloaded name C instance C::C(void) instance C::C(const C &) DBG> Note that SHOW SYMBOL/FULL does not display members of base classes or derived classes. Use the commands SHOW SYMBOL/FULL base_class_name and SHOW SYMBOL/FULL derived_class_name to display information about members of those classes. For example: DBG> SHOW SYMBOL /FULL B1 type B1 struct (B1, 8 components), size: 24 bytes inherits: virtual A is inherited by: C contains the following members: i : longword integer, size: 4 bytes, offset: 0 bytes overloaded name B1 void f(void) B1 & =(const B1 &) void h(void) [virtual] __vptr : typed pointer type, size: 4 bytes, offset: 4 bytes __bptr : typed pointer type, size: 4 bytes, offset: 8 bytes structure has been padded, size: 12 bytes, offset: 12 bytes overloaded name B1 instance B1::B1(void) instance B1::B1(const B1 &) DBG> Use the command SHOW SYMBOL/FULL class_member_name to display information about class members. For example: DBG> SHOW SYMBOL /FULL j record component C::j address: offset 24 bytes from beginning of record atomic type, longword integer, size: 4 bytes record component A::j address: offset 4 bytes from beginning of record atomic type, longword integer, size: 4 bytes DBG> Use the SHOW SYMBOL/FULL command to display detailed information about an object. Note that SHOW SYMBOL does not currently support qualified names. For example, the following commands are not currently supported: SHOW SYMBOL object_name.function_name SHOW SYMBOL class_name::member_name 4 Displaying_Information_About_an_Object The debugger uses C++ symbol lookup rules to display information about objects. Use the command EXAMINE to display the current value of an object. For example: DBG> EXAMINE a CXXDOCEXAMPLE\main\a: struct A i: 0 j: 1 __vptr: 131168 DBG> You can also display individual object members using the member access operators, period (.) and right arrow (->), with the EXAMINE command. For example: DBG> EXAMINE ptr CXXDOCEXAMPLE\main\ptr: 40 DBG> EXAMINE *ptr *CXXDOCEXAMPLE\main\ptr: struct A i: 0 j: 1 __vptr: 131168 DBG> EXAMINE a.i CXXDOCEXAMPLE\main\a.i: 0 DBG> EXAMINE ptr->i CXXDOCEXAMPLE\main\ptr->i: 0 DBG> The debugger correctly interprets virtual inheritance. For example: DBG> EXAMINE c CXXDOCEXAMPLE\main\c: struct C inherit B1 inherit virtual A i: 8 j: 9 __vptr: 131200 i: 10 __vptr: 131232 __bptr: 131104 inherit B2 inherit virtual A (already printed, see above) i: 11 __vptr: 131280 __bptr: 131152 j: 12 __vptr: 131232 __bptr: 131104 DBG> Use the scope resolution operator (::) to reference global variables, to reference hidden members in base classes, to explicitly reference a member that is inherited, or otherwise to name a member hidden by the current context. For example: DBG> EXAMINE c.j CXXDOCEXAMPLE\main\c.j: 12 DBG> EXAMINE c.A::j CXXDOCEXAMPLE\main\c.A::j: 9 DBG> EXAMINE x CXXDOCEXAMPLE\main\x: 101 DBG> EXAMINE ::x CXXDOCEXAMPLE\x: 13 DBG> To resolve ambiguous member references, the debugger lists the members that satisfy the reference and requests an unambiguous reference to the member. For example: DBG> EXAMINE c.i %DEBUG-I-AMBIGUOUS, 'i' is ambiguous, matching the following CXXDOCEXAMPLE\main\c.B1::i CXXDOCEXAMPLE\main\c.B2::i %DEBUG-E-REENTER, reenter the command using a more precise pathname DBG> EXAMINE c.B1::i CXXDOCEXAMPLE\main\c.B1::i: 10 DBG> Use the scope resolution operator (::) to refer to static data members. For example: DBG> EXAMINE c.s CXXDOCEXAMPLE\main\c.s: 42 DBG> EXAMINE C::s C::s: 42 DBG> Use the SHOW SYMBOL/FULL to display the class type of an object (see Displaying Information About a Class). 4 Setting_Watchpoints You can set watchpoints on objects. All nonstatic data members are watched (including those in base classes). Static data members are not watched when you set a watchpoint on the object. However, you can explicitly set watchpoints on static data members. For example: DBG> SET WATCH c %DEBUG-I-WPTTRACE, non-static watchpoint, tracing every instruction DBG> GO watch of CXXDOCEXAMPLE\main\c.i at CXXDOCEXAMPLE\main\%LINE 50+8 50: c.B2::i++; old value: 11 new value: 12 break at CXXDOCEXAMPLE\main\%LINE 51 51: c.s++; DBG> SET WATCH c.s DBG> GO watch of CXXDOCEXAMPLE\main\c.s at CXXDOCEXAMPLE\main\%LINE 51+16 51: c.s++; old value: 43 new value: 44 break at CXXDOCEXAMPLE\main\%LINE 53 53: b1.f(); DBG> 4 Debugging_Functions The debugger uses C++ symbol lookup rules to display information on member functions. For example: DBG> EXAMINE /SOURCE b1.f module CXXDOCEXAMPLE 14: void f() {} DBG> SET BREAK B1::f DBG> GO break at routine B1::f 14: void f() {} DBG> The debugger correctly interprets references to the this pointer. For example: DBG> EXAMINE this B1::f::this: 16 DBG> EXAMINE *this *B1::f::this: struct B1 inherit virtual A i: 2 j: 3 __vptr: 131184 i: 4 __vptr: 131248 __bptr: 131120 DBG> EXAMINE this->i B1::f::this->i: 4 DBG> EXAMINE this->j B1::f::this->A::j: 3 DBG>EXAMINE i B1::f::this->i: 4 DBG> EXAMINE j B1::f::this->A::j: 3 DBG> The debugger correctly references virtual member functions. For example: DBG> EXAMINE /SOURCE %LINE 53 module CXXDOCEXAMPLE 53: b1.f(); DBG> SET BREAK this->h DBG> SHOW BREAK breakpoint at routine B1::f breakpoint at routine B1::h !! !! We are at the call to B1::f made at 'c.B1::f()'. !! Here this->h matches C::h. !! DBG> GO break at routine B1::f 14: void f() {} DBG> EXAMINE /SOURCE %LINE 54 module CXXDOCEXAMPLE 54: c.B1::f(); DBG> SET BREAK this->h DBG> SHOW BREAK breakpoint at routine B1::f breakpoint at routine B1::h breakpoint at routine C::h !! !! Handling overloaded functions !! DBG> SET BREAK g %DEBUG-I-NOTUNQOVR, symbol 'g' is overloaded overloaded name C::g instance C::g(int) instance C::g(long) instance C::g(char) %DEBUG-E-REENTER, reenter the command using a more precise pathname DBG> SET BREAK g(int) DBG> CANCEL BREAK/ALL DBG> If you try to set a break on an overloaded function, the debugger lists the instances of the function and requests that you specify the correct instance. For example, with Debugger Version 7.2: DBG> SET BREAK g %DEBUG-I-NOTUNQOVR, symbol 'g' is overloaded overloaded name C::g instance void g(int) instance void g(long) instance void g(char *) %DEBUG-E-REENTER, reenter the command using a more precise pathname DBG> SET BREAK g(int) DBG> NOTE The means of displaying and specifying overloaded functions is different than in the OpenVMS Debugger Version 7.1C. The debugger provides support for debugging constructors, destructors, and operators. For example: DBG> SET BREAK C %DEBUG-I-NOTUNQOVR, symbol 'C' is overloaded overloaded name C instance C::C(void) instance C::C(const C &) %DEBUG-E-REENTER, reenter the command using a more precise pathname DBG> SHOW SYMBOL /FULL ~C routine C::~C type signature: ~C(void) code address: #, size: 152 bytes procedure descriptor address: # DBG> SET BREAK %NAME'~C' DBG> SET BREAK %NAME'==' %DEBUG-W-UNALLOCATED, '==' is not allocated in memory (optimized away) %DEBUG-E-CMDFAILED, the SET BREAK command has failed DBG> SHOW SYMBOL /FULL == routine C::== type signature: int ==(C &) address: unallocated DBG> SHOW BREAK breakpoint at routine C::~C DBG> 4 Limitations_on_Debugger_Support_for_C++ The following limitations apply when you debug a C++ program: o You cannot specify a template by name in a debugger command. You must use the name of the instantiation of the template. o In C++, expressions in the instantiated template name can be full constant expressions, such as stack. This form is not yet supported in the debugger; you must enter the value of the expression (for example, if f is 10 in the stack example, you must enter 100). 3 C++ The following subtopics describe debugger support for C++ programs compiled with C++ compiler versions prior to Version 5.5. 4 The_%name_Lexical_Function Use of the %name lexical function is required with debugger commands to reference certain entities in Compaq C++, such as functions and data members. When used, this function is always placed between the command and the reference. Examples of correct usage are shown in the following sections for cases where its use is required. 4 Operators_in_Language_Expressions Supported C++ operators in language expressions include: Kind Symbol Function Prefix * Indirection Prefix & Address of Prefix sizeof size of Infix + Addition Infix * Multiplication Infix / Division Infix % Remainder Infix << Left shift Infix >> Right shift Infix == Equal to Infix != Not equal to Infix > Greater than Infix >= Greater than or equal to Infix < Less than Infix <= Less than or equal to Prefix ~ Bit-wise NOT (tilde) Infix & Bit-wise AND Infix | Bit-wise OR Infix ^ Bit-wise exclusive OR Prefix ! Logical NOT Infix && Logical AND Infix || Logical OR Because the exclamation point (!) is an operator, it cannot be used in C++ programs as a comment delimiter. However, to permit debugger log files to be used as debugger input, the debugger still recognizes an exclamation point as a comment delimiter if it is the first nonspace character on a line. In C++ language mode, the debugger accepts /* as the comment delimiter. The comment continues to the end of the current line. (A matching */ is neither needed nor recognized.) The debugger accepts the asterisk (*) prefix as an indirection operator in both C++ language expressions and debugger address expressions. In address expressions, the * prefix is synonymous to the period (.) prefix or at sign @ prefix when the language is set to C++. To prevent unintended modifications to the program being debugged, the debugger does not support any of the assignment operators in C++ (or any other language). Thus, such operators as =, +=, ++, and -- are not recognized. To alter the contents of a memory location, you must do so with an explicit deposit command. 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for C++ follow: Symbol Construct [ ] Subscripting . Structure component selection (period) -> Pointer dereferencing 4 Data_Types Supported C++ data types follow: C++ Data Type Operating System Data Type Name __int64 (Alpha specific) Quadword Integer (Q) unsigned __int64 (Alpha Quadword Unsigned (QU) specific) __int32 (Alpha specific) Longword Integer (L) unsigned __int32 (Alpha Longword Unsigned (LU) specific) int Longword Integer (L) unsigned int Longword Unsigned (LU) __int16 (Alpha specific) Word Integer (W) unsigned __int16 (Alpha Word Unsigned (WU) specific) short int Word Integer (W) unsigned short int Word Unsigned (WU) char Byte Integer (B) unsigned char Byte Unsigned (BU) float F_Floating (F) __f_float (Alpha F_Floating (F) specific) double D_Floating (D) double G_Floating (G) __g_float (Alpha G_Floating (G) specific) float (Alpha specific) IEEE S_Floating (FS) __s_float (Alpha IEEE S_Floating (FS) specific) double (Alpha specific) IEEE T_Floating (FT) __t_float (Alpha IEEE T_Floating (FT) specific) enum (None) struct (None) union (None) Pointer Type (None) Array Type (None) Floating-point numbers of type float may be represented by F_ Floating or IEEE S_Floating, depending on compiler switches. Floating-point numbers of type double may be represented by IEEE T_Floating, D_Floating, or G_Floating, depending on compiler switches. 4 Case_Sensitivity Symbol names are case sensitive for C++, meaning that uppercase and lowercase letters are treated as different characters. 4 Qualified_Class_Names Discussions in some of the following sections use the term qualified class names to describe how to compose the names of class members when using the debugger. If a class is not defined within another class, the qualified class name is merely the name of the class itself. However, if a class is nested within another class, the name of the immediately containing class must precede it, separated with a pair of colons (::). If the containing class is itself nested, its name must be prefixed, and so on. The following are examples of properly qualified class names: DBG> set break %name 'C::f' ! f is a member of class C DBG> set break %name 'FOO::BAR::BAZ::g' ! g is a member of BAZ, ! which is nested in BAR, ! which is nested in FOO 4 Using_the_Debugger_with_C++_Data This section describes how to use the debugger with C++ data. 5 Nonstatic_Data_Members This section describes how to refer to data members that are not declared static. 6 Noninherited_Data_Members To refer to a nonstatic data member that is defined directly in a C++ class (or a struct or union), use its name just as with a C language struct or union member. The following example shows the correct use of a nonstatic data member reference: DBG> examine x.m, p->m 6 Inherited_Data_Members Currently, debugger support distinguishes nonstatic data members inherited from various base classes by prefixing their names with a sequence of significant base class names on the inheritance path to the member, and then the class that the member is declared in. A base class on a path from an object to a member is significant if the base class in question is derived from using multiple inheritances. Thus, a base class is significant if it is mentioned in a base list containing more than one base specifier. This notation generates the minimum number of base class prefixes necessary to describe the inheritance path to a base class, because it involves naming only those base classes where one must choose where to proceed next when traversing the path. When no multiple inheritance is involved, the reference is of the following form: %name'CLASS::member' To refer to nonstatic data members inherited from base classes of an object, quote the sequence of significant qualified base class names and the member name (separated by double colons) with %name. Specify the sequence of significant base classes, in the order from the object's most derived significant class, to the significant base class closest to the object. For example, consider the inheritance graph for the following declarations: struct A { int a_member; }; struct B : A { int b_member; }; struct C { int c_member; }; struct D : B, C { int d_member; }; struct E : D { int e_member; }; struct F { int f_member; }; struct G : F { int g_member; }; struct H : E, G { int h_member; }; struct I : H { int i_member; }; struct J : I { int j_member; }; static J j_object; Because classes B, C, E and G are mentioned in base lists, which involve multiple inheritance, they are the significant classes that appear as prefixes. The following examples are references to all the members through debugger deposit commands. Note that the class of the inherited member itself appears before the member name, regardless of whether or not the member belongs to a significant class. 6 Inherited_Virtual_Data_Members In the debugger, symbolic access to data members of virtual base classes is currently not supported. The one exception to this is that the pointer member named __bptr is present in such objects. 5 Static_Data_Members To refer to a static data member, quote its qualified class name, two colons (::), and then the member name, with %name. The following examples show the correct use of static data member references: DBG> examine %name 'C::s' DBG> examine %name 'FOO::BAR::BAZ::sdm' 5 Reference_Objects_and_Reference_Members To access the values of objects declared with a reference, use the name of the object. The debugger treats data members declared with a reference type as though they were pointer variables; thus, you must use the * or -> dereference operators on their names. For example, consider the following code: class C { public: int &ref_mem; C(int &arg) : ref_mem(arg) {} }; main() { auto int obj = 5; auto int &ref_obj = obj; auto C c(obj); obj = 23; } . . . The following sequence shows the correct way to use the debugger to examine the members: stepped on return from routine REF\main to REF\main\%LINE 13+16 13: } DBG> examine obj, ref_obj REF\main\obj: 23 REF\main\ref_obj: 23 DBG> examine c REF\main\c ref_mem: 2144211292 DBG> symbolize c.ref_mem address 7FCE1154: REF\main\c DBG> examine *c.ref_mem *REF\main\c.ref_mem: 23 5 Pointers_to_Members Objects that are pointers to members are represented as 64-bit integers. 5 Referencing_Entities_by_Type To examine and display the value of an object or member by type, use the command EXAMINE/TYPE. Similarly, you can modify the value of an expression to be deposited to a type you specify by using the DEPOSIT/TYPE command. With the /TYPE qualifier, the syntax for these commands is as follows: deposit/type=(name) examine/type=(name) The type denoted by name must be the name of a variable or data type declared in the program. The /type qualifier is particularly useful for referencing C++ objects that have been declared with more than one type. 4 Using_the_Debugger_with_C++_Functions This section describes how to reference the various kinds of functions and function arguments. 5 Referring_to_Overloaded_Functions To find the symbolic names of functions in your code, use the SHOW SYMBOL command. If the function is overloaded, use the asterisk wildcard character (*) in the name specification to display the overloaded symbol names. For example, consider the following code: class base { public: base(); base( int ); ~base(); int base_f1(); void base_f2(); void base_f2( int ); void base_f2( char ); }; The following sequence shows how to display overloaded symbols and determine the appropriate function reference: DBG> set break %name 'base::base_f2' %DEBUG-E-NOTUNQOVR, symbol 'base::base_f2' is overloaded use SHOW SYMBOL to find the unique symbol names DBG> show symbol *base_f2 overloaded symbol CXX_T10_179\base::base_f2 overloaded instance CXX_T10_179\base::base_f2__1 overloaded instance CXX_T10_179\base::base_f2__2 overloaded instance CXX_T10_179\base::base_f2__3 DBG> set break %name 'base::base_f2__2' DBG> step stepped to CXX_T10_179\main\%LINE 20 20: x.base_f2(); DBG> step stepped to CXX_T10_179\main\%LINE 21 21: x.base_f2(5); DBG> step break at routine CXX_T10_179\base::base_f2__2 12: void base_f2( int ) {} DBG> step stepped to CXX_T10_179\main\%LINE 22 22: x.base_f2('W'); stepped to CXX_T10_179\main\%LINE 22 DBG> go 'Normal successful completion' DBG> ^Z 5 Referring_to_Static_and_Nonstatic_Member_Functions To refer to a member function, quote, with %name, its qualified class name, two colons (::), and the name of the member function. If the member function is overloaded, append the suffix __integer-number. The following examples show the correct use of member function references: DBG> set break %name 'MYSTRING::length' DBG> set break %name 'MYCOMPLEX::format__1', %name 'MYCOMPLEX::format__2' 5 Referring_to_Constructors To refer to a constructor, state the name. If a constructor is overloaded, append the suffix __integer-number. The following examples show the correct use of constructor references: DBG> set break FOO DBG> set break MYSTRING__1 5 Referring_to_Destructors To refer to a destructor, quote its name, including the tilde (~), with %name. The following example shows the correct use of a destructor reference: DBG> set break %name '~FOO' 5 Referring_to_Conversions To refer to conversion operators from a class SRC to a type dest, quote SRC, two colons (::), and then dest with %name. The set of atomic types is drawn from the following set of names: void char signed_char unsigned_char signed_short unsigned_short int signed_int unsigned_int signed_long unsigned_long float double long_double Pointer types are named (type*). Reference types are named (type&). The types struct, union class and enum are named by their tags and the qualifiers const and volatile precede their types with a space in between. For example: DBG> set break %name 'C::int', %name 'C::(const S)&' 5 Referring_to_User-Defined_Operators The following operators may be overloaded by user-defined functions: + - * / % ^ & | ~ ! = < > += -= *= /= %= ^= &= |= << >> >>= <<= == != <= >= && | ++ -- ->* , -> [] () delete new See Section 7.2 of The Annotated C++ Reference Manual (shipped with C++ documentation) for more details. To refer to such user-defined functions, quote the operator characters with %name. As with regular functions, prefix the string quoted by %name with a qualified class name and two colons (::) if the user-defined operator is a member function. Similarly, if the function is overloaded, append the suffix __integer_number to the operator characters. In particular, this suffix is necessary if both unary and binary instances of an operator such as + are defined, or if prefix instances of ++ or - are defined. The following examples show the correct use of user-defined function references: DBG> set break %name 'MYSTRING::+' DBG> set break %name 'COUNTER::++__1', %name 'COUNTER::++__2' 5 Referring_to_Function_Arguments In debugger referencing, you use this, *this, and this->m as follows: o All nonstatic member functions have a pointer parameter available named this. For example: DBG> examine this o Use *this to examine the prefix object that a member function is invoked against. For example: DBG> examine *this o Use the this parameter to refer to a data member m of the prefix argument to a member function. For example: DBG> examine this->m 3 COBOL The following subtopics describe debugger support for COBOL. 4 Operators_in_Language_Expressions Supported COBOL operators in language expressions include: Kind Symbol Function Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix ** Exponentiation (VAX specific) Infix = Equal to Infix NOT = Not equal to Infix > Greater than Infix NOT < Greater than or equal to Infix < Less than Infix NOT > Less than or equal to Infix NOT Logical NOT Infix AND Logical AND Infix OR Logical OR 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for COBOL follow: Symbol Construct ( ) Subscripting OF Record component selection IN Record component selection 4 Data_Types Supported COBOL data types follow: COBOL Data Type Operating System Data Type Name COMP Longword Integer (L,LU) COMP Word Integer (W,WU) COMP Quadword Integer (Q,QU) COMP-1 F_Floating (F) COMP-1 (Alpha specific) S_Floating (FS) COMP-2 D_Floating (D) COMP-2 (Alpha specific) T_Floating (FT) COMP-3 Packed Decimal (P) INDEX Longword Integer (L) Alphanumeric ASCII Text (T) Records (None) Numeric Unsigned Numeric string, unsigned (NU) Leading Separate Sign Numeric string, left separate sign (NL) Leading Overpunched Sign Numeric string, left overpunched sign (NLO) Trailing Separate Sign Numeric string, right separate sign (NR) Trailing Overpunched Sign Numeric string, right overpunched sign (NRO) Floating-point numbers of type COMP-1 may be represented by F_ Floating or IEEE S_Floating, depending on compiler switches. Floating-point numbers of type COMP-2 may be represented by D_ Floating or IEEE T_Floating, depending on compiler switches. 4 Source_Display The debugger can show source text included in a program with the COPY, COPY REPLACING, or REPLACE statement. However, when COPY REPLACING or REPLACE is used, the debugger shows the original source text instead of the modified source text generated by the COPY REPLACING or REPLACE statement. The debugger cannot show the original source lines associated with the code for a REPORT section. You can see the DATA SECTION source lines associated with a REPORT, but no source lines are associated with the compiled code that generates the report. 4 COBOL_INITIALIZE_Statement_and_Large_Tables_(Arrays)_(Alpha_Only)_ On OpenVMS Alpha systems, the debugger can take an unusually great amount of time and resources if you use the STEP command to execute an INITIALIZE statement in a COBOL program when a large table (array) is being initialized. To work around this problem, set a breakpoint on the first executable line past the INITIALIZE statement, rather than stepping across the INITIALIZE statement. 3 DIBOL (VAX only) 4 Operators_in_Language_Expressions Supported DIBOL operators in language expressions include: Kind Symbol Function Prefix # Round Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix // Division with fractional result Infix .EQ. Equal to Infix .NE. Not equal to Infix .GT. Greater than Infix .GE. Greater than or equal to Infix .LT. Less than Infix .LE. Less than or equal to Infix .NOT. Logical NOT Infix .AND. Logical AND Infix .OR. Logical OR Infix .XOR. Exclusive OR 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for DIBOL follow: Symbol Construct ( ) Substring [ ] Subscripting . Record component selection (period) 4 Data_Types Supported DIBOL data types follow: DIBOL Data Type Operating System Data Type Name I1 Byte Integer (B) I2 Word Integer (W) I4 Longword Integer (L) Pn Packed Decimal String (P) Pn.m Packed Decimal String (P) Dn Numeric String, Zoned Sign (NZ) Dn.m Numeric String, Zoned Sign (NZ) An ASCII Text (T) Arrays (None) Records (None) 3 Fortran The following subtopics describe debugger support for Fortran. 4 Operators_in_Language_Expressions Supported Fortran operators in language expressions include: Kind Symbol Function Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix ** Exponentiation (VAX specific) Infix // Concatenation Infix .EQ. Equal to Infix == Equal to Infix .NE. Not equal to Infix /= Not equal to Infix .GT. Greater than Infix > Greater than Infix .GE. Greater than or equal to Infix >= Greater than or equal to Infix .LT. Less than Infix < Less than Infix .LE. Less than or equal to Infix <= Less than or equal to Prefix .NOT. Logical NOT Infix .AND. Logical AND Infix .OR. Logical OR Infix .XOR. Exclusive OR Infix .EQV. Equivalence Infix .NEQV. Exclusive OR 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for Fortran follow: Symbol Construct ( ) Subscripting . (period) Record component selection % (percent Record component selection sign) 4 Predefined_Symbols Supported Fortran predefined symbols follow: Symbol Description .TRUE. Logical True .FALSE. Logical False 4 Data_Types Supported Fortran data types follow: Fortran Data Type Operating System Data Type Name LOGICAL*1 Byte Unsigned (BU) LOGICAL*2 Word Unsigned (WU) LOGICAL*4 Longword Unsigned (LU) LOGICAL*8 (Alpha Quadword Unsigned (QU) specific) BYTE Byte (B) INTEGER*1 Byte Integer (B) INTEGER*2 Word Integer (W) INTEGER*4 Longword Integer (L) INTEGER*8 (Alpha Quadword Integer (Q) specific) REAL*4 F_Floating (F) REAL*4 (Alpha specific) IEEE S_Floating (FS) REAL*8 D_Floating (D) REAL*8 G_Floating (G) REAL*8 (Alpha specific) IEEE T_Floating (FT) REAL*16 (Alpha specific) H_Floating (H) COMPLEX*8 F_Complex (FC) COMPLEX*8 (Alpha IEEE S_Floating (SC) specific) COMPLEX*16 D_Complex (DC) COMPLEX*16 G_Complex (GC) COMPLEX*16 (Alpha IEEE T_Floating (TC) specific) CHARACTER ASCII Text (T) Arrays (None) Records (None) Even though the data type codes for unsigned integers (BU, WU, LU, QU) are used internally to describe the LOGICAL data types, the debugger (like the compiler) treats LOGICAL variables and values as being signed when they are used in language expressions. The debugger prints the numeric values of LOGICAL variables or expressions instead of .TRUE. or .FALSE. Normally, only the low- order bit of a LOGICAL variable or value is significant (0 is .FALSE. and 1 is .TRUE.). However, Fortran does allow all bits in a LOGICAL value to be manipulated and LOGICAL values can be used in integer expressions. For this reason, it is at times necessary to see the entire integer value of a LOGICAL variable or expression, and that is what the debugger shows. COMPLEX constants such as (1.0,2.0) are not supported in debugger expressions. Floating-point numbers of type REAL*4 and COMPLEX*8 may be represented by F_Floating or IEEE S_Floating, depending on compiler switches. Floating-point numbers of type REAL*8 and COMPLEX*16 may be represented by D_Floating, G_Floating, or IEEE T_Floating, depending on compiler switches. On OpenVMS Alpha systems, the debugger cannot evaluate expressions that contain complex variables. To work around this problem, examine the complex variable and then evaluate the expression using the real and imaginary parts of the complex variable as shown by the EXAMINE command. 4 Initialization_Code When you debug a program that compiled with the /CHECK=UNDERFLOW or /PARALLEL qualifier, a message appears, as in the following example: DBG> RUN FORMS Language: FORTRAN, Module: FORMS Type GO to reach main program DBG> The "Type GO to reach MAIN program" message indicates that execution is supended before the start of the main program, so that you can execute initialization code under debugger control. Entering the GO command places you at the start of the main program. At that point, enter the GO command again to start program execution, as with other types of Fortran programs. 3 MACRO-32 The following subtopics describe debugger support for MACRO-32. 4 Operators_in_Language_Expressions The MACRO-32 language does not have expressions in the same sense as high-level languages. Only assembly-time expressions and only a limited set of operators are accepted. To permit the MACRO-32 programmer to use expressions at debug-time as freely as in other languages, the debugger accepts a number of operators in MACRO- 32 language expressions that are not found in MACRO-32 itself. In particular, the debugger accepts a complete set of comparison and Boolean operators modeled after BLISS. It also accepts the indirection operator and the normal arithmetic operators. Kind Symbol Function Prefix @ Indirection Prefix . Indirection Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix MOD Remainder Infix @ Left shift Infix EQL Equal to Infix EQLU Equal to Infix NEQ Not equal to Infix NEQU Not equal to Infix GTR Greater than Infix GTRU Greater than unsigned Infix GEQ Greater than or equal to Infix GEQU Greater than or equal to unsigned Infix LSS Less than Infix LSSU Less than unsigned Infix LEQ Less than or equal to Infix LEQU Less than or equal to unsigned Prefix NOT Bit-wise NOT Infix AND Bit-wise AND Infix OR Bit-wise OR Infix XOR Bit-wise exclusive OR Infix EQV Bit-wise equivalence 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for MACRO-32 follow: Symbol Construct [ ] Subscripting Bit field selection as in BLISS The DST information generated by the MACRO-32 assembler treats a label that is followed by an assembler directive for storage allocation as an array variable whose name is the label. This enables you to use the array syntax of a high-level language when examining or manipulating such data. In the following example of MACRO-32 source code, the label LAB4 designates hexadecimal data stored in four words: LAB4: .WORD ^X3F,5[2],^X3C The debugger treats LAB4 as an array variable. For example, the following command displays the value stored in each element (word): DBG> EXAMINE LAB4 .MAIN.\MAIN\LAB4 [0]: 003F [1]: 0005 [2]: 0005 [3]: 003C The following command displays the value stored in the fourth word (the first word is indexed as element "0"): DBG> EXAMINE LAB4[3] .MAIN.\MAIN\LAB4[3]: 03C 4 Data_Types MACRO-32 binds a data type to a label name according to the assembler directive that follows the label definition. Supported MACRO-32 directives follow: MACRO-32 Directives Operating System Data Type Name .BYTE Byte Unsigned (BU) .WORD Word Unsigned (WU) .LONG Longword Unsigned (LU) .SIGNED_BYTE Byte Integer (B) .SIGNED_WORD Word Integer (W) .LONG Longword Integer (L) .QUAD Quadword Integer (Q) .F_FLOATING F_Floating (F) .D_FLOATING D_Floating (D) .G_FLOATING G_Floating (G) .H_FLOATING H_Floating (H) (VAX specific) (Not Packed decimal (P) applicable) 4 MACRO-32_Compiler_(AMACRO) (Alpha only) Programmers who are porting applications written in MACRO-32 to Alpha systems use the MACRO-32 compiler (AMACRO). A debugging session for compiled MACRO-32 code is similar to that for assembled code. However, there are some important differences that are described in this section. For complete information on porting these applications, see the Porting VAX MACRO Code from OpenVMS VAX to OpenVMS Alpha manual. 5 Code_Relocation One major difference is the fact that the code is compiled. On a VAX system, each MACRO-32 instruction is a single machine instruction. On an Alpha system, each MACRO-32 instruction may be compiled into many Alpha machine instructions. A major side effect of this difference is the relocation and rescheduling of code if you do not specify /NOOPTIMIZE in your compile command. After you have debugged your code, you can recompile without /NOOPTIMIZE to improve performance. 5 Symbolic_Variables Another major difference between debugging compiled code and debugging assembled code is a new concept to MACRO-2, the definition of symbolic variables for examining routine arguments. On VAX systems, when you were debugging a routine and wanted to examine the arguments, you would typically do something like the following: DBG> EXAMINE @AP ; to see the argument count DBG> EXAMINE @AP+4 ; to examine the first arg or DBG> EXAMINE @AP ; to see arg count DBG> EXAMINE .+4:.+20 ; to see first 5 args On Alpha systems, the arguments do not reside in a vector in memory as they did on VAX systems. Furthermore, there is no AP register on Alpha systems. If you type EXAMINE @AP when debugging MACRO compiled code, the debugger reports that AP is an undefined symbol. In the compiled code, the arguments can reside in some combination of: o Registers o On the stack above the routine's stack frame o In the stack frame, if the argument list was "homed" (that is, placed in the fixed position of the stack frame to resolve VAX AP references) or if there are calls out of the routine that would require the register arguments to be saved The compiler does not require that you read the generated code to locate the arguments. Instead, it provides $ARGn symbols that point to the correct argument locations. $ARG0 is the same as @AP+0 is on VAX systems, that is, the argument count. $ARG1 is the first argument, $ARG2 is the second argument, and so forth. These symbols are defined in CALL_ENTRY and JSB_ENTRY directives, but not in EXCEPTION_ENTRY directives. 5 Locating_Arguments_Without_$ARGn_Symbols There may be additional arguments in your code for which the compiler did not generate a $ARGn symbol. The number of $ARGn symbols defined for a .CALL_ENTRY routine is the maximum number detected by the compiler (either by automatic detection or as specified by MAX_ARGS) or 16, whichever is less. For a .JSB_ENTRY routine, since the arguments are homed in the caller's stack frame and the compiler cannot detect the actual number, it always creates eight $ARGn symbols. In most cases, you can easily find any additional arguments, but in some cases you cannot. 5 Arguments_That_Are_Easy_to_Locate You can easily find additional arguments if: o The argument list is not homed, and $ARGn symbols are defined to $ARG7 or higher. If the argument list is not homed, the $ARGn symbols $ARG7 and above always point into the list of parameters passed as quadwords on the stack. Subsequent arguments will be in quadwords following the last defined $ARGn symbol. o The argument list has been homed, and you want to examine an argument that is less than or equal to the maximum number detected by the compiler (either by automatic detection or as specified by MAX_ARGS). If the argument list is homed, $ARGn symbols always point into the homed argument list. Subsequent arguments will be in longwords following the last defined $ARGn symbol. For example, you can examine arguments beyond the eighth argument in a JSB routine (where the argument list must be homed in the caller), as follows: DBG> EX $ARG8 ; highest defined $ARGn . . . DBG> EX .+4 ; next arg is in next longword . . . DBG> EX .+4 ; and so on This example assumes that the caller detected at least ten arguments when homing the argument list. To find arguments beyond the last $ARGn symbol in a routine that did not home the arguments, proceed exactly as in the previous example except substitute EX .+8 for EX .+4. 5 Arguments_That_Are_Not_Easy_to_Locate You cannot easily find additional arguments if: o The argument list is homed, and you want to examine arguments beyond the number detected by the compiler. The $ARGn symbols point to the longwords that are stored in the homed argument list. The compiler only moves as many arguments as it can detect into this list. Examining longwords beyond the last argument that was homed will result in examining various other stack context. o The argument list is not homed, and $ARGn symbols are defined only as high as $ARG6. In this case, the existing $ARGn symbols will either point to registers or to quadword locations in the stack frame. In both cases, subsequent arguments cannot be examined by looking at quadword locations beyond the defined $ARGn symbols. The only way to find the additional arguments in these cases is to examine the compiled machine code to determine where the arguments reside. Both of these problems are eliminated if MAX_ ARGS is specified correctly for the maximum argument that you want to examine. 5 Debugging_Code_with_Floating-Point_Data The following list provides important information about debugging compiled MACRO-32 code with floating-point data on an Alpha system: o You can use the EXAMINE/FLOAT command to examine an Alpha integer register for a floating-point value. Even though there is a set of registers for floating-point operations on Alpha systems, those registers are not used by compiled MACRO-32 code that contains floating-point operations. Only the Alpha integer registers are used. Floating-point operations in compiled MACRO-32 code are performed by emulation routines that operate outside the compiler. Therefore, performing MACRO-32 floating-point operations on, say, R7, has no effect on Alpha floating-point register 7. o When using the EXAMINE command to examine a location that was declared with a .FLOAT directive or other floating-point storage directives, the debugger automatically displays the value as floating-point data. o When using the EXAMINE command to examine the G_FLOAT data type, the debugger does not use the contents of two registers to build the value for VAX data. Consider the following example: EXAMINE/G_FLOAT R4 In this example, the lower longwords of R4 and R5 are not used to build the value as is the case on VAX. Instead, the quadword contents of R4 are used. The code the compiler generates for D_FLOAT and G_FLOAT operations preserves the VAX format of the data in the low longwords of two consecutive registers. Therefore, using EXAMINE/G_FLOAT on either of these two registers will not give the true floating-point value, and issuing DEPOSIT/G_FLOAT to one of these registers will not give the desired results. You can manually combine the two halves of such a value, however. For example, assume you executed the following instruction: MOVG DATA, R6 You could then read the G_FLOAT value which now resides in R6 and R7 with a sequence like the following: DBG> EX R6 .MAIN.\%LINE 100\%R6: 0FFFFFFFF D8E640D1 DBG> EX R7 .MAIN.\%LINE 100\%R7: 00000000 2F1B24DD DBG> DEP R0 = 2F1B24DDD8E640D1 DBG> EX/G_FLOAT R0 .MAIN.\%LINE 100\%R0: 4568.89900000000 o You can deposit floating-point data in an Alpha integer register with the DEPOSIT command. The syntax is the same as it is on VAX. o H_FLOAT is unsupported. 5 Debugging_Code_with_Packed_Decimal_Data The following list provides important information about debugging compiled MACRO-32 code with packed decimal data on an Alpha system: o When using the EXAMINE command to examine a location that was declared with a .PACKED directive, the debugger automatically displays the value as a packed decimal data type. o You can deposit packed decimal data. The syntax is the same as it is on VAX. 3 MACRO-64 (Alpha only) The following subtopics describe debugger support for MACRO-64. 4 Operators_in_Language_Expressions Language MACRO-64 does not have expressions in the same sense as high-level languages. Only assembly-time expressions and only a limited set of operators are accepted. To permit the MACRO-64 programmer to use expressions at debug-time as freely as in other languages, the debugger accepts a number of operators in MACRO- 64 language expressions that are not found in MACRO-64 itself. In particular, the debugger accepts a complete set of comparison and Boolean operators modeled after BLISS. It also accepts the indirection operator and the normal arithmetic operators. Kind Symbol Function Prefix @ Indirection Prefix . Indirection Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix MOD Remainder Infix @ Left shift Infix EQL Equal to Infix EQLU Equal to Infix NEQ Not equal to Infix NEQU Not equal to Infix GTR Greater than Infix GTRU Greater than unsigned Infix GEQ Greater than or equal to Infix GEQU Greater than or equal to unsigned Infix LSS Less than Infix LSSU Less than unsigned Infix LEQ Less than or equal to Infix LEQU Less than or equal to unsigned Prefix NOT Bit-wise NOT Infix AND Bit-wise AND Infix OR Bit-wise OR Infix XOR Bit-wise exclusive OR Infix EQV Bit-wise equivalence 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for MACRO-64 follow: Symbol Construct Bit field selection as in BLISS 4 Data_Types MACRO-64 binds a data type to a label name according to the data directive that follows the label definition. For example, in the following code fragment, the .LONG data directive directs MACRO- 64 to bind the longword integer data type to labels V1, V2, and V3: .PSECT A, NOEXE .BYTE 5 V1: V2: V3: .LONG 7 To confirm the type bound to V1, V2, and V3, issue a SHOW SYMBOL/TYPE command with a V* parameter. The following display results: data .MAIN.\V1 atomic type, longword integer, size: 4 bytes data .MAIN.\V2 atomic type, longword integer, size: 4 bytes data .MAIN.\V3 atomic type, longword integer, size: 4 bytes) Supported MACRO-64 directives follow: MACRO-64 Directives Operating System Data Type Name .BYTE Byte Unsigned (BU) .WORD Word Unsigned (WU) .LONG Longword Unsigned (LU) .SIGNED_BYTE Byte Integer (B) .SIGNED_WORD Word Integer (W) .LONG Longword Integer (L) .QUAD Quadword Integer (Q) .F_FLOATING F_Floating (F) .D_FLOATING D_Floating (D) .G_FLOATING G_Floating (G) .S_FLOATING S_Floating (S) (Alpha specific) .T_FLOATING T_Floating (T) (Alpha specific) (Not Packed decimal (P) applicable) 3 Pascal The following subtopics describe debugger support for Pascal. 4 Operators_in_Language_Expressions Supported Pascal operators in language expressions include: Kind Symbol Function Prefix + Unary plus Infix + Addition, concatenation Infix * Multiplication Infix / Real division Infix DIV Integer division Infix MOD Modulus Infix REM Remainder Infix ** Exponentiation (VAX specific) Infix IN Set membership Infix = Equal to Infix <> Not equal to Infix > Greater than Infix >= Greater than or equal to Infix < Less than Infix <= Less than or equal to Prefix NOT Logical NOT Infix AND Logical AND Infix OR Logical OR The typecast operator (::) is not supported in language expressions. 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for Pascal follow: Symbol Construct [ ] Subscripting . (period) Record component selection ^ Pointer dereferencing (circumflex) 4 Predefined_Symbols Supported Pascal predefined symbols follow: Symbol Meaning TRUE Boolean True FALSE Boolean False NIL Nil pointer 4 Built-In_Functions Supported Pascal built-in functions follow: Symbol Meaning SUCC Logical successor PRED Logical predecessor 4 Data_Types Supported Pascal data types follow: Pascal Data Type Operating System Data Type Name INTEGER Longword Integer (L) INTEGER Word Integer (W,WU) INTEGER Byte Integer (B,BU) UNSIGNED Longword Unsigned (LU) UNSIGNED Word Unsigned (WU) UNSIGNED Byte Unsigned (BU) SINGLE, REAL F_Floating (F) REAL (Alpha IEEE S_Floating (FS) specific) DOUBLE D_Floating (D) DOUBLE G_Floating (G) DOUBLE (Alpha IEEE T_Floating (FT) specific) QUADRUPLE (VAX H_Floating (H) specific) BOOLEAN (None) CHAR ASCII Text (T) VARYING OF CHAR Varying Text (VT) SET (None) FILE (None) Enumerations (None) Subranges (None) Typed Pointers (None) Arrays (None) Records (None) Variant records (None) The debugger accepts Pascal set constants such as [1,2,5,8..10] or [RED, BLUE] in Pascal language expressions. Floating-point numbers of type REAL may be represented by F_ Floating or IEEE S_Floating, depending on compiler switches or source code attributes. Floating-point numbers of type DOUBLE may be represented by D_ Floating, G_Floating, or IEEE T_Floating, depending on compiler switches or source code attributes. 4 Additional_Information In general, you can examine, evaluate, and deposit into variables, record fields, and array components. An exception to this occurs under the following circumstances: if a variable is not referenced in a program, the Pascal compiler might not allocate the variable. If the variable is not allocated and you try to examine it or deposit into it, you will receive an error message. When you deposit data into a variable, the debugger truncates the high-order bits if the value being deposited is larger than the variable; the debugger fills the high-order bits with zeros if the value being deposited is smaller than the variable. If the deposit violates the rules of assignment compatibility, the debugger displays an informational message. You can examine and deposit into automatic variables (within any active block); however, because automatic variables are allocated in stack storage and are contained in registers, their values are considered undefined until the variables are initialized or assigned a value. 4 Restrictions Restrictions in debugger support for Pascal are as follows. You can examine a VARYING OF CHAR string, but you cannot examine the .LENGTH or .BODY fields using the normal language syntax. For example, if VARS is the name of a string variable, the following commands are not supported: DBG> EXAMINE VARS.LENGTH DBG> EXAMINE VARS.BODY To examine these fields, use the techniques illustrated in the following examples. Use Instead of EXAMINE/WORD VARS EXAMINE VARS.LENGTH EXAMINE/ASCII EXAMINE VARS.BODY VARS+2 3 PL-I The following subtopics describe debugger support for PL/I. 4 Operators_in_Language_Expressions Supported PL/I operators in language expressions include: Kind Symbol Function Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix ** Exponentiation Infix || Concatenation Infix = Equal to Infix ^= Not equal to Infix > Greater than Infix >= Greater than or equal to Infix ^< Greater than or equal to Infix < Less than Infix <= Less than or equal to Infix ^> Less than or equal to Prefix ^ Bit-wise NOT Infix & Bit-wise AND Infix | Bit-wise OR 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for PL/I follow: Symbol Construct ( ) Subscripting . Structure component selection (period) -> Pointer dereferencing 4 Data_Types Supported PL/I data types follow: PL/I Data Type Operating System Data Type Name FIXED BINARY Byte- (B), Word- (W), or Longword- (L) Integer FIXED DECIMAL Packed Decimal (P) FLOAT BIN/DEC F_Floating (F) FLOAT BIN/ DEC D_Floating (D) FLOAT BIN/DEC G_Floating (G) FLOAT BIN/DEC (VAX H_Floating (H) specific) BIT Bit (V) BIT Bit Unaligned (VU) CHARACTER ASCII Text (T) CHARACTER VARYING Varying Text (VT) FILE (None) Labels (None) Pointers (None) Arrays (None) Structures (None) 4 Static_and_Nonstatic_Variables Variables of the following storage classes are allocated statically: STATIC EXTERNAL GLOBALDEF GLOBALREF Variables of the following storage classes are allocated nonstatically (on the stack or in registers): AUTOMATIC BASED CONTROLLED DEFINED PARAMETER 4 Examining_and_Manipulating_Data The following subtopics give examples of the EXAMINE command with PL/I data types. They also highlight aspects of debugger support that are specific to PL/I. 5 EXAMINE_Command_Examples The following examples show use of the EXAMINE command with a few selected PL/I data types. o Examine the value of a variable declared as FIXED DECIMAL (10,5): DBG> EXAMINE X PROG4\X: 540.02700 o Examine the value of a structure variable: DBG> EXAMINE PART MAIN_PROG\INVENTORY_PROG\PART ITEM: "WF-1247" PRICE: 49.95 IN_STOCK: 24 o Examine the value of a pictured variable (note that the debugger displays the value in quotation marks): DBG> EXAMINE Q MAIN\Q: "666.3330" o Examine the value of a pointer (which is the virtual address of the variable it accesses) and display the value in hexadecimal radix instead of decimal (the default): DBG> EXAMINE/HEXADECIMAL P PROG4\SAMPLE.P: 0000B2A4 o Examine the value of a variable with the BASED attribute; in this case, the variable X has been declared as BASED(PTR), with PTR its pointer: DBG> EXAMINE X PROG\X: "A" o Examine the value of a variable X declared as BASED with a variable PTR declared as POINTER; here, PTR is associated with X by the following line of PL/I code (instead of X having been declared as BASED(PTR) as in the preceding example): ALLOCATE X SET (PTR); In this case, you examine the value of X as follows: DBG> EXAMINE PTR->X PROG6\PTR->X: "A" 5 Notes_on_Debugger_Support Note the following points about debugger support for PL/I. You cannot use the DEPOSIT command with entry or label variables or formats, or with entire arrays or structures. You cannot use the EXAMINE command with entry or label variables or formats; instead, use the EVALUATE/ADDRESS command. You cannot use the EXAMINE command to determine the values or attributes of global literals (such as GLOBALDEF VALUE literals) because they are static expressions. Instead, use the EVALUATE command. You cannot use the EXAMINE, EVALUATE, and DEPOSIT commands with compile-time variables and procedures. However, you can use EVALUATE and DEPOSIT (but not EXAMINE) with a compile-time constant, as long as the constant is the source and not the destination. Note that an uninitialized automatic variable does not have valid contents until after a value has been assigned to it. If you examine it before that point, the value displayed is unpredictable. You can deposit a value into a pointer variable either by depositing another pointer's value into it, thus making symbolic reference to both pointers, or by depositing a virtual address into it. (You can find out the virtual address of a variable by using the EVALUATE/ADDRESS command, and then deposit that address into the pointer.) When you examine a pointer, the debugger displays its value in the form of the virtual address of the variable that the pointer points to. The debugger treats all numeric constants of the form n or n.n in PL/I language expressions as packed decimal constants, not integer or floating-point constants, in order to conform to PL/I language rules. The internal representation of 10 is therefore 0C01 hexadecimal, not 0A hexadecimal. You can enter floating-point constants using the syntax nEn or n.nEn. There is no PL/I syntax for entering constants whose internal representation is Longword Integer. This limitation is not normally significant when debugging, since the debugger supports the PL/I type conversion rules. However, it is possible to enter integer constants by using the debugger's %HEX, %OCT, and %BIN operators, because nondecimal radix constants are assumed to be FIXED BINARY. For example, the EVALUATE/HEXADECIMAL 53 + %HEX 0 command displays 00000035. 3 RPG_II (VAX only) The follow subtopics describe debugger support for RPG II. 4 Operators_in_Language_Expressions The following operators are supported in language expressions when the language is set to RPG II: Kind Symbol Function Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix = Equal to Infix NOT = Not equal to Infix > Greater than Infix NOT < Greater than or equal to Infix < Less than Infix NOT > Less than or equal to Prefix NOT Logical NOT Infix AND Logical AND Infix OR Logical OR 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for RPG II follow: Symbol Construct ( ) Subscripting 4 Data_Types Supported RPG II data types follow: RPG II Data Type Operating System Data Type Name Longword binary Longword Integer (L) numeric Word binary Word Integer (W) numeric Packed decimal Packed Decimal (P) Character ASCII Text (T) Overpunched Right Overpunched Sign (NRO) decimal Arrays (None) Tables (None) 4 Setting_Breakpoints_or_Tracepoints With RPG II programs, you can set breakpoints using source line numbers, logic cycle labels, user-defined tag names, and subroutine labels. Debugging RPG II programs is somewhat different from debugging programs in other languages, and the additional topics explain where and how you can set breakpoints or tracepoints. 5 Specifications The following paragraphs describe where you can set breakpoints (or tracepoints) in specifications, using line numbers. The RPG II program cycle determines the order in which program lines are processed. When setting breakpoints or tracepoints, you can reference the line numbers that RPG II assigns to your program and appear in a listing file or in a debugger source display. The line numbers you specify in columns 1 through 5 of a specification are not used. The compiler assigns line numbers only to certain specifications at specific points in the logic cycle; therefore, you can specify a breakpoint or tracepoint at these points in the program: o A breakpoint at a File Description specification occurs before an input or update file is opened or just before an output file is created. The line number of this breakpoint corresponds to the File Description specification for this file. o A breakpoint at an Input specification occurs before the fields are loaded with data from a record. The line number of this breakpoint corresponds to the record definition in an Input specification. o You can set two breakpoints for each Calculation specification. The first breakpoint occurs just after testing control-level indicators, if used, and just before testing conditioning indicators. The second breakpoint occurs just before executing the operation code. Use the following syntax: SET BREAK line-number.statement-number For example, assume that a Calculation specification begins with line number 25. The SET BREAK 25.1 command enables you to test indicators. The SET BREAK 25.2 command puts a breakpoint just before the operation code is executed. If a Calculation specification has no conditioning indicators, the SET BREAK 25 command puts a breakpoint just before the operation code is executed. You can specify statement numbers only with Calculation specifications that have conditioning indicators. o A breakpoint at an Output specification occurs after the output buffer has been built but before the record is output. The line number of the breakpoint corresponds to the record definition in an Output specification. 5 Labels You can specify an RPG II label as a breakpoint or a tracepoint. The following RPG II labels, which correspond to specific points in the logic cycle, are provided in addition to user-defined tags. Note that these labels do not appear in the source code but are accessible from the debugger. The labels do appear in the machine code listing. RPG II Label Description and Breakpoint Behavior *DETL Breaks just before outputting heading and detail lines *GETIN Breaks just before reading the next record from the primary or secondary file *TOTC Breaks just before performing total-time calculations *TOTL Breaks just before performing total-time output *OFL Breaks just before performing overflow output *DETC Breaks just before performing detail-time calculations For example: DBG> SET BREAK *TOTL 4 EXAMINE_Command The EXAMINE command enables you to look at the contents of a variable, the current table entry, an array element, or the I/O buffer. To examine an array variable, use array syntax as in the following example: DBG> EXAMINE ARR3(9) ! Display element 9 of array ARR3 DBG> EXAMINE ARRY(1:7) ! Display elements 1-7 of array ARRY Specifying a table name enables you to examine the entry retrieved from the last LOOKUP operation. To display the contents of the I/O buffer, specify the name of the input file, update file, or output file, followed by the string $BUF. For example, the following command displays the contents of the I/O buffer for the input file INPUT: DBG> EXAMINE INPUT$BUF The following command displays the ASCII equivalent of the string STRING, which is 6 characters long: DBG> EXAMINE/ASCII:6 STRING To examine a variable which contains the at sign (@), use %NAME as follows: DBG> EXAMINE %NAME 'ITEM@' To examine a nonexternal indicator, precede it with the string *IN. For example: DBG> EXAMINE *IN56 *IN56: "0" If an indicator is set off, 0 is displayed. If an indicator is set on, 1 is displayed. You cannot examine external indicators in this manner. To examine external indicators, you must first link the program with the /NOSYSSHR qualifier; then, use the CALL command, as in the following example which displays the value of U5: DBG> CALL RPG$EXT_INDS(5) value returned is 0 4 DEPOSIT_Command Note the following points when using the DEPOSIT command: o You can deposit a single value into an element of an array using array syntax as in the following example, which deposits the value 150 into element 2 of array ARR: DBG> DEPOSIT ARR(2) = 150 o You can deposit multiple values into an array of character strings, by using the /ASCII qualifier with the DEPOSIT command. For example, assume PARTS is an array of 10 elements in program INV.RPG, each a character string of length 3. The following DEPOSIT command deposits the strings P04, P05, and P06 into elements 4, 5, and 6, respectively, of array PARTS: DBG> DEPOSIT/ASCII PARTS(4) = "P04P05P06" DBG> EXAMINE PARTS(4:6) INV\PARTS (4): 'P04' (5): 'P05' (6): 'P06' o Values deposited into numeric fields are aligned on the decimal point. Shorter fields are padded with zeros to the left and right of the decimal point. o Values deposited into character fields are left justified. If the value contains fewer characters than the character field, the field is padded on the right with spaces. o To set a nonexternal indicator on or off with the DEPOSIT command, precede the indicator with the string *IN. Depositing the value 1 or 0 sets the indicator on or off, respectively. For example, the following command sets indicator 56 on: DBG> DEPOSIT *IN56 = "1" 4 EDIT_Command The EDIT command invokes the RPG II editor rather than the Language-Sensitive Editor. 3 SCAN (VAX only) The following subtopics describe debugger support for SCAN. 4 Operators_in_Language_Expressions Supported SCAN operators in language expressions include: Kind Symbol Function Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix & Concatenation Infix = Equal to Infix <> Not equal to Infix > Greater than Infix >= Greater than or equal to Infix < Less than Infix <= Less than or equal to Prefix NOT Complement Infix AND Intersection Infix OR Union Infix XOR Exclusive OR 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for SCAN follow: Symbol Construct ( ) Subscripting . Record component selection (period) -> Pointer dereferencing 4 Predefined_Symbols Supported SCAN predefined symbols follow: Symbol Meaning TRUE Boolean True FALSE Boolean False NIL Nil pointer 4 Data_Types Supported SCAN data types follow: SCAN Data Type Operating System Data Type Name BOOLEAN (None) INTEGER Longword Integer (L) POINTER (None) FIXED STRING TEXT with CLASS=S (n) VARYING STRING TEXT with CLASS=VS (n) DYNAMIC STRING TEXT with CLASS=D TREE (None) TREEPTR (None) RECORD (None) OVERLAY (None) There is no specific support for the following data types: FILE TOKEN GROUP SET 4 Names You can use the names of the following SCAN constructs in debugger commands: procedures macros constants variables labels 4 Controlling_Execution Note the following points about SCAN breakpoints, tracepoints, and watchpoints. 5 Breakpoints_and_Tracepoints You can set breakpoints and tracepoints on procedures, trigger macros, syntax macros, and labels, as well as line numbers. For example: DBG> SET BREAK find_keyword ! break on a trigger macro DBG> CANCEL BREAK exit ! cancel break on label DBG> SET BREAK compare_trees ! break on a procedure Conventional breakpoints and tracepoints are not especially convenient for monitoring SCAN's picture matching. Where do you set a breakpoint or tracepoint to observe the tokens built by your program? There is no statement in your program on which to set such a breakpoint. To solve this problem, VAX SCAN defines several events. By setting breakpoints or tracepoints on these events, you can observe the picture matching process. The following event keywords are defined for SCAN programs: Event Keyword Description TOKEN A token is built. PICTURE An operand in a picture is being matched. INPUT A new line of the input stream is read. OUTPUT A new line of the output stream is written. TRIGGER A trigger macro is starting or terminating. SYNTAX A syntax macro is starting or terminating. ERROR Picture matching error recovery is starting or terminating. Use these keywords with the /EVENT qualifier of the following commands: (SET,CANCEL,ACTIVATE,DEACTIVATE) BREAK (SET,CANCEL,ACTIVATE,DEACTIVATE) TRACE For example, the following command sets a breakpoint that triggers whenever a TOKEN is built: DBG> SET BREAK/EVENT=TOKEN Recognition of SCAN events is enabled automatically by the debugger if the main program is written in SCAN. If you are debugging a program written in another language that calls a SCAN routine, proceed as follows to set up the SCAN environment: 1. Enter the SET LANGUAGE SCAN command to enable recognition of language-dependent operators, expressions, and other constructs (see the SET LANGUAGE command). 2. Enter the SET EVENT_FACILITY SCAN command to enable recognition of SCAN events (see the SET EVENT_FACILITY command). The SHOW EVENT_FACILITY command identifies the current facility and its events. 5 Watchpoints Note the following points about SCAN watchpoints: o Variables declared at MODULE level are static by default. o Variables declared at PROCEDURE or MACRO level are automatic (nonstatic) by default. o DYNAMIC STRING variables are dynamically built. The storage used to hold the value of the string can change when the value of the string changes. Thus, the storage the debugger is watching may not be the correct storage if the string's value is changed. 4 Examining_and_Depositing The following subtopics explain how to examine and deposit into the following SCAN variables: STRING FILL POINTER TREE TREEPTR RECORD OVERLAY 5 STRING_Variables If you deposit into a FIXED STRING variable, truncation will occur if the deposited string is longer than the size established by the declaration of that variable. If you deposit into a VARYING STRING variable, truncation will occur if the deposited string is longer than the maximum size established by the declaration of that variable. If you deposit into a DYNAMIC STRING variable, truncation will occur if the deposited string is longer than the current size of the variable. With FIXED and DYNAMIC STRING variables, if the deposited string is shorter than the current size of the variable, the unfilled portion of the variable will be blank padded to the right, with the new string left justified in the variable. In the case of VARYING STRING variables, the current size of the variable storage space will be adjusted to the size of the deposited string. 5 FILL_Variables Examining a FILL variable causes the contents of the specified variable to be displayed as a string, by default, and so may have little meaning. If the characteristics (or type) of the fill are known, the appropriate qualifier applied to the command will produce a more meaningful display. The following command example shows a fill x that is known to be a single floating number: DBG> EXAMINE/FLOAT x 5 POINTER_Variables You can examine a POINTER by name to find the address of the variable it points to. Use the operator that combines the minus sign and the greater than symbol to examine the variable that is based on the POINTER. Consider these declarations and assignments: TYPE symnode: RECORD ptr: POINTER TO symnode, vstr: VARYING STRING( 20 ), END RECORD; DECLARE x : symnode; DECLARE xptr: POINTER TO symnode; xptr = POINTER(x); x.vstr = 'prehensile'; The following command displays the value of the vstr component of x: DBG> EXAMINE x.vstr POINTER\MAINPOINTER\X.VSTR: 'prehensile' The following command displays the value of vstr based on the POINTER: DBG> EXAMINE xptr->.vstr POINTER\MAINPOINTER\XPTR->.VSTR: 'prehensile ' 5 TREE_and_TREEPTR_Variables You can examine the contents of the nodes in a tree using the following syntax: EXAMINE tree_variable([subscript], . . . ) You cannot deposit into a TREE variable. If you specify the name of a tree with the EXAMINE command, the debugger displays the contents of all nodes and leaves of the tree. For example: DBG> EXAMINE voters You can specify an interior node by entering the subscript for that node. For example: DBG> EXAMINE voters('salem') You can examine the leaf node in a tree by specifying all subscripts leading to the desired leaf. For example: DBG> EXAMINE voters('salem',ward2) If you examine a TREEPTR variable, such as cityptr or wardptr, the debugger displays the address of that tree node. You examine what a TREEPTR variable is pointing to as follows: DBG> EXAMINE cityptr-> 5 RECORD_and_OVERLAY_Variables If you specify a RECORD by name with the EXAMINE command, all components of the RECORD are presented. To examine individual components of the RECORD, specify the full name of each component. The general format is as follows: EXAMINE recordname EXAMINE recordname.componentname.componentname . . . You examine an OVERLAY in the same way. All components are again presented; thus, if a four-byte region is a FILL(4), an INTEGER, and a VARYING STRING(2), the four bytes will be displayed three different ways. 3 Language_UNKNOWN The following subtopics describe debugger support for language UNKNOWN. 4 Operators_in_Language_Expressions Supported operators in language expressions for language UNKNOWN follow: Kind Symbol Function Prefix + Unary plus Infix + Addition Infix * Multiplication Infix / Division Infix ** Exponentiation (VAX specific) Infix & Concatenation Infix // Concatenation Infix = Equal to Infix <> Not equal to Infix /= Not equal to Infix > Greater than Infix >= Greater than or equal to Infix < Less than Infix <= Less than or equal to Infix EQL Equal to Infix NEQ Not equal to Infix GTR Greater than Infix GEQ Greater than or equal to Infix LSS Less than Infix LEQ Less than or equal to Prefix NOT Logical NOT Infix AND Logical AND Infix OR Logical OR Infix XOR Exclusive OR Infix EQV Equivalence 4 Constructs_in_Language_and_Address_Expressions Supported constructs in language and address expressions for language UNKNOWN follow: Symbol Construct [ ] Subscripting ( ) Subscripting . (period) Record component selection ^ Pointer dereferencing (circumflex) 4 Predefined_Symbols Supported predefined symbols for language UNKNOWN follow: Symbol Meaning TRUE Boolean True FALSE Boolean False NIL Nil pointer 4 Data_Types When the language is set to UNKNOWN, the debugger understands all data types accepted by other languages except a few very language-specific types, such as picture types and file types. In UNKNOWN language expressions, the debugger accepts most scalar OpenVMS calling standard data types. o For language UNKNOWN, the debugger accepts the dot-notation for record component selection. For example, if C is a component of a record B which in turn is a component of a record A, then C can be referenced as A.B.C. Subscripts can be attached to any array components; for example, if B is an array, then C can be referenced as A.B[2,3].C. o For language UNKNOWN, the debugger accepts brackets and parentheses for subscripts. For example, A[2,3] and A(2,3) are equivalent. 2 Logical_Names 3 DBG$DECW$DISPLAY Specifies the debugger interface (Compaq DECwindows Motif for OpenVMS or command) or the display device (if you are displaying the interface on a workstation). By default, DBG$DECW$DISPLAY is either undefined or has the same definition as the application-wide logical name DECW$DISPLAY. The Compaq DECwindows Motif for OpenVMS user interface is the default on workstations. To display the command interface instead of the Compaq DECwindows Motif for OpenVMS user interface, enter the following definition before starting the debugger: $ DEFINE DBG$DECW$DISPLAY " " For complete information about the Compaq DECwindows Motif for OpenVMS user interface, see the debugger's Compaq DECwindows Motif for OpenVMS documentation. 3 DBG$IMAGE_DSF_PATH (Alpha only) Specifies the directory in which a separate Debug Symbol File (.DSF) file resides. Debugging an executable file that has a separate .DSF file requires the following: o The name of the .DSF file must match the name of the .EXE file being debugged. o You must define DBG$IMAGE_DSF_PATH to point to the directory that contains the .DSF file. 3 DBGHK$IMAGE_PATH (Alpha only) Specifies the directory path of .DSF files when you are using the OpenVMS Alpha System-Code Debugger. For complete information on using this debugger, see the Writing OpenVMS Alpha Device Drivers in C. 3 DBG$INIT If the logical name DBG$INIT is defined at the start of a debugging session, then the file that it translates to is used as an initialization file. The commands in the file are executed as if the file had been called with the execute procedure (@) command. This is useful if there is a particular set of commands that you always execute when you start up the debugger, for example to specify a source directory search list, enable screen mode, log the session. Example: $ CREATE MY_DEBUG.COM SET SOURCE SYS$DISK:[],SRC$ SET MODE SCREEN SET STEP SILENT . . . $ DEFINE DBG$INIT [JONES.CMD]DEBUG_INIT.COM 3 DBG$INPUT_and_DBG$OUTPUT The value of the logical name DBG$INPUT determines the debugger input device. By default, this is SYS$INPUT. The value of the logical name DBG$OUTPUT determines the debugger output device. By default, this is SYS$OUTPUT. If you plan to debug a program that takes its input from a file and your debugger input from the terminal, establish the following definitions before starting the debugger: $ DEFINE SYS$INPUT program-input-file $ DEFINE/PROCESS DBG$INPUT 'F$LOGICAL("SYS$COMMAND") That is, define DBG$INPUT to point to the translation of SYS$COMMAND. If you define DBG$INPUT to point to SYS$COMMAND, the debugger will try to get its input from the file. 2 Messages To get help about a debugger message, use the following general command format: DBG> HELP Messages message-identifier where message-identifier is the keyword displayed to the left of the message text. The additional topics list all message identifiers alphabetically. The following information is provided for each message identifier: message text, explanation, and user action. 3 Example For example, suppose the debugger displays the following message: Language: BASIC, Module: TEST In this example, the message identifier is INITIAL. To get information about this message, enter the following command: DBG> HELP Messages INITIAL 3 Message_Format The following example shows the elements of a debugger diagnostic message: %DEBUG-W-NOSYMBOL, symbol 'X' is not in the symbol table 1 2 3 4 1 The facility name (DEBUG). 2 The severity level (W, in this example). 3 The message identifier (NOSYMBOL, in this example). The message identifier is an abbreviation of the message text. 4 The message text. The identifier enables you to find the explanation for a diagnostic message from the debugger's online help (and the action you need to take, if any). 3 Severity_Levels The possible severity levels for diagnostic messages are as follows: S (success) I (informational) W (warning) E (error) F (fatal, or severe error) Success and informational messages inform you that the debugger has performed your request. Warning messages indicate that the debugger might have performed some, but not all, of your request and that you should verify the result. Error messages indicate that the debugger could not perform your request, but that the state of the debugging session was not changed. The only exceptions are if the message identifier was DBGERR or INTERR. These identifiers signify an internal debugger error, and you should contact your Compaq support representative. Fatal messages indicate that the debugger could not perform your request and that the debugging session is in an indeterminate state from which you cannot recover reliably. Typically, the error ends the debugging session. 3 ABORTCMD aborting command due to kernel debugger termination Facility: DEBUG, VMS Debugger Explanation: The kernel debugger terminated so the current command was aborted. User Action: Check the reason the kernel debugger terminated. 3 ABORTED command aborted by user request Facility: DEBUG, VMS Debugger Explanation: The command being executed was stopped when you typed CTRL-C. User Action: No action necessary. 3 ABSDATSYN absolute date-time syntax error Facility: DEBUG, VMS Debugger Explanation: The date-time value could not be converted because it is not in the proper VMS format. User Action: Re-enter the date-time value using the correct VMS date-time format. 3 ACCADDCOM access violation in address computation for address_value Facility: DEBUG, VMS Debugger Explanation: The address computation for the specified variable resulted in an access violation. This normally means that a register value or a descriptor needed in the address computation is uninitialized or corrupted. User Action: If the necessary register or descriptor is not yet initialized, the variable is not available at this point in the code. If the register or descriptor is corrupted, the cause of this error should be located and corrected. 3 ACTIVATING program is activating Facility: DEBUG, VMS Debugger Explanation: The process process-specification has just activated, and is now connected to the main debugger. Any SET BREAK/ACTIVATING or SET TRACE/ACTIVATING events will now take effect. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 ADDRANCOV address range covers more than one module address_value is in path_ name address_value is in path_name Facility: DEBUG, VMS Debugger Explanation: The address range specified in a debugger EXAMINE/SOURCE command covers more than a single module. This is not allowed. The start address CZ is in module mod1 and the end address yyy is in module mod2. User Action: Re-enter the command with a valid address range. 3 ADDRESSMODE instruction uses illegal or undefined addressing modes Facility: DEBUG, VMS Debugger 3 ADDRMBZ a must-be-zero field in an address was not zero Facility: DEBUG, VMS Debugger Explanation: This is an internal debugger error. User Action: If the error is reproducible, submit a Software Performance Report and, if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 ADDRREG & not allowed on register variables: operand bound to register_name Facility: DEBUG, VMS Debugger Explanation: The C language & operator could not be applied to the given operand because the operand is a register variable. This is not allowed in the C language definition. User Action: Do not use the & operator on a register variable. 3 ALOCMEMERR error allocating memory for an object in routine function_name. Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when allocating memory. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 ALRDYCONNECTED a debugger has already connected to the desired process. Facility: DEBUG, VMS Debugger Explanation: The process you are trying to connect to is already connected to a debugger (maybe your current debugger). There can only be one connection at a time. User Action: Check to see if you have already connected (SHOW PROCESS/ALL) to the desired process. If not, then some other debug session is connected to it. Disconnect the other debugger from the desired process before attempting to reconnect your session. 3 AMBFIELD field_name is an ambiguous field name Facility: DEBUG, VMS Debugger Explanation: The reference to the given field cannot be resolved because there is more than one field with the given name. User Action: Fully qualify the reference with a complete name for the desired field. 3 AMBIGQUAL qualifier qualifier_name is ambiguous Facility: DEBUG, VMS Debugger Explanation: The qualifier cannot be resolved to a single option. There is more than one option to the command that starts with these characters. User Action: Add more of the characters to the qualifier string to make the option unambiguous. The qualifier should be unambiguous when it has at least four characters. 3 AMBIGUOUS 'member_name' is ambiguous, matching the following Facility: DEBUG, VMS Debugger Explanation: The reference to the given member cannot be resolved because there is more than one member with the given name. User Action: Fully qualify the reference with a complete name for the desired member. 3 AMPERSAND operand of ampersand must be lvalue Facility: DEBUG, VMS Debugger Explanation: The C language & operator cannot be applied to the result of an expression. This is not allowed in the C language definition. User Action: Do not use the & operator in this context. 3 ANPKERNOTAVAIL analyze process dump kernel of the VMS debugger not available Facility: DEBUG, VMS Debugger Explanation: The analyze process dump kernel for the VMS debugger is not available on this system. User Action: Contact your Digital Representative on the availability of this feature. 3 ARGLSTNOREAD argument list for frame frame-addr is not readable at address arg- addr Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers. The debugger has determined that part or all of the argument list for the frame at frame-addr is not accessible for reading. This argument list lies at arg- addr. This usually indicates a corrupt frame list, but could also indicate that the program has protected part of memory in which the frame lies. In either case, this is an error. User Action: Determine what part of your code is writing into the FP register or overwriting the saved frame pointer on the call stack (or a preceding saved frame pointer) and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 ARGNEEDSCOM a VMS command must be specified in order to pass arguments in a RUN or RERUN command Facility: DEBUG, VMS Debugger Explanation: In order to specify arguments on a VMS run command, the command must be specified using a foreign command, or set using SET COMMAND. This VMS definition must be supplied to the Debugger RUN command using the /COMMAND qualifier. User Action: Supply the proper /COMMAND qualifier along with the /ARGUMENT switch. 3 ASTARGNOREAD AST arguments for AST frame frame-addr at astarg-addr is not readable Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers. The debugger has determined that part or all of the AST argument array for the AST frame at frame-addr is not accessible for reading. This vector lies at astarg-addr. This usually indicates a corrupt frame list, but could also indicate that the program has protected part of memory in which the frame lies. In either case, this is an error. User Action: Determine what part of your code is writing into the FP register or overwriting the saved frame pointer on the call stack (or a preceding saved frame pointer) and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 ASTWASDISABLED ASTs were disabled, and are still disabled Facility: DEBUG, VMS Debugger Explanation: The delivery of asynchronous system traps ASTs were already turned off in your program when the DISABLE AST command was issued. User Action: None 3 ASTWASENABLED ASTs were enabled, and are still enabled Facility: DEBUG, VMS Debugger Explanation: The delivery of asynchronous system traps ASTs were already turned on in your program when the ENABLE AST command was issued. User Action: None 3 ATNEEDSENABLE the /AT qualifier was specified, /ENABLE was not Facility: DEBUG, VMS Debugger Explanation: The /AT qualifier is only appropriate with the /ENABLE qualifier. User Action: Reenter the command, specifying /ENABLE. 3 ATTACHED terminal is now attached to process process_name Facility: DEBUG, VMS Debugger Explanation: The control of your terminal is being passed from the current process to another process by means of the ATTACH command. User Action: None 3 ATTREQREF attach request refused Facility: DEBUG, VMS Debugger Explanation: The specified process could not be attached to. Either it was not detached or it did not belong to the caller's job. User Action: Ensure that the specified process is detached and belongs to the caller's job. 3 BADADDSPA attempted to compare addresses in different address spaces Facility: DEBUG, VMS Debugger Explanation: This is an internal debugger error. User Action: If the error is reproducible, submit a Software Performance Report and, if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 BADADDSTA attempted to compare addresses with different address states, error occurred comparing address with address Facility: DEBUG, VMS Debugger Explanation: This is an internal debugger error. User Action: If the error is reproducible, submit a Software Performance Report and, if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 BADBODPACK incorrect package spec name in body-spec spec-name, module mod-name Facility: DEBUG, VMS Debugger Explanation: The compiler has generated invalid Debug Symbol Table information. User Action: Please submit a Software Performance Report against the compiler. 3 BADDESCR descriptor for 'symbol_name' is bad or is not set up yet Facility: DEBUG, VMS Debugger Explanation: The descriptor for the given symbol points into memory that cannot be read by the Debugger. User Action: Correct the descriptor. 3 BADDISCVAL incorrect value of tag_value in discriminant field tag_name. Facility: DEBUG, VMS Debugger Explanation: The discriminate value you gave was out of range. User Action: Supply a discriminate value that is within the correct range. 3 BADDST bad Debugger Symbol Table (DST) (compiler error) Facility: DEBUG, VMS Debugger Explanation: The debugger has detected an error in the Debug Symbol Table of your program. This indicates an internal error in either the debugger or the compiler of this module. User Action: Please submit a Software Performance Report (SPR). 3 BADEVNPAR parameter does not have permitted data type for this event Facility: DEBUG, VMS Debugger Explanation: The event you specified cannot be used with the specified symbol. For example, you cannot specify the RUN event except on TASK type symbols. Please see the documentation for details on which events can be specified with which symbol types. User Action: Specify the correct symbol type for this event. 3 BADEXH the user-mode exit handler list is corrupt Facility: DEBUG, VMS Debugger Explanation: While walking the list of user-mode exit handlers, the debugger detected a forward link which pointed to an inaccessible exit control block. User Action: Check for a call to the SYS$DCLEXH system service that specifies an illegal exit control block argument. Also verify that exit control blocks are not getting corrupted later in the program. 3 BADFRAME bad FP or bad saved FP at pointer-addr in call stack, can't read frame near frame-addr Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers. The FP register (if pointer- addr is "FFFFFFFF") or the saved frame pointer at location pointer-addr points to a frame at least part of which is not read accessible near location frame-addr. User Action: Determine what part of your code is writing into the FP register or overwriting the saved frame pointer on the call stack (or a preceding saved frame pointer) and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 BADHANDLE non-existent object handle passed to routine Facility: DEBUG, VMS Debugger Explanation: The debugger uses object handles for passing information around within itself. The debugger has used a non- existent or corrupt handle for an operation. The user should never see this message. User Action: Submit a Software Performance Report (SPR). 3 BADINCAR the target system has the wrong incarnation Facility: DEBUG, VMS Debugger Explanation: After a network failure, the debugger has attempted to re-connect to the target system. However, the target systems incarnation value does not match the last known incarnation, therefore this debug session is no longer valid. This is most likely due to the target system rebooting. User Action: Start up the debugger and target system again from scratch. 3 BADOPCODE opcode opcode_name is unknown Facility: DEBUG, VMS Debugger Explanation: The opcode opcode_name specified as a command parameter is unknown to the debugger. It may be the case that an opcode synonym has been specified which is not recognized by the debugger. User Action: Specify a valid opcode or specify an opcode synonym that the debugger recognizes. 3 BADPARAM bad parameter value Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 BADSCOPE invalid pathname path_name, SCOPE not changed Facility: DEBUG, VMS Debugger Explanation: The scope path_name specified in the SET SCOPE command contained a pathname that does not exist. User Action: Specify a valid scope. 3 BADSIGARG bad sigarg pointer at pointer-addr or bad sigarg vector, can't read sigarg vector near sigarg-addr Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers, and has encountered an exception handler. The signal argument pointer at location pointer-addr points to a signal argument vector at least part of which is not read accessible near location sigarg-addr. User Action: Determine what part of your code is overwriting the stored signal argument pointer on the call stack, or part of the signal argument vector itself, and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 BADSTACK WARNING: stack corrupted; session integrity not guaranteed Facility: DEBUG, VMS Debugger Explanation: While walking the call stack, the debugger has determined that the stack is corrupted. The debugger will attempt to establish some context and give the user control. Continuation in the presence of a corrupted stack typically results in unpredictable program and debugger behavior. User Action: See the secondary message, if any, for more information. Look at what little valid information is left and then start over. Attempt to find and fix the point where the stack gets corrupted. It may be possible to examine program state, but continuing instruction execution typically results in unpredictable program and debugger behavior. 3 BADSTARTPC cannot start from PC address_value Facility: DEBUG, VMS Debugger Explanation: Location address_value is not an accessible address and therefore cannot be executed. This is often caused when a GO command with no address specification is entered after the program has terminated. The debugger tries to execute an instruction at location 0, which is not accessible. User Action: Specify a different address specification in the GO command or, if the program has terminated, you can exit from the debugger and initiate the program with the DCL command RUN. 3 BADSTATUS bad status returned from routine-name Facility: DEBUG, VMS Debugger Explanation: The debugger got an unexpected error status from the system service or RTL routine routine-name. User Action: Examine the error message and consider if the problem is related to a lack of quota or otherwise related to your program's behavior. If so, then take corrective action. If, after this evaluation, you believe that the problem lies in the debugger, then submit a Software Performance Report. 3 BADSUBPAR incorrect parent name in subunit sym-name, in module mod-name Facility: DEBUG, VMS Debugger Explanation: The compiler has generated invalid Debug Symbol Table information. User Action: Please submit a Software Performance Report (SPR) against the compiler. 3 BADTAGVAL incorrect value of tag_value in tag field tag_name. Facility: DEBUG, VMS Debugger Explanation: The tag value you gave was out of range. User Action: Supply a tag that is within the correct range. 3 BADTARGET target location protected, cannot perform deposit Facility: DEBUG, VMS Debugger Explanation: The target address of the DEPOSIT command cannot be made writeable. The DEPOSIT command cannot be performed. User Action: None. 3 BADUSEPACK incorrect package name in use clause use-name, module module-name Facility: DEBUG, VMS Debugger Explanation: The compiler has generated invalid Debug Symbol Table information. User Action: Please submit a Software Performance Report against the compiler. 3 BADUSREVNT bad user-specified event table or event entry in user RTL Facility: DEBUG, VMS Debugger Explanation: The debugger has detected an internal inconsistency in the event tables of the Run Time Library. This indicates an internal error in either the debugger or the Run Time Library. User Action: Please submit a Software Performance Report. 3 BADWATCH cannot watch protected address address_value Facility: DEBUG, VMS Debugger Explanation: A SET WATCH command specified a protected address. Note that you cannot place a watchpoint on a dynamically allocated variable because these variables are stored on the stack. User Action: Do not use watchpoint on this address. 3 BADWIDGET the debugger can not write to the command dialog box, is not initialized. Facility: DEBUG, VMS Debugger Explanation: The debugger got an unexpected status when trying to write to the command dialog box. This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 BASVARNOTSET base variable not set up yet Facility: DEBUG, VMS Debugger Explanation: The pointer to the based variable has not been set up by an ALLOCATE statement. Without a valid pointer, the reference cannot be made. User Action: Execute the ALLOCATE statement that defines the pointer for this based variable and then use the pointer to dereference the desired variable. 3 BEPOSITIVE length 'number_value' must be greater than zero Facility: DEBUG, VMS Debugger Explanation: The specified length expression yielded a non- positive value, in a context in which that does not make sense. User Action: Enter a length expression that yields a value which is greater than zero. 3 BITRANGE bit range out of limits Facility: DEBUG, VMS Debugger Explanation: The EVALUATE command specified a bit field that is too wide. User Action: The low limit of the bit field is 0 and the high limit is 31; the maximum range is 31:0. 3 BKPTNOTFOUND error searching for this breakpoint. Facility: DEBUG, VMS Debugger Explanation: The debugger detected and error when searching for the existence of the breakpoint in the list current breakpoints. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 BPTDIFMOD breakpoint or tracepoint being set in a different module. Facility: DEBUG, VMS Debugger Explanation: The specified line number was not found in the current module. Consequently, Debug is setting the breakpoint or tracepoint in a module later in the call stack or in a set module not on the call stack. User Action: If the breakpoint or tracepoint was intended to be set in the current module, cancel the breakpoint or tracepoint and specify a line number in the current module. 3 BPTONDATA execution breakpoint or tracepoint set on data item Facility: DEBUG, VMS Debugger Explanation: The command requested a breakpoint or tracepoint for a data item. Typically breakpoints are set only on code locations. User Action: See the following message. 3 BUFFEROVF buffer overflow Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 BUFOVRFLOW an internal buffer overflow has been detected. Facility: DEBUG, VMS Debugger Explanation: The size of an internal buffer is insufficient to perform this operation User Action: Please submit a Software Performance Report (SPR). 3 BUTTONEXISTS button !AC already exists in the button list. Facility: DEBUG, VMS Debugger 3 BUTTONNOTFOUND button !AC not found in the internal button list Facility: DEBUG, VMS Debugger 3 BUTTONTOOMANY too many buttons, cannot generate a unique button name. Facility: DEBUG, VMS Debugger 3 BWLGISMUS B, W, L, G, I, or S must precede ^ for operand number operand_number Facility: DEBUG, VMS Debugger Explanation: You must specify the type of offset as either B (byte), W (word), or L (longword). You must specify the type of literal as either I (immediate) or S (short). You may specify the addressing mode as G (general). User Action: Enter the instruction again, specifying the operand using one of the above modes. 3 CALLDONE call to user program complete Facility: DEBUG, VMS Debugger Explanation: This signal is generated by the debugger kernel after a called routine returns. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 CALLINGNONSTATIC calling non-static member function in a static fashion Facility: DEBUG, VMS Debugger Explanation: You are attempting to use the CALL command to call a non-static member function using a static syntax, eg. Class::Func. This may result in incorrect parameters being passed to the called routine, resulting in unpredictable results. User Action: Use a non-static syntax when calling the routine, eg. Obj.Func() 3 CANBRKWAT cancel it and set a watchpoint if that is what was intended Facility: DEBUG, VMS Debugger Explanation: If you intended to get notified when the specified location was modified rather than executed, then a watchpoint should have been set rather than a breakpoint. User Action: If a watchpoint was intended, then cancel the breakpoint and set a watchpoint. 3 CANTACCESSMAIN cannot access the main debugger Facility: DEBUG, VMS Debugger Explanation: The kernel debugger cannot access the main debugger. The reason is given in the message following this message. User Action: Correct the problem given by the messages following this message. If the problem cannot be solved, submit a Software Performance Report (SPR). 3 CANTBLDATTRLIST cannot build an ACA Services attribute list. Facility: DEBUG, VMS Debugger Explanation: Debug could not build the attribute list needed to invoke an ACA Services function. The ACA Services function will not be executed. User Action: Submit a Software Performance Report (SPR). 3 CANTCREATEMAIN could not create the debugger subprocess Facility: DEBUG, VMS Debugger Explanation: An error occurred while trying to create a subprocess to run the sharable main debugger image. The reason is given in the message following this message. User Action: Correct the problem given by the messages following this message. If the problem cannot be solved, submit a Software Performance Report (SPR). 3 CANTDELLNM unable to delete logical logical name Facility: DEBUG, VMS Debugger Explanation: The debugger process lacks the privleges necessary to delete this logical. User Action: Deassign the logical and redefine it in a less privleged table and mode, e.g. /job/user_mode. 3 CANTFINDELEM cannot retrieve optional arguments to the DEBUG message. Facility: DEBUG, VMS Debugger Explanation: Optional arguments were specified to the DEBUG message however Debug cannot retrieve these arguments from ACA Services. User Action: Submit a Software Performance Report (SPR). 3 CANTFREEATTRLIST cannot deallocate an ACA Services attribute list. Facility: DEBUG, VMS Debugger Explanation: Debug could not deallocate the attribute list needed to invoke an ACA Services function. User Action: No action necessary. 3 CANTGETFID cannot get file-id for image file opened on channel channel-number Facility: DEBUG, VMS Debugger Explanation: An error occurred while trying to get the file-id of the image file opened on channel channel-number. The reason is given in the message following this message. User Action: Correct the problem given by the messages following this message. If the problem cannot be solved, submit a Software Performance Report (SPR). 3 CANTGETLISTCNT cannot retrieve the list count on an item list. Facility: DEBUG, VMS Debugger Explanation: An item list was secified in an ACA Services message to Debug, however, in the course of processing the message, Debug could not retrieve the count of the number of items in the list from ACA Services. User Action: Submit a Software Performance Report (SPR). 3 CANTGETMAINFID cannot get file-id for the main image file opened on channel channel-number Facility: DEBUG, VMS Debugger Explanation: An error occurred while trying to get the file-id of the main image file opened on channel channel-number. The reason is given in the message following this message. User Action: Correct the problem given by the messages following this message. Note that trying to debug a remote image is NOT currently supported. If you are not trying to debug a remote image and the problem cannot be solved, submit a Software Performance Report. 3 CANTINTPRO cannot interrupt process !AC Facility: DEBUG, VMS Debugger Explanation: The debugger could not interrupt the specified process because it was deleted. This message usually indicates that the specified process terminated abnormally-either via the DCL STOP command or via a call to $DELPRC. User Action: The debugger failed to interrupt the process. Unless the reason for this is apparent, submit a Software Performance Report (SPR). 3 CANTOPNIMG cannot open image image_name (File: device_name:(file_id,file_ id,file_id)) Facility: DEBUG, VMS Debugger Explanation: The information the debugger needs to allow you to debug this section of code is in an image file that could not be opened. User Action: Check for the existence of the specified file and/or its associated file protection attributes. 3 CANTPAST cannot paste to read-only window. Facility: DEBUG, VMS Debugger Explanation: The window which has the input focus is a read-only window. You cannot paste to a read-only window. User Action: Assign the input focus to a writeable window and, if applicable, to the appropriate text-entry field. 3 CANTREGSERVER could not register Debug as ACA Services server. Facility: DEBUG, VMS Debugger Explanation: Debug could not register itself as an ACA Services Server. User Action: Verify that ACA Services is installed and that the Control Server is running on the current system. If ACA Services is installed and the Control Server is running on the current system and this problem still exist, submit a Software Performace Report, otherwise install ACA Services and start the Control Server. 3 CANTUNREGSERVER could not unregister Debug as ACA Services server. Facility: DEBUG, VMS Debugger Explanation: Debug could not unregister itself as an ACA Services Server. User Action: Use ACA Services command, STOP SERVER, to unregister Debug as an ACA Services server. 3 CIRCSTK circular stack at frame address frame-addr Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers. The debugger has determined that the linked frames loop back on themselves at frame-addr. User Action: Determine what part of your code is writing into the FP register or overwriting the saved frame pointer on the call stack (or a preceding saved frame pointer) and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 CIREXLST command aborted after number_of_handlers exit handlers displayed circular exit handler list suspected Facility: DEBUG, VMS Debugger Explanation: After displaying information about 100 exit handlers, the debugger suspects a circular exit handler list. User Action: If there is a circular exit handler list, then identify and correct the error in the user program. 3 CLIBRDFAI clipboard operation failure Facility: DEBUG, VMS Debugger Explanation: One of the DECtoolkit clipboard routines has failed. The attempt to write to the clipboard may not have completed successfully. User Action: Verify that the clipboard contains the data that you wrote to it. If it does not, attempt the operation again. 3 CLIBRDLCK clipboard locked Facility: DEBUG, VMS Debugger Explanation: Some other DECWINDOWS application has locked the clipboard. User Action: Wait until the other application has released the clipboard. 3 CMDBUFFERR error in the command buffer size. Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when trying to process the input command. Debug determined that the command buffer size was to small to store the command buffer. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 CMDFAILED the !AC command has failed Facility: DEBUG, VMS Debugger Explanation: The command has failed. The command has had no effect on the current debugging session. User Action: Reenter the command after correcting the problem. 3 CMDISCOR the correct command is command_name Facility: DEBUG, VMS Debugger Explanation: The previous message shows the obsolete command. The command replacing it is shown in this message. User Action: Use the correct command as shown. The obsolete command will not be available in a future release of the debugger. 3 CMDISOBS command command_name is obsolete Facility: DEBUG, VMS Debugger Explanation: This command is obsolete. User Action: Do not use this command, it will not be available in a future release of the debugger. 3 CMDNOTANAPROC The !AC command is not allowed when analyzing a process dump Facility: DEBUG, VMS Debugger Explanation: The specified command may not be used within a process dump analysis. User Action: Do not use the command when analyzing a process dump. 3 CMDNOTAVAIL the command command_name is not available Facility: DEBUG, VMS Debugger Explanation: The specified command, although available in some debug implementations, is not available in this one. One reason why is that the qualifier just doesn't make sense on the platform. For example, the /JSB qualifier on a STEP command doesn't make sense on Alpha VMS because there is no "JSB" instruction like there is on VAX VMS. User Action: Choose another command. 3 CMDNOTDW The !AC command is not allowed in the DECWindows debugger Facility: DEBUG, VMS Debugger Explanation: The specified command may not be used with the DECWindows debugger. User Action: Do not use the command with the DECWindows debugger. 3 CMDNOTONE The !AC command is not allowed in the one process debugger Facility: DEBUG, VMS Debugger Explanation: The specified command may not be used with the single process debugger. User Action: Do not use the command with the one process debugger. 3 CMDSYNERR command syntax error at or near 'the debugger_command_segment' Facility: DEBUG, VMS Debugger Explanation: There is a syntax error in the Debug command somewhere near the string shown in the message. User Action: Correct the syntax error and re-enter the command. 3 CMPNOTFND specified component not found in this type Facility: DEBUG, VMS Debugger Explanation: The enumeration component named in this operation could not be found in the list of components defined for this type. User Action: Correct the name of the enumeration component or correct the expression. 3 CNTRLWRDNOTACCESS the vector control word is not accessible Facility: DEBUG, VMS Debugger Explanation: The debugger does not have direct access to the vector control word. Therefore the operands of this instruction cannot be displayed correctly. User Action: Do not attempt to display the operands of vector instructions whose control word is not accessible to the debugger. 3 COMPNAME variant selector 'compname' must be an unqualified component name Facility: DEBUG, VMS Debugger Explanation: When the language is C or C++, a variant selector must specify a component of the union being selected. User Action: Specify a component name. 3 COMPNDSTRNG error generating a compound string. Facility: DEBUG, VMS Debugger Explanation: The debugger could not generate a compound string that is utilized by the Xtoolkit. User Action: No action necessary. 3 CONFLICT illegal combination of command elements - check documentation Facility: DEBUG, VMS Debugger Explanation: Command line elements conflict in their operations. The command will not be performed. User Action: Do not specify conflicting command line elements. 3 CONFROMEXC WARNING: continuing after severe error; integrity not guaranteed Facility: DEBUG, VMS Debugger Explanation: The debugger has encountered a severe error in the users program and is continuing. The integrity of this debugging session can no longer be guaranteed. User Action: Determine and correct the cause of the severe error. 3 CONSTRCOMP illegal deposit to a constrained record component Facility: DEBUG, VMS Debugger Explanation: The debugger cannot DEPOSIT into a constrained record component. User Action: Do not attempt to deposit into a constrained record component. 3 COULDNOTRUN the RUN or RERUN command did not succeed Facility: DEBUG, VMS Debugger Explanation: An error occurred while trying to create a subprocess for the program to run. The error status returned from the RUN or RERUN command is appended to this message. User Action: If the error is correctable, correct the problem and reenter the command. If not, the RUN and RERUN commands are unavailable. 3 CPOSTDECR side effect on post-decrement operation not performed Facility: DEBUG, VMS Debugger Explanation: The debugger does not support the evaluation of a post-decrement expression. User Action: None 3 CPOSTINCR side effect on post-increment operation not performed Facility: DEBUG, VMS Debugger Explanation: The debugger does not support the evaluation of a post-increment expression. User Action: None 3 CPREDECR side effect on pre-decrement operation not performed Facility: DEBUG, VMS Debugger Explanation: The debugger does not support the evaluation of a pre-decrement expression. User Action: None 3 CPREINCR side effect on pre-increment operation not performed Facility: DEBUG, VMS Debugger Explanation: The debugger does not support the evaluation of a pre-increment expression. User Action: None 3 CRMPSCFAIL failed to map-in the Debugger Symbol Table (DST) Facility: DEBUG, VMS Debugger Explanation: There will always be a secondary message describing why the debugger failed to map-in the debugger symbol table (DST) or global symbol table (GST). User Action: Please refer to the secondary message to take the appropriate action. 3 CVTNEGUNS cannot convert negative value to unsigned value at or near opcode_ name Facility: DEBUG, VMS Debugger Explanation: The command is attempting to assign a negative value to an unsigned type. This is not allowed. User Action: Do not attempt to put a negative value into an unsigned variable. 3 DBGERR debugger error or session corruption. Facility: DEBUG, VMS Debugger Explanation: The debugger has encountered an internal error or session corruption. User Action: If the error is reproducible, and is not an obvious side effect of the user program (i.e. stack corruption, resource exhaustion, etc.) submit a Software Performance Report (SPR) and if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 DBGSTOPPED a debugger process from a previous debugging session has been terminated Facility: DEBUG, VMS Debugger Explanation: While attempting to create a process to run the debugger, a debug process from a previous debugging session was found and terminated. User Action: Under normal circumstances, the debugger process will exit when a debugging session ends via the EXIT or QUIT commands. If the previous debugging session was terminated with an EXIT or QUIT command and this error is reproducable, then submit a Software Performance Report (SPR) 3 DECLARERR too many declarations, parameter_name ignored Facility: DEBUG, VMS Debugger Explanation: There is a mismatch between the number of declarations in a command procedure and the number of parameters passed to that command procedure. User Action: Check the command procedure and the DECLARE statements within to see if they agree with the number of parameters on the command line. 3 DECOVF decimal overflow at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: The value being deposited does not fit into the specified address. User Action: Specify either a smaller value or a different target address. 3 DECROPRAND illegal packed or decimal string value (Reserved Operand fault occurred during conversion) Facility: DEBUG, VMS Debugger Explanation: The debugger encountered a Reserved Operand Fault when attempting to convert the specified value. This indicates that the packed or decimal string value did not contain a valid number. User Action: Ensure that the string value contains only valid digits. 3 DEFKEY state_name key key_name has been defined Facility: DEBUG, VMS Debugger Explanation: The defining of functions keys has just been performed using the DEFINE/KEY command. This command assigns a string to function key. This is the logging message for the DEFINE/KEY command. User Action: None 3 DEFKEYERR error in processing DEFINE/KEY command: Facility: DEBUG, VMS Debugger Explanation: There was an error in defining the given key in the display system. The key may not be redefinable, either because the display system will not allow it or because there are protections that prevent it. The key definition may be invalid. User Action: Correct the error in the key definition. 3 DEFTOOREC command defined with too many levels of recursion. Facility: DEBUG, VMS Debugger Explanation: Commands may only be defined to a specified depth of recursion (now set at 100). User Action: Redefine your command such that it uses less levels of recursion. 3 DELKEY state_name key key_name has been deleted Facility: DEBUG, VMS Debugger Explanation: The undefining of functions keys has just been performed using the DELETE/KEY command. This command deletes the key definitions that were established by the DEFINE/KEY command or, by default by the debugger.This is the logging message for the DELETE/KEY command. User Action: None 3 DELKEYERR error in processing DELETE/KEY command: Facility: DEBUG, VMS Debugger Explanation: There was an error in deleting the given key definition from the display mechanism. The key may not be a defined key. The key definition might also be protected against deletions. User Action: Correct the error in the command or correct the protections of the key in the display mechanism being used. 3 DELTIMTOO delta time too large Facility: DEBUG, VMS Debugger Explanation: The debugger encountered an error when attempting to convert the string form of the delta time to binary. User Action: Enter the delta time specifying a smaller value. 3 DESCNOTSET descriptor not set up yet Facility: DEBUG, VMS Debugger Explanation: A descriptor used in an expression in the command is not yet fully initialized. Some of the fields are not valid, which means that the Debugger cannot completely evaluate the expression. User Action: Examine the descriptor that caused the problem and determine which fields are not correct. Fill in these fields with the correct values. 3 DISABLEAST ASTs were enabled, and are now disabled Facility: DEBUG, VMS Debugger Explanation: Delivery of asynchronous system traps (ASTs) has been turned off in your program by a DISABLE AST command. User Action: None 3 DISNAMREQ display name required with this command Facility: DEBUG, VMS Debugger Explanation: user did not specify a display name with this command User Action: enter a display name with this command 3 DISNOTSEL display not selected; was removed from screen Facility: DEBUG, VMS Debugger Explanation: You specified a display which is removed from the screen. User Action: Either specify a display which is not removed from the screen, or place the specified display onto the screen and attempt the operation again. 3 DISPEXISTS display_name display already exists Facility: DEBUG, VMS Debugger Explanation: You attempted to create a display which already exists, either by explicitly creating the display or by trying to save the contents of a display into currently existing display. User Action: Specify a display which does not exist. 3 DISPKINDINV the display kind display_name is not available Facility: DEBUG, VMS Debugger Explanation: The specified display kind, although available in some debug implementations, is not available in this one. User Action: Do not select the display kind. 3 DISPRLENSIZ the size of display_name is too small for its display-window increase the display size or decrease the display-window length Facility: DEBUG, VMS Debugger Explanation: You attempted to (re)size a display, e.g. DISPLAY/SIZE=n or EXPAND/DOWN=m, such that the defined display size is less than its display-window length. (See the SHOW DISPLAY command.) This is not allowed. The command was aborted. User Action: Try again with either a larger display size, e.g. bigger n in DISPLAY/SIZE=n, OR a smaller expansion, e.g. smaller m in EXPAND/DOWN=m. 3 DIVBYZERO attempted to divide by zero Facility: DEBUG, VMS Debugger Explanation: During the evaluation of an expression, the debugger noticed an attempt to divide by zero. User Action: Correct the expression so that it does not divide by zero. 3 DSFMISMATCH using file_specification BUT it does NOT appear to match with file_ specification Facility: DEBUG, VMS Debugger Explanation: The debugger is pulling debug symbol information for an image from the image DSF file BUT the link time in the image header for the DSF does NOT match with the image EXE. This means there may be symbolic and/or source line correlation misinterpretations or omissions. User Action: Verify that, if defined, the dbg$image_dsf_path is set up correctly. Verify that your DSF was created by the same link that created your image EXE. 3 DSTERRG error in DST (compiler error). GOTO DST has been ignored Facility: DEBUG, VMS Debugger Explanation: This represents an internal compiler, linker or debugger error. User Action: If this can be reproduced please submit a Software Performance Report (SPR). 3 DSTLOC error occurs offset byte!%S from beginning of DST Facility: DEBUG, VMS Debugger Explanation: This is a secondary message which gives detailed information about where the DST error occurs. It is intended primarily to be used by Digital. User Action: If you are submitting a problem report on the primary error message, be sure to include this one, too. 3 DSTNESDEP DST nesting depth too deep in module path_name Facility: DEBUG, VMS Debugger Explanation: Symbol table nesting depth is too deep in the specified module. This occurs if routine nesting or data record nesting is very deep in the user program. User Action: Simplify the user program and run again. 3 DUPLVQUAL duplicate or conflicting vector qualifier specified at 'command_ line' Facility: DEBUG, VMS Debugger Explanation: The qualifier indicated in the shown command line fragment has already been specified, or is conflicting with an earlier specified qualifier. User Action: Delete the qualifier in error. 3 DUPSTATLINK more than one static link DST encountered in path_name, compiler error Facility: DEBUG, VMS Debugger Explanation: Only one static link DST record is permitted for a given module, Ada package, or routine. This message indicates that this constraint was violated somewhere within the specified module. This message usually indicates a compiler error. User Action: Submit a Software Performance Report (SPR). 3 DWERR a DECwindows toolkit error has occurred the message text is '!AS' Facility: DEBUG, VMS Debugger Explanation: An error has been reported by the DECwindows toolkit. This indicates that either the toolkit or the X server has detected a problem with the debuggers DECwindows display(s). User Action: Try to correct the problem specified in the message. For further information or assistance on this problem, contact your System Manager. 3 DWNOT1PROC the 1 process debugger cannot be run in DECwindows mode Facility: DEBUG, VMS Debugger Explanation: The debugger must have ASTs enabled at all times in order to properly run as a DECwindows program. This is not possible for a 1 process debugger. Therefore, the debugger is defaulting to not run as a DECwindows debugger. User Action: Correct the logical name assignment for DBG$PROCESS to be either "MULTIPROCESS" or "DEFAULT", and try again. 3 DYNIMGSET setting image image_name Facility: DEBUG, VMS Debugger Explanation: The debugger is automatically setting the image containing the current PC. This is only an informational message. User Action: None 3 DYNLNGSET setting language language_name Facility: DEBUG, VMS Debugger Explanation: The debugger is automatically setting up the language to correspond to the the module containing the current PC. This is only an informational message. User Action: None 3 DYNMODSET setting module path_name Facility: DEBUG, VMS Debugger Explanation: The debugger is automatically setting the module containing the current PC. This is only an informational message. User Action: None 3 EDITDISVER the original version is file_specification Facility: DEBUG, VMS Debugger Explanation: The original file has been revised since the start of the debug session. This message indicates that source lines may not correspond to the ones used to compile this module User Action: Use SET SOURCE command to point to the original source file if possible and retry operation. 3 EDITERROR error while trying to EDIT Facility: DEBUG, VMS Debugger Explanation: An error occurred because of specifying a bad command line or because of choosing an editor which is not installed on this system. User Action: Check command line syntax and re-enter, or select an editor which is installed on the system. For further information on the installed editors contact your system manager. 3 EDITFILE editing file file_specification Facility: DEBUG, VMS Debugger Explanation: The debugger is currently setup to edit the file as specified in the message. This is only an informational message. User Action: None 3 EDITNOFILE no source file to use for editing Facility: DEBUG, VMS Debugger Explanation: This messages indicates that the debugger could not find the specified source file to use for editing. User Action: Use SET SOURCE command to point to the original source file if possible and retry operation. 3 EDITREVVER editing a revised version of the original source file Facility: DEBUG, VMS Debugger Explanation: The original source file has been revised since the start of the debug session. This message indicates that future source line may not correspond to the ones used to compile this module. User Action: Use SET SOURCE command to point to the original source file if possible and retry operation. 3 EMPTFIELDVIEW error retrieving information from view. Facility: DEBUG, VMS Debugger Explanation: The debugger could not retrieve the necessary information for a particular view display. This inhibits the debugger from manipulating the contents of the window at this time. User Action: No action necessary. 3 ENABLEAST ASTs were disabled, and are now enabled Facility: DEBUG, VMS Debugger Explanation: Delivery of asynchronous system traps (ASTs) has been turned off in your program by a DISABLE AST command. User Action: None 3 ENTRYMASK entry mask has non-zero value in bits 12:13 Facility: DEBUG, VMS Debugger Explanation: This is an internal status signal, it should never be seen by the user. If this message does occur please submit a Software Performance Report (SPR). User Action: Submit a Software Performance Report (SPR). 3 ENTRYNOTFND error searching for a window object. Facility: DEBUG, VMS Debugger Explanation: When looking for a window object, the debugger detected an error. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 ENUMRANGE enumeration value out of range Facility: DEBUG, VMS Debugger Explanation: An error in your program indicates that the value of this enumeration is out of range. User Action: Examine this field in numeric format to determine its value. Determine the error in your code and make the appropriate corrections. 3 ERRACTIMG unable to activate image Facility: DEBUG, VMS Debugger Explanation: A bad status was returned from LIB$FIND_IMAGE_ SYMBOL. User Action: The image the debugger was trying to activate could not be activated. The following error should help to resolve the problem. 3 ERRASSIGN failed to acquire an I/O channel for the debugger Facility: DEBUG, VMS Debugger Explanation: A bad status was returned from a $ASSIGN type of call. This message should be issued in the $DBG_INFO context. User Action: The debugger needs to acquire I/O channels to do I/O. In this case the debugger failed to acquire such a channel. Check your process quotas. 3 ERRCLSFILE unable to close file Facility: DEBUG, VMS Debugger Explanation: A bad status was returned from a call to close a file. User Action: The debugger failed to close a file. Unless the reason for this is apparent, submit a Software Performance Report (SPR). 3 ERRCREATPB error trying to create a user defined button. Facility: DEBUG, VMS Debugger Explanation: The debugger detected and error when trying to create the user defined push button. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 ERRCREATWIND error trying to create a window in routine function_name. Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when trying to create a window. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 ERRCRELNM unable to create a logical name Facility: DEBUG, VMS Debugger Explanation: The debugger failed to create the required logical names for input and output redirection. User Action: Submit a Software Performance Report (SPR). 3 ERRDEASSIGN failed to deassign an I/O channel acquired by the debugger Facility: DEBUG, VMS Debugger Explanation: The debugger wanted to deassign an I/O channel that is acquired for internal purposes. This error notes the failure of the SYS$DASSGN system service, probably due to an invalid channel. User Action: Submit a Software Performance Report (SPR). 3 ERRFAO unable to format output string Facility: DEBUG, VMS Debugger Explanation: An error was returned from a call to $FAO. User Action: Submit a Software Performance Report (SPR). 3 ERRFETCHWID error fetching objects from MRM in routine function_name. Facility: DEBUG, VMS Debugger Explanation: The debugger could not find one of the necessary objects in the Motif Resource Manager (MRM). This may prevent the debugger from continuing the session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 ERRGETDVI unable to get device information Facility: DEBUG, VMS Debugger Explanation: The debugger needed some information from $GETDVI and the call failed. This indicates an internal programming error. User Action: Submit a Software Performance Report (SPR). 3 ERRGETEF attempt to allocate an event flag failed Facility: DEBUG, VMS Debugger Explanation: The debugger wanted to allocate a local event flag for it's own use. For some reason the routine called to allocate the event flag failed. This message is usually issued in the $DBG_INFO context. User Action: The debugger needs event flags to operate. Check the program being debugged for excessive allocation of event flags. 3 ERRINSDEC error decoding instruction at current PC Facility: DEBUG, VMS Debugger Explanation: The debugger has encountered an error during decoding of an instruction at the current PC User Action: The address may be an entry mask, examine the instruction 2 bytes beyond the specified address. 3 ERRINSIGNAL signal arguments were incorrect, signal cannot be decoded Facility: DEBUG, VMS Debugger Explanation: The arguments which were passed as part of the signal in your program were incorrect. The debugger encountered an error in trying to analyze the signal arguments. The error is shown in the message following this message. User Action: Analyze the arguments passed to LIB$SIGNAL by your program, and correct the error. 3 ERRINVEDIT error invoking editor Facility: DEBUG, VMS Debugger Explanation: While trying to invoke an editor a bad status was returned. User Action: Is the requested editor available and working properly. If so, submit a Software Performance Report (SPR). 3 ERROPENHIER error opening the Motif resource (UID) file, in routine function_ name. Facility: DEBUG, VMS Debugger User Action: Please make sure that resource (UID) file for the debugger is in appropriate directory (Usually SYS$SYSTEM). Please consult your system manager. 3 ERROR debugger error or session corruption Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error or session corruption. User Action: Correct the problem given by the messages following this message. If the problem cannot be solved, submit a Software Performance Report (SPR). 3 ERRORLIMIT Error limit = error-limit, dumping terminated Facility: DEBUG, VMS Debugger Explanation: The error limit specified for the DST dump was exceeded; the dumper was unable to continue processing the input file. By default, the error limit is set at 5. Use the /ERROR_ LIMIT qualifier to change the value. 3 ERRORTEXT !AS Facility: DEBUG, VMS Debugger Explanation: Unspecified error. 3 ERROR_BLOCK error handle signalled, address = address Facility: DEBUG, VMS Debugger Explanation: The debugger signalled an error handle. This should never happen. The error handles are an internal construct which are used to obtain information within the debugger. They should never appear in user-visible messages. User Action: Submit a Software Performance Report (SPR). 3 ERRQIOW error from $QIOW Facility: DEBUG, VMS Debugger Explanation: A bad status was returned from a call to $QIOW. User Action: If problem can be recreated, submit a Software Performance Report (SPR). 3 ERRSMG error returned from a call to the Screen Management Facility (SMG) Facility: DEBUG, VMS Debugger Explanation: A bad status was returned from a call to SMG. This could be a result of any number of things which may or may not be a debugger problem. User Action: Check the user program for potential interactions between it and the debugger; pasteboard sharing and the like. Also, check the set up of the terminal which might cause SMG some problem. If the error still can't be explained submit a Software Performance Report (SPR). 3 ERRSYSSERV error returned from an internal debugger system service call Facility: DEBUG, VMS Debugger Explanation: A bad status was returned from a call to a system service. This message will list the particular system service. User Action: Submit a Software Performance Report (SPR). 3 ERRTARGOP unable to perform operation for current target system Facility: DEBUG, VMS Debugger Explanation: This is an internal debugger error. User Action: If the error is reproducible, submit a Software Performance Report and, if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 ERRUSREVNT error in user-specified event Facility: DEBUG, VMS Debugger Explanation: When attempting to process the specified event, the debugger called the Run Time Library, which returned an error status. The error status returned by the Run Time Library follows this message. User Action: Correct the problem based on the associated message which follows the debugger error message. 3 EXABEYREG attempt to examine beyond the end of a register Facility: DEBUG, VMS Debugger Explanation: A ranged examine command was specified that attempted to examine beyond the end of a bounded register. User Action: Respecify the command so that it does not go past the end of the register. 3 EXARANGE invalid range of addresses Facility: DEBUG, VMS Debugger Explanation: The first address of a range to examine must be less than the second address in this range. User Action: Enter the address range specifying the addresses in increasing order. 3 EXCBREREP exception breakpoint replaced Facility: DEBUG, VMS Debugger Explanation: A SET BREAK/EXCEPTION was done when exception breaks were already in effect. The old exception break was replaced with the new one. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 EXCDURCAL error occurred while executing routine called from exception break Facility: DEBUG, VMS Debugger Explanation: While executing a routine called from an exception break using the CALL command, an exception occurred. Any exceptions from routines called from an exception break cause this message to be displayed followed by the text of the exception. Execution of the called routine is then terminated. User Action: Either correct the CALL command if it was in error, or correct the routine that caused the exception. To use the debugger to help find the cause of the exception, try calling the routine while not at an exception break. 3 EXITARG exitloop argument num_levels is too large Facility: DEBUG, VMS Debugger Explanation: The parameter specified on the EXITLOOP command is greater than the number of loops nested at this time. It is also possible that you have specified an EXITLOOP command when you are not inside of a loop. User Action: Reduce the parameter on the EXITLOOP command to no more than the number of loops nested at the time the EXITLOOP command is to be executed. If there are no loops currently being executed, then the EXITLOOP command is redundant. 3 EXITERR an error occurred while trying to exit the program Facility: DEBUG, VMS Debugger Explanation: An error status was returned from the call to the debugger-kernel service that terminates program execution. Depending on the severity of the error, the program may or may not have terminated. User Action: Examine the error message after this message and consider if the problem is related to a lack of quota or otherwise related to your program's behavior. If so, then take corrective action. If, after this evaluation, you believe that the problem lies in the debugger, then submit a Software Performance Report (SPR). 3 EXITSTATUS is 'status_value' Facility: DEBUG, VMS Debugger Explanation: The program has exited with the status status_value. User Action: None. 3 EXPMEMPOOL expanding debugger memory pool Facility: DEBUG, VMS Debugger Explanation: The debugger kernel maintains a memory pool from which it allocates data structures to keep track of breakpoints, tracepoints, watchpoints, and so on. The initial size of the memory pool is 256 pages. The memory pool is expanded automatically when needed, and this informational is signaled when memory pool expansion occurs. If you have set a large number of breakpoints, tracepoints, or watchpoints, this message is to be expected. User Action: If this message appears for no evident reason (i.e. you have not set a large number of breakpoints, tracepoints, or watchpoints), there may be something wrong with the debugger. In this case, submit a Software Performance Report (SPR). 3 FAILFINDIMG could not find the DECwindows image to be initialized. Facility: DEBUG, VMS Debugger Explanation: The debugger could not find the DECwindows image that it was trying to initialize. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 FAILHANDLERBRK failed to set breakpoint on a condition handler address Facility: DEBUG, VMS Debugger Explanation: The user had requested a SET BREAK/HANDLERS but a frame based condition handler was found that Debug was unable to set a breakpoint on. User Action: You have several options. If the particular handler is NOT of interest, then it is safe to ignore the set the breakpoint error messages. You also have the option to CANCEL BREAK/HANDLERS and SET BREAK on only the breakpointable handlers of interest. Finally, if the handler IS of interest AND IS in an installed resident image, then you should activate the image privately via a logical, e.g. "DEFINE LIBOTS SYS$LIBRARY:LIBOTS.EXE;". That should bring the handler's activated address into the process's writeable address space. 3 FAILHEIRKY could not open the user interface definition (UID) file, SYS$LIBRARY:DEBUGUIL.UID. Facility: DEBUG, VMS Debugger Explanation: The debugger could not find one of the necessary file to support the DECWindows interface, preventing the debugger from continuing this session. User Action: Check for the existance and accessability of SYS$LIBRARY:DEBUGUIL.UID. For further assistance and information on this probelm check with your system manager. 3 FAILXTINIT error trying to connect to the DECWindows software. Facility: DEBUG, VMS Debugger Explanation: The debugger failed to establish a connection to the X server preventing the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 FATALSTATUS a fatal condition was detected by the debugger. Facility: DEBUG, VMS Debugger Explanation: The debugger got an unexpected status from the system service or RTL routine routine-name which prevents this DEBUG session from continuing. User Action: Examine the error message and consider if the problem is related to a lack of quota or otherwise related to your program's behavior. If so, then take corrective action. If, after this evaluation, you believe that the problem lies in the debugger, then submit a Software Performance Report. 3 FETCHLITERAL error fetching literals from MRM. Facility: DEBUG, VMS Debugger Explanation: The debugger could not find one of the necessary literals in the Motif Resource Manager (MRM). This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 FILENAMETOOLONG maximum file name length is 251 characters Facility: DEBUG, VMS Debugger Explanation: The name of the file specified by the user is too large for the debugger to handle User Action: Try to redo the operation with a shorter string. 3 FILEUNAL file not available Facility: DEBUG, VMS Debugger Explanation: The source file for the given program cannot be read. User Action: Change the protections on the source file, or use SET SOURCE to tell the Debugger where the source file really exists. 3 FLTOVF floating overflow at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: The value being deposited does not fit into the specified address. User Action: Specify either a smaller value or a different target address. 3 FRAMENOREAD stack frame at frame address frame-addr is not readable Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers. The debugger has determined that part or all of the frame at frame-addr is not accessible for reading. This usually indicates a corrupt frame list, but could also indicate that the program has protected part of memory in which the frame lies. In either case, this is an error. User Action: Determine what part of your code is writing into the FP register or overwriting the saved frame pointer on the call stack (or a preceding saved frame pointer) and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 HEIGHTDIFF desired height of specified_height is not allowed, height is set to actual_height Facility: DEBUG, VMS Debugger Explanation: The device specified by DBG$OUTPUT had a screen height that wasn't in the range of 18-100. User Action: Use SHOW TERMINAL command and verify that the terminal height is correct, it is in the range 18-100, and is pointing to a valid terminal type. 3 IDENTLONG identifier too long, please shorten Facility: DEBUG, VMS Debugger Explanation: Identifiers in address expressions must be shorter than 256 characters. User Action: Enter a shorter identifier. 3 IFIXUND precision lost during fixed point operation Facility: DEBUG, VMS Debugger Explanation: While doing operations on fixed point data items, the debugger recognized that some precision was lost. User Action: You should understand that the result of the operation is imprecise and may not be exactly what you expect. 3 IFLTUND floating underflow at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: While performing the arithmetic operation, a floating-point value became less than the smallest representable value for that data type. User Action: You should understand that the result of the operation is imprecise and may not be exactly what you expect. 3 IGNORELNM ignoring logical logical name Facility: DEBUG, VMS Debugger Explanation: The debugger is ignoring this logical likely because a previous error, e.g. unable to delete logical. User Action: If there was an error message previous to this one, see its user action and correct it. 3 IINTOVF integer overflow at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: While performing the arithmetic operation, a floating-point value exceeded the largest representable value for that data type. User Action: You should understand that the result of the operation is imprecise and may not be exactly what you expect. 3 ILLADDCON illegal constant constant_name in address expression Facility: DEBUG, VMS Debugger Explanation: The constant in the message evaluates to a non- integer type. Only integer types can be used in an address expression. User Action: Change the constant to the appropriate integer value. 3 ILLASTER subscript range ('*') not permitted here (must be at lowest level of data structure) Facility: DEBUG, VMS Debugger Explanation: The debugger does not allow an asterisk as a range in an EXAMINE except as the last index in the array. That is, the memory to examine must be a contiguous region. Unconnected slices of arrays are not allowed. User Action: Remove the asterisk from the expression to examine. Placing the corrected EXAMINE inside a Debugger FOR loop command could provide the functionality needed to do the command as originally desired. 3 ILLDEFNAM illegal name for DEFINE: defined_name Facility: DEBUG, VMS Debugger Explanation: A defined name must be non-null. User Action: Enter a non-null name to DEFINE. 3 ILLENUMVAL enumeration value out of legal range Facility: DEBUG, VMS Debugger Explanation: The predecessor (or successor) function has been used on the first (or last) component of the enumeration. The result would not be a valid value of the enumeration. User Action: Do not use the predecessor (or successor) function on the first (or last) component of the enumeration. 3 ILLEVNSTR Attempt to pass an illegal event structure: structure-name Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit an SPR. 3 ILLFILPTR file variable points to invalid file descriptor Facility: DEBUG, VMS Debugger Explanation: The file variable references a file descriptor that cannot be read, is incomplete, or points to a file that is not open. User Action: Correct the file descriptor. 3 ILLFLOAT float_value is an illegal floating point value Facility: DEBUG, VMS Debugger Explanation: The Debugger attempted to parse the given floating point number and encountered an illegal character. User Action: Correct the floating point number. 3 ILLINVNUM invalid invocation number at invoc_num Facility: DEBUG, VMS Debugger Explanation: An illegal invocation number was specified (must be in decimal radix). User Action: Specify a legal decimal invocation number. 3 ILLLENGTH illegal length field length_value in structure reference Facility: DEBUG, VMS Debugger Explanation: A negative value was given for the length of a field in a structure reference. User Action: Change the field length to a non-negative value. 3 ILLNUMPATH illegal numeric pathname at path_name Facility: DEBUG, VMS Debugger Explanation: An illegal numeric pathname was specified (must be in decimal radix). User Action: Specify a legal decimal numeric pathname. 3 ILLPACSIZ illegal packed size size_value; must be 0..31 Facility: DEBUG, VMS Debugger Explanation: The specified size on a /PACKED qualifier is illegal. It must be a value between 0 and 31. User Action: Specify a legal value with the /PACKED qualifier. 3 ILLPATH1 illegal use of %SOURCE_SCOPE (must not be combined with invocation numbers) Facility: DEBUG, VMS Debugger Explanation: %SOURCE_SCOPE has been used in the same path with other scope numbers. User Action: Remove all but one of the references to the desired scope. 3 ILLPATH2 illegal use of %SOURCE_SCOPE (must appear at the start of the pathname) Facility: DEBUG, VMS Debugger Explanation: %SOURCE_SCOPE has been used in a path name in an illegal position. The %SOURCE_SCOPE lexical must be the first item in the path list. User Action: Move the %SOURCE_SCOPE lexical to the first position in the pathname. 3 ILLPATHELEM illegal pathname element at path_name Facility: DEBUG, VMS Debugger Explanation: Invocation numbers cannot be used with other pathnames. User Action: Eliminate the continuation of the pathname after the invocation number. 3 ILLPATHIDENT unknown identifier in pathname at path_name Facility: DEBUG, VMS Debugger Explanation: An illegal identifier was specified in the pathname. User Action: Specify a legal identifier. 3 ILLPOSFLD position field value position_value is too large Facility: DEBUG, VMS Debugger Explanation: The value of the position specifier in the BLISS field reference is an incredibly large number, larger than the Debugger can handle. The value may be negative, which is also illegal. User Action: Change the value of the position specifier in the BLISS field reference to a smaller (or positive) value. 3 ILLQUALIF illegal or unsupported qualifier on command Facility: DEBUG, VMS Debugger Explanation: One of the qualifiers to the command is incorrect. User Action: Remove the incorrect qualifier to the command. 3 ILLRANGE subscript range not permitted here (must be at lowest level of data structure) Facility: DEBUG, VMS Debugger Explanation: The Debugger does not allow a range in an EXAMINE except as the last index in the array. That is, the memory to examine must be a contiguous region. Unconnected slices of arrays are not allowed. User Action: Remove the range from the expression to examine. Placing the corrected EXAMINE inside a Debugger FOR loop command could provide the functionality needed to do the command as originally desired. 3 ILLSETCON illegal set constant in expression Facility: DEBUG, VMS Debugger Explanation: One of the constants specified in the given set expression has a type that is inconsistent with the set type. User Action: Change the erroneous set constant value to a constant with a type that agrees with the set type. 3 ILLSIGEXT illegal sign extension field value extension_value Facility: DEBUG, VMS Debugger Explanation: An illegal value has been entered for the sign extension field in a field reference. User Action: Re-enter the command using a valid sign extension field value. 3 ILLSIZFLD illegal size field size_value; must be 0..size_limit Facility: DEBUG, VMS Debugger Explanation: The size value for a BLISS field reference contains an illegal value. User Action: Change the size value of the field reference to an integer between 0 and size_limit, inclusive. 3 ILLSUBLEN substring length larger than 32K not supported Facility: DEBUG, VMS Debugger Explanation: The calculated length of a substring in the expression is larger than can be handled by the Debugger. User Action: Do not use a substring with a length greater than 32K in an expression to be evaluated by the Debugger. 3 ILLSUBSTR can only apply substring operation to string data types Facility: DEBUG, VMS Debugger Explanation: The Debugger has found a substring operation, but the data type of the operand is not a string type. User Action: Correct the data type of the string operand in the substring expression. 3 ILLTHUNKADDR illegal thunk call address Facility: DEBUG, VMS Debugger Explanation: The debugger detected a 0 addressed compiler- supplied routine during Value Spec evaluation. User Action: Submit a Software Performance Report (SPR) to the appropriate compiler. 3 ILLTYPE illegal type of operand(s) Facility: DEBUG, VMS Debugger Explanation: The type of the operand is illegal for the operator specified. User Action: Change the operand. 3 ILLVQUAL illegal vector instruction qualifier specified at 'command_line' Facility: DEBUG, VMS Debugger Explanation: A vector instruction qualifier that is illegal for this vector instruction was specified during a DEPOSIT/INSTRUCTION command. User Action: Do not specify that illegal qualifier on that instruction. 3 IMAGENF target image file_specification not found on host system Facility: DEBUG, VMS Debugger Explanation: An image that is loaded on the target system or represented in the dump file does not have a matching copy on the host system. The debugger can not load any information about this image, therefore, symbolic debugging of code in the image is impossible. User Action: Check the the image search path on the host system for this image. Either fix the search path or place a copy of this image in that path and restart the debug session. 3 IMGMISMATCH target system image file_specification does not match host copy Facility: DEBUG, VMS Debugger Explanation: An image that is loaded on the target system does not match the host copy of that image. This occurs when the link time in the image header for the DSF or EXE file on the host does not match the link time of the target system's image. User Action: Verify that the image path is set up correctly and that it points to the same images as are loaded on the target system. 3 INCDSTNES incorrect DST nesting in module path_name, compiler error Facility: DEBUG, VMS Debugger Explanation: Incorrect symbol table nesting occurred, such as improper routine or data record nesting in the specified module. This message normally indicates a compiler error. User Action: Submit a Software Performance Report. 3 INCMPSTACK WARNING: stack corrupted; session integrity not guaranteed Facility: DEBUG, VMS Debugger Explanation: While walking the call stack, the debugger has determined that the stack has been corrupted. It did however, find some valid call frames and will attempt to continue with that information. Continuation in the presence of a corrupted stack typically results in unpredictable program and debugger behavior. User Action: Look at what little valid information is left and then start over. Attempt to find and fix the point where the stack gets corrupted. It may be possible to examine program state, but continuing instruction execution typically results in unpredictable program and debugger behavior. 3 INCOMPOPR operand number operand_number incomplete Facility: DEBUG, VMS Debugger Explanation: When parsing an instruction, the debugger found an incomplete operand. User Action: Specify complete operands when entering machine instructions. 3 INCOMPPTR pointers of different size, cannot perform subtraction Facility: DEBUG, VMS Debugger Explanation: The two pointers point to objects with incompatible types. A computation involving these pointers does not have a meaningful result. User Action: Do not attempt to mix pointers of different types in arithmetic computations. 3 INCOMQUAL qualifier qualifier_name is not compatible with qualifier_name(s) Facility: DEBUG, VMS Debugger Explanation: Qualifiers specified with the command conflict in their operations. User Action: Specify non-conflicting qualifiers. 3 INCOMTARGET a debugger_type kernel debugger is incompatible with a debugger_type main debugger Facility: DEBUG, VMS Debugger Explanation: A kernel debugger attempted to connect to a main debugger with which it is not compatible. User Action: Make sure that the logical names used to point at the sharable and non_sharable debugger images are defined to point to the same type of debuggers. 3 INCOMVERSION the RPC versions of the main and kernel debuggers are incompatible Facility: DEBUG, VMS Debugger Explanation: A kernel debugger attempted to connect to a main debugger with which it is not compatible. User Action: Make sure that the logical names used to point at the sharable and non_sharable debugger images are defined to point to the same type of debuggers. 3 INDBASEQL index and base registers are equal for operand number operand_number Facility: DEBUG, VMS Debugger Explanation: When parsing an instruction, the debugger found an operand whose base register and index registers were the same. The VAX instruction architecture forbids this construction. User Action: Specify different registers for the base and index registers. 3 INIBRK target system interrupted Facility: DEBUG, VMS Debugger Explanation: The target system has hit a break point in the INI$BRK system routine. The system code calls this routine in order to return control to the debugger either because the call is compiled into the code or an IPL 14 interrupt was generated. User Action: None. 3 INITERR an error has occurred during debugger initialization, unable to continue this session. Facility: DEBUG, VMS Debugger Explanation: The debugger encountered an error during initialization which does not allow this debugging session to proceed. User Action: Use the message which preceded this message to analyze and correct the error, and try again. 3 INITIAL Language: language_name, Module: path_name Facility: DEBUG, VMS Debugger Explanation: This message is displayed when the debugger is invoked by the image activator. The language is set to language_ name, and the module to path_name. Module path_name is the first module specified in the LINK command, and language language_name is the language used in that module. User Action: None. 3 INPREADERR error reading input line: Facility: DEBUG, VMS Debugger Explanation: There was an error from the system while trying to read the input line. User Action: Re-enter the command line. Check to see that the Debugger has read access to the input source. If the problem persists, submit a Software Performance Report (SPR). 3 INSNOTCURAV No instructions for address address_value Facility: DEBUG, VMS Debugger Explanation: No instructions correspond to the address address_ value. User Action: None. This message is informational. 3 INSVIRMEM insufficient virtual memory for the debugger memory pool Facility: DEBUG, VMS Debugger Explanation: Failed to allocate additional memory for working storage. User Action: Cancel set modules to free space in memory and try again. 3 INTERR debugger error in debugger_routine_name or session corruption Facility: DEBUG, VMS Debugger Explanation: The debugger has encountered an internal error or session corruption. User Action: If the error is reproducible, and is not an obvious side effect of the user program (i.e. stack corruption, resource exhaustion, etc.) submit a Software Performance Report (SPR) and if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 INTERRUPTED process interrupted via cross-process signal Facility: DEBUG, VMS Debugger Explanation: This signal is delivered asyncronously to a process to cause the debugger to be invoked in that process. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 INTMEMERR internal memory-pool error Facility: DEBUG, VMS Debugger Explanation: The debugger's internal memory area has been corrupted or is inconsistent. This can be caused by an internal debugger error or by random stores by the user program. User Action: Correct the user program. If the problem still exists, submit a Software Performance Report (SPR). 3 INTOVF integer overflow at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: The value being deposited does not fit into the specified address. User Action: Specify either a smaller value or a different target address. 3 INTVECERR internal debugger coding error in using vector instruction(s) Facility: DEBUG, VMS Debugger Explanation: An internal debugger error has been encountered when attempting to execute a vector instruction. Messages will follow this text which will more fully explain the error. User Action: If the error is reproducible, submit a Software Performance Report and, if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 INUMTRUNC number truncated at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: On some conversions packed numbers need to be truncated to fit into their destination. Truncation is done from the least significant digit to the most significant digit. User Action: You should understand that the result of the operation is imprecise and may not be exactly what you expect. 3 INVALTEXTRANG error retrieving text from an object. Facility: DEBUG, VMS Debugger Explanation: The debugger found a discrepancy in the ranges of the text string that was retrieved. User Action: No action necessary. 3 INVARGLIS invalid argument list for 'the debugger_command_segment' Facility: DEBUG, VMS Debugger Explanation: There is an error with the argument list. The Debugger may be expecting an argument list when none was supplied. The Debugger may have found an argument list where one was not expected. The Debugger may have found an argument list that was too long or too short. Finally, the Debugger may have found an inconsistency in the argument list. User Action: Correct the command. Supply the correct argument list if one was missing or in error. Delete the inappropriate argument list, if one was present. 3 INVARRDIM array dimension is out of range Facility: DEBUG, VMS Debugger Explanation: The array dimension is out of the range of the declared size and shape of the array. Either the dimension requested is less than zero, or it is greater than the number of dimensions the array was declared with. User Action: Correct the invalid array dimension. 3 INVARRDSC invalid array descriptor Facility: DEBUG, VMS Debugger Explanation: An array descriptor in the image does not have the correct format. This can be caused by a reference to a VAX BASIC array when the first line of the program has not been executed. The array is not set up correctly until the BASIC program initialization is done. This message can also be caused by a user program or DEPOSIT commands altering a compiler generated array descriptor. This can also be caused by an incomplete array declaration in C or C++. For example, the declaration extern int element_array[] can result in an array descriptor with a zero stride. User Action: If the reference is to a VAX BASIC array, enter a STEP or GO command to ensure that the BASIC program initialization is done and then repeat the reference. If the reference is to an Alpha C array, try accessing the global symbol table definition for the array by upper-casing the array name. Otherwise, submit a Software Performance Report (SPR). 3 INVCHAR invalid character Facility: DEBUG, VMS Debugger Explanation: When parsing the command, an invalid character was detected. User Action: Enter the command specifying only valid characters. 3 INVCHARLOCALE invalid character in current locale Facility: DEBUG, VMS Debugger Explanation: An illegal character in the current locale has been found. User Action: Reenter the string using valid characters. 3 INVCHRCON invalid character constant in expression Facility: DEBUG, VMS Debugger Explanation: When evaluating a language expression, the debugger expected to find a closing single quote mark, or the end of the command. Some other character was found, which resulted in an illegal language expression. User Action: Enter a valid language expression. 3 INVCMD command is not available for this configuration Facility: DEBUG, VMS Debugger Explanation: This command is not available for this configuration of the debugger. It may be available in a future version. User Action: None. 3 INVDEPTH unable to access stack to depth of depth Facility: DEBUG, VMS Debugger Explanation: The debugger is trying to access the register set of a frame depth frames down on the stack. User Action: If you explictly requested for information about that frame, (e.g. via a previous SET SCOPE command), modify your command such that it is requesting information about a valid frame. 3 INVDESC invalid string descriptor Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 INVDIGBIN invalid digit in binary number: number_value Facility: DEBUG, VMS Debugger Explanation: A numeric value other than '0' and '1' was found in a binary number. User Action: Enter binary numbers specifying only digits '0' and '1'. 3 INVDIGDEC invalid digit in decimal number: number_value Facility: DEBUG, VMS Debugger Explanation: A numeric value other than in the range '0' through '9' was found in a decimal number. User Action: Enter decimal numbers specifying only digits '0' through '9'. 3 INVDIGHEX invalid digit in hexadecimal number: number_value Facility: DEBUG, VMS Debugger Explanation: A numeric value other than in the range '0' through '9' or an alphabetic value other than in the range 'A' through 'F' was found in a hexadecimal number. Hexadecimal numbers must also start with a numeric character, for example '0F'. User Action: Enter hexadecimal numbers specifying only digits '0' through '9' and alphabetic values 'A' through 'F'. 3 INVDIGOCT invalid digit in octal number: number_value Facility: DEBUG, VMS Debugger Explanation: A numeric value other than in the range '0' through '7' was found in a decimal number. User Action: Enter decimal numbers specifying only digits '0' through '7'. 3 INVDIRNAM invalid directory name: file_specification Facility: DEBUG, VMS Debugger Explanation: The directory name 'file_specification' given in a DEBUGGER command SET SOURCE is not valid. Either the directory syntax is incorrect or the directory does not exist. User Action: Ensure that the directory exists and that the syntax is correct. 3 INVDMTPTR invalid DMT pointer; internal linker or debugger error Facility: DEBUG, VMS Debugger Explanation: The debugger found that the pointer in the image header to the Debug Module Table (DMT) was invalid. The debugger will continue from this error trying to initialize based on the Debug Symbol Table (DST). User Action: Check that the image file hasn't been modified or corrupted in some way. If not, submit a Software Performance Report (SPR). 3 INVDSPSIZ invalid display size: display_size Facility: DEBUG, VMS Debugger Explanation: The SIZE value for a display must be between 1 and 1000. User Action: Specify the SIZE value between 1 and 1000. 3 INVDSTREC invalid DST record Facility: DEBUG, VMS Debugger Explanation: The debugger has detected an error in the Debug Symbol Table of your program. This indicates an internal error in either the debugger or the compiler of this module. User Action: Please submit a Software Performance Report (SPR). 3 INVEXPR invalid expression for operand number operand_number Facility: DEBUG, VMS Debugger Explanation: The specified operand was not correct for this instruction. User Action: Please check the documentation for the correct operands for this instruction, and re-enter the instruction with the correct operands. 3 INVFILHNDL invalid file handle Facility: DEBUG, VMS Debugger Explanation: The debugger has detected an invalid file handle for the given context connection. This indicates an internal error in either the debugger or the compiler. User Action: Please submit a Software Performance Report. 3 INVFIXDST invalid DST fixup records in image image_name, symbol references to shareable images may be erroneous Facility: DEBUG, VMS Debugger Explanation: While attempting to read the symbol table information in the specified image, the debugger found errors in the symbol table address fixup records. These records are used to adjust for the base addresses of shareable images. This means that any symbols in this image which point to addresses in other (shareable) images will most likely be incorrect. Symbols which refer to addresses in this image will be correct unless this is also a shareable image. User Action: Relink the image and, if the error is reproducible, submit a Software Performance Report explaining how the image file was created. 3 INVFLDREF invalid field reference; too many or few parameters Facility: DEBUG, VMS Debugger Explanation: The Debugger could not complete the parse of the BLISS field reference specification. Either the closing angle bracket terminator was found too soon, or it was not found when it was expected. User Action: Correct the field reference. 3 INVGSTREC invalid GST record Facility: DEBUG, VMS Debugger Explanation: The debugger has detected an error in the Global Symbol Table of your program. This indicates an internal error in either the debugger or the compiler of this module. User Action: Please submit a Software Performance Report (SPR). 3 INVGSTTYP invalid GST record; GST is partially built Facility: DEBUG, VMS Debugger Explanation: The debugger found an invalid Global Symbol Table (GST) record in the image. The debugger will discontinue initializing the GST at this point. The debugger will continue from this error, however global symbol information may not be complete. User Action: Check that the image file hasn't been modified or corrupted in some way. If not, submit a Software Performance Report (SPR). 3 INVMAR right margin must be greater than left Facility: DEBUG, VMS Debugger Explanation: You specified a right margin that was less than the left margin in the debugger command SET MARGIN. The right margin must be greater than the left margin. User Action: Re-enter the command specifying a valid margin range. 3 INVNUMBER invalid numeric string 'number_value' Facility: DEBUG, VMS Debugger Explanation: A numeric value which was not in the specified radix was found in the language expression. User Action: Enter numbers specifying only valid digits for that radix. 3 INVNUMSRC invalid number of source files Facility: DEBUG, VMS Debugger Explanation: An invalid number of source files was specified on the SET MAX_SOURCE_FILES command. The maximum number of source files that the debugger will keep open simultaneously is 20. User Action: Re-enter the command specifying a valid number within the range. 3 INVNUMSTR invalid numeric string at or near 'number_value' Facility: DEBUG, VMS Debugger Explanation: The debugger encountered an error when attempting to convert the specified value. This indicates that the string value did not contain a valid number. User Action: Ensure that the string value contains only valid digits. 3 INVOPADDR invalid operator 'operator_symbol' in address expression Facility: DEBUG, VMS Debugger Explanation: Address expressions cannot contain operators. User Action: Enter the address expression without operators. 3 INVOPSYM invalid operator symbol 'operator_symbol' in expression Facility: DEBUG, VMS Debugger Explanation: Identifiers in address expressions must be shorter than 256 characters. User Action: Enter a shorter identifier. 3 INVPAGE invalid screen height, value must be between minimum_height and maximum_height Facility: DEBUG, VMS Debugger Explanation: The height of the terminal which the debugger uses to place it's windows must be between the values specified. User Action: Specify the page size of the screen to be between the values specified. 3 INVPASS the password does not match the target system password Facility: DEBUG, VMS Debugger Explanation: The password specified in the connect command does not match the password in the target systems password file. Or, no password was specified and the target system requires one. User Action: Check to make sure the correct node name and password were specified. Check the target system to make sure both were set up correctly. 3 INVPRCSYN process specification syntax error Facility: DEBUG, VMS Debugger Explanation: The specified process specification is syntactically invalid User Action: Re-enter the command specifying a correct process specification 3 INVPRIOR invalid task priority value specified Facility: DEBUG, VMS Debugger Explanation: The priority of an Ada task must be between 0 and 15. User Action: Specify a valid priority for the task. 3 INVRANSPEC invalid range specification in array subscript Facility: DEBUG, VMS Debugger Explanation: A range specification in an array reference is illegal. The Debugger may have found a range where none is allowed. An asterisk may have been used as a range where it is not allowed. The array subscripts may have more than one set of ranges, which is not allowed. The range may be invalid, with bounds greater than the declared bounds of the array. Finally, the lower bound of the range may be greater than the upper bound of the array. User Action: Correct the range specification in the array subscript. 3 INVSELDIS invalid selection of display_name display; wrong display kind Facility: DEBUG, VMS Debugger Explanation: Some attributes can only be placed on certain types of displays. For example, the SOURCE attribute can only be placed on source displays. The attribute you specified cannot be placed on the display you specified. User Action: See the debugger documentation of the SELECT command for details on which attributes can be placed on which displays. Specify attributes which are compatible with the display kind. 3 INVSRCLIN invalid source line range Facility: DEBUG, VMS Debugger Explanation: An invalid source line range was entered in the debugger TYPE command. The first line number of the range must be non-negative and less than or equal to the second number in the range. User Action: Re-enter the command specifying a valid line number range. 3 INVTIMSLI time slice was not set, parameter is out of range Facility: DEBUG, VMS Debugger Explanation: The value specified for the time slice was out of range for the Ada type DURATION used by the debugger. User Action: See the Ada documentation for the range of the DURATION type. Specify time slice values which are in range. 3 INVWIDTH invalid screen width, must be between minimum_width and maximum_ width Facility: DEBUG, VMS Debugger Explanation: The width of the terminal which the debugger uses to place its windows must be between the values specified. User Action: Specify the width of the screen to be between the values specified. 3 INVWINPAR invalid window parameter: number_value Facility: DEBUG, VMS Debugger Explanation: The value specified was out of range of the screen on which the window will be placed. If the debugger is placing its windows on a terminal screen, the beginning row and column numbers must be between 1 and the height and width of the screen, and the beginning value plus the height or width of the window must not exceed the height or width of the terminal screen. If the debugger is running with the DECwindows interface, the beginning row and column numbers must be greater than 0. User Action: Specify valid parameters for the window row and column values, and for the height and width of the window. 3 IRFAOVF record file address overflow at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: The conversion of the ASCII string to a record file address caused an overflow. The conversion was performed however. User Action: Check the value to make sure the conversion performed as expected. 3 ISTRTRU string truncated at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: The string did not fit into the specified destination resulting in lost trailing characters. The conversion was performed however. User Action: Check the value to make sure the conversion performed as expected. 3 ITMNOTAVA item not available Facility: DEBUG, VMS Debugger Explanation: The user should never see this message. The debugger uses an item list construct for passing information between its parts. This message indicates that the requesting routine requested data which the target routine was not capable of providing. Appearance of this message indicates an internal problem in the debugger. User Action: Submit a Software Performance Report (SPR) 3 ITMTRUNC item truncated - buffer of insufficient size Facility: DEBUG, VMS Debugger Explanation: The user should never see this message. The debugger uses an item list construct for passing information between its parts. This message indicates that the requesting routine allocated a buffer which was too small for the requested data. Appearance of this message indicates an internal problem in the debugger. User Action: Submit a Software Performance Report (SPR) 3 IVALNOFIT value does not fit into target location at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: The value can not be represented in the target location and may be truncated. The bit field is not large enough to hold the value. User Action: Check the value in the target location. 3 IVALOUTBNDS value assigned is out of bounds at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: The value is out of the bounds defined for the data. The operation was performed however. User Action: Check the results of the operation to make sure they are as you expected. 3 IVPRCLOG logical name DBG$PROCESS must be either MULTIPROCESS or DEFAULT Facility: DEBUG, VMS Debugger Explanation: The logical name DBG$PROCESS translates to something other than "MULTIPROCESS" or "DEFAULT". User Action: Correct the logical name assignment for DBG$PROCESS and try again. 3 KEPTNOT1PROC the Kept Debugger must be run as a multi-process debugger Facility: DEBUG, VMS Debugger Explanation: The kept debugger must be a master process running and rerunning programs as subprocesses. This is not possible for a one process debugger. The kept debugger must be run using more than one process. User Action: Correct the logical name assignment for DBG$PROCESS to be either "MULTIPROCESS" or "DEFAULT", and try again. 3 KERFUNCNYI Kernel Function function_name not yet implemented on this architecture Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 KERNOTAVAIL host kernel of the VMS system debugger not available Facility: DEBUG, VMS Debugger Explanation: The host kernel for the VMS system debugger is not available on this system so a connection could not be made. User Action: Contact your Digital Representative on the availability of this feature. 3 KEYNAMERR unrecognized key name: key_name Facility: DEBUG, VMS Debugger Explanation: This keyname is in error. It can not be defined by the user. User Action: Check spelling of the key name. 3 KEYSTATERR unrecognized state name: state_name Facility: DEBUG, VMS Debugger Explanation: This key state is in error. It has not been defined by the user. User Action: Check spelling of the state name or define the state. 3 LASTCHANCE stack exception handlers lost, re-initializing stack Facility: DEBUG, VMS Debugger Explanation: The user's program contained an error that caused the exception handling mechanism to fail. This error occurs when the stack is overwritten by the user program or by deposit commands. User Action: Identify and correct the error in the user program. 3 LINEINFO line-description Facility: DEBUG, VMS Debugger Explanation: This is either 'No line information available', or 'No line , previous line is , next line is ' 3 LOGFILEIS the error log is in file file_specification Facility: DEBUG, VMS Debugger Explanation: An internal debugger error has occurred, and information which will be useful in locating the error has been written to file_specification. User Action: If the error is reproducible, submit a Software Performance Report (SPR) and, if possible, enclose a copy of the program being debugged, program build steps, and a logged debugging session that reproduces the error. 3 LONGSTRING strings longer than 2**16 characters not supported Facility: DEBUG, VMS Debugger Explanation: The length of a string or the range of one array bound is greater than 2**16. The string or array is too large for the Debugger. User Action: Do not use strings of this length with the Debugger. 3 LOOPINCR loop increment cannot be zero Facility: DEBUG, VMS Debugger Explanation: The loop increment specified on the FOR command is zero. User Action: Change the loop increment to be a non-zero value. 3 LOOPVAR loop var loop_variable has been redefined; exiting for loop Facility: DEBUG, VMS Debugger Explanation: Since the loop variable has been redefined, the debugger will exit the loop. No further comparison is possible. User Action: None. 3 LOWBNDOPT lower bound of subrange was optimized away Facility: DEBUG, VMS Debugger Explanation: The lower bound of the subrange was optimized away. The largest negative number on the machine is being used as the lower bound. User Action: You may wish to recompile the program without optimizations. 3 MAINFUNCNYI Main Function function_name not yet implemented on this architecture Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 MASKMISMATCH mask/target subscripts do not match, displaying mask Facility: DEBUG, VMS Debugger Explanation: The subscript values for the supplied mask value are different then the subscript values for the target value. To minimize confusion, Debug is showing the mask values as well as the target values. User Action: None, this message is informational. 3 MASKNOTUSED mask operations not allowed on record and SCAN tree objects Facility: DEBUG, VMS Debugger Explanation: A mask operation (as specified by the /TMASK or /FMASK qualifiers) cannot be performed on a record or SCAN tree object. User Action: Specify an array or address range to perform the mask operation on. 3 MASKNOTVMR mask used is not %VMR, displaying specified mask Facility: DEBUG, VMS Debugger Explanation: The supplied mask is not %VMR. To minimize confusion, Debug is showing the mask values as well as the target values. User Action: None, this message is informational. 3 MASKPARNREQ parenthesis required in 'EXAMINE/xMASK=(x)' Facility: DEBUG, VMS Debugger Explanation: Parentheses are required around the mask expression specified with the /TMASK or /FMASK qualifiers on the Examine command. User Action: Include parantheses when specifying a mask expression. 3 MATQUOMIS matching quote is missing Facility: DEBUG, VMS Debugger Explanation: The matching quote at the end of a quoted string is missing. User Action: Correct the error and re-enter the command. 3 MCHVECNOREAD mechanism array for exception frame frame-addr at mchvec-addr is not readable Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers. The debugger has determined that part or all of the mechanism array for the exception frame at frame-addr is not accessible for reading. This vector lies at mchvec-addr. This usually indicates a corrupt frame list, but could also indicate that the program has protected part of memory in which the frame lies. In either case, this is an error. User Action: Determine what part of your code is writing into the FP register or overwriting the saved frame pointer on the call stack (or a preceding saved frame pointer) and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 MISCLOSUB missing closing subscript parenthesis Facility: DEBUG, VMS Debugger Explanation: This is a syntax error in a Debug command User Action: Reinvoke the command with the proper syntax 3 MISINVNUM misplaced invocation number in path_name Facility: DEBUG, VMS Debugger Explanation: The invocation number was not placed after the innermost (rightmost) routine name in the specified pathname. User Action: Correct the pathname and re-enter the command. 3 MISINVOPER missing or invalid operator at 'operator_symbol' Facility: DEBUG, VMS Debugger Explanation: An operand was encountered in a language expression when an operator was expected. For example, 'EVALUATE A B' instead of 'EVALUATE A + B'. User Action: Specify valid operators between operands. 3 MISMODBEG missing Module-Begin record in DST (compiler error) Facility: DEBUG, VMS Debugger Explanation: An expected Module-Begin record was not found in the debugger Symbol Table. This indicates a probable error in the compiler output. User Action: Submit a Software Performance Report (SPR). 3 MISMODEND missing Module-End in DST for path_name (compiler error) Facility: DEBUG, VMS Debugger Explanation: An expected Module-End record was not found in the debugger Symbol Table. This indicates a probable error in the compiler output. User Action: Submit a Software Performance Report (SPR). 3 MISOPEMIS misplaced operator or missing operand at 'operator_symbol' Facility: DEBUG, VMS Debugger Explanation: An operand was encountered in a language expression when an operator was expected, or an operand did not follow an operator. For example, 'EVALUATE A B' or 'EVALUATE A + ' instead of 'EVALUATE A + B'. User Action: Specify valid operators between operands. 3 MODUSCOPE a module name was expected; path_name not valid Facility: DEBUG, VMS Debugger Explanation: This is a syntax error in a Debug command User Action: Reinvoke the command with the proper syntax 3 MONITMNOTFND error searching for information on a monitor item. Facility: DEBUG, VMS Debugger Explanation: When looking for up information for a particular monitor item, the debugger detected an error. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 MONVALTRUNC monitor value truncated to 256 characters. Facility: DEBUG, VMS Debugger Explanation: The monitor view displays a maximum of 256 character values. User Action: You may monitor specific character ranges or monitor the value in hex. 3 MPARENREQ parenthesis required around process list in debug_command Facility: DEBUG, VMS Debugger Explanation: Parentheses must be placed around the process list for debugger commands SET/PROCESS=(process-list) or DO/PROCESS=(process-list). User Action: Place parentheses around the process list in the command. 3 MPCOMMAND command is only valid when multiprocess support is enabled Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to execute the specified command since it is only valid when the debugger's multiprocess support is enabled. User Action: Restart the debugging session with multiprocess support enabled. Multiprocess support is enabled by defining the logical name DBG$PROCESS as follows: ($ DEFINE/JOB DBG$PROCESS MULTIPROCESS) 3 NAMSTRMIS name string missing or invalid in %NAME construct Facility: DEBUG, VMS Debugger Explanation: The %NAME construct requires either a quoted string or a name to be supplied. User Action: Specify a valid name after the %NAME construct. 3 NAMTOOLONG name is too long: 'symbol_name' Facility: DEBUG, VMS Debugger Explanation: Display and window names must be less than 80 characters in length. User Action: Shorten the name to be less than 80 characters long. 3 NEEDMORE unexpected end of command line Facility: DEBUG, VMS Debugger Explanation: The command entered was not complete. A required part of the command was omitted. User Action: Re-enter the complete command. 3 NEEDPAREN parenthesis required in THEN, ELSE, and DO clauses Facility: DEBUG, VMS Debugger Explanation: Parenthesis are required in THEN, ELSE, and DO clauses to group the containing debugger commands. User Action: Correct the THEN, ELSE, or DO clause by including parenthesis. 3 NETFAIL network connection failed, reason = reason_code Facility: DEBUG, VMS Debugger Explanation: The network connection between the host debugger and target system can fail for a variaty of reasons. The target system may have stopped responding or crashed. Or there could have been too many collisions on the network. User Action: Check the reason code in the documentation. 3 NETRETRY connection to target system failed, retrying Facility: DEBUG, VMS Debugger Explanation: Either the connection could not be started or was interrupted due to a failure. The host debugger will try to re- connect to the target system. User Action: If no connection is re-made after many retries, check the target system's console for errors. Also check the network. 3 NOACCESSR no read access to address address_value Facility: DEBUG, VMS Debugger Explanation: The address you specified cannot be read by the debugger. Therefore the operation you requested cannot be performed. User Action: Verify that the address being read is correct. One way to do this is to use EVALUATE to find the address of the specified symbol, or to EXAMINE the descriptor to see if it specifies a valid address. 3 NOACCESSW no write access to address address_value Facility: DEBUG, VMS Debugger Explanation: A DEPOSIT, SET BREAK, or SET TRACE command specified the address address_value. The debugger does not have write access to that page. The debugger requires write access in order to be able to set up breakpoints and tracepoints. User Action: None. You cannot do the requested operation without proper access. 3 NOADDRREG register register_name does not have an address use @register_name to obtain the contents of register register_name Facility: DEBUG, VMS Debugger Explanation: The user has requested the address of a register but registers do not have addresses User Action: Examine the register directly 3 NOALOCERRLIST could not allocate an error list. Facility: DEBUG, VMS Debugger Explanation: A problem was detected in the processing of an ACA Services message and Debug could not allocate an error list so that this error could be reported to ACA Services. User Action: Submit a Software Performance Report (SPR). 3 NOALTERSP deposit into register 14 (stack pointer) not allowed Facility: DEBUG, VMS Debugger Explanation: You cannot deposit into the stack pointer register because the debugger is on the stack and it would corrupt the debugger or program stack frames. User Action: None. 3 NOATTACH attach command failed Facility: DEBUG, VMS Debugger Explanation: The ATTACH command could be not performed because of an error which was returned by the system service called by the debugger. The error status returned by the system service routine follows this message. User Action: Correct the problem based on the associated message which follows the debugger error message. 3 NOBKPTEXT error retrieving the text associated with a breakpoint. Facility: DEBUG, VMS Debugger Explanation: The debugger could not retrieve the associated text which belongs to a breakpoint. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 NOBKPTVIEW the breakpoint view has not been activated. Facility: DEBUG, VMS Debugger User Action: Create the breakpoint view from the "VIEW" menu. 3 NOBREAGGR break or trace points on registers, records or arrays are not allowed Facility: DEBUG, VMS Debugger Explanation: Only watchpoints are allowed on registers, records or arrays. User Action: Either change the address of the breakpoint or tracepoint, or specify a watchpoint on the address. 3 NOBREAKAT cannot set break or trace at address address_value Facility: DEBUG, VMS Debugger Explanation: The user has requested that a breakpoint be set at an address that is either non-writable, in Debug, or invalid in some other way. User Action: Correct the address and reissue the command 3 NOBREAKS no breakpoints are set Facility: DEBUG, VMS Debugger Explanation: The SHOW BREAK command was entered and no breakpoints were set. User Action: None. 3 NOCALLS no active call frames Facility: DEBUG, VMS Debugger Explanation: The call stack cannot be displayed because your program has run to completion, and there are no call frames on the stack. User Action: None. 3 NOCANMAIN cannot cancel main image Facility: DEBUG, VMS Debugger Explanation: The user has requested that the main image symbols be canceled. This is an invalid operation. User Action: No action required - operation invalid. 3 NOCLI no CLI present to perform function Facility: DEBUG, VMS Debugger Explanation: There is no command line interpreter in the target process from which to perform the operation. User Action: None. You cannot perform the attempted operation. 3 NOCONNECT CONNECT command failed Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to execute the connect command. The reason is given in the message following this message. User Action: Correct the problem given by the messages following this message. Most often, the problem is due to specifying a process that does not exist. 3 NOCONNECTDEBUG you cannot connect a debugger to itself Facility: DEBUG, VMS Debugger Explanation: The process you are trying to connect to is this debugger. User Action: Use the connect command with a process name or process id of the process you actually want to connect to and that is NOT your current main debugger. 3 NOCORRFAC cannot perform operation without the Correlation Facility Facility: DEBUG, VMS Debugger Explanation: The given operation requires the Correlation Facility and the appropriate correlation data. Without this information, the debugger cannot determine how to complete the operation. User Action: Make sure that the Correlation Facility is appropriately set up and in use when compiling and debugging the given program. 3 NOCROSSPROC cross-process signal system service is not available Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to execute the specified command because the cross-process signal system service is not available in this version of VMS. User Action: Upgrade to a version of VMS that has the cross- process signal system service. 3 NOCROSSUICGRP cannot connect to a process with a different UIC group Facility: DEBUG, VMS Debugger Explanation: The given operation is not supported by the Debugger. You can only connect to processes with the same UIC group as the process running the Debugger. User Action: Make sure that the process you want to connect to is in the same UIC group as the process running the Debugger. 3 NOCURLOC current location not defined Facility: DEBUG, VMS Debugger Explanation: '.' is not currently defined. User Action: Do not reference '.' until an EXAMINE or EVALUATE/ADDRESS command has been performed. 3 NODECTHREADSUP this command qualifier is not supported by POSIX Threads Facility: DEBUG, VMS Debugger Explanation: The POSIX Threads facility does not support this feature. User Action: None. 3 NODEFSCPE No default scope list: error performing !AC Facility: DEBUG, VMS Debugger Explanation: The specified command or built-in symbol requires that the default scope list be established. User Action: To establish the default scope list, perform a CANCEL SCOPE command. 3 NODEFWIND no default window in which to attach your display. Facility: DEBUG, VMS Debugger Explanation: The display specified did not have a window associated with it. The Debugger attempted to attach it to a default window called H1. Debugger discovered that the H1 window had been deleted. User Action: Either re-create window H1 or specifically specify a window that exists when creating a new display. 3 NODELIMTR missing or invalid instruction operand delimiter Facility: DEBUG, VMS Debugger Explanation: A DEPOSIT command specified an invalid instruction operand format. User Action: Re-enter the command with valid operands. 3 NODEPDEBUG depositing into the debugger's address space is not allowed Facility: DEBUG, VMS Debugger Explanation: The user has tried to deposit into addresses occupied by the Debugger. This is not allowed. User Action: Correct the address and reissue the command. 3 NODIRLISM no source directory list in effect for path_name Facility: DEBUG, VMS Debugger Explanation: The debugger command CANCEL SOURCE/MODULE=path_name failed because there is no source directory search list in effect for module path_name. User Action: This is an informational message. However, if the wrong module was specified, the command should be re-entered with the correct name. 3 NODIRLIST no source directory list in effect Facility: DEBUG, VMS Debugger Explanation: The debugger command CANCEL SOURCE had no effect because no source directory search list is currently in effect. User Action: None. This message is informational. 3 NODIRNAMESELECTED no directory is selected. Facility: DEBUG, VMS Debugger 3 NODISCONNECT DISCONNECT command failed Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to execute the disconnect command. The reason is given in the message following this message. User Action: Correct the problem given by the messages following this message. Most often, the problem is due to specifying a process that does not exist. 3 NODSTIMG no symbols in image_name Facility: DEBUG, VMS Debugger Explanation: The image is linked with the /NODEBUG qualifier, so there is no symbol table. User Action: Relink the image with the /DEBUG qualifier. 3 NODSTS no Debugger Symbol Table: no DSF file found and Facility: DEBUG, VMS Debugger Explanation: The information the debugger needs to allow you to debug this section of code is in an image file that could not be opened. User Action: Check for the existence of the specified file and/or its associated file protection attributes. 3 NOELABBODY package body path_name has no executable code Facility: DEBUG, VMS Debugger 3 NOELABSPEC package spec path_name has no executable code Facility: DEBUG, VMS Debugger 3 NOEND string beginning with 'string_value' is missing end delimiter delimiter_character Facility: DEBUG, VMS Debugger Explanation: A DEPOSIT command specified an ASCII string or INSTRUCTION string beginning with characters string_value that do not have a terminating apostrophe. User Action: Re-enter the command with characters containing a terminating apostrophe. 3 NOEPTSPEC no eventpoints were specified with a SHOW or CANCEL command. Facility: DEBUG, VMS Debugger Explanation: Eventpoints were not given with a SHOW or CANCEL command. User Action: Try the command again, specifying eventpoints to operate on. 3 NOEVALEXPR unable to evaluate expression for following reason Facility: DEBUG, VMS Debugger Explanation: The expression could not be evaluated. The following message indicates why. User Action: See the following message. 3 NOEVENTFAC the /EVENT qualifier is not allowed: first type 'SET EVENT facility' to specify an event facility Facility: DEBUG, VMS Debugger Explanation: No event facility has been set up yet, therefore no events which use an event facility can be set, canceled, or displayed. User Action: Set an event facility, and try the operation again. 3 NOEXCBRE no exception breaks were set Facility: DEBUG, VMS Debugger Explanation: A CANCEL BREAK/EXCEPTION command was entered when exception breaks were not in effect. The CANCEL BREAK/EXCEPTION command had no effect. User Action: None. This message is informational. 3 NOEXHND no exit handlers are declared Facility: DEBUG, VMS Debugger Explanation: There are no user-mode exit handlers currently declared. User Action: None. This message is informational. 3 NOEXITRUN cannot exit running process !UL-you must STOP it first Facility: DEBUG, VMS Debugger Explanation: The debugger cannot exit from the indicated process because it is running. In order exit the process, it must first be stopped. User Action: Use the STOP command to exit the process. 3 NOFIELD 'field_name' is not a field in this record Facility: DEBUG, VMS Debugger Explanation: An attempt was made to reference a field that is not defined in the record. User Action: Check the field specified to ensure that it is defined in the record. 3 NOFREE no free storage available Facility: DEBUG, VMS Debugger Explanation: The debugger has used all memory available. User Action: Memory must be made available before the debugger can continue executing. SET modules could be canceled, or the debugging session can be stopped and the system manager can increase the virtual memory on your system. 3 NOGLOBALS some or all global symbols not accessible Facility: DEBUG, VMS Debugger Explanation: The image was linked with the /NODEBUG qualifier, and there are no global symbols in the symbol table. User Action: Relink the image with the /DEBUG qualifier. 3 NOHEAP the Heap Analyzer will not be invoked Facility: DEBUG, VMS Debugger Explanation: The debugger encountered a problem trying to define the librtl logical required to invoke the Heap Analyzer. User Action: Insure there is enough room in the process logical name table for the debugger to define the librtl logical. If so, and the command still fails, define the librtl logical at the DCL level, restart the debugger and reexecute the RUN or RERUN command. 3 NOHIDDENDEBUG message cannot be executed when the UI is hidden. Facility: DEBUG, VMS Debugger Explanation: The Debug message cannot be executed when a HideUI message is in effect. User Action: Send the ShowUI message and then re-execute the Debug message. 3 NOHLPLIB the debugger could not open the help library file Facility: DEBUG, VMS Debugger Explanation: The debugger could not open the help library file because there was some low level file open error. User Action: Check for user quotas being exceeded. For further assistance and information on this problem check with your system manager. 3 NOINPAVAIL input objects not available Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to open either DBG$INPUT or SYS$INPUT. User Action: Check that logicals used to point at input files or devices are properly defined. 3 NOINPFOC debugger must have input focus to accept paste operation Facility: DEBUG, VMS Debugger Explanation: A writeable debugger window and, if applicable, a text-entry field in that window must have the input focus before the selection can be pasted to it from the clipboard. User Action: Assign the input focus to a writeable window and, if applicable, to the appropriate text-entry field. 3 NOINSTRAN cannot translate opcode at location address_value Facility: DEBUG, VMS Debugger Explanation: The address specified in the EXAMINE command is not the beginning of a valid instruction. This can be caused by specifying an address that is in the middle of an instruction or by an address that is in a data area. User Action: Specify an address that contains a valid instruction. 3 NOINVCTXINSTHAN cannot retrieve the invocation context instance handle. Facility: DEBUG, VMS Debugger Explanation: In the course of trying to execute an ACA Services message, Debug has tried and failed to retrieve the invocation context instance handle from ACA Services. User Action: Submit a Software Performance Report (SPR). 3 NOKERNEL this kernel debugger does not exist in this context Facility: DEBUG, VMS Debugger Explanation: Debug main is trying to communicate with the kernel debugger in a context where the kernel debugger does not exist. User Action: Submit a Software Performance Report (SPR). 3 NOKEYDEF cannot accept keypad input, mode is set to NOKEYPAD Facility: DEBUG, VMS Debugger Explanation: The user is trying to define or set a keypad definition which can not be performed due to the current operating mode. User Action: Use a terminal that supports keypad operations. 3 NOKEYPAD unable to set up keypad definitions Facility: DEBUG, VMS Debugger Explanation: An error status was returned from the Screen Management Facility that indicates that the debugger keypad definitions are corrupted. User Action: Try to set keypad mode again (SET MODE KEYPAD). If this fails to correct the problem submit a Software Performance Report (SPR). 3 NOLASTVAL last value is not defined Facility: DEBUG, VMS Debugger Explanation: '\' is not currently defined. User Action: Do not reference '\' until a DEPOSIT or EVALUATE command has been performed. 3 NOLINXXX line_descriptor Facility: DEBUG, VMS Debugger Explanation: The line number range CZ:yyy specified on the DEBUGGER command TYPE does not exist. There are no such line numbers in the specified module (or the default module). User Action: Re-enter the command specifying line numbers that do exist. 3 NOLIST list of parameter values not allowed - check use of comma (,) Facility: DEBUG, VMS Debugger Explanation: A command that only accepts a single input value for a parameter contains multiple values separated by commas (,). User Action: Re-enter the command; specify one value. If necessary, issue the command once for each value. 3 NOLOCALS image does not contain local symbols Facility: DEBUG, VMS Debugger Explanation: All the modules in the image were compiled or assembled without traceback information. There is no local symbol information in the image. User Action: Recompile or reassemble the modules using the /DEBUG qualifier and then relink them. 3 NOMAIN error trying to fetch the main window from the Motif Resource Manager (MRM). Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when trying to fetch debuggers main window from the Resource Manager. This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 NOMAINIMAGE host copy of the main system image not found Facility: DEBUG, VMS Debugger Explanation: The debugger running on the host system could not find a local copy of the target system's main image - SYS$BASE_ IMAGE. User Action: Check to make sure the image search path for the host is set up correctly. See the System-Code Debugger documentation for details. 3 NOMARKCHNG [NO]MARK_CHANGE qualifier not applicable to display_name display Facility: DEBUG, VMS Debugger Explanation: The /MARK_CHANGE and /NOMARK_CHANGE qualifiers can not be applied to the indicated kind of display. User Action: None. 3 NOMATCH no matches Facility: DEBUG, VMS Debugger Explanation: A SEARCH command was being used and no matches were found User Action: No action required 3 NOMONEXPR no monitor entry was found matching "expression" Facility: DEBUG, VMS Debugger Explanation: The input "monitor /delete" expression does not match with any currenly monitored item. User Action: Retry "monitor /delete" with corrected expression. 3 NOMORE wildcard request complete Facility: DEBUG, VMS Debugger Explanation: This is a debugger internal error code. User Action: If the debugger reports this error please submit a Software Performance Report. 3 NOMOTIF Motif images not found; defaulting to command interface Facility: DEBUG, VMS Debugger Explanation: The images of the Motif layered product are optionally installed. If the Motif user interface to the debugger is desired, then Motif must be properly installed, otherwise the default character cell mode will run. User Action: If desiring the Motif user interface, check that Motif is installed correctly. 3 NONAMEDWIDGET widget by name !AC not found in the UID file. Facility: DEBUG, VMS Debugger 3 NONAMEMATCH specified name does not match any name in the selection box. Facility: DEBUG, VMS Debugger Explanation: A name was entered as the selection that is not in the selection box. User Action: Select a name from the box. 3 NONEXPR nonexistent process Facility: DEBUG, VMS Debugger Explanation: A process name or process identification specified in a command is not valid. User Action: Verify that the process name or identification is correct and that the process was not already deleted. Also verify that you have the required privilege to access the process. 3 NONEXPRC process process-specification does not exist Facility: DEBUG, VMS Debugger Explanation: The process-specification was not valid or the specified process did not exist. User Action: Verify that the process specification is correct and that the process still exists and then re-enter the command. 3 NONUMSCOPE scope does not exist or is not in set module: scope_number Facility: DEBUG, VMS Debugger Explanation: The debugger could not find the scope indicated by the numbered scope in the scope list. User Action: Set the module that contains that scope. 3 NONXTLIN next line for source display not defined Facility: DEBUG, VMS Debugger Explanation: The debugger command TYPE or SEARCH was entered without specifying a line number (for example, the next line after the last source line printed should be used). But no next source line is currently defined. User Action: Re-enter the command explicitly specifying the desired line number. 3 NOOCCLDISP display_name display may not be occluded Facility: DEBUG, VMS Debugger Explanation: A display was positioned over the indicated display that is not allowed to be occluded. The indicated display was popped to the front. User Action: You may wish to move the display so it is not occluded by the display named in the message. 3 NOOPNIMAGE cannot open image image_name Facility: DEBUG, VMS Debugger Explanation: The information the debugger needs to allow you to debug this section of code is in an image file that could not be opened. User Action: Check for the existence of the specified file and/or its associated file protection attributes. 3 NOOUTAVAIL output objects are not available Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to open either DBG$OUTPUT or SYS$OUTPUT. User Action: Check that logicals used to point at output files or devices are properly defined. 3 NOOUTVIEW error writing to the Message view. Facility: DEBUG, VMS Debugger Explanation: The debugger got an unexpected status when trying to write to the Message view . This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 NOPACKMEMBODY 'symbol_name' is not a member of package body path_name Facility: DEBUG, VMS Debugger 3 NOPACKMEMSPEC 'symbol_name' is not a member of package spec path_name Facility: DEBUG, VMS Debugger 3 NOPARSEINSTHAND cannot parse the invocation context instance handle. Facility: DEBUG, VMS Debugger Explanation: Debug cannot parse the invocation context instance handle retrieved from ACA Services. User Action: Submit a Software Performance Report (SPR). 3 NOPRED logical predecessor not defined Facility: DEBUG, VMS Debugger Explanation: The logical predecessor of the identifier or instruction referenced is not defined. User Action: None. This message is informational. 3 NOPROCDEBUG there are currently no processes being debugged Facility: DEBUG, VMS Debugger Explanation: The debug session is currently not connected to any user processes. User Action: Either RUN a program or CONNECT to a program. 3 NOPROCESSES the current command is targetted at an empty process set Facility: DEBUG, VMS Debugger Explanation: The set of processes at which the current command is targetted is empty. User Action: Either change the current process set, run a program, connect to a program, stop a program or wait for a program 3 NOPROGRAM function function_name requires a running program. Facility: DEBUG, VMS Debugger Explanation: There is no program currently being debugged. User Action: Start a program using RUN or RERUN, then reenter the command. 3 NOPROMPT cannot delete, remove, unselect, or change kind of the display_name display Facility: DEBUG, VMS Debugger Explanation: This display can not be deleted, removed, unselected, or have it's kind changed. User Action: None. 3 NOPTHDBG no compatible pthread debugger established Facility: DEBUG, VMS Debugger Explanation: Either this threaded application is not controlled by PTHREAD$RTL or else this debugger was built to interface with a PTHREAD$DBGSHR that is incompatible with the system PTHREAD$RTL version User Action: pthread commands are not possible, use older task commands, for example, SHOW TASK/ALL, or upgrade your POSIX Threads environment 3 NORADBLIFLD radix override not allowed with BLISS fields Facility: DEBUG, VMS Debugger Explanation: The use of a radix override qualifier is not supported when evaluating a BLISS field reference. BLISS field references are always displayed using a decimal notation. It is, however, possible to use a radix override qualifier when refering to the contents of a BLISS field. User Action: Don't use a radix switch with a BLISS field. 3 NORECSYM recursive symbol_type symbol definition encountered at or near 'debugger_command_segment' Facility: DEBUG, VMS Debugger Explanation: While attempting to expand a defined symbol, a recursive symbol definition was encountered. User Action: Redefine the symbol specified in the error message so that it does not contain any circular dependencies and then re-enter the command. 3 NOREDEFINE predefined process set !AC cannot be redefined Facility: DEBUG, VMS Debugger Explanation: Predefined process set cannot be redefined. User Action: Choose a different name for the user-defined process set. 3 NORERUNPGM there is no program to RERUN. Facility: DEBUG, VMS Debugger Explanation: You must RUN a program first before you can RERUN it. User Action: Use the RUN command and specify a program. 3 NORESUME unable to resume execution, stack or PC corrupted in %PROCESS_NUMBER process_id Facility: DEBUG, VMS Debugger Explanation: The debugger has determined that the stack or PC is corrupted. The top application frame is so corrupted that the debugger is unable to do normal STEPs and GOs. User Action: Look at what little valid information is left, especially the call stack, machine instruction view, current PC, FP, etc. It may be possible to realize the stack corruption and fix it by hand through deposits to stack locations and registers. It should also be possible to CALL or GO newPC if the call target or newPC is valid. More likely, you will need exit/quit, start over, and attempt to find and fix the point where your application corrupts the stack or PC. 3 NORETBRKALTBRK unable to set return break; breakpoint set on caller's return PC. Facility: DEBUG, VMS Debugger Explanation: This is a debugger internal error code. User Action: If the debugger reports this error please submit a Software Performance Report. 3 NORETBRKSTEP unable to set return break, stepping to caller's return PC. Facility: DEBUG, VMS Debugger Explanation: This is a debugger internal error code. User Action: If the debugger reports this error please submit a Software Performance Report. 3 NORMAL successful debugger status Facility: DEBUG, VMS Debugger Explanation: This is an internal status signal, it should never be seen by the user. If this message does occur please submit a Software Performance Report (SPR). User Action: Submit a Software Performance Report (SPR). 3 NORSTBLD cannot build symbol table Facility: DEBUG, VMS Debugger Explanation: The debugger is unable to build a symbol table because of errors in the format of the image file. User Action: Relink the image and, if the error is reproducible, submit a Software Performance Report explaining how the image file was created. 3 NOSAVEDREGS can't find the saved registers for the CALL command for frame frame- addr Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers. The debugger has determined that the frame at frame-addr was caused by a CALL command from the debugger. The debugger is unable to find the register set it saved for the context before the CALL command. User Action: Determine what part of your code is writing into the FP register or overwriting the saved frame pointer on the call stack (or a preceding saved frame pointer) and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 NOSAVPROG cannot save a program I/O display Facility: DEBUG, VMS Debugger Explanation: The SAVE command is not allowed on a program I/O display since the debugger does not know the contents of the display. User Action: None. 3 NOSCOPE no scope exists to look up line line_number Facility: DEBUG, VMS Debugger Explanation: The specified line_number cannot be found because there is no current scope to look it up in. User Action: Specify the module explicitly and retry the operation. 3 NOSCOPELIST a list of scopes is not allowed with this command. Facility: DEBUG, VMS Debugger Explanation: You cannot enter a list of scopes with the previously executed command. User Action: Enter the command with only one scope item. 3 NOSCRATCHSPACE the target system has run out of scratch space Facility: DEBUG, VMS Debugger Explanation: Scratch space is allocated on the target system to implement single stepping. The target system has run out of this space so no more work can be done. User Action: Reboot the target system with more scratch space and try the debugger again. See the documentation for more details. 3 NOSCRDEV screen mode is not supported on this device screen mode output is being lost Facility: DEBUG, VMS Debugger Explanation: The debugger output is being sent to a device that the Screen Management Facility does can not write to. While the debugger will continue to process commands, the screen mode output will be lost. User Action: Make sure the logical DBG$OUTPUT is pointed to a device that the Screen Management Facility can write to. 3 NOSCRMODE screen mode is not supported on this terminal screen mode is not set Facility: DEBUG, VMS Debugger Explanation: Screen mode is not allowed on the terminal type used by the current session. User Action: Use another terminal if screen mode is desired 3 NOSCROLL no scrolling display selected or missing display name Facility: DEBUG, VMS Debugger Explanation: The user did not enter a display name with the command, and the debugger attempted to use the display with the SCROLL attribute. However, no display currently has the SCROLL attribute. User Action: Either reenter the command, specifying a display name, or SELECT a display to have the SCROLL attribute and reenter the command. 3 NOSCROLLDISP display_name display may not be scrolled Facility: DEBUG, VMS Debugger Explanation: This display can not be scrolled. User Action: None. 3 NOSEGLIST error trying to access a source display segment in routine function_ name. Facility: DEBUG, VMS Debugger Explanation: The debugger got an unexpected status when trying to access a source display segment. This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 NOSEMEVENTS no semantic events defined for the specified symbol Facility: DEBUG, VMS Debugger Explanation: There are no semantic events defined for the specified symbol. User Action: Pick a different symbol. 3 NOSETTERM the SET TERMINAL command is not supported on this terminal Facility: DEBUG, VMS Debugger Explanation: The SET TERMINAL command is not allowed on the terminal being used for the current session User Action: Use another type of terminal 3 NOSMG could not locate SMGSHR (or locale specific equivalent) Facility: DEBUG, VMS Debugger Explanation: The debugger relies on the ability to dynamically link to the SMGSHR.EXE (or a locale specific equivalent) at runtime. (The locale specific equivalent of SMGSHR.EXE is denoted by defining logical, DBG$SMGSHR.) When this error occurs, the debugger cannot locate the SMG sharable image and hence, cannot run. User Action: Verify that the SMG sharable image exists. If so, please submit a Software Performance Report. 3 NOSPAWN spawn command failed Facility: DEBUG, VMS Debugger Explanation: The debugger failed to perform a SPAWN command or SPAWN an editor. The error status returned from the SPAWN command is appended to this error message. User Action: If the SPAWN error is correctable, correct the problem and reenter the command. If not, the SPAWN command is unavailable. 3 NOSRCHSTR search string not set Facility: DEBUG, VMS Debugger Explanation: No current search string is defined for the debugger command SEARCH. The SEARCH command was entered without a search string indicating that the current search string should be used. But no previous SEARCH command has been entered to define a current search string. User Action: Explicitly specify the desired search string on the command. 3 NOSRCLIN no source line for address address_value Facility: DEBUG, VMS Debugger Explanation: No source line corresponds to the address address_ value specified on the debugger command EXAMINE/SOURCE. User Action: None. This message is informational. 3 NOSTEPGO no STEP, GO, SET PROCESS/VISIBLE or CALL commands allowed in screen displays Facility: DEBUG, VMS Debugger Explanation: A STEP, GO, SET PROCESS/VISIBLE or CALL command was used in a screen display command list. The debugger does not allow the use of such commands in display command lists. User Action: Re-specify the screen display command list without using any of the disallowed commands. 3 NOSUCC logical successor not defined Facility: DEBUG, VMS Debugger Explanation: The logical successor of the referenced instruction or identifier is not defined. User Action: None. This message is informational. 3 NOSUCHBPT no such breakpoint Facility: DEBUG, VMS Debugger Explanation: The CANCEL BREAK command specified an address that is not the address of a breakpoint. User Action: Use the SHOW BREAK command to find the location of the current breakpoints, and then cancel any of these breakpoints that you want to cancel. 3 NOSUCHDISP no such display defined: display_name Facility: DEBUG, VMS Debugger Explanation: The specified display does not exist. User Action: Re-enter the command, specifying an existing display. 3 NOSUCHELP no such help topic or invalid HELP command Facility: DEBUG, VMS Debugger Explanation: The user has requested help for a topic for which there is no help or the syntax used to request the help was invalid User Action: Try another topic or just type HELP for a topic list 3 NOSUCHIMG image image_name not found Facility: DEBUG, VMS Debugger Explanation: The specified image does not exist. User Action: Re-enter the command, specifying an existing image. 3 NOSUCHMODU module path_name is not in module chain Facility: DEBUG, VMS Debugger Explanation: The module path_name, specified in the SET MODULE command, does not exist in the image. This message can be caused when: (1) a module name has been entered incorrectly or (2) a module is compiled with the /NOTRACE switch. User Action: Specify a module that is in the image. 3 NOSUCHPACK library package path_name is not in the symbol table Facility: DEBUG, VMS Debugger 3 NOSUCHSCOPE scope does not exist or is not in set module: scope_name Facility: DEBUG, VMS Debugger Explanation: The user has requested that the current scope be set to a scope that is invalid for the current module User Action: Correct the scope specification and reissue the command 3 NOSUCHTASK no such task exists or no task satisfies criteria Facility: DEBUG, VMS Debugger Explanation: The user entered a task expression that does not correspond to an existing task, or no existing task satisfies the task expression. User Action: Reenter the command with a task expression that specifies an existing task. 3 NOSUCHTPT no such tracepoint Facility: DEBUG, VMS Debugger Explanation: The CANCEL TRACE command specified an address that was not the address of a tracepoint. User Action: Use the SHOW TRACE command to display the current tracepoints and then cancel any that you want to cancel. 3 NOSUCHWIND no such window defined: display_name Facility: DEBUG, VMS Debugger Explanation: The specified, or defaulted window does not exist. User Action: Reenter the command, specifying an existing window name. 3 NOSUCHWPT no such watchpoint Facility: DEBUG, VMS Debugger Explanation: The CANCEL WATCH command specified an address that was not the address of a watchpoint. User Action: Use the SHOW WATCH command to display the current watchpoints and then cancel any that you want to cancel. 3 NOSYMBOL symbol 'symbol_name' is not in the symbol table Facility: DEBUG, VMS Debugger Explanation: The debugger could not find the symbol '' in its symbol table. User Action: The symbol may have been entered incorrectly, in which case the fix is to enter the symbol correctly. The other possibility is that the module the symbol is defined in has not been loaded into the debugger's symbol table; perform a SET MODULE of the appropriate module. 3 NOSYMBOLR no symbol 'symbol_name' was declared in routine path_name Facility: DEBUG, VMS Debugger 3 NOTADAPROG program is not an ADA program; command ignored Facility: DEBUG, VMS Debugger Explanation: The entered command applies only to Ada programs ; since this is not an Ada program, the command cannot be executed. User Action: No user action required. 3 NOTARRAY type of variable is not array Facility: DEBUG, VMS Debugger Explanation: The variable being treated as an array has not been defined as one. User Action: Check that the correct variable reference is being made. 3 NOTASTRUCT 'symbol_name' was not declared as a structure Facility: DEBUG, VMS Debugger Explanation: A VAX BLISS-32 structure reference specified a symbol symbol_name that was not declared a structure. User Action: Re-enter the command with a valid symbol reference. 3 NOTATMAIN Type GO to reach MAIN program Facility: DEBUG, VMS Debugger Explanation: The debugger has started at the beginning of LIB$INITIALIZE code. User Action: If you want to get to the actual start of the main program you should type GO at the debug prompt. The debugger will allow the program to execute the LIB$INITIALIZE code and then break at the start of the main program. If you'd like to debug the LIB$INITIALIZE code you are positioned to do so at this point. 3 NOTCURPC target of EXAMINE/OPERANDS is not the current PC results may be unexpected Facility: DEBUG, VMS Debugger Explanation: The operands being examined will probably give incorrect results, because the context for the instruction is probably not set up properly. Specifically, the values of registers used in address computations depend on the previous series of instructions being executed, which was not done in this case. User Action: Only use EXAMINE/OPERANDS with .0\%PC 3 NOTDECTHREADS program does not use POSIX Threads services. Facility: DEBUG, VMS Debugger Explanation: The entered command applies only to programs using POSIX Threads services. User Action: No user action required. 3 NOTDEFINE defined_symbol was not defined Facility: DEBUG, VMS Debugger Explanation: The symbol was not found in the defined symbol table. User Action: Check your spelling or use SHOW DEFINE to see what symbols have been defined. 3 NOTEDITABLE this text can not be edited. Facility: DEBUG, VMS Debugger 3 NOTEXPANDABLE this entry cannot be expanded. Facility: DEBUG, VMS Debugger 3 NOTEXTSELECTED select some text and try again. Facility: DEBUG, VMS Debugger 3 NOTIMPLAN expression_type is not implemented at command level Facility: DEBUG, VMS Debugger Explanation: The expression_type is not supported at this type. User Action: Specify a type of expression that the debugger supports. 3 NOTIMSLI time slice modification not supported by this event facility Facility: DEBUG, VMS Debugger Explanation: The current event facility does not support the ability to to dynamically modify time slicing in the debugger. User Action: This operation is not supported by the debugger. The user must recode his application to change time slicing. 3 NOTINLOOP exitloop encountered when not in a loop Facility: DEBUG, VMS Debugger Explanation: An incorrect nesting of loops exist in the command stream currently being executed. User Action: Correct the command stream 3 NOTINSCOPE specified scope cannot be found in the default scope list Facility: DEBUG, VMS Debugger Explanation: The specified scope was not in the current default scope list. User Action: Enter the command with a scope that is in the default scope list. 3 NOTINST examined address is not the start of an instruction Facility: DEBUG, VMS Debugger Explanation: The examined address does not denote the start of an instruction. User Action: Specify an address that does denote the start of an instruction. 3 NOTKEPT Function function_name applies only to Kept Debugger configuration. Facility: DEBUG, VMS Debugger Explanation: This command only makes sense when executed from the Kept Debugger configuration of DECdebug. User Action: Restart debugger using the Kept Debugger configuration and re-enter the command. 3 NOTNUMSCOPE specified scope is not a numbered scope. Facility: DEBUG, VMS Debugger Explanation: The SET SCOPE/CURRENT command requires a numbered scope. User Action: Enter the command with a numbered scope. 3 NOTORIGSRC original version of source file not found file used is file_ specification Facility: DEBUG, VMS Debugger Explanation: A source file was found for some module. But the revision date and time or the file size indicates that this may not be the same version of the file that was used in the original compilation of the module. This warning message indicates that future source line displays from this source file may not correspond to the actual source used to compile the module. User Action: None, unless the original source is available. Then you can use the debugger command SET SOURCE to indicate the location of the source to the debugger. 3 NOTPTR variable must be of pointer or file type Facility: DEBUG, VMS Debugger Explanation: The variable should be a pointer or a file type. User Action: Specify a variable of pointer or file type. 3 NOTRACES no tracepoints are set, no opcode tracing Facility: DEBUG, VMS Debugger Explanation: There are no tracepoints or opcode tracing set. User Action: None. This message is informational. 3 NOTRAZERO Unable to find a trailing zero for ASCIZ object at address address_ value Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to find a trailing zero for the specified ASCIZ string. User Action: The ASCIZ string is missing a trailing zero, or the object examined is not an ASCIZ string. 3 NOTRECORD variable is not record; cannot select component component_name Facility: DEBUG, VMS Debugger Explanation: The user has requested a record operation on a variable which is not a record. User Action: Correct the command and reissue it 3 NOTREE SCAN tree or subtree not found SCAN error message Facility: DEBUG, VMS Debugger 3 NOTRUNDW the debugger is uncertain about the DECWindow configuration. Facility: DEBUG, VMS Debugger Explanation: The debugger is uncertain about the systems DECWindow configuration User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 NOTSAVED Unable to save configuration options. Facility: DEBUG, VMS Debugger Explanation: The Debugger was unable to access the necessary resource file. User Action: If attempting to SAVE OPTIONS, check to be sure that the logical name DECW$USER_DEFAULTS is properly defined and that the assigned directory has write access. If attempting to RESTORE DEFAULT OPTIONS, check to be sure both logicals DECW$USER_DEFAULTS and DECW$SYSTEM_DEFAULTS are properly defined and are accessible. The user defaults directory must have write access while the system defaults directory must have read access. Finally, be sure that the file DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT exists (installed during Operating System installation). If not, contact your system manager. 3 NOTTASKVAL expression does not specify a valid task value Facility: DEBUG, VMS Debugger Explanation: The expression entered does not specify a valid task value. Only Ada task values are known as such in the symbol table - Thread values are considered to be pointers. User Action: Unless you are debugging threads, reenter the command, correctly specifying a task value. 3 NOTTHREADNUM expression does not specify a valid thread number Facility: DEBUG, VMS Debugger Explanation: The expression entered does not specify a valid thread sequence number. User Action: Reenter the command, correctly specifying a thread number. 3 NOTUISOSC the debugger will be unable to create a separate window; OSC not enabled. Facility: DEBUG, VMS Debugger Explanation: The debugger requires OSC support enabled to create a separate window (see SET MODE SEPARATE). User Action: To allow the debugger to create a separate window, type at DCL: DEFINE/SYSTEM UIS$VT_ENABLE_OSC_STRINGS TRUE. You may wish to put this line in your private startup file. 3 NOTUISV30 the debugger will be unable to create a separate window; UIS too old. Facility: DEBUG, VMS Debugger Explanation: The debugger requires VWS V3.0 or later to create a separate window (see SET MODE SEPERATE). User Action: To allow the debugger to create a separate window, install VWS V3.0 or later, and in your private startup file (or at DCL), DEFINE/SYSTEM UIS$VT_ENABLE_OSC_STRINGS TRUE. 3 NOTUNQOVR symbol 'symbol_name' is overloaded Facility: DEBUG, VMS Debugger Explanation: More than one instance of the specified symbol '' exists in the user program. Without further information, the debugger cannot determine which symbol to use. User Action: Re-enter the command, uniquely specifying the symbol to be used. The SHOW SYMBOL command can be used to find the unique symbol names. 3 NOTUPDATE instruction screen display not updated Facility: DEBUG, VMS Debugger Explanation: The instruction screen display was not updated because of the preceding error message. User Action: See the preceding error message. 3 NOTYPEINFO symbol type information not available please SET the module that describes this type Facility: DEBUG, VMS Debugger Explanation: The user has requested information about a symbol which cannot be provided in the current context. User Action: SET the module containing the information and reissue the command 3 NOTYPELEN 'symbol_name' has no type or length information, cannot proceed. Facility: DEBUG, VMS Debugger Explanation: The requested information cannot be obtained because the entity in question doesn't have all the attributes necessary to follow through with the request. User Action: None. This message is informational. 3 NOUI debugger user interface image not found; defaulting to command interface Facility: DEBUG, VMS Debugger Explanation: The user interface portion of the debugger is a separate image which cannot be located. User Action: Check that the debugger is properly installed. If so, please submit a Software Performance Report (SPR). 3 NOUNIQ symbol 'symbol_name' is not unique Facility: DEBUG, VMS Debugger Explanation: The symbol specified was not in a default scope or was defined in more than one scope. User Action: Specify the scope of the symbol in a pathname or change the default scope. 3 NOUNIQUE symbol 'symbol_name' is not unique Facility: DEBUG, VMS Debugger Explanation: The symbol specified was not in a default scope or was defined in more than one scope. User Action: Specify the scope of the symbol in a pathname or change the default scope. 3 NOUNIVERSALS shareable image contains no universal symbols Facility: DEBUG, VMS Debugger Explanation: No universal symbols were found in the image. User Action: None. 3 NOUSREVNT no user-specified events are allowed; none are declared Facility: DEBUG, VMS Debugger Explanation: A reference was made to an event, when no such event had been defined (language not SCAN). User Action: Reenter the last command, without specifying any events. 3 NOVALATPC entity 'symbol_name' does not have a value at the current PC Facility: DEBUG, VMS Debugger Explanation: The value of the specified variable does not exist at this point in the program's execution. For example, the variable might be assigned to a register that is currently being used for some other purpose. User Action: Retry the operation at a point in the program's execution when the variable is being referenced. 3 NOVALTYP 'symbol_name' has no value because it is a type name Facility: DEBUG, VMS Debugger 3 NOVALUE reference does not have a value Facility: DEBUG, VMS Debugger Explanation: The command specified a reference that has no value. User Action: Change the reference. 3 NOVECT no vector support - command cannot be performed Facility: DEBUG, VMS Debugger Explanation: An attempt was made to modify vector state on a system which has neither hardware vector capabilities nor the VVIEF. This includes the EXAMINE vector-register, DEPOSIT vector- register, and SET VECTOR_MODE commands. User Action: Do not attempt to modify vector state on a system which does not have vector capabilities. 3 NOVIEWQUAL no qualifier specified on the VIEW command Facility: DEBUG, VMS Debugger Explanation: There were no qualifiers specified on the VIEW command. User Action: Reenter the command, specifying a qualifier for the VIEW command. 3 NOWATCHES no watchpoints are set Facility: DEBUG, VMS Debugger Explanation: No watchpoints are set. User Action: None. This message is informational. 3 NOWATONOPT cannot watch entity; not in memory (was optimized away) Facility: DEBUG, VMS Debugger Explanation: A watchpoint cannot be set on that entity due to optimizations performed by the compiler User Action: Recompile the program with no optimizations in effect 3 NOWATTAR cannot watch protected target Facility: DEBUG, VMS Debugger Explanation: You are attempting to set a /STATIC watchpoint on a location that is either a register, is not in your program, or is on the stack (P1 space). These kinds of locations cannot be watchpointed with the /STATIC qualifier. User Action: Either use the /NOSTATIC qualifier, or do not watch- point this location. 3 NOWATVARIA cannot set watchpoints on variant records Facility: DEBUG, VMS Debugger Explanation: The user has requested that a watchpoint be set on a variant record. This operation is not currently supported User Action: No user action required 3 NOWATVARSTG watchpoints not allowed after SET TYPE ASCIC, ASCIW, or ASCIZ Facility: DEBUG, VMS Debugger 3 NOWBPT cannot insert breakpoint Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 NOWILD no wildcard permitted Facility: DEBUG, VMS Debugger Explanation: Wildcards are not permitted in this context User Action: Re-enter the command without using wildcards 3 NOWILDFIL file name, type, and version cannot be wildcarded Facility: DEBUG, VMS Debugger Explanation: The components of a file specification entered in a SET SOURCE command may not be wildcarded. User Action: Reenter the command without wildcarding any file specification components. 3 NOWOPCO cannot replace breakpoint with opcode Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 NOWPROT cannot set protection Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 NOWRITEACCESS unable to set breakpoint at break-addr, no write access. Facility: DEBUG, VMS Debugger Explanation: Most debugger startups set a breakpoint in the user program and then return control to that program. The debugger regains control when that breakpoint is hit. It is necessary for the debugger to have write access to the user program in order to set breakpoints. User Action: Change/allow write access to your program's code. 3 NO_SYNC_FROM_EXC_BRE synchronize can not be done from an exception break. Facility: DEBUG, VMS Debugger Explanation: A synchronize command can not be done from an exception break. User Action: Do not perform a synchronization command when at an exception break. 3 NPROMPT could not initialize state to accept input. Facility: DEBUG, VMS Debugger Explanation: The debugger it could not properly setup the state to accept input. This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 NULLPTR cannot dereference null pointer Facility: DEBUG, VMS Debugger 3 NULWIDGET error retrieving widget information in routine function_name. Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when retrieving information on a particular widget in the MOTIF toolkit. This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 NUMCONLONG numeric constant too long, please shorten Facility: DEBUG, VMS Debugger Explanation: A number entered in the command line is too long. User Action: Reenter the command, shortening the long number. 3 NUMTRUNC number truncated Facility: DEBUG, VMS Debugger Explanation: The number entered is greater than the largest signed longword integer. The value has been truncated to the the largest signed integer. User Action: None. 3 NYI function is not yet implemented. Facility: DEBUG, VMS Debugger 3 OBJECTINV requested object is invalid Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit an SPR. 3 OBJPTRINV the pointer associated with the requested object is invalid Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit an SPR. 3 OBJTYPMIS the type associated with the requested object is incorrect Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit an SPR. 3 OBSOLETE_1 this message is available for reuse Facility: DEBUG, VMS Debugger Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report. 3 OBSOLETE_2 this message is available for reuse Facility: DEBUG, VMS Debugger Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report. 3 OBSOLETE_3 this message is available for reuse Facility: DEBUG, VMS Debugger Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report. 3 OBSOLETE_4 this message is available for reuse Facility: DEBUG, VMS Debugger Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report. 3 OBSOLETE_5 this message is available for reuse Facility: DEBUG, VMS Debugger Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report. 3 OPCDEC no support for G/H instructions at or near opcode_name Facility: DEBUG, VMS Debugger 3 OPNOTALLOW operator 'operator_symbol' not allowed on given data types Facility: DEBUG, VMS Debugger Explanation: The debugger encountered a problem when performing the operation '' on the specified operands. This may be a data type conversion error. User Action: Reenter the command, specifying compatible operands. 3 OPSYNTAX instruction operand syntax error for operand number operand_number Facility: DEBUG, VMS Debugger Explanation: The debugger encountered an error in one of the operands of an instruction. User Action: If the instruction was entered by the user, reenter the instruction, correcting the operand error. If not, then there may be an error in the user program instructions. 3 OUTPUTLOST output being lost, both NOTERMINAL and NOLOG are in effect Facility: DEBUG, VMS Debugger Explanation: The SET OUTPUT command has set the output conditions to NOTERMINAL and NOLOG; consequently, the output is not displayed on the terminal or written to a log file. The output normally displayed by the debugger will not be available. User Action: Use the SET OUTPUT command to send output to the terminal or to a log file. 3 OVRWIDGETFAIL error trying to fetch and override an object from MRM in routine function_name. Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when fetching an object from the Motif Resource Manager (MRM) for the purpose of overriding behavior. This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 PACSIZREQ packed size required Facility: DEBUG, VMS Debugger Explanation: A size parameter is required User Action: Supply a size parameter and reissue the command 3 PARENREQ parentheses required around qualifier value in 'debug_cmd_segment' Facility: DEBUG, VMS Debugger Explanation: The indicated qualifier value must be surrounded by parentheses. User Action: Place parentheses around the type of expression specified. 3 PARSTKOVR parse stack overflow, simplify expression Facility: DEBUG, VMS Debugger Explanation: The expression was too complex for the debugger to evaluate. User Action: Simplify the expression. 3 PASTHRU The primary handler should ignore this signal Facility: DEBUG, VMS Debugger Explanation: This is an internal status signal, it should never be seen by the user. If this message does occur please submit a Software Performance Report (SPR). User Action: Submit a Software Performance Report (SPR). 3 PATHNOTACP pathname qualifiers (path_name) not allowed in SHOW SYMBOL data name Facility: DEBUG, VMS Debugger Explanation: The user has issued a command with invalid syntax User Action: No user action required 3 PATHTLONG too many qualifiers on name Facility: DEBUG, VMS Debugger Explanation: There are too many pathname elements in the entered pathname for the debugger to handle. User Action: Shorten the pathname entered, either by abbreviating the pathname, defining a symbol for the pathname, or setting a search scope so that you can use a shorter pathname. 3 PATHTOOLONG pathname too long at path_name Facility: DEBUG, VMS Debugger Explanation: The entered pathname is too long for the debugger to handle. User Action: Shorten the pathname entered, either by abbreviating the pathname, defining a symbol for the pathname, or setting a search scope so that you can use a shorter pathname. 3 PCLINLOOKUP error trying to associate the PC with a line number. Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when looking up the PC to line number correlation. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 PCNOTALL PC not allowed in context for operand number operand_number Facility: DEBUG, VMS Debugger Explanation: Using the PC as an operand in the entered instruction is not allowed. User Action: If the instruction was entered by the user, reenter the instruction, without using the PC in the operand. If not, then there may be an error in the user program instructions. 3 PLICVTERR PLI conversion error at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: An error occurred in the PL/I RTL performing a data type conversion, for the object . User Action: Reenter the command, specifying a legitimate object for the operation desired. 3 PREDEPTNOT predefined eventpoint(s) not canceled Facility: DEBUG, VMS Debugger Explanation: Any existing predefined eventpoints have not been canceled as the result of a CANCEL command. User Action: Specify the /PREDEFINED qualifier with the CANCEL command to cancel predefined eventpoints. 3 PRMNOTAVAIL the command parameter parameter_name is not available Facility: DEBUG, VMS Debugger Explanation: The specified command parameter, although available in some debug implementations, is not available in this one. One reason why is that the parameter just doesn't make sense on the platform. For example, the JSB parameter on a SET STEP command doesn't make sense on Alpha VMS because there is no "JSB" instruction like there is on VAX VMS. User Action: Reissue the command without the parameter. 3 PRNOTRDY process not ready Facility: DEBUG, VMS Debugger Explanation: A process name or process identification specified in a command is either delete pending or not fully connected to yet. User Action: Verify that the process name or identification is correct and that the process was not already deleted. Also verify that you have the required privilege to access the process. 3 PROFRANOT proper frame not found on call stack for path_name Facility: DEBUG, VMS Debugger Explanation: You attempted to look at a variable in a routine invocation that does not exist. User Action: Specify a routine or routine invocation that is currently active. 3 PROMPTCLEN display_name display width not changed, must be full width of screen Facility: DEBUG, VMS Debugger Explanation: This display's width can not be changed. It must be the full width of the screen. User Action: None. 3 PROMPTOCCL display_name display now occludes some or all of display_name display's text Facility: DEBUG, VMS Debugger Explanation: This display now occludes some or all of the specified display. User Action: None. 3 PROMPTRLEN display_name display length not changed, must be at least 2 lines long Facility: DEBUG, VMS Debugger Explanation: This display's length can not be changed to less than the minimum value specified. User Action: None. 3 PROVRFLOW too many levels of @ procedure nesting Facility: DEBUG, VMS Debugger Explanation: The user has nested indirect command processing too deeply User Action: Try to eliminate some of the levels of indirection or look for a recursive invocation 3 PSHINARYNYI PUSH_INNER_ARRAY DST stack machine operator for array 'symbol_name' is not yet implemented Facility: DEBUG, VMS Debugger Explanation: The named array is unconstrained, and its subscript bounds live in different places at different points in the program's execution. This cannot be denoted using DEBUG Symbol Table (DST) features which this version of the debugger supports. User Action: Verify that you are using the latest releases of the compiler and debugger. Examine the nearest object code which references the variable and simulate the access algorithm by hand. 3 PSHVALNYI PUSH_VALSPEC DST stack machine operator for variable 'symbol_name' is not yet implemented Facility: DEBUG, VMS Debugger Explanation: The named variable's address is complex, and its computation uses operands which live in different places at different points in the program's execution. This cannot be denoted using DEBUG Symbol Table (DST) features which this version of the debugger supports. User Action: Verify that you are using the latest releases of the compiler and debugger. Try recompiling the application without optimization. Examine the nearest object code which references the variable and simulate the access algorithm by hand. 3 PTHDBGFAIL PTHREAD debugger call failed, error code (hex) status Facility: DEBUG, VMS Debugger Explanation: The OpenVMS Debug PTHREAD command calls a POSIX Threads Debugger image. That call failed. User Action: Check your POSIX Threads Debugger command syntax and semantics (see Guide to POSIX Threads, debugging appendix). 3 PTHREADINVALCMD invalid POSIX Threads debugger command Facility: DEBUG, VMS Debugger Explanation: Your PTHREAD command had an invalid POSIX Threads debugger command string. See Debugger Manual and Guide To POSIX Threads for legal POSIX Threads debugger command strings. User Action: Re-issue the command with a legal POSIX Threads debugger command string. 3 PTRNOTSET 'symbol_name' is not initialized (try a STEP command first) Facility: DEBUG, VMS Debugger Explanation: An object containing either virtual member functions or virtual base classes contain pointers to tables which are used to implement those features of the C++ language. Such a pointer is initialized by a constructor, and hence is not valid prior to the execution of that constructor. Certain debugger operations applied to such an object require that such a pointer to be valid in order for the debugger operation to complete successfully. User Action: Advance the program until the appropriate constructor has been executed. Usually, a single STEP command will suffice. 3 PXCN record object or record formal parameter must prefix 'CONSTRAINED Facility: DEBUG, VMS Debugger 3 QUALNOTAVAIL the command qualifier qualifier_name is not available Facility: DEBUG, VMS Debugger Explanation: The specified command qualifier, although available in some debug implementations, is not available in this one. One reason why is that the qualifier just doesn't make sense on the platform. For example, the /JSB qualifier on a STEP command doesn't make sense on Alpha VMS because there is no "JSB" instruction like there is on VAX VMS. User Action: Reissue the command without the qualifier. 3 QUALREQ A direction qualifier must be specified with the EXPAND and MOVE commands. Facility: DEBUG, VMS Debugger Explanation: Direction ( UP, DOWN, LEFT, RIGHT ) information is missing from the command. User Action: Provide a direction with the command and try again. 3 QUOSTRLONG quoted string too long, please shorten Facility: DEBUG, VMS Debugger Explanation: A quoted string was entered in a debugger command that was too large for the debugger to handle. User Action: Reenter the command, shortening the string entered. 3 READERR debugger input read error; session may terminate Facility: DEBUG, VMS Debugger Explanation: Excessive read errors have occurred from the input command stream. The Debugger may exit after printing this message. User Action: Check the physical integrity of the device containing the input stream. Also check that the input buffer is large enough to handle the input stream or reduce the rate of command entry. 3 REENTER reenter the command using a more precise pathname Facility: DEBUG, VMS Debugger Explanation: More than one instance of the specified symbol exists in the user program. Without further information, the debugger cannot determine which symbol to use. User Action: Re-enter the command, uniquely specifying the symbol to be used. The SHOW SYMBOL command can be used to find the unique symbol names. 3 REFUSED attach request refused Facility: DEBUG, VMS Debugger Explanation: Either you have attempted to attach to a process that is your own process or that is not part of your process tree. User Action: None. You cannot perform the attempted operation. 3 REGMASKHIDDEN register save mask hidden for stack frame frame_number Facility: DEBUG, VMS Debugger Explanation: Information on where the designated routine invocation might save registers is in a module which has not been set. Symbolic references to non-static variables of callers of this routine may not be resolved correction by the debugger. User Action: Set the module by using the SET MODULE or SET MODULE/CALLS commands, or enable dynamic module setting with the SET MODE DYNAMIC command. Then retry the action which produced this message. 3 REGMASKMISSING register save mask missing for stack frame frame_number Facility: DEBUG, VMS Debugger Explanation: Information on where the designated routine invocation might save registers is not available. Symbolic references to non-static variables of callers of this routine may not be resolved correction by the debugger. User Action: Recompile or reassemble the modules using the /DEBUG qualifier and then relink them. 3 REGNAMEFAIL error registering resources with MRM. Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when registering resources with the Motif Resource Manager (MRM). This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 REGREQ register required in context for operand number operand_number Facility: DEBUG, VMS Debugger Explanation: A register is required to establish context for the specified operand. User Action: If the instruction was entered by the user, reenter the instruction, using a register with the specified operand. If not, then there may be an error in the user program instructions. 3 REGWRERR unable to write/update register set, stack likely corrupted. Facility: DEBUG, VMS Debugger Explanation: Debug kernel failed to write/update the current context register set. Any pending deposits or steps may fail. Continuation in the presence of a corrupted stack typically results in unpredictable program and/or debugger behavior. User Action: Look at what little valid information is left and then start over. Attempt to find and fix the point where the stack gets corrupted. It may be possible to examine program state, but continuing instruction execution typically results in unpredictable program and/or debugger behavior. 3 RENAMENOT Unable to look up 'symbol_name', object being renamed not found in symbol table Facility: DEBUG, VMS Debugger Explanation: The user has requested an operation on an object that was not found in the symbol table. User Action: Correct and reissue the command 3 RESUMERR an error occurred while trying to resume execution of the program Facility: DEBUG, VMS Debugger Explanation: An error status was returned from the call to the debugger-kernel service that resumes program execution. Depending on the severity of the error, the program may or may not have resumed execution. User Action: Examine the error message after this message and consider if the problem is related to a lack of quota or otherwise related to your program's behavior. If so, then take corrective action. If, after this evaluation, you believe that the problem lies in the debugger, then submit a Software Performance Report (SPR). 3 RETURNED control returned to process process_name Facility: DEBUG, VMS Debugger Explanation: Control has returned to the parent process. User Action: None. 3 RNDFCTROUT round factor out of range Facility: DEBUG, VMS Debugger Explanation: The DIBOL scale factor is out of the acceptable range 3 ROPRANDF reserved operand fault at or near opcode_name Facility: DEBUG, VMS Debugger Explanation: The debugger encountered an opcode that is reserved to Digital. User Action: If the instruction was entered by the user, reenter the instruction, without using an opcode reserved to Digital. If not, then there may be an error in the user program instructions. 3 ROUTNOTAVAIL the source to routine !AC is not available Facility: DEBUG, VMS Debugger Explanation: There is no source available for this routine. 3 RPCDBBDT Bad DTYPE for RPC Data Blocking. Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 RPCERR an internal inter-process communications error has occurred Facility: DEBUG, VMS Debugger Explanation: An internal communications error has occurred. The reason is given in the message following this message. User Action: If the error is reproducible, and not a result of continued instruction execution after a severe error (stack corruption, resource exhaustion, etc.) submit a Software Performance Report (SPR) and if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 RPCINVDSC invalid RPC descriptor Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 RPCOVF RPC packet overflow Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 RPCUNF undefined RPC function encountered Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 RPCUNKARG undefined RPC argument encountered Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 RSTERR error in symbol table Facility: DEBUG, VMS Debugger Explanation: There is a format error in the symbol table. User Action: If the format error is not caused by a user program error or a DEPOSIT command, submit a Software Performance Report. 3 SAVED File: DECW$USER_DEFAULTS:VMSDEBUG.DAT Facility: DEBUG, VMS Debugger Explanation: The Debuggers current customization resources have been written to the DECW$USER_DEFAULTS directory (typically sys$login). If the user selected RESTORE DEFAULT OPTIONS, then a copy of the system-wide resource file, DECW$SYSTEM_ DEFAULTS:VMSDEBUG.DAT, has been copied to the users resource directory, DECW$USER_DEFAULTS. User Action: The resources will be activated the next time the Debugger is started. 3 SCALEADD pointer addition: scale factor of scale_factor applied to right/left argument Facility: DEBUG, VMS Debugger Explanation: Indicates the scale factor applied in computing the address. User Action: None. 3 SCALESUB pointer subtraction: a scale factor of scale_factor applied to the right/left Facility: DEBUG, VMS Debugger Explanation: Indicates the scale factor applied in computing the address. User Action: None. 3 SCRNOACCESSR no read access to address address_value for display in display_name Facility: DEBUG, VMS Debugger 3 SCRNOSRCLIN No source line for address: address_value Facility: DEBUG, VMS Debugger Explanation: No source line corresponds to the address address_ value specified on the debugger command EXAMINE/SOURCE. User Action: None. This message is informational. 3 SCRNOTORIGSRC original version of source file not found for display in display_ name file used is file_specification Facility: DEBUG, VMS Debugger Explanation: A source file was found for some module. But the revision date and time or the file size indicates that this may not be the same version of the file that was used in the original compilation of the module. This warning message indicates that future source line displays from this source file may not correspond to the actual source used to compile the module. User Action: None, unless the original source is available. Then you can use the debugger command SET SOURCE to indicate the location of the source to the debugger. 3 SCRTOBIG screen too big for Screen Mode width must be less than maximum_ width, height less than maximum_height Facility: DEBUG, VMS Debugger Explanation: The current screen dimensions are too large for debugger screen mode. User Action: Change the screen dimensions to be small enough for debugger screen mode. 3 SCRTOSMALL screen too small for Screen Mode width must be at least minimum_ width, height must be at least minimum_height Facility: DEBUG, VMS Debugger Explanation: The current screen dimensions are too small for debugger screen mode. User Action: Change the screen dimensions to be large enough for debugger screen mode. 3 SCRUNAOPNSRC unable to open source file file_specification Facility: DEBUG, VMS Debugger Explanation: Source lines from the file file_specification cannot be displayed because the debugger was unable to open the source file (represented as file_specification). The accompanying RMS status message gives more information about the reasons for the source file not being opened. User Action: Examine the RMS status message to determine the reasons for the source file not being opened, and take the appropriate action based on that information. 3 SCRUNAREASRC unable to read source file file_specification Facility: DEBUG, VMS Debugger Explanation: Source lines from the file file_specification cannot be displayed because the debugger was unable to read the source file (represented as file_specification). The accompanying RMS status message gives more information about the reasons for the source file not being opened. User Action: Examine the RMS status message to determine the reasons for the source file not being read, and take the appropriate action based on that information. 3 SDDKERNOTAVAIL system dump kernel of the VMS system dump debugger not available Facility: DEBUG, VMS Debugger Explanation: The system dump kernel for the VMS system dump debugger is not available on this system. User Action: Contact your Digital Representative on the availability of this feature. 3 SELECTFAIL error processing the user's selection. Facility: DEBUG, VMS Debugger Explanation: The debugger detected an error when processing the user's selection. The selection did not match any of the specified selections in the list box. This prevents the debugger from continuing this session. User Action: Try the debugger again, if the same results exist submit a Software Performance Report (SPR). 3 SENDRETRY network failure occurred during a send, retrying Facility: DEBUG, VMS Debugger Explanation: A network failure occurred during a send. This is most likely due to excessive network traffic. The debugger will retry the send until it sees a network time-out. Then it will try to re-establish the connection. User Action: Wait for progress or network failure. 3 SETKEY keypad state has been set to state_name Facility: DEBUG, VMS Debugger Explanation: The specified keypad state has been set. User Action: None. 3 SETKEYERR error in processing SET KEY command: Facility: DEBUG, VMS Debugger Explanation: An error has occurred during a SET KEY command 3 SFCNTNEG shift count is negative Facility: DEBUG, VMS Debugger 3 SHOKEYERR error in processing SHOW KEY command: Facility: DEBUG, VMS Debugger Explanation: An error has occurred during the processing of a SHOW KEY command 3 SHRPRC debugger sharing users process Facility: DEBUG, VMS Debugger Explanation: An error occurred while trying to create a subprocess to run the main debugger image. This message indicates that the debugger is attempting to run in the user process. User Action: Correct the problem specified in the messages preceding this message. If the problem cannot be solved, submit a Software Performance Report (SPR). 3 SIDEFFECT operators with side effects not supported (++, -) Facility: DEBUG, VMS Debugger Explanation: The user has requested the use of an operator that has side effects. This operation is not currently supported by the Debugger. User Action: Issue the operation and the side effects as individual commands 3 SIGVECNOREAD signal vector for exception frame frame-addr at sigvec-addr is not readable Facility: DEBUG, VMS Debugger Explanation: The debugger is attempting to chain down the call stack, following frame pointers. The debugger has determined that part or all of the signal vector for the exception frame at frame-addr is not accessible for reading. This vector lies at sigvec-addr. This usually indicates a corrupt frame list, but could also indicate that the program has protected part of memory in which the frame lies. In either case, this is an error. User Action: Determine what part of your code is writing into the FP register or overwriting the saved frame pointer on the call stack (or a preceding saved frame pointer) and correct it. Since the debugger looks at the call stack to symbolize addresses, you may suppress some of these messages by typing the command "SET MODE NOSYMBOLIC". 3 SIGVECTRUNC signal vector was truncated Facility: DEBUG, VMS Debugger Explanation: The signal vector on this stack frame was too big to fit into the DEBUG buffer. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 SILENTERROR silent error Facility: DEBUG, VMS Debugger Explanation: This error should never be displayed to the debug user. It is an internal debuger only condition code. User Action: None. 3 SIZEATOMIC only atomic data types are supported with 'SIZE Facility: DEBUG, VMS Debugger Explanation: SIZE is not supported on the item requested User Action: No user action required 3 SIZETRUNC size field truncated to size_limit bits Facility: DEBUG, VMS Debugger Explanation: The size of the entry in a BLISS field specification was larger then size_limit. The debugger set the entry size to size_limit and executed the command. User Action: None. This message is informational. 3 SOURCESCOPE Source lines not available for .0 Facility: DEBUG, VMS Debugger Explanation: There were no source lines available for the current PC, so the debugger displayed the source lines for the calling routine. The source lines may be unavailable because the code associated with the current PC is not available (e.g. is in a Digital-supplied shareable image) or was compiled or linked /NODEBUG. User Action: If source modules is available, then recompile and relink the application using the /DEBUG qualifier. 3 SPAWNED subprocess spawned Facility: DEBUG, VMS Debugger Explanation: This message is output by the DEBUG command SPAWN when it spawns a subprocess. User Action: None. This message is informational. 3 SRCLINNOT source lines not available for module path_name Facility: DEBUG, VMS Debugger Explanation: The source lines from module CZ cannot be displayed or searched because there is no source line information in the symbol table for that module. Either the compiler is not able to generate such information or the /DEBUG qualifier was not used on the compilation or link command. User Action: If the language in question supports source line display, recompile and relink with the /DEBUG qualifier. If the language does not support source line display, source lines will not be available to the debugger for modules written in that language. 3 SRCNOTCURAV source code for line !UL in module !AC not currently available. Facility: DEBUG, VMS Debugger 3 SSIEARLYSTOP checking for static watchpoint hits before the actual system service return address Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to set a breakpoint at or step to a system sevice return address. It attempts to do this when intercepting system service calls during static watchpoint event processing. User Action: If there was a watchpoint hit, examine the call stack and find the frame before the DBGSSISHR (or SYS$SSISHR) frame in order to realize the correct context and instruction for the watchpoint hit. Otherwise, it is safe to ignore this message. 3 SS_INT system service intercepted Facility: DEBUG, VMS Debugger Explanation: This error code is used by the debugger to indicate that a system service has been intercepted. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 SS_INT_END system service intercept cycle end Facility: DEBUG, VMS Debugger Explanation: This error code is used by the debugger to indicate that a system service has been intercepted. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 SS_INT_START system service intercept cycle start Facility: DEBUG, VMS Debugger Explanation: This error code is used by the debugger to indicate that a system service has been intercepted. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 STEPINTO cannot step over PC = address_value Facility: DEBUG, VMS Debugger Explanation: The debugger was unable to step over the routine and executed a step into the routine instead. User Action: None. This message is informational. 3 STGTRUNC string truncated Facility: DEBUG, VMS Debugger Explanation: While processing the command, the debugger truncated a text string. User Action: The debugger failed to allocate a large enough buffer to store the command output. Unless the reason for this is apparent, submit a Software Performance Report (SPR). 3 STRNGPAD string operand lengths don't match, shorter padded with blanks on the right Facility: DEBUG, VMS Debugger Explanation: The operands of a string comparison ( 'ABC' < 'AB' ) did not have the same length. The shorter one is blank extended on the right. User Action: Use strings of the same length. 3 STRTOOLONG strings longer than 255 characters not supported Facility: DEBUG, VMS Debugger Explanation: The string that was specified by the user is too large for the debugger to handle User Action: Try to redo the operation with a shorter string 3 STRUCSIZE structure size declared as num_units allocation units, num_units was given Facility: DEBUG, VMS Debugger Explanation: The VAX BLISS-32 structure size was declared to be num_units units but was referenced with num_units units. User Action: None. This message is informational. 3 SUBOUTBND subscript subscript_number is out of bounds Facility: DEBUG, VMS Debugger Explanation: An attempt to subscript out of the bounds of an array was made. User Action: Change the value of the subscript. 3 SUBSCRNG subscript out of range, low/high bound for dimension subscript_ number is subscript_bound Facility: DEBUG, VMS Debugger Explanation: The subscript specification is not within the bounds of the array. User Action: Reenter the command, specifying a subscript specification that is within the bounds defined for the array. 3 SUBSTRING invalid substring (start: low_bound, end: high_bound), object has length string_size Facility: DEBUG, VMS Debugger Explanation: The substring specification (start: low_bound, end: high_bound ) is not within the bounds defined for the data type. User Action: Specify a substring specification within the bounds defined for the data type. 3 SUPERDEBUG SUPERDEBUG not available Facility: DEBUG, VMS Debugger Explanation: This is a Debug internal message. The user should never see this message. User Action: If you see this message, please submit an SPR describing the circumstances. 3 SYMNOTACT non-static variable 'symbol_name' is not active Facility: DEBUG, VMS Debugger Explanation: The symbol symbol_name is not defined in an active call frame. User Action: Check the symbol specified; if correct, ensure that you have defined the scope correctly. 3 SYMNOTFND no symbols matching defined_symbol are defined Facility: DEBUG, VMS Debugger Explanation: You attempted to use the SHOW SYMBOL command to show a symbol that is not defined. User Action: Verify that the symbol is defined and reenter the command. 3 SYNCDONE vector synchronization complete Facility: DEBUG, VMS Debugger Explanation: This signal is generated by the debugger kernel after it has executed the synchronization instruction(s) necessary to insure that all vector exceptions have been reported. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 SYNCREPCOM Synchronize reporting complete Facility: DEBUG, VMS Debugger Explanation: All current vector exceptions have been reported. User Action: None, this message is informational. 3 SYNC_ALREADY_IN_PROGRESS synchronize already in progress. Facility: DEBUG, VMS Debugger Explanation: Only one synchronize command is allowed at a time. User Action: Do not perform a synchronization command until the previous command has completed. 3 SYNERREXPR syntax error in expression at or near 'debugger_command_segment' Facility: DEBUG, VMS Debugger Explanation: The debugger encountered text it does not understand near ''. User Action: Reenter the command, correcting the syntax error. 3 SYNERRLABEL syntax error in %LABEL construct, see HELP Built_in_Symbols %LABEL Facility: DEBUG, VMS Debugger Explanation: The debugger encountered an error in the use of the %LABEL built-in symbol. User Action: Reenter the command line, correcting the error in the %LABEL construct. 3 SYNERRLINE syntax error in %LINE construct, see HELP Built_in_Symbols %LINE Facility: DEBUG, VMS Debugger Explanation: The debugger encountered an error in the use of the %LINE built-in symbol. User Action: Reenter the command line, correcting the error in the %LINE construct. 3 SYNTAX command syntax error at or near 'debugger_command_segment' Facility: DEBUG, VMS Debugger Explanation: The debugger encountered a command syntax error near the element debugger_command_segment. User Action: Re-enter the command. 3 TARGREJ target system rejected the connection request Facility: DEBUG, VMS Debugger Explanation: The target system rejected. This can be because the target system is not in a debuggable state, you have specified the password incorrectly, or a system with this name does not exist on the network. User Action: Check spelling of the node name or password. Also verify that the system is in a debuggable state (booted with the correct flags). 3 TASKERROR error error_code from ADA multitasking Facility: DEBUG, VMS Debugger Explanation: An unexpected error was returned to the debugger from the Ada RTL. Additional information from the Ada RTL is appended to this error message. User Action: User action is dependent on the information returned from the Ada RTL. If the error is not recoverable, the user may wish to enter an SPR on the Ada compiler. 3 TASKNONULL Null task cannot be selected or modified Facility: DEBUG, VMS Debugger 3 TASKNOREGS Task has no registers (it is the Null task) Facility: DEBUG, VMS Debugger 3 TASKNOTABORT task not aborted; ADA multitasking is executing critical section Facility: DEBUG, VMS Debugger Explanation: The task specified may not be aborted at this time. User Action: Retry the abort at a later time. 3 TASKNOTACT task cannot be made the active task; task is not ready or running Facility: DEBUG, VMS Debugger Explanation: The task specified to made the active task is not in either the READY nor the RUNNING state. Tasks not in those states cannot be made the active task. To determine the state of the task, perform a SHOW TASK command. User Action: If the task is in the TERMINATED state, no action is possible. If the task is in the SUSPENDED state, the action required to get the task in the READY or RUNNING state depends on the user program and the state of the debugging session. 3 TASKNULL task is null; cannot set attributes of null task Facility: DEBUG, VMS Debugger 3 TERMINATING program is terminating Facility: DEBUG, VMS Debugger Explanation: The process process-specification has just finished execution. All exit handlers in your program have run. Any SET BREAK/TERMINATING or SET TRACE/TERMINATING events will now take effect. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 THDSTACKOVER thread thread_number's stack is close to overflowing Facility: DEBUG, VMS Debugger Explanation: This thread's stack is close to overflowing, it is over 66% full. Note that the debug kernel image runs on the user stacks, i.e. consumes user stack resources. Also the debug main image will run on the user stacks IF the debugger configuration is one process (DBG$PROCESS logical set to "NONE"). If a stack does overflow, memory errors, e.g. access violations, bus errors, segmentation faults, will likely occur. User Action: Your code may need to change to create this thread with a larger stack, see the Guide to POSIX Threads. Also always run the debugger in its DEFAULT or MULTIPROCESS configuration when debugging threaded applications. 3 THISMEMBER primary (at address) has already been built for this->membername Facility: DEBUG, VMS Debugger Explanation: This is an internal status signal, it should never be seen by the user. If this message does occur please submit a Software Performance Report (SPR). User Action: Submit a Software Performance Report (SPR). 3 TIMESLICE time slice interval has been slowed to 10.0 seconds Facility: DEBUG, VMS Debugger Explanation: DEBUG has changed the ADA time slice interval to 10.0 seconds. When you set watchpoints, DEBUG automatically increases the value of pragma TIME_SLICE to 10.0. This is because of interaction between the watchpoint implementation and VAX Ada's time slicing. Slowing down the time-slice rate prevents problems from occurring. User Action: If the change in time-slice setting is undesirable, then avoid the use of watchpoints. 3 TOOFEWSUB too few subscripts, array has num_dimensions dimensions Facility: DEBUG, VMS Debugger Explanation: The user has specified a symbol reference with too few subscripts User Action: Correct and reissue the command 3 TOOMANDIM too many dimensions in array Facility: DEBUG, VMS Debugger 3 TOOMANERR too many errors, some errors not reported Facility: DEBUG, VMS Debugger Explanation: Too many MISMODBEG or certain other errors occurred. Other similar errors are not reported. User Action: None. This message is informational. 3 TOOMANINV too many invocation numbers in symbol pathname Facility: DEBUG, VMS Debugger 3 TOOMANPARM too many parameters on command Facility: DEBUG, VMS Debugger 3 TOOMANSUB too many subscripts, array has num_dimensions dimensions Facility: DEBUG, VMS Debugger Explanation: The user has specified a symbol reference with too many subscripts User Action: Correct and reissue the command 3 TRUNC64 address !@XH being truncated in !AC Facility: DEBUG, VMS Debugger Explanation: A 64-bit address is being truncated to 32-bits, such that information is being lost. This is a debugger internal error. User Action: Please submit a Software Performance Report (SPR). 3 UIISHIDDEN the User Interface is currently hidden. Facility: DEBUG, VMS Debugger Explanation: Debug did not hide the UI because it is already hidden. User Action: No action necessary. 3 UIISSHOWN the User Interface is currently displayed. Facility: DEBUG, VMS Debugger Explanation: Debug did not show the UI because it is currently displayed. User Action: No action necessary. 3 UNAACCREG unable to access beyond end of register set Facility: DEBUG, VMS Debugger Explanation: The command entered attempted to read or write beyond the end of a register or register set. User Action: Re-enter the command, insuring that you do not attempt to access beyond the end of the register set. 3 UNACREDBGO unable to create DBG$OUTPUT, SYS$OUTPUT used Facility: DEBUG, VMS Debugger 3 UNACVT unable to convert radixvalue to datatype_name Facility: DEBUG, VMS Debugger Explanation: Debug was unable to perform the requested conversion User Action: No user action required 3 UNACVTBYTTAU error converting byte count into target addressable units Facility: DEBUG, VMS Debugger Explanation: This is an internal debugger error. User Action: If the error is reproducible, submit a Software Performance Report and, if possible, enclose a copy of the program being debugged, its build procedure, and a logged debugging session that reproduces the error. 3 UNALIGNED data is not aligned on a byte boundary Facility: DEBUG, VMS Debugger Explanation: The user has requested a type override that can not be performed User Action: No user action required 3 UNALLOCATED 'symbol_name' is not allocated in memory (optimized away) Facility: DEBUG, VMS Debugger Explanation: The requested entity is not available for use due to optimizations performed by the compiler User Action: Recompile the program with no optimizations in effect 3 UNAOPEDBGI unable to open DBG$INPUT, SYS$INPUT used Facility: DEBUG, VMS Debugger 3 UNAOPESCR unable to open DBG$OUTPUT for screen output Facility: DEBUG, VMS Debugger 3 UNAOPNDSF unable to open Debugger Symbol File file_specification Facility: DEBUG, VMS Debugger Explanation: The Debugger Symbol File (DSF) cannot be opened. The accompanying VMS RMS status message gives you more information about the reasons for the file not being opened. User Action: Examine the VMS RMS status message to determine the reasons for the debugger symbol file not being opened, and take action based on that information. Also, verify that the logical name DBG$IMAGE_DSF_PATH is defined to indicate the proper file. 3 UNAOPNHLP unable to open help library file_specification Facility: DEBUG, VMS Debugger Explanation: The help library file_specification cannot be opened to look for the help you requested. The accompanying VAX RMS status message gives you more information about the reasons for the library not being opened. User Action: Examine the VAX RMS status message to determine the reasons for the help library not being opened, and take the appropriate action based on that information. Also, verify that the logical name DBG$HELP is either not defined, or is defined to indicate the proper file. 3 UNAOPNINI unable to open initialization file file_specification Facility: DEBUG, VMS Debugger Explanation: The initialization file cannot be opened. The accompanying VMS RMS status message gives you more information about the reasons for the file not being opened. User Action: Examine the VMS RMS status message to determine the reasons for the initialization file not being opened, and take action based on that information. Also, verify that the logical name DBG$INIT is defined to indicate the proper file. 3 UNAOPNSRC unable to open source file file_specification Facility: DEBUG, VMS Debugger Explanation: Source lines from the file file_specification cannot be displayed because the debugger was unable to open the source file (represented as file_specification). The accompanying RMS status message gives more information about the reasons for the source file not being opened. User Action: Examine the RMS status message to determine the reasons for the source file not being opened, and take the appropriate action based on that information. 3 UNAORIGSRC unable to open the original source file file specification Facility: DEBUG, VMS Debugger Explanation: Source lines from the original (before preprocessing) source file cannot be displayed because the debugger could not get the necessary information from the Correlation Facility. User Action: Check your Correlation Facility logicals and library to see that they are referencing the proper files. 3 UNAREASRC unable to read source file file_specification Facility: DEBUG, VMS Debugger Explanation: Source lines from the file file_specification cannot be displayed because the debugger was unable to read the source file (represented as file_specification). The accompanying RMS status message gives more information about the reasons for the source file not being opened. User Action: Examine the RMS status message to determine the reasons for the source file not being read, and take the appropriate action based on that information. 3 UNASAVVAL unable to save value for defined_symbol, definition ignored Facility: DEBUG, VMS Debugger 3 UNASETEVENT unable to set thread event Facility: DEBUG, VMS Debugger Explanation: This is likely an internal error in either the debugger or the thread facility. Please submit a Software Performance Report (SPR). User Action: Submit a Software Performance Report (SPR). 3 UNASETIMG unable to set image image_name because it has no symbol table Facility: DEBUG, VMS Debugger Explanation: The image is linked with the /NODEBUG qualifier, so there is no symbol table. User Action: Relink the image with the /DEBUG qualifier. 3 UNASETTAS unable to set visible task: registers not available Facility: DEBUG, VMS Debugger 3 UNASWISTA Unable to create debugger stack, using program stack Facility: DEBUG, VMS Debugger Explanation: DEBUG failed to set the protection ($SETPRT) on the DEBUG stack's guard pages. This message indicates an internal debugger error. User Action: Submit an SPR. 3 UNBPAREN unbalanced parentheses in expression Facility: DEBUG, VMS Debugger 3 UNDEXPN undefined exponentiation at or near opcode_name Facility: DEBUG, VMS Debugger 3 UNDKEY state_name key key_name is undefined Facility: DEBUG, VMS Debugger Explanation: You attempted to use the SHOW/KEY or the DELETE/KEY command to show or delete the definition of a key that is not defined. User Action: Verify that the key is defined and reenter the command. 3 UNHANDLED The primary handler should now handle this unhandled exception Facility: DEBUG, VMS Debugger Explanation: This is an internal status signal, it should never be seen by the user. If this message does occur please submit a Software Performance Report (SPR). User Action: Submit a Software Performance Report (SPR). 3 UNIMPLENT attempt to evaluate unimplemented type, cannot proceed. Facility: DEBUG, VMS Debugger Explanation: The data type of the entity in question has not been implemented in the debugger. The debugger doesn't have the needed information on the entity's type to follow through with request. 3 UNKNOWNCODE unknown debugger function code !UL. Facility: DEBUG, VMS Debugger User Action: Make sure that none of the user definable function codes reference numbers that are not documented. 3 UNMTCHPARN unmatched left parenthesis found Facility: DEBUG, VMS Debugger Explanation: A left parenthesis (() was found, but the matching right parenthesis ()) is missing. User Action: Include the right parenthesis ()). 3 UNREQVQUAL unrecognized vector instruction qualifier specified at 'command_ line' Facility: DEBUG, VMS Debugger Explanation: The qualifier indicated in the shown command line fragment is unreqcognized. User Action: Specify a legal vector instruction qualifier. 3 UPBNDOPT upper bound of subrange was optimized away Facility: DEBUG, VMS Debugger Explanation: The upper bound of the specified subrange was optimized away by the compiler. In place of the actual upper bound, DEBUG used the hex value 7FFFFFFF. User Action: None. This message is informational. 3 USEPTHREADCMD this command qualifier is obsolete, use PTHREAD command equivalent Facility: DEBUG, VMS Debugger Explanation: This is a POSIX Threads application in which the debugger has interfaced with a POSIX Threads debugger image. Thread, mutex, condition value, and more state can be accessed via the "PTHREAD debugger-command-string" command, e.g. "PTHREAD THREAD 2 -F". See Debugger Manual and Guide To POSIX Threads or the "PTHREAD HELP" command for legal POSIX Threads debugger command strings. User Action: Use PTHREAD "debugger command string" command instead. 3 USERINPUTBUSY user input thread is busy Facility: DEBUG, VMS Debugger Explanation: The debugger's user input thread is busy trying to collect a new input line. User's should never see this informational. User Action: Please submit a Software Performance Report. 3 USREVNIGN DEBUG detected a bad RTL EVCB sentinel-Event ignored. Facility: DEBUG, VMS Debugger Explanation: While process a pseudo-go operation, the EVCB sent to the debugger by the RTL had a bogus sentinel field. Therefore, the debugger ignored the event. User Action: None. 3 USREVNTERR user-specified event error code error_code returned by user RTL Facility: DEBUG, VMS Debugger 3 VALNOTADDR value of variable 'symbol_name' not usable as address Facility: DEBUG, VMS Debugger Explanation: The value of the specified variable is not usable as an address. The address must be a longword. User Action: Modify the address and retry the operation. 3 VALRNG value is subscript_value, bounds are low_bound..high_bound Facility: DEBUG, VMS Debugger Explanation: An attempt to subscript out of the bounds of an array was made. User Action: Change the value of the subscript. 3 VARNESDEP variant nesting depth exceeds 20, cannot access record component Facility: DEBUG, VMS Debugger 3 VECDIS debugger-generated vector disabled fault Facility: DEBUG, VMS Debugger Explanation: This signal is generated by the debugger kernel while it is processing a vector disabled fault that it has caused. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 VECREASON the reason values for this vector error are reason_values Facility: DEBUG, VMS Debugger Explanation: An internal error has occurred with the debuggers use of vector instructions. The particular error code has two values which are associated with it, which more fully explain what went wrong. User Action: None. 3 VECSCP0 vector registers can be accessed only in scope 0 Facility: DEBUG, VMS Debugger Explanation: An attempt was made to reference a vector register from a scope other than scope 0. DEBUG will not accept a command which specifies any other scope for a vector register. User Action: If the current scope has been set to a scope other than scope 0 (using the SET SCOPE command), use an explicit 0\ pathname to access the vector register. 3 VECTSUBRNG vector register subscript out of bounds, bounds are low_bound..high_ bound Facility: DEBUG, VMS Debugger Explanation: An attempt to subscript out of the bounds of an array was made. User Action: Change the value of the subscript. 3 VERIFYICF opening/closing command procedure file_specification Facility: DEBUG, VMS Debugger Explanation: The debugger is verifying a command procedure. This message is displayed before the command procedure is executed and after all the commands have been displayed. User Action: None. This message is informational. 3 VERSIONNUM the debugger_type debugger has the following RPC version: major_ version/minor_version Facility: DEBUG, VMS Debugger Explanation: This message is to inform you of the version number(s) of the main and kernel debuggers. It will only appear as part of another message, such as INCOMVERSION. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 VERSMISMATCH the host (!AC) and target (!AC) versions are incompatible Facility: DEBUG, VMS Debugger Explanation: The host kernel and target kernel versions are incompatible. This is usually due to different versions of the operating system on the host and target systems. User Action: Check the versions of the operating systems. Review the System-Code Debugger documentation to find out which versions are compatible. 3 VFLTDIV Reserved operand, encoded as floating divide by zero Facility: DEBUG, VMS Debugger Explanation: During a floating-point operation, an attempt was made to divide by zero. User Action: Examine the code that caused the fault. Verify that the operands or variables are specified correctly. Verify that the encoded reserved operand was not deposited by a non-floating- point operation. 3 VFLTOVF Reserved operand, encoded as floating overflow Facility: DEBUG, VMS Debugger Explanation: During a floating-point operation, a floating point value exceeded the largest representable value for that data type. User Action: Examine the code that caused the fault. Verify that the operands or variables are specified correctly. Verify that the encoded reserved operand was not deposited by a non-floating- point operation. 3 VFLTROP Reserved operand, encoded as floating reserved operand Facility: DEBUG, VMS Debugger Explanation: During a floating-point operation, an attempt is made to divide by zero. User Action: Examine the code that caused the fault. Verify that the operands or variables are specified correctly. Verify that the encoded reserved operand was not deposited by a non-floating- point operation. 3 VFLTUND Reserved operand, encoded as floating underflow Facility: DEBUG, VMS Debugger Explanation: An arithmetic exception condition occurred as a result of floating-point underflow. User Action: Examine the code that caused the fault. Verify that the operands or variables are specified correctly. Verify that the encoded reserved operand was not deposited by a non-floating- point operation. 3 WATCHSETUP instruction at current PC may trigger a watchpoint Facility: DEBUG, VMS Debugger Explanation: This signal is generated by the debugger kernel when it is about to execute an instruction that may trigger a watchpoint. User Action: Submit an SPR. This message is handled internally, and should never be signaled to the user. 3 WATCHSIZE cannot WATCH variables longer than 512 bytes Facility: DEBUG, VMS Debugger 3 WATCHSIZESMALL cannot WATCH variable of 0 or negative size Facility: DEBUG, VMS Debugger 3 WATNOWCAN watchpoint now cancelled Facility: DEBUG, VMS Debugger Explanation: This message is a sub-message to WATVARSCP, WATVARPTR, WATVARPROT, etc. This message indicates that the original watchpoint has been cancelled (is no longer active). User Action: None. This message is informational. 3 WATNOWWAT now watching variable name Facility: DEBUG, VMS Debugger Explanation: This message is a sub-message to WATVARSCP and WATVARPTR. This message indicates the new name under which a variable which either went out of scope or whose pointer(s) changed is addressed by the debugger. If this message appears, the watchpoint is still active under this new name. User Action: None. This message is informational. 3 WATVARGSGONE global section associated with watched variable variable name has been unmapped Facility: DEBUG, VMS Debugger Explanation: The global-section which contained a global- section watchpoint is no longer mapped by any process that is under debugger control. This message is always followed by the WATNOWCAN message, since the debugger must delete the watchpoint. User Action: No action necessary. 3 WATVARGSOVR watched variable overlaps into a global section Facility: DEBUG, VMS Debugger Explanation: The specified variable spans a range of virtual memory which includes a global-section and a private-section or two different global-sections. A watched variable must either be entirely in one global-section or entirely in a private-section. User Action: Do not use watchpoint on this address range. 3 WATVARINAC watched variable variable name is no longer accessible Facility: DEBUG, VMS Debugger Explanation: Some action by the program has made the target variable inaccessible to the debugger. The program might have deleted the virtual memory which contains some part of the variable or one of the pointers in the pointer chain to the variable, or the program might have set the protection of such virtual memory such that the debugger can not read it. This message is always followed by the WATNOWCAN message, since the debugger must delete the watchpoint. User Action: None. This message is informational. 3 WATVARNOWGBL watched variable variable name has been re-mapped to a global section Facility: DEBUG, VMS Debugger Explanation: The program mapped a global-section over a watched variable. This message indicates that the debugger made the watchpoint a global-section watchpoint. If the global-section is mapped by more than one process that is under the debugger control, the watched variable will be watched in each process that is mapped to the global section. User Action: No action necessary. 3 WATVARNOWOVR watched variable variable name now overlaps different sections Facility: DEBUG, VMS Debugger Explanation: The specified variable spans a range of virtual memory which has been re-mapped to include a global-section and a private-section or two different global-sections. A watched variable must either be entirely in one global-section or entirely in a private-section. User Action: Do not use watchpoint on this address range. 3 WATVARNOWPVT watched variable variable name has been re-mapped to a private section Facility: DEBUG, VMS Debugger Explanation: The program mapped a private-section over a watched global section variable. This message indicates that the debugger made the watchpoint a private-section watchpoint. User Action: No action necessary. 3 WATVARPROT watched variable variable name has been protected by the program Facility: DEBUG, VMS Debugger Explanation: Some action by the user program has made it impossible for the debugger to set the protection on part or all of the variable. The debugger will therefore not detect changes to the variable. This message is always followed by the WATNOWCAN message, since the debugger must delete the watchpoint. User Action: None. This message is informational. 3 WATVARPTR watched variable variable name now points to a different address Facility: DEBUG, VMS Debugger Explanation: Some pointer in the variable reference has changed value. This message is accompanied by a further message indicating whether the debugger has cancelled the watchpoint or re-defined the watchpoint to address the original data by a different name. User Action: None. This message is informational. 3 WATVARSCP watched variable variable name has gone out of scope Facility: DEBUG, VMS Debugger Explanation: The identified variable is no longer accessible by its original name. The program may have returned from the routine in which the variable was defined, or it may have called another routine. This message is accompanied by a further message indicating whether the debugger has cancelled the watchpoint (in the case that the variable is truly gone) or re-defined the watchpoint to address the same data by a different name. User Action: None. This message is informational. 3 WIDTHDIFF desired width of display_width is not allowed, width is set to display_width Facility: DEBUG, VMS Debugger Explanation: After creating the display pasteboard using the SMG routine SMG$CREATE_PASTEBOARD, DEBUG found that the display width was not in the range 20-255. User Action: Issue the DCL command SHOW TERMINAL and verify that the terminal width is correct and in the range 20-255. 3 WORKSTACMD the command debugger-command is only supported on VWS workstations Facility: DEBUG, VMS Debugger Explanation: The debugger only supports the command debugger- command on workstations running VWS. User Action: None. This capability of the debugger does not exist for your terminal or machine. 3 WPTTRACE non-static watchpoint, tracing every instruction Facility: DEBUG, VMS Debugger Explanation: Setting a watchpoint on a non-static location such as the stack or on a register forces the debugger to trace every instruction that is executed. This will slow down execution of your program by a considerable amount. User Action: If you do not want execution of your program slowed down, then you must cancel the watchpoint. 3 WRITE_FAILED an attempt to write into a memory location failed Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 WRITE_INTO_KERNEL cannot write into the debugger kernel's address space Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 WRITE_INTO_KERNEL_STACK cannot write into the debugger kernel's stack Facility: DEBUG, VMS Debugger Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report (SPR). 3 ZERLENDST zero length DST record has been ignored (compiler error) Facility: DEBUG, VMS Debugger Explanation: A zero-length DST record was encountered within a module. This message normally indicates a compiler error. User Action: Submit a Software Performance Report. 3 ZEROINCR increment for ranged examine is zero; exiting loop Facility: DEBUG, VMS Debugger Explanation: While performing a ranged examine, DEBUG no successor to the current data item was found because the length of the current data item was zero bytes. User Action: None. This message is informational. 2 Path_Names If your program has multiple symbols with the same name, you may need to use path names to resolve symbol ambiguities. For example, your program may have a variable X in procedure A, another variable X in procedure B which is nested in procedure A, and still another variable X in procedure C. If you specify X, as in this example, the debugger uses symbol search conventions (based on the PC scope) to resolve the ambiguity: DBG> EXAMINE X If the debugger cannot do so, it issues the following message: %DEBUG-W-NOUNIQUE, X is not unique. To resolve the ambiguity, you can specify which X you want by using a path name. For example: DBG> EXAMINE A\X DBG> EXAMINE A\B\X DBG> EXAMINE C\X For more information, see the SET SCOPE command. 2 SS$_DEBUG SS$_DEBUG (defined in STARLET) is a condition you can signal from your program to start the debugger. Signalling SS$_DEBUG from your program is equivalent to entering Ctrl/Y followed by DEBUG at that point. You can pass commands to the debugger at the time you signal it with SS$_DEBUG. For example, to start the debugger and issue a SHOW CALLS command at a given point in your program, you could put the following into your program (this example is coded in BLISS): SIGNAL(SS$_DEBUG, 1, UPLIT BYTE(%ASCIC 'SHOW CALLS')); 2 System_Management The debugger consists of two parts (main and kernel), to accommodate the debugging of multiprocess programs. o For a program that runs in one process, a debugging session requires two processes instead of one. o For a multiprocess program, a debugging session requires as many processes as are used by the program, plus an additional process for the main debugger. Under these conditions, several users who are simultaneously debugging programs can place an additional load on a system. The subtopics describe the resources used by the debugger so that you can tune your system for this activity. The discussion covers only the resources used by the debugger. In the case of multiprocess programs, you might also have to tune your system to support the programs themselves. 3 User_Quotas Each user needs a PRCLM quota sufficient to create an additional process for the debugger, beyond the number of processes needed by the program. BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may need to be increased to account for the debugger process as follows: o Each user's ENQLM quota should be increased by at least the number of processes being debugged. o Each user's PGFLQUOTA might need to be increased. If a user has an insufficient PGFLQUOTA, the debugger might fail to activate or might cause "virtual memory exceeded" errors during execution. o Each user's BYTLM and FILLM quotas may need to be increased. The debugger requires BYTLM and FILLM quotas sufficient to open each image file being debugged, the corresponding source files, and the debugger input, output, and log files. 4 Behavior_After_Stack_Corruption The debugger allocates a certain amount of memory at startup and shares the stack with the user's program. If a user process exception results in exhaustion of resources or corruption of the stack, the debugger may be incapable of regaining control, and the debug session may terminate. Be aware of this potential behavior after the occurrence of stack corruption messages or warnings about continuing from a severe error. In either case, the integrity of the debug session cannot be guaranteed. It is recommended that you try one of the following measures: o Change your source code, temporarily or permanently, to reduce resource consumption or lessen the use of stack space o Increase quotas o Specify a larger stack size when linking your program 3 System_Resources The kernel and main debugger communicate through global sections. The main debugger communicates with up to 8 kernel debuggers through a 65-page global section. Therefore, the system global- page and global-section parameters (GBLPAGES and GBLSECTIONS, respectively) might need to be increased. For example, if 10 users are using the debugger simultaneously, 10 global sections using a total of 650 global pages are required by the debugger. 2 VWS_Workstations The following commands are recognized only when you are using the debugger at a workstation running VWS (not Compaq DECwindows Motif for OpenVMS): o SET MODE [NO]SEPARATE o SET PROMPT/[NO]POP 2 @_(Execute_Procedure) Executes a debugger command procedure. Format @file-spec [parameter[, . . . ]] 3 Parameters file-spec Specifies the command procedure to be executed. For any part of the full file specification not provided, the debugger uses the file specification established with the last SET ATSIGN command, if any. If the missing part of the file specification was not established by a SET ATSIGN command, the debugger assumes SYS$DISK:[]DEBUG.COM as the default file specification. You can specify a logical name. parameter Specifies a parameter that is passed to the command procedure. The parameter can be an address expression, a value expression in the current language, or a debugger command; the command must be enclosed within quotation marks ("). Unlike with DCL, you must separate parameters by commas. Also, you can pass as many parameters as there are formal parameter declarations within the command procedure. For more information about passing parameters to command procedures, see the DECLARE command. 3 Description A debugger command procedure can contain any debugger commands, including another execute procedure (@) command. The debugger executes commands from the command procedure until it reaches an EXIT or QUIT command or reaches the end of the command procedure. At that point, the debugger returns control to the command stream that invoked the command procedure. A command stream can be the terminal, an outer (containing) command procedure, a DO clause in a command such as SET BREAK, or a DO clause in a screen display definition. By default, commands read from a command procedure are not echoed. If you enter the SET OUTPUT VERIFY command, all commands read from a command procedure are echoed on the current output device, as specified by DBG$OUTPUT (the default output device is SYS$OUTPUT). For information about passing parameters to command procedures, see the DECLARE command. Related commands: DECLARE (SET,SHOW) ATSIGN SET OUTPUT [NO]VERIFY SHOW OUTPUT 3 Example DBG> SET ATSIGN USER:[JONES.DEBUG].DBG DBG> SET OUTPUT VERIFY DBG> @CHECKOUT %DEBUG-I-VERIFYICF, entering command procedure CHECKOUT SET MODULE/ALL SET BREAK SUB1 GO break at routine PROG5\SUB2 EXAMINE X PROG5\SUB2\X: 376 . . . %DEBUG-I-VERIFYICF, exiting command procedure MAIN DBG> In this example, the SET ATSIGN command establishes that debugger command procedures are, by default, in USER:[JONES.DEBUG] and have a file type of .DBG. The @CHECKOUT command executes the command procedure USER:[JONES.DEBUG]CHECKOUT.DBG. The debugger echoes commands in the command because of the SET OUTPUT VERIFY command. 2 ACTIVATE 3 BREAK Activates a breakpoint that you have previously set and then deactivated. Format ACTIVATE BREAK [address-expression[, . . . ]] 4 Parameters address-expression Specifies a breakpoint to be activated. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER. 4 Qualifiers /ACTIVATING Activates a breakpoint established by a previous SET BREAK/ACTIVATING command. /ALL By default, activates all user-defined breakpoints. When used with /PREDEFINED, activates all predefined breakpoints but no user-defined breakpoints. To activate all breakpoints, use /ALL/USER/PREDEFINED. /BRANCH Activates a breakpoint established by a previous SET BREAK/BRANCH command. /CALL Activates a breakpoint established by a previous SET BREAK/CALL command. /EVENT /EVENT=event-name Activates a breakpoint established by a previous SET BREAK/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET BREAK/EVENT command. To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command. /EXCEPTION Activates a breakpoint established by a previous SET BREAK/EXCEPTION command. /HANDLER Activates a breakpoint established by a previous SET BREAK/HANDLER command. /INSTRUCTION Activates a breakpoint established by a previous SET BREAK/INSTRUCTION command. /LINE Activates a breakpoint established by a previous SET BREAK/LINE command. Do not specify an address expression with this qualifier. /PREDEFINED Activates a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, activates all predefined breakpoints. /SYSEMULATE (Alpha only) Activates a breakpoint established by a previous SET BREAK/SYSEMULATE command. /TERMINATING Activates a breakpoint established by a previous SET BREAK/TERMINATING command. /UNALIGNED_DATA (Alpha only) Activates a breakpoint established by a previous SET BREAK/UNALIGNED_DATA command, or reactivates a breakpoint previously disabled by a DEACTIVATE BREAK/UNALIGNED_DATA command. /USER Activates a specified user-defined breakpoint without affecting any predefined breakpoints. To activate all user-defined breakpoints, use the /ALL qualifier. /VECTOR_INSTRUCTION (VAX only) Activates a breakpoint established by a previous SET BREAK/VECTOR_INSTRUCTION command. 4 Description User-defined breakpoints are activated when you set them with the SET BREAK command. Predefined breakpoints are activated by default. Use the ACTIVATE BREAK command to activate one or more breakpoints that you deactivated with DEACTIVATE BREAK. Activating and deactivating breakpoints enables you to run and rerun your program with or without breakpoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all breakpoints (activated or deactivated). You can activate and deactivate user-defined breakpoints or predefined breakpoints or both. To check if a breakpoint is activated, use the SHOW BREAK command. Related commands: CANCEL ALL RERUN (SET,SHOW,CANCEL,DEACTIVATE) BREAK (SET,SHOW) EVENT_FACILITY 4 Examples 1.DBG> ACTIVATE BREAK MAIN\LOOP+10 This command activates the user-defined breakpoint set at the address expression MAIN\LOOP+10. 2.DBG> ACTIVATE BREAK/ALL This command activates all user-defined breakpoints. 3.DBG> ACTIVATE BREAK/ALL/USER/PREDEFINED This command activates all breakpoints, both user-defined and predefined. 3 TRACE Activates a tracepoint that you have previously set and then deactivated. Format ACTIVATE TRACE [address-expression[, . . . ]] 4 Parameters address-expression Specifies a tracepoint to be activated. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER. 4 Qualifiers /ACTIVATING Activates a tracepoint established with a previous SET TRACE/ACTIVATING command. /ALL By default, activates all user-defined tracepoints. When used with /PREDEFINED, activates all predefined tracepoints but no user-defined tracepoints. To activate all tracepoints, use /ALL/USER/PREDEFINED. /BRANCH Activates a tracepoint established with a previous SET TRACE/BRANCH command. /CALL Activates a tracepoint established with a previous SET TRACE/CALL command. /EVENT /EVENT=event-name Activates a tracepoint established with a previous SET TRACE/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET TRACE/EVENT command. To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command. /EXCEPTION Activates a tracepoint established with a previous SET TRACE/EXCEPTION command. /INSTRUCTION Activates a tracepoint established with a previous SET TRACE/INSTRUCTION command. /LINE Activates a tracepoint established with a previous SET TRACE/LINE command. /PREDEFINED Activates a specified predefined tracepoint without affecting any user-defined tracepoints. When used with /ALL, activates all predefined tracepoints. /TERMINATING Activates a tracepoint established with a previous SET TRACE/TERMINATING command. /USER Activates a specified user-defined tracepoint without affecting any predefined tracepoints. To activate all user-defined tracepoints, use the /ALL qualifier. /VECTOR_INSTRUCTION (VAX only) Activates a tracepoint established with a previous SET TRACE/VECTOR_INSTRUCTION command. 4 Description User-defined tracepoints are activated when you set them with the SET TRACE command. Predefined tracepoints are activated by default. Use the ACTIVATE TRACE command to activate one or more tracepoints that you deactivated with DEACTIVATE TRACE. Activating and deactivating tracepoints enables you to run and rerun your program with or without tracepoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all tracepoints (activated or deactivated). You can activate and deactivate user-defined tracepoints or predefined tracepoints or both. To check if a tracepoint is activated, use the SHOW TRACE command. Related commands: CANCEL ALL RERUN (SET,SHOW) EVENT_FACILITY (SET,SHOW,CANCEL,DEACTIVATE) TRACE 4 Examples 1.DBG> ACTIVATE TRACE MAIN\LOOP+10 This command activates the user-defined tracepoint at the location MAIN\LOOP+10. 2.DBG> ACTIVATE TRACE/ALL This command activates all user-defined tracepoints. 3 WATCH Activates a watchpoint that you have previously set and then deactivated. Format ACTIVATE WATCH [address-expression[, . . . ]] 4 Parameters address-expression Specifies a watchpoint to be activated. With high-level languages, this is typically the name of a variable. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression with /ALL. 4 Qualifiers /ALL Activates all watchpoints. 4 Description Watchpoints are activated when you set them with the SET WATCH command. Use the ACTIVATE WATCH command to activate one or more watchpoints that you deactivated with DEACTIVATE WATCH. Activating and deactivating watchpoints enables you to run and rerun your program with or without watchpoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all static watchpoints (activated or deactivated). The state of a particular nonstatic watchpoint might or might not be saved depending on the scope of the variable being watched relative to the main program unit (where execution restarts). To check if a watchpoint is activated, use the SHOW WATCH command. Related commands: CANCEL ALL RERUN (SET,SHOW,CANCEL,DEACTIVATE) WATCH 4 Examples 1.DBG> ACTIVATE WATCH SUB2\TOTAL This command activates the watchpoint at variable TOTAL in module SUB2. 2.DBG> ACTIVATE WATCH/ALL This command activates all watchpoints you have set and deactivated. 2 ANALYZE 3 /CRASH_DUMP Opens a system dump for analysis by the System Dump Debugger (kept debugger only). Format ANALYZE/CRASH_DUMP 4 Description Invokes the OpenVMS Alpha System Dump Debugger (SDD) to analyze a system dump. SDD is similar in concept to the System Code Debugger (SCD). While SCD allows connection to a running system, with control of the system's execution and the examination and modification of variables, SDD allows analysis of memory as recorded in a system dump. Use of SDD usually involves two systems, although all of the required environment can be set up on a single system. The description that follows assumes that two systems are being used: o The build system, where the image that causes the system crash has been built o The test system, where the image is executed and the system crash occurs In common with SCD, the OpenVMS debugger user interface allows you to specify variable names, routine names, and so on, precisely as they appear in your source code. Also, SDD can display the source code where the software was executing at the time of the system crash. SDD recognizes the syntax, data typing, operators, expressions, scoping rules, and other constructs of a given language. If your code or driver is written in more than one language, you can change the debugging context from one language to another during a debugging session. To use SDD you must do the following: o Build the system image or device driver that is causing the system crash. o Boot a system, including the system image or device driver, and perform the necessary steps to cause the system crash. o Reboot the system and save the dump file. o Invoke SDD, which is integrated with the OpenVMS debugger. For more information about using the SDD, including a sample SDD session, see the OpenVMS Alpha System Analysis Tools Manual. Related commands: ANALYZE/PROCESS_DUMP CONNECT %NODE SDA 4 Example DBG> ANALYZE/CRASH_DUMP DBG> Invokes SDD from within the kept debugger. 3 /PROCESS_DUMP Opens a process dump for analysis with the System Code Debugger (kept debugger only) Format ANALYZE/PROCESS_DUMP dumpfile 4 Parameters dumpfile The name of the process dump file to be analyzed. The file type must be .DMP. 4 Qualifiers /IMAGE_PATH /IMAGE_PATH=directory-spec Specifies the search path for the debugger to find the files that contains the debugger symbol tables (DSTs). The files must be of type .DSF or .EXE, with the same name as the image names in the dumpfile. For example, if image name foo.exe is in the dump file, then the debugger searches for foo.dsf or foo.exe. 4 Description (Kept debugger only.) Opens a process dump for analysis with the System Code Debugger (SCD). The qualifier /PROCESS_DUMP is required and distinguishes this command from the one that invokes the System Dump Debugger (SDD), ANALYZE/CRASH_DUMP. The qualifier /IMAGE_PATH=directory-spec is optional, and specifies the search path the debugger is to use to find the debugger symbol table (DST) files. The debugger builds an image list from the saved process image list. When you set an image (the main image is automatically set), the debugger attempts to open that image in order to find the DSTs. If you include the /IMAGE_PATH=directory-spec qualifier, the debugger searches for the .DST file in the specified directory. The debugger first tries to translate directory-spec as the logical name of a directory search list. If that fails, the debugger interprets directory-spec as a directory specification, and searches that directory for matching .DSF or .EXE files. A .DSF file takes precedence over an .EXE file. The name of the .DSF or .EXE file must match the image name. If you do not include the /IMAGE_PATH=directory-spec qualifier, the debugger looks for the DST file first in the directory that contains the dump file. If that fails, the debugger next searches directory SYS$SHARE and then directory SYS$MESSAGE. If the debugger fails to find a DST file for the image, symbolic information available to the debugger is limited to global and universal symbol names. The debugger checks for link date-time mismatches between the dump file image and the DST file and issues a warning if one is discovered. The parameter dumpfile is the name of the process dump file to be analyzed. Note that the process dump file type must be .DMP and the DST file type must be either .DSF or .EXE. For more information about using SCD, see the OpenVMS Alpha System Analysis Tools Manual. Related commands: ANALYZE/CRASH_DUMP CONNECT %NODE SDA 4 Example DBG> ANALYZE/PROCESS/IMAGE_DUMP=my_disk$:[my_dir] my_disk$:[my_ dir]wecrash.dmp %SYSTEM-F-IMGDMP, dynamic image dump signal at PC=001C0FA0B280099C, PS=001C003C break on unhandled exception preceding WECRASH\th_ run\%LINE 26412 in THREAD 8 26412: if (verify) { DBG> SET RADIX HEXEXADECIMAL; EXAMINE PC WECRASH\th_run\%PC: 0000000000030244 DBG> 2 ATTACH Passes control of your terminal from the current process to another process. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format ATTACH process-name 3 Parameters process-name Specifies the process to which your terminal is to be attached. The process must already exist before you try to attach to it. If the process name contains nonalphanumeric or space characters, you must enclose it in quotation marks ("). 3 Description The ATTACH command enables you to go back and forth between a debugging session and your command interpreter, or between two debugging sessions. To do so, you must first use the SPAWN command to create a subprocess. You can then attach to it whenever you want. To return to your original process with minimal system overhead, use another ATTACH command. Related command: SPAWN 3 Examples 1.DBG> SPAWN $ ATTACH JONES %DEBUG-I-RETURNED, control returned to process JONES DBG> ATTACH JONES_1 $ In this example, the series of commands creates a subprocess named JONES_1 from the debugger (currently running in the process JONES) and then attaches to that subprocess. 2.DBG> ATTACH "Alpha One" $ This example illustrates using quotation marks to enclose a process name that contains a space character. 2 CALL Calls a routine that was linked with your program. Format CALL routine-name [(argument[, . . . ])] 3 Parameters routine-name Specifies the name or the memory address of the routine to be called. argument Specifies an argument required by the routine. Arguments can be passed by address, by descriptor, by reference, and by value, as follows: %ADDR (Default, except for C and C++.) Passes the argument by address. The format is as follows: CALL routine-name (%ADDR address-expression) The debugger evaluates the address expression and passes that address to the routine specified. For simple variables (such as X), the address of X is passed into the routine. This passing mechanism is how Fortran implements ROUTINE(X). In other words, for named variables, using %ADDR corresponds to a call by reference in Fortran. For other expressions, however, you must use the %REF function to call by reference. For complex or composite variables (such as arrays, records, and access types), the address is passed when you specify %ADDR, but the called routine might not handle the passed data properly. Do not specify a literal value (a number or an expression composed of numbers) with %ADDR. %DESCR Passes the argument by descriptor. The format is as follows: CALL routine-name (%DESCR language-expression) The debugger evaluates the language expression and builds a standard descriptor to describe the value. The descriptor is then passed to the routine you named. You would use this technique to pass strings to a Fortran routine. %REF Passes the argument by reference. The format is as follows: CALL routine-name (%REF language-expression) The debugger evaluates the language expression and passes a pointer to the value, into the called routine. This passing mechanism corresponds to the way Fortran passes the result of an expression. %VAL (Default for C and C++.) Passes the argument by value. The format is as follows: CALL routine-name (%VAL language-expression) The debugger evaluates the language expression and passes the value directly to the called routine. 3 Qualifiers /AST /AST (default) /NOAST Controls whether the delivery of asynchronous system traps (ASTs) is enabled or disabled during the execution of the called routine. The /AST qualifier enables the delivery of ASTs in the called routine. The /NOAST qualifier disables the delivery of ASTs in the called routine. If you do not specify /AST or /NOAST with the CALL command, the delivery of ASTs is enabled unless you have previously entered the DISABLE AST command. /SAVE_VECTOR_STATE /SAVE_VECTOR_STATE /NOSAVE_VECTOR_STATE (default) Applies to VAX vectorized programs. Controls whether the current state of the vector processor is saved and then restored when a routine is called with the CALL command. The state of the vector processor comprises the following: o The values of the vector registers (V0 to V15) and the vector control registers (VCR, VLR, and VMR) o Any vector exception (an exception caused by the execution of a vector instruction) that might be pending delivery When you use the CALL command to execute a routine, execution of the routine might change the state of the vector processor as follows: o By changing the values of vector registers or vector control registers o By causing a vector exception o By causing the delivery of a vector exception that was pending when the CALL command was issued The /SAVE_VECTOR_STATE qualifier specifies that after the called routine has completed execution, the debugger restores the state of the vector processor that exists before the CALL command is issued. This ensures that, after the called routine has completed execution: o Any vector exception that was pending delivery before the CALL command was issued is still pending delivery o No vector exception that was triggered during the routine call is still pending delivery o The values of the vector registers are identical to their values before the CALL command was issued The /NOSAVE_VECTOR_STATE qualifier (which is the default) specifies that the state of the vector processor that exists before the CALL command is issued is not restored by the debugger after the called routine has completed execution. In this case, the state of the vector processor after the routine call depends on the effect (if any) of the called routine. The /[NO]SAVE_VECTOR_STATE qualifiers have no effect on the general registers. The values of these registers are always saved and restored when you execute a routine with the CALL command. 3 Description The CALL command is one of the four debugger commands that can be used to execute your program (the others are GO, STEP, and EXIT). The CALL command enables you to execute a routine independently of the normal execution of your program. The CALL command executes a routine whether or not your program actually includes a call to that routine, as long as the routine was linked with your program. When you enter a CALL command, the debugger takes the following actions. For more information, see the qualifier descriptions. 1. Saves the current values of the general registers. 2. Constructs an argument list. 3. Executes a call to the routine specified in the command and passes any arguments. 4. Executes the routine. 5. Displays the value returned by the routine in register R0. By convention, after a called routine has executed, register R0 contains the function return value (if the routine is a function) or the procedure completion status (if the routine is a procedure that returns a status value). If a called procedure does not return a status value or function value, the value in R0 might be meaningless, and the "value returned" message can be ignored. 6. Restores the values of the general registers to the values they had just before the CALL command was executed. 7. Issues the prompt. The debugger assumes that the called routine conforms to the procedure calling standard (see the OpenVMS Calling Standard). However, the debugger does not know about all the argument- passing mechanisms for all supported languages. Therefore, you might need to specify how to pass parameters, for example, use CALL SUB1(%VAL X) rather than CALL SUB1(X). For complete information about how arguments are passed to routines, see your language documentation. When the current language is C or C++, the CALL command by default now passes arguments by value rather than by reference. In addition, you can now pass the following arguments without using a passing mechanism lexical (such as %REF or %VAL): o Routine references o Quoted strings (treated as %REF strings) o Structures, records, and objects o Floating-point parameters by value in F_, D_, G_, S_, and T_ floating format by dereferencing a variable of that type. If the routine contains parameters that are not read-only, the values assigned to parameters may not be visible, and access to values is unreliable. This is because the debugger adjusts parameter values in an internal argument list, not the program argument list. To examine changing values, consider using static variables instead of parameters. The CALL command converts all floating-point literals to F_ floating format. Passing a floating-point literal in a format other than F_floating is not supported. (See the example below.) A common debugging technique at an exception breakpoint (resulting from a SET BREAK/EXCEPTION or STEP/EXCEPTION command) is to call a dump routine with the CALL command. When you enter the CALL command at an exception breakpoint, any breakpoints, tracepoints, or watchpoints that were previously set within the called routine are temporarily disabled so that the debugger does not lose the exception context. However, such eventpoints are active if you enter the CALL command at a location other than an exception breakpoint. 3 Description,_Continued... When an exception breakpoint is triggered, execution is suspended before any application-declared condition handler is invoked. At an exception breakpoint, entering a GO or STEP command after executing a routine with the CALL command causes the debugger to resignal the exception (see the GO and STEP commands). On Alpha processors, you cannot debug routines that are activated before the routine activated by a CALL command. For example, your program is stopped in routine MAIN, and you set a breakpoint in routine SORT. You issue the debugger command CALL SORT. While debugging routine SORT, you cannot debug routine MAIN. You must first return from the call to routine SORT. If you are debugging a multiprocess program, the CALL command is executed in the context of the current process set. In addition, when debugging a multiprocess program, the way in which execution continues in your process depends on whether you entered a SET MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By default (SET MODE NOINTERRUPT), when one process stops, the debugger takes no action with regard to the other processes. Also by default (SET MODE WAIT), the debugger waits until all processes in the current process set have stopped before prompting for a new command. Related commands: GO EXIT SET PROCESS SET MODE [NO]INTERRUPT SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only) STEP SYNCHRONIZE VECTOR_MODE (VAX only) 3 Examples 1.DBG> CALL SUB1(X) value returned is 19 DBG> This command calls routine SUB1, with parameter X (by default, the address of X is passed). In this case, the routine returns the value 19. 2.DBG> CALL SUB(%REF 1) value returned is 1 DBG> This command passes a pointer to a memory location containing the numeric literal 1, into the routine SUB. 3.DBG> SET MODULE SHARE$LIBRTL DBG> CALL LIB$SHOW_VM 1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM, 122216 bytes still allocated, value returned is 00000001 DBG> This example calls Run-Time Library routine LIB$SHOW_VM (in shareable image LIBRTL) to display memory statistics. The SET MODULE command makes the universal symbols (routine names) in LIBRTL visible in the main image. See also the SHOW MODULE/SHARE command. 4.DBG> CALL testsub (%val 11.11, %val 22.22, %val 33.33) This example passes floating-point parameters by value, to a C subroutine with the function prototype void testsub (float, float, float). The floating-point parameters are passed in F_ floating format. 2 CANCEL 3 ALL Cancels all breakpoints, tracepoints, and watchpoints. Restores the scope and type to their default values. Restores the line, symbolic, and G_floating modes established with the SET MODE command to their default values. Format CANCEL ALL 4 Qualifiers /PREDEFINED Cancels all predefined (but no user-defined) breakpoints and tracepoints. /USER Cancels all user-defined (but no predefined) breakpoints, tracepoints, and watchpoints. This is the default unless you specify /PREDEFINED. 4 Description The CANCEL ALL command does the following: 1. Cancels all user-defined eventpoints (those created with the commands SET BREAK, SET TRACE, and SET WATCH). This is equivalent to entering the commands CANCEL BREAK/ALL, CANCEL TRACE/ALL, and CANCEL WATCH/ALL. Depending on the type of program (for example Ada, multiprocess), certain predefined breakpoints or tracepoints might be set automatically when you start the debugger. To cancel all predefined but no user- defined eventpoints, use CANCEL ALL/PREDEFINED. To cancel all predefined and user-defined eventpoints, use CANCEL ALL/PREDEFINED/USER. 2. Restores the scope search list to its default value (0,1,2, . . . ,n). This is equivalent to entering the CANCEL SCOPE command. 3. Restores the data type for memory locations that are associated with a compiler-generated type to the associated type. Restores the type for locations that are not associated with a compiler-generated type to "longword integer". This is equivalent to entering the CANCEL TYPE/OVERRIDE and SET TYPE LONGWORD commands. 4. Restores the line, symbolic, and G_floating modes established with the SET MODE command to their default values. This is equivalent to entering the following command: DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT The CANCEL ALL command does not affect the current language setting or modules included in the run-time symbol table. Related commands: (CANCEL,DEACTIVATE) BREAK CANCEL SCOPE (CANCEL,DEACTIVATE) TRACE CANCEL TYPE/OVERRIDE (CANCEL,DEACTIVATE) WATCH (SET,CANCEL) MODE SET TYPE 4 Examples 1.DBG> CANCEL ALL This command cancels all user-defined breakpoints and tracepoints and all watchpoints, and restores scopes, types, and some modes to their default values. In this example, there are no predefined breakpoints or tracepoints. 2.DBG> CANCEL ALL %DEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled This command cancels all user-defined breakpoints and tracepoints and all watchpoints, and restores scopes, types, and some modes to their default values. In this example, there is a predefined breakpoint or tracepoint; this is not canceled by default. 3.DBG> CANCEL ALL/PREDEFINED This command cancels all predefined breakpoints and tracepoints, and restores scopes, types, and some modes to their default values. No user-defined breakpoints or tracepoints are affected. 3 BREAK Cancels a breakpoint. Format CANCEL BREAK [address-expression[, . . . ]] 4 Parameters address-expression Specifies a breakpoint to be canceled. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER. 4 Qualifiers /ACTIVATING Cancels the effect of a previous SET BREAK/ACTIVATING command. /ALL By default, cancels all user-defined breakpoints. When used with /PREDEFINED, cancels all predefined breakpoints but no user-defined breakpoints. To cancel all breakpoints, use CANCEL BREAK/ALL/USER/PREDEFINED. /BRANCH Cancels the effect of a previous SET BREAK/BRANCH command. /CALL Cancels the effect of a previous SET BREAK/CALL command. /EVENT /EVENT=event-name Cancels the effect of a previous SET BREAK/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET BREAK/EVENT command. To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command. /EXCEPTION Cancels the effect of a previous SET BREAK/EXCEPTION command. /HANDLER Cancels the effect of a previous SET BREAK/HANDLER command. /INSTRUCTION Cancels the effect of a previous SET BREAK/INSTRUCTION command. /LINE Cancels the effect of a previous SET BREAK/LINE command. /PREDEFINED Cancels a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, cancels all predefined breakpoints. /SYSEMULATE (Alpha only) Cancels the effect of a previous SET BREAK/SYSEMULATE command. /TERMINATING Cancels the effect of a previous SET BREAK/TERMINATING command. /UNALIGNED_DATA (Alpha only) Cancels the effect of a previous SET BREAK/UNALIGNED_DATA command. /USER Cancels a specified user-defined breakpoint without affecting any predefined breakpoints. This is the default unless you specify /PREDEFINED. To cancel all user-defined breakpoints, use the /ALL qualifier. /VECTOR_INSTRUCTION (VAX only) Cancels the effect of a previous SET BREAK/VECTOR_ INSTRUCTION command. 4 Description 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 ZQUIT 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. To cancel only user-defined breakpoints, do not specify /PREDEFINED with the CANCEL BREAK command (the default is /USER). To cancel only predefined breakpoints, specify /PREDEFINED but not /USER. To cancel both predefined and user-defined breakpoints, specify both /PREDEFINED and /USER. In general, the effect of the CANCEL BREAK command is symmetrical with that of the SET BREAK command (even though the SET BREAK command is used only with user-defined breakpoints). Thus, to cancel a breakpoint that was established at a specific location, specify that same location (address expression) with the CANCEL BREAK command. To cancel breakpoints that were established on a class of instructions or events, specify the class of instructions or events with the corresponding qualifier (/LINE, /BRANCH, /ACTIVATING, /EVENT=, and so on). For more information, see the qualifier descriptions. If you want the debugger to ignore a breakpoint without your having to cancel it (for example, if you want to rerun the program with and without breakpoints), use the DEACTIVATE BREAK instead of the CANCEL BREAK command. Later, you can activate the breakpoint (with ACTIVATE BREAK). Related commands: (ACTIVATE,DEACTIVATE) BREAK CANCEL ALL (SET,SHOW) BREAK (SET,SHOW) EVENT_FACILITY (SET,SHOW,CANCEL) TRACE 4 Examples 1.DBG> CANCEL BREAK MAIN\LOOP+10 This command cancels the user-defined breakpoint set at the address expression MAIN\LOOP+10. 2.DBG> CANCEL BREAK/ALL This command cancels all user-defined breakpoints. 3.DBG> CANCEL BREAK/ALL/USER/PREDEFINED This command cancels all user-defined and predefined breakpoints. 4.all> CANCEL BREAK/ACTIVATING This command cancels a previous user-defined SET BREAK/ACTIVATING command. As a result, the debugger does not suspend execution when a new process is brought under debugger control. 5.DBG> CANCEL BREAK/EVENT=EXCEPTION_TERMINATED/PREDEFINED This command cancels the predefined breakpoint set on task terminations due to unhandled exceptions. This breakpoint is predefined for Ada programs and programs that call POSIX Threads or Ada routines. 3 DISPLAY Permanently deletes a screen display. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format CANCEL DISPLAY [display-name[, . . . ]] 4 Parameters display-name Specifies the name of a display to be canceled. Do not specify the PROMPT display, which cannot be canceled. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify a display name with /ALL. 4 Qualifiers /ALL Cancels all displays, except the PROMPT display. 4 Description When a display is canceled, its contents are permanently lost, it is deleted from the display list, and all the memory that was allocated to it is released. You cannot cancel the PROMPT display. Related commands: (SHOW) DISPLAY (SET,SHOW,CANCEL) WINDOW 4 Examples 1.DBG> CANCEL DISPLAY SRC2 This command deletes display SRC2. 2.DBG> CANCEL DISPLAY/ALL This command deletes all displays, except the PROMPT display. 3 MODE Restores the line, symbolic, and G_floating modes established by the SET MODE command to their default values. Also restores the default input/output radix. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format CANCEL MODE 4 Description The effect of the CANCEL MODE command is equivalent to the following commands: DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT DBG> CANCEL RADIX The default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, which have a default radix of hexadecimal. Related commands: (SET,SHOW) MODE (SET,SHOW,CANCEL) RADIX 4 Example DBG> CANCEL MODE This command restores the default radix mode and all default mode values. 3 RADIX Restores the default radix for the entry and display of integer data. Format CANCEL RADIX 4 Qualifiers /OVERRIDE Cancels the override radix established by a previous SET RADIX/OVERRIDE command. This sets the current override radix to "none" and restores the output radix mode to the value established with a previous SET RADIX or SET RADIX/OUTPUT command. If you did not change the radix mode with a SET RADIX or SET RADIX/OUTPUT command, the CANCEL RADIX/OVERRIDE command restores the radix mode to its default value. 4 Description The CANCEL RADIX command cancels the effect of any previous SET RADIX and SET RADIX/OVERRIDE commands. It restores the input and output radix to their default value. The default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, which have a default radix of hexadecimal. The effect of the CANCEL RADIX/OVERRIDE command is more limited and is explained in the description of the /OVERRIDE qualifier. Related commands: EVALUATE (SET,SHOW) RADIX 4 Examples 1.DBG> CANCEL RADIX This command restores the default input and output radix. 2.DBG> CANCEL RADIX/OVERRIDE This command cancels any override radix you might have set with the SET RADIX/OVERRIDE command. 3 SCOPE Restores the default scope search list for symbol lookup. Format CANCEL SCOPE 4 Description The CANCEL SCOPE command cancels the current scope search list established by a previous SET SCOPE command and restores the default scope search list, namely 0,1,2, . . . ,n, where n is the number of calls in the call stack. The default scope search list specifies that, for a symbol without a path-name prefix, a symbol lookup such as EXAMINE X first looks for X in the routine that is currently executing (scope 0); 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), then searches the global symbol table (GST), if necessary. Related commands: (SET,SHOW) SCOPE 4 Example DBG> CANCEL SCOPE This command cancels the current scope. 3 SOURCE Cancels a source directory search list, a source directory search method, or both a list and method established by a previous SET SOURCE command. Format CANCEL SOURCE 4 Qualifiers /DISPLAY Cancels the effect of a previous SET SOURCE/DISPLAY command, which specifies the directory search list to be used by the debugger when displaying source code. Canceling this command means the debugger searches for a source file in the directory in which it was compiled. /EDIT Cancels the effect of a previous SET SOURCE/EDIT command, which specifies the directory search list to be used during execution of the debugger's EDIT command. Canceling this command means the debugger searches for a source file in the directory in which it was compiled. /EXACT Cancels the effect of a previous SET SOURCE/EXACT command, which specifies a directory search method. Canceling this command means that the debugger no longer searches for the exact version of the source file from compilation; it reverts to the default behavior of searching for the latest version of the file. /LATEST Cancels the effect of a previous SET SOURCE/LATEST command, which specifies a directory search method. In this case, the CANCEL SOURCE/LATEST command directs the debugger to return to searching for the exact version of the source file from compilation. Because /LATEST is the default setting, this qualifier only makes sense when used with other qualifiers, for example, /MODULE. /MODULE /MODULE=module-name Cancels the effect of a previous SET SOURCE/MODULE=module- name command in which the same module name and qualifiers were specified. (The /MODULE qualifier allows you to specify a unique directory search list, directory search method, or both, for the named module.) You can append one or more of the qualifiers listed above to the SET SOURCE/MODULE and CANCEL SOURCE/MODULE commands. If you issue a CANCEL SOURCE/MODULE command with additional qualifiers, you cancel the effect of the specified qualifiers on the module. If you issue an unqualified CANCEL SOURCE/MODULE command, the debugger no longer differentiates the module from any other module in your directories. /ORIGINAL (Applies to STDL programs only. Requires the installation of the Correlation Facility (a separate layered product) and invocation of the kept debugger.) Cancels the effect of a previous SET SOURCE/ORIGINAL command. The SET SOURCE/ORIGINAL command is required to debug STDL source files, and must be canceled when you debug source files written in other languages. 4 Description CANCEL SOURCE cancels the effect of a previous SET SOURCE command. The nature of this cancellation depends on the qualifiers activated in previous SET SOURCE commands. See the CANCEL SOURCE examples to see how CANCEL SOURCE and SET SOURCE interact. 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. CANCEL SOURCE without the /DISPLAY or /EDIT qualifier cancels the effect of both SET SOURCE/DISPLAY and SET SOURCE/EDIT, if both were previously given. The /DISPLAY qualifier is needed when the files to be displayed are no longer in the compilation directory. The /EDIT qualifier is needed when the files used for the display of source code are different from the editable files. 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 that you edit when using the EDIT command. For information specific to Ada programs, see the Language_Support Ada help topic. Related commands: (SET,SHOW) SOURCE 4 Examples 1.DBG> SET SOURCE/MODULE=CTEST/EXACT [],SYSTEM::DEVICE:[PROJD] DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC] . . . DBG> SHOW SOURCE source directory search list for CTEST, match the exact source file version: [] SYSTEM::DEVICE:[PROJD] source directory list for all other modules, match the latest source file version: [PROJA] [PROJB] [PETER.PROJC] DBG> CANCEL SOURCE DBG> SHOW SOURCE source directory search list for CTEST, match the exact source file version: [] SYSTEM::DEVICE:[PROJD] all other source files will try to match the latest source file version In this example, the SET SOURCE command establishes a directory search list and a search method (the default, latest version) for source files other than CTEST. The CANCEL SOURCE command cancels the directory search list but does not cancel the search method. 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 the SET SOURCE/EXACT command, but also affects the SET SOURCE [JONES] command. 3 TRACE Cancels a tracepoint. Format CANCEL TRACE [address-expression[, . . . ]] 4 Parameters address-expression Specifies a tracepoint to be canceled. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER. 4 Qualifiers /ACTIVATING Cancels the effect of a previous SET TRACE/ACTIVATING command. /ALL By default, cancels all user-defined tracepoints. When used with /PREDEFINED, it cancels all predefined tracepoints but no user-defined tracepoints. To cancel all tracepoints, use /ALL/USER/PREDEFINED. /BRANCH Cancels the effect of a previous SET TRACE/BRANCH command. /CALL Cancels the effect of a previous SET TRACE/CALL command. /EVENT /EVENT=event-name Cancels the effect of a previous SET TRACE/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET TRACE/EVENT command. To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command. /EXCEPTION Cancels the effect of a previous SET TRACE/EXCEPTION command. /INSTRUCTION Cancels the effect of a previous SET TRACE/INSTRUCTION command. /LINE Cancels the effect of a previous SET TRACE/LINE command. /PREDEFINED Cancels a specified predefined tracepoint without affecting any user-defined tracepoints. When used with /ALL, it cancels all predefined tracepoints. /TERMINATING Cancels the effect of a previous SET TRACE/TERMINATING command. /USER Cancels a specified user-defined tracepoint without affecting any predefined tracepoints. This is the default unless you specify /PREDEFINED. To cancel all user-defined tracepoints, use /ALL. /VECTOR_INSTRUCTION (VAX only) Cancels the effect of a previous SET TRACE/VECTOR_ INSTRUCTION command. 4 Description Tracepoints can be user defined or predefined. User-defined tracepoints are explicitly set 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. To cancel only user-defined tracepoints, do not specify /PREDEFINED with the CANCEL TRACE command (the default is /USER). To cancel only predefined tracepoints, specify /PREDEFINED but not /USER. To cancel both user-defined and predefined tracepoints, use CANCEL TRACE/ALL/USER/PREDEFINED. In general, the effect of CANCEL TRACE is symmetrical with that of SET TRACE (even though SET TRACE is used only with user-defined tracepoints). Thus, to cancel a tracepoint that was established at a specific location, specify that same location (address expression) with CANCEL TRACE. To cancel tracepoints that were established on a class of instructions or events, specify the class of instructions or events with the corresponding qualifier (/LINE, /BRANCH, /ACTIVATING, /EVENT=, and so on). For more information, see the qualifier descriptions. To cause the debugger to temporarily ignore a tracepoint, but retain definition of the tracepoint, use the command DEACTIVATE TRACE. You can later activate the tracepoint (with ACTIVATE TRACE). Related commands: (ACTIVATE,DEACTIVATE,SET,SHOW) TRACE CANCEL ALL (SET,SHOW,CANCEL) BREAK (SET,SHOW) EVENT_FACILITY 4 Examples 1.DBG> CANCEL TRACE MAIN\LOOP+10 This command cancels the user-defined tracepoint at the location MAIN\LOOP+10. 2.DBG> CANCEL TRACE/ALL This command cancels all user-defined tracepoints. 3.all> CANCEL TRACE/TERMINATING This command cancels a previous SET TRACE/TERMINATING command. As a result, a user-defined tracepoint is not triggered when a process does an image exit. 4.DBG> CANCEL TRACE/EVENT=RUN %TASK 3 This command cancels the tracepoint that was set to trigger when task 3 (task ID = 3) entered the RUN state. 3 TYPE 4 /OVERRIDE Cancels the override type established by a previous SET TYPE/OVERRIDE command. Format CANCEL TYPE/OVERRIDE 5 Description The CANCEL TYPE/OVERRIDE command sets the current override type to "none." As a result, a program location associated with a compiler-generated type is interpreted according to that type. Related commands: DEPOSIT EXAMINE (SET,SHOW) EVENT_FACILITY (SET,SHOW) TYPE/OVERRIDE 5 Example DBG> CANCEL TYPE/OVERRIDE This command cancels the effect of a previous SET TYPE/OVERRIDE command. 3 WATCH Cancels a watchpoint. Format CANCEL WATCH [address-expression[, . . . ]] 4 Parameters address-expression Specifies a watchpoint to be canceled. With high-level languages, this is typically the name of a variable. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression with /ALL. 4 Qualifiers /ALL Cancels all watchpoints. 4 Description The effect of the CANCEL WATCH command is symmetrical with the effect of the SET WATCH command. To cancel a watchpoint that was established at a specific location with the SET WATCH command, specify that same location with CANCEL WATCH. Thus, to cancel a watchpoint that was set on an entire aggregate, specify the aggregate in the CANCEL WATCH command; to cancel a watchpoint that was set on one element of an aggregate, specify that element in the CANCEL WATCH command. The CANCEL ALL command also cancels all watchpoints. To cause the debugger to temporarily ignore a watchpoint, but not delete the definition of the watchpoint, use the command DEACTIVATE WATCH. You can later activate the watchpoint (with ACTIVATE WATCH). Related commands: (ACTIVATE,DEACTIVATE,SET,SHOW) WATCH CANCEL ALL (SET,SHOW,CANCEL) BREAK (SET,SHOW,CANCEL) TRACE 4 Examples 1.DBG> CANCEL WATCH SUB2\TOTAL This command cancels the watchpoint at variable TOTAL in module SUB2. 2.DBG> CANCEL WATCH/ALL This command cancels all watchpoints you have set. 3 WINDOW Permanently deletes a screen window definition. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format CANCEL WINDOW [window-name[, . . . ]] 4 Parameters window-name Specifies the name of a screen window definition to be canceled. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify a window definition name with /ALL. 4 Qualifiers /ALL Cancels all predefined and user-defined window definitions. 4 Description When a window definition is canceled, you can no longer use its name in a DISPLAY command. The CANCEL WINDOW command does not affect any displays. Related commands: (SHOW,CANCEL) DISPLAY (SET,SHOW) WATCH 4 Example DBG> CANCEL WINDOW MIDDLE This command permanently deletes the screen window definition MIDDLE. 2 CONNECT (Kept debugger only.) Interrupts an image that is running without debugger control in another process and brings that process under debugger control. When used without a parameter, CONNECT brings any spawned process that is waiting to connect to the debugger under debugger control. On Alpha systems, the debugger command CONNECT can also be used to bring a target system running the Alpha operating system under the control of the OpenVMS Alpha System-Code Debugger. The OpenVMS Alpha System-Code Debugger is a kernel debugger that you activate through the OpenVMS Debugger. If you are using the CONNECT command to debug the Alpha operating system, you must complete the instructions described in the System Code Debugger chapter of the OpenVMS Alpha System Analysis Tools Manual before you issue the command. (These instructions include the creation of an Alpha device driver and the setup commands activating the OpenVMS Alpha System-Code Debugger.) You must also have started the OpenVMS Debugger with the DCL command DEBUG/KEEP. Format CONNECT [process-spec] CONNECT %NODE_NAME node-name 3 Parameters process-spec Specifies a process in which an image to be interrupted is running. The process must be in the same OpenVMS job as the process in which the debugger was started. Use any of the following forms: [%PROCESS_NAME] proc- The OpenVMS process name, if that name name contains no space or lowercase characters. The process name can include the asterisk (*) wildcard character. [%PROCESS_NAME] "proc- The OpenVMS process name, if that name name" contains space or lowercase characters. You can also use apostrophes (') instead of quotation marks ("). %PROCESS_PID proc-id The OpenVMS process identifier (PID, a hexadecimal number). node-name (Alpha only) When you are debugging the Alpha operating system, specifies the node name of the machine to which you are connecting (the target machine running the Alpha operating system). 3 Qualifiers /PASSWORD /PASSWORD="password" (Alpha only) When you are debugging the Alpha operating system, specifies the password for the machine to which you are connecting (the target machine running the Alpha operating system). If a password has not been established for that machine, this qualifier can be omitted. /IMAGE_PATH /IMAGE_PATH="image-path" (Alpha only) When you are debugging the Alpha operating system, specifies the image-path for the machine from which you are connecting (the host machine running the debugger). The image- path is a logical name that points to the location of system images. The default logical name is DBGHK$IMAGE_PATH:. 3 Description (Kept debugger only.) When you specify a process, the CONNECT command enables you to interrupt an image that is running without debugger control in that process and bring the process under debugger control. The command is useful if, for example, you run a debuggable image with the DCL command RUN/NODEBUG, or if your program issues a LIB$SPAWN Run-Time Library call that does not start the debugger. You cannot connect to a process created through a $CREPRC system service call. Depending on the version of the debugger you are running on your system, you may be restricted to connection with processes you created, or you may be able to connect to processes created by any member of your user identification code (UIC) group. (In some cases, you may have to set the SYSGEN SECURITY_POLICY parameter to 8 before you create the process.) Restrictions on Process Creation, by Debugger Version Number lists the restrictions that apply to specific versions of the debugger. Table 1-1 Restrictions on Process Creation, by Debugger Version Number Then you can connect to a process started If you are running... by... With the SYSGEN Parameter? VAX Version 5.5-2, You No earlier Alpha Version 6.0, earlier VAX Version 6.0 You, Member Yes of UIC Group VAX Version 6.1, You, Member No later of UIC Group Alpha Version 6.1, later If debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG, DBG$PROCESS, DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and VMSDEBUGUIL) exist, they must translate to the same definitions in both the debugger and the target process. The image modules must have been compiled and linked with the /DEBUG qualifier. The image cannot have been linked with the /NOTRACEBACK qualifier. When the process is brought under debugger control, execution of the image is suspended at the point at which it was interrupted. When you do not specify a process, the CONNECT command brings any processes that are waiting to connect to your debugging session under debugger control. If no process is waiting, you can press Ctrl/C to abort the CONNECT command. By default, a tracepoint is triggered when a process is brought under debugger control. This predefined tracepoint is equivalent to that resulting from entering the SET TRACE/ACTIVATING command. The process is then known to the debugger and can be identified in a SHOW PROCESS display. You cannot use the CONNECT command to connect to a subprocess of a process running under debugger control. Use the SET PROCESS command to connect to such a subprocess. Using the CONNECT Command to Debug the Alpha Operating System (Alpha only) You can use the CONNECT command to debug Alpha operating system code with the OpenVMS Alpha System-Code Debugger (SCD). Typically, you issue this command from a timesharing (host) Alpha machine (running SCD), and you connect to a standalone (target) Alpha machine (running the Alpha operating system). Communication between the two machines occurs over the Ethernet network. NOTE The port used for SCD on the target machine is not configured at all, and cannot be used for any other purpose, such as DECnet, LAT, user applications, and so on. Therefore, to be able to use DECnet or to be in a cluster while using SCD, you must have another Ethernet port for that traffic. In some cases, you may find that you need to use the alternative Delta/XDelta Debugger to debug operating system code. These cases include: o When you have access to only one Alpha machine for debugging o When you are debugging portions of code that generate Ethernet traffic on the target system and have only one ethernet port. Generally, however, the OpenVMS Alpha System-Code Debugger is preferred for debugging Alpha operating system code. For complete information on using this debugger, see the OpenVMS Alpha System Analysis Tools Manual. Related commands: DISCONNECT Ctrl/Y (SET,SHOW,CANCEL) TRACE 3 Examples 1.DBG_1> CONNECT This command brings under debugger control any processes that are waiting to be connected to the debugger. 2.DBG_1> CONNECT JONES_3 This command interrupts the image running in process JONES_3 and brings the process under debugger control. Process JONES_ 3 must be in the same UIC group as the process in which the debugger was started. Also, the image must not have been linked with the /NOTRACEBACK qualifier. 3.DBG> CONNECT %NODE_NAME SCDTST /PASSWORD="eager_beaver" %DEBUG-I-NOLOCALS, image does not contain local symbols DBG> On Alpha systems, this CONNECT command brings the target system running Alpha operating-system code under debugger control. This example specifies that the Alpha target machine (running the operating system) has a node name of SCDTST and a password of eager_beaver. The Alpha host machine (running the debugger) has the default DBGHK$IMAGE_PATH: image-path. 2 Ctrl 3 /C When entered from within a debugging session, Ctrl/C aborts the execution of a debugger command or interrupts program execution without interrupting the debugging session. NOTE Do not use Ctrl/Y from within a debugging session. Format 4 Description Pressing Ctrl/C enables you to abort the execution of a debugger command or to interrupt program execution without interrupting the debugging session. This is useful when, for example, the program is executing an infinite loop that does not have a breakpoint, or you want to abort a debugger command that takes a long time to complete. The debugger prompt is then displayed, so that you can enter debugger commands. If your program already has a Ctrl/C AST service routine enabled, use the SET ABORT_KEY command to assign the debugger's abort function to another Ctrl-key sequence. Note, however, that 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. If your program does not have a Ctrl/C AST service routine enabled and you assign the debugger's abort function to another Ctrl-key sequence, then Ctrl/C behaves like Ctrl/Y-that is, it interrupts the debugging session and returns you to DCL level. 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. You can use the SPAWN and ATTACH commands to leave and return to a debugging session without losing the debugging context. Related commands: ATTACH Ctrl/Y (SET,SHOW) ABORT_KEY SPAWN 4 Example DBG> GO . . . DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 1000: 0 1004: 0 1008: 0 1012: 0 1016: 0 %DEBUG-W-ABORTED, command aborted by user request DBG> This example shows how to use Ctrl/C to interrupt program execution and then to abort the execution of a debugger command. 3 /W Refreshes the screen in screen mode (like DISPLAY/REFRESH). See the DISPLAY/REFRESH command. Format 3 /Y When entered from DCL level, Ctrl/Y interrupts an image that is running without debugger control, enabling you then to start the debugger with the DCL command DEBUG. NOTES Do not use Ctrl/Y from within a debugging session. Instead, use Ctrl/C or an equivalent abort-key sequence established with the SET ABORT_KEY command. When you start the debugger with the Ctrl/Y-DEBUG sequence, you cannot then use the debugger RUN or RERUN commands. Format 4 Description Pressing Ctrl/Y at DCL level enables you to interrupt an image that is running without debugger control, so that you can then start the debugger with the DCL command DEBUG. You can bring an image under debugger control only if, as a minimum, that image was linked with the /TRACEBACK qualifier (/TRACEBACK is the default for the LINK command). When you press Ctrl/Y to interrupt the image's execution, control is passed to DCL. If you then enter the DCL command DEBUG, the interrupted image is brought under control of the debugger. The debugger sets its language-dependent parameters to the source language of the module in which execution was interrupted and displays its prompt. You can then determine where execution was suspended by entering a SHOW CALLS command. The Ctrl/Y-DEBUG sequence is not supported in the kept debugger configuration. The Ctrl/Y-DEBUG sequence is not supported in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Instead, use the STOP button. Within a debugging session, you can use the CONNECT command to connect an image that is running without debugger control in another process (of the same job) to that debugging session. Related commands: CONNECT Ctrl/C DEBUG (DCL command) RUN (DCL command) 4 Examples 1.$ RUN/NODEBUG TEST_B . . . Interrupt $ DEBUG Debugger Banner and Version Number Language: ADA, Module: SWAP DBG> In this example, the RUN/NODEBUG command executes the image TEST_B without debugger control. Execution is interrupted with Ctrl/Y. The DEBUG command then causes the debugger to be started. The debugger displays its banner, sets the language- dependent parameters to the language (Ada, in this case) of the module (SWAP) in which execution was interrupted, and displays the prompt. 2.$ RUN/NODEBUG PROG2 . . . Interrupt $ DEBUG Debugger Banner and Version Number Language: FORTRAN, Module: SUB4 predefined trace on activation at SUB4\%LINE 12 in %PROCESS_NUMBER 1 DBG> In this example, the DEFINE/JOB command establishes a multiprocess debugging configuration. The RUN/NODEBUG command executes the image PROG2 without debugger control. The Ctrl/Y- DEBUG sequence interrupts execution and starts the debugger. The banner indicates that a new debugging session has been started. The activation tracepoint indicates where execution was interrupted when the debugger took control of the process. 3 /Z Ends a debugging session (like EXIT). See the EXIT command. Format 2 DEACTIVATE 3 BREAK Deactivates a breakpoint, which you can later activate. Format DEACTIVATE BREAK [address-expression[, . . . ]] 4 Parameters address-expression Specifies a breakpoint to be deactivated. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER. 4 Qualifiers /ACTIVATING Deactivates a breakpoint established by a previous SET BREAK/ACTIVATING command. /ALL By default, deactivates all user-defined breakpoints. When used with /PREDEFINED, deactivates all predefined breakpoints but no user-defined breakpoints. To deactivate all breakpoints, use /ALL/USER/PREDEFINED. /BRANCH Deactivates a breakpoint established by a previous SET BREAK/BRANCH command. /CALL Deactivates a breakpoint established by a previous SET BREAK/CALL command. /EVENT /EVENT=event-name Deactivates a breakpoint established by a previous SET BREAK/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET BREAK/EVENT command. To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command. /EXCEPTION Deactivates a breakpoint established by a previous SET BREAK/EXCEPTION command. /HANDLER Deactivates a breakpoint established by a previous SET BREAK/HANDLER command. /INSTRUCTION Deactivates a breakpoint established by a previous SET BREAK/INSTRUCTION command. /LINE Deactivates a breakpoint established by a previous SET BREAK/LINE command. /PREDEFINED Deactivates a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, deactivates all predefined breakpoints. /SYSEMULATE (Alpha only) Deactivates a breakpoint established by a previous SET BREAK/SYSEMULATE command. /TERMINATING Deactivates a breakpoint established by a previous SET BREAK/TERMINATING command. /UNALIGNED_DATA (Alpha only) Deactivates a breakpoint established by a previous SET BREAK/UNALIGNED_DATA command. /USER Deactivates a specified user-defined breakpoint. To deactivate all user-defined breakpoints, use the /ALL qualifier. /VECTOR_INSTRUCTION (VAX only) Deactivates a breakpoint established by a previous SET BREAK/VECTOR_INSTRUCTION command. 4 Description User-defined breakpoints are activated when you set them with the SET BREAK command. Predefined breakpoints are activated by default. Use the DEACTIVATE BREAK command to deactivate one or more breakpoints. If you deactivate a breakpoint, the debugger ignores the breakpoint during program execution. To activate a deactivated breakpoint, use the ACTIVATE BREAK command. You can activate and deactivate user-defined and predefined breakpoints separately. Activating and deactivating breakpoints enables you to run and rerun your program with or without breakpoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all breakpoints (activated or deactivated). To check if a breakpoint is deactivated, use the SHOW BREAK command. Related commands: CANCEL ALL RERUN (SET,SHOW,CANCEL,ACTIVATE) BREAK (SET,SHOW) EVENT_FACILITY 4 Examples 1.DBG> DEACTIVATE BREAK MAIN\LOOP+10 This command deactivates the user-defined breakpoint set at the address expression MAIN\LOOP+10. 2.DBG> DEACTIVATE BREAK/ALL This command deactivates all user-defined breakpoints. 3 TRACE Deactivates a tracepoint, which you can later activate. Format DEACTIVATE TRACE [address-expression[, . . . ]] 4 Parameters address-expression Specifies a tracepoint to be deactivated. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER. 4 Qualifiers /ACTIVATING Deactivates a tracepoint established with a previous SET TRACE/ACTIVATING command. /ALL By default, deactivates all user-defined tracepoints. When used with /PREDEFINED, it deactivates all predefined tracepoints but no user-defined tracepoints. To deactivate all tracepoints, use /ALL/USER/PREDEFINED. /BRANCH Deactivates a tracepoint established with a previous SET TRACE/BRANCH command. /CALL Deactivates a tracepoint established with a previous SET TRACE/CALL command. /EVENT /EVENT=event-name Deactivates a tracepoint established with a previous SET TRACE/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET TRACE/EVENT command. To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command. /EXCEPTION Deactivates a tracepoint established with a previous SET TRACE/EXCEPTION command. /INSTRUCTION Deactivates a tracepoint established with a previous SET TRACE/INSTRUCTION command. /LINE Deactivates a tracepoint established with a previous SET TRACE/LINE command. /PREDEFINED Deactivates a specified predefined tracepoint without affecting any user-defined tracepoints. When used with /ALL, it deactivates all predefined tracepoints. /TERMINATING Deactivates a tracepoint established with a previous SET TRACE/TERMINATING command. /USER Deactivates a specified user-defined tracepoint without affecting any predefined tracepoints. When used with /ALL, it deactivates all user-defined tracepoints. The /USER qualifier is the default unless you specify /PREDEFINED. /VECTOR_INSTRUCTION (VAX only) Deactivates a tracepoint established with a previous SET TRACE/VECTOR_INSTRUCTION command. 4 Description User-defined tracepoints are activated when you set them with the SET TRACE command. Predefined tracepoints are activated by default. Use the DEACTIVATE TRACE command to deactivate one or more tracepoints. If you deactivate a tracepoint, the debugger ignores the tracepoint during program execution. To activate a deactivated tracepoint, use the ACTIVATE TRACE command. You can activate and deactivate user-defined and predefined tracepoints separately. Activating and deactivating tracepoints enables you to run and rerun your program with or without tracepoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all tracepoints (activated or deactivated). To check if a tracepoint is deactivated, use the SHOW TRACE command. Related commands: CANCEL ALL RERUN (SET,SHOW) EVENT_FACILITY (SET,SHOW,CANCEL,ACTIVATE) TRACE 4 Examples 1.DBG> DEACTIVATE TRACE MAIN\LOOP+10 This command deactivates the user-defined tracepoint at the location MAIN\LOOP+10. 2.DBG> DEACTIVATE TRACE/ALL This command deactivates all user-defined tracepoints. 3 WATCH Deactivates a watchpoint, which you can later activate. Format DEACTIVATE WATCH [address-expression[, . . . ]] 4 Parameters address-expression Specifies a watchpoint to be deactivated. With high-level languages, this is typically the name of a variable. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression with /ALL. 4 Qualifiers /ALL Deactivates all watchpoints. 4 Description Watchpoints are activated when you set them with the SET WATCH command. Use the DEACTIVATE WATCH command to deactivate one or more watchpoints. If you deactivate a watchpoint, the debugger ignores the watchpoint during program execution. To activate a deactivated watchpoint, use the ACTIVATE WATCH command. Activating and deactivating watchpoints enables you to run and rerun your program with or without watchpoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all static watchpoints (activated or deactivated). The state of a particular nonstatic watchpoint might or might not be saved depending on the scope of the variable being watched relative to the main program unit (where execution restarts). To check if a watchpoint is deactivated, use the SHOW WATCH command. Related commands: CANCEL ALL RERUN (SET,SHOW,CANCEL,ACTIVATE) WATCH 4 Examples 1.DBG> DEACTIVATE WATCH SUB2\TOTAL This command deactivates the watchpoint at variable TOTAL in module SUB2. 2.DBG> DEACTIVATE WATCH/ALL This command deactivates all watchpoints you have set. 2 DECLARE Declares a formal parameter within a command procedure. This enables you to pass an actual parameter to the procedure when entering an execute procedure (@) command. Format DECLARE p-name:p-kind [,p-name:p-kind[, . . . ]] 3 Parameters p-name Specifies a formal parameter (a symbol) that is declared within the command procedure. Do not specify a null parameter (represented either by two consecutive commas or by a comma at the end of the command). p-kind Specifies the parameter kind of a formal parameter. Valid keywords are as follows: ADDRESS Specifies that the actual parameter is interpreted as an address expression. Same effect as DEFINE/ADDRESS symbol-name = actual-parameter. COMMAND Specifies that the actual parameter is interpreted as a command. Same effect as DEFINE/COMMAND symbol-name = actual-parameter. VALUE Specifies that the actual parameter is interpreted as a value expression in the current language. Same effect as DEFINE/VALUE symbol-name = actual-parameter. 3 Description The DECLARE command is valid only within a command procedure. The DECLARE command binds one or more actual parameters, specified on the command line following the execute procedure (@) command, to formal parameters (symbols) declared within a command procedure. Each p-name:p-kind pair specified by a DECLARE command binds one formal parameter to one actual parameter. Formal parameters are bound to actual parameters in the order in which the debugger processes the parameter declarations. If you specify several formal parameters on a single DECLARE command, the leftmost formal parameter is bound to the first actual parameter, the next formal parameter is bound to the second, and so on. If you use a DECLARE command in a loop, the formal parameter is bound to the first actual parameter on the first iteration of the loop; the same formal parameter is bound to the second actual parameter on the next iteration, and so on. Each parameter declaration acts like a DEFINE command: it associates a formal parameter with an address expression, a command, or a value expression in the current language, according to the parameter kind specified. The formal parameters themselves are consistent with those accepted by the DEFINE command and can in fact be deleted from the symbol table with the DELETE command. The %PARCNT built-in symbol, which can be used only within a command procedure, enables you to pass a variable number of parameters to a command procedure. The value of %PARCNT is the number of actual parameters passed to the command procedure. Related commands: @ (Execute Procedure) DEFINE DELETE 3 Examples 1.! ***** Debugger Command Procedure EXAM_GO.COM ***** DECLARE L:ADDRESS, M:COMMAND EXAMINE L; M DBG> @EXAM_GO X "@DUMP" In this example, the command procedure EXAM_GO.COM accepts two parameters, an address expression (L) and a command string (M). The address expression is then examined and the command is executed. At the debugger prompt, the @EXAM_GO X "@DUMP" command executes EXAM_GO.COM, passing the address expression X and the command string @DUMP. 2.! ***** Debugger Command Procedure VAR.DBG ***** SET OUTPUT VERIFY FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) DBG> @VAR.DBG 12,37,45 %DEBUG-I-VERIFYIC, entering command procedure VAR.DBG FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) 12 37 45 %DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG DBG> In this example, the command procedure VAR.DBG accepts a variable number of parameters. That number is stored in the built-in symbol %PARCNT. At the debugger prompt, the @VAR.DBG command executes VAR.DBG, passing the actual parameters 12, 37, and 45. Therefore, %PARCNT has the value 3, and the FOR loop is repeated 3 times. The FOR loop causes the DECLARE command to bind each of the three actual parameters (starting with 12) to a new declaration of X. Each actual parameter is interpreted as a value expression in the current language, and the EVALUATE X command displays that value. 2 DEFINE Assigns a symbolic name to an address expression, command, or value. Format DEFINE symbol-name=parameter [,symbol-name=parameter[, . . . ]] 3 Parameters symbol-name Specifies a symbolic name to be assigned to an address, command, or value. The symbolic name can be composed of alphanumeric characters and underscores. The debugger converts lowercase alphabetic characters to uppercase. The first character must not be a number. The symbolic name must be no more than 31 characters long. parameter Depends on the qualifier specified. 3 Qualifiers /ADDRESS (Default) Specifies that the defined symbol is an abbreviation for an address expression. In this case, parameter is an address expression. /COMMAND Specifies that the defined symbol is treated as a new debugger command. In this case, parameter is a quoted character string. This qualifier provides, in simple cases, essentially the same capability as the following DCL command: $ symbol := string To define complex commands, you might need to use command procedures with formal parameters. For more information about declaring parameters to command procedures, see the DECLARE command. /LOCAL Specifies that the definition is valid only in the command procedure in which it is defined. The defined symbol is not visible at debugger command level. By default, a symbol defined within a command procedure is visible outside that procedure. /VALUE Specifies that the defined symbol is an abbreviation for a value. In this case, parameter is a language expression in the current language. 3 Description The DEFINE/ADDRESS command assigns a symbolic name to an address expression in a program. You can define a symbol for a nonsymbolic program location or for a symbolic program location having a long path-name prefix. You can then refer to that program location with the symbolic name. The /ADDRESS qualifier is the default. The DEFINE/COMMAND command enables you to define abbreviations for debugger commands or even define new commands, either from the debugger command level or from command procedures. The DEFINE/VALUE command enables you to assign a symbolic name to a value (or the result of evaluating a language expression). The DEFINE/LOCAL command confines symbol definitions to command procedures. By default, defined symbols are global (visible outside the command procedure). To enter several DEFINE commands with the same qualifier, first use the SET DEFINE command to establish a new default qualifier (for example, SET DEFINE COMMAND makes subsequent DEFINE commands behave like DEFINE/COMMAND). You can override the current default qualifier for a single DEFINE command by specifying another qualifier. In symbol translation, the debugger searches symbols you define during the debugging session first. So if you define a symbol that already exists in your program, the debugger translates the symbol according to its defined definition, unless you specify a path-name prefix. If a symbol is redefined, the previous definition is canceled, even if you used different qualifiers with the DEFINE 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. If 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 always available for all images. Use the SHOW SYMBOL/DEFINED command to determine the equivalence value of a symbol. Use the DELETE command to cancel a symbol definition. Related commands: DECLARE DELETE SET IMAGE SHOW DEFINE SHOW SYMBOL/DEFINED 3 Examples 1.DBG> DEFINE/VALUE COUNTER=0 DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1) In this example, the DEFINE/VALUE command assigns a value of 0 to the symbol COUNTER. The SET TRACE command causes the debugger to increment the value of the symbol COUNTER by 1 whenever address R is encountered. In other words, this example counts the number of calls to R. 2.DBG> DEFINE/COMMAND BRE = "SET BREAK" This command assigns the symbol BRE to the debugger command SET BREAK. 3 /KEY Assigns a string to a function key. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format DEFINE/KEY key-name "equivalence-string" 4 Parameters key-name Specifies a function key to be assigned a string. Valid key names are as follows: Key LK201 Name Keyboard VT100-type VT52-type PF1 PF1 PF1 Blue PF2 PF2 PF2 Red PF3 PF3 PF3 Black PF4 PF4 PF4 KP0-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9 PERIOD Keypad Keypad period (.) period (.) COMMA Keypad comma Keypad comma (,) (,) E1 Find E2 Insert Here E3 Remove E4 Select E5 Prev Screen E6 Next Screen HELP Help DO Do F6-F20 F6-F20 On LK201 keyboards: o You cannot define keys F1 to F5 or the arrow keys (E7 to E10). o You can define keys F6 to F14 only if you have first entered the DCL command SET TERMINAL/NOLINE_EDITING. In that case, the line-editing functions of the left and right arrow keys (E8 and E9) are disabled. equivalence-string Specifies the string to be processed when you press the specified key. Typically, this is one or more debugger commands. If the string includes any space or nonalphanumeric characters (for example, a semicolon separating two commands), enclose the string in quotation marks ("). 4 Qualifiers /ECHO /ECHO (default) /NOECHO Controls whether the command line is displayed after the key has been pressed. Do not use /NOECHO with /NOTERMINATE. /IF_STATE /IF_STATE=(state-name[, . . . ]) /NOIF_STATE (default) Specifies one or more states to which a key definition applies. The /IF_STATE qualifier assigns the key definition to the specified states. You can specify predefined states, such as DEFAULT and GOLD, or user-defined states. A state name can be any appropriate alphanumeric string. The /NOIF_STATE qualifier assigns the key definition to the current state. /LOCK_STATE /LOCK_STATE /NOLOCK_STATE (default) Controls how long the state set by /SET_STATE remains in effect after the specified key is pressed. The /LOCK_STATE qualifier causes the state to remain in effect until it is changed explicitly (for example, with a SET KEY/STATE command). The /NOLOCK_STATE qualifier causes the state to remain in effect only until the next terminator character is typed, or until the next defined function key is pressed. /LOG /LOG (default) /NOLOG Controls whether a message is displayed indicating that the key definition has been successfully created. The /LOG qualifier displays the message. The /NOLOG qualifier suppresses the message. /SET_STATE /SET_STATE=state-name /NOSET_STATE (default) Controls whether pressing the key changes the current key state. The /SET_STATE qualifier causes the current state to change to the specified state when you press the key. The /NOSET_STATE qualifier causes the current state to remain in effect. /TERMINATE /TERMINATE /NOTERMINATE (default) Controls whether the specified string is terminated (processed) when the key is pressed. The /TERMINATE qualifier causes the string to be terminated when the key is pressed. The /NOTERMINATE qualifier enables you to press other keys before terminating the string by pressing the Return key. 4 Description Keypad mode must be enabled (SET MODE KEYPAD) before you can use this command. Keypad mode is enabled by default. The DEFINE/KEY command enables you to assign a string to a function key, overriding any predefined function that was bound to that key. When you then press the key, the debugger enters the currently associated string into your command line. The DEFINE/KEY command is like the DCL command DEFINE/KEY. For a list of the predefined key functions, see the Keypad_ Definitions_CI online help topic. On VT52- and VT100-series terminals, the function keys you can use include all of the numeric keypad keys. Newer terminals and workstations have the LK201 keyboard. On LK201 keyboards, the function keys you can use include all of the numeric keypad keys, the nonarrow keys of the editing keypad (Find, Insert Here, and so on), and keys F6 to F20 at the top of the keyboard. A key definition remains in effect until you redefine the key, enter the DELETE/KEY command for that key, or exit the debugger. You can include key definitions in a command procedure, such as your debugger initialization file. The /IF_STATE qualifier enables you to increase the number of key definitions available on your terminal. The same key can be assigned any number of definitions as long as each definition is associated with a different state. By default, the current key state is the DEFAULT state. The current state can be changed with the SET KEY/STATE command, or 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 (SET,SHOW) KEY 4 Examples 1.DBG> SET KEY/STATE=GOLD %DEBUG-I-SETKEY, keypad state has been set to GOLD DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX" %DEBUG-I-DEFKEY, GOLD key KP9 has been defined In this example, the SET KEY command establishes GOLD as the current key state. The DEFINE/KEY command assigns the SET RADIX/OVERRIDE HEX command to keypad key 9 (KP9) for the current state (GOLD). The command is processed when you press the key. 2.DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK %LINE " %DEBUG-I-DEFKEY, BLUE key KP9 has been defined This command assigns the unterminated command string "SET BREAK %LINE" to keypad key 9 for the BLUE state. After pressing BLUE- KP9, you can enter a line number and then press the Return key to terminate and process the SET BREAK command. 3.DBG> SET KEY/STATE=DEFAULT %DEBUG-I-SETKEY, keypad state has been set to DEFAULT DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 "" %DEBUG-I-DEFKEY, DEFAULT key F12 has been defined In this example, the SET KEY command establishes DEFAULT as the current state. The DEFINE/KEY command makes the F12 key (on an LK201 keyboard) a state key. Pressing F12 while in the DEFAULT state causes the current state to become RED. The key definition is not terminated and has no other effect (a null string is assigned to F12). After pressing F12, you can enter "RED" commands by pressing keys that have definitions associated with the RED state. 3 /PROCESS_SET Assigns a symbolic name to a list of process specifications. Format DEFINE/PROCESS_SET process-set-name =process-spec[, . . . ] 4 Parameters process-set-name Specifies a symbolic name to be assigned to a list of process specifications. The symbolic name can be composed of alphanumeric characters and underscores. The debugger converts lowercase alphabetic characters to uppercase. The first character must not be a number. The symbolic name must be no more than 31 characters long. 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. If you do not specify a process, the symbolic name is created but contains no process entries. 4 Description The DEFINE/PROCESS_SET command assigns a symbol to a list of process specifications. You can then use the symbol in any command where a list of process specifications is allowed. The DEFINE/PROCESS_SET command does not verify the existence of a specified process. This enables you to specify processes that do not yet exist. To identify a symbol that was defined with the DEFINE/PROCESS_SET command, use the SHOW SYMBOL/DEFINED command. To delete a symbol that was defined with the DEFINE/PROCESS_SET command, use the DELETE command. Related commands: DELETE (SET,SHOW) DEFINE SHOW SYMBOL/DEFINED 4 Examples 1.all> DEFINE/PROCESS_SET SERVERS=FILE_SERVER,NETWORK_SERVER all> SHOW PROCESS SERVERS Number Name State Current PC * 1 FILE_SERVER step FS_PROG\%LINE 37 2 NETWORK_SERVER break NET_PROG\%LINE 24 all> This DEFINE/PROCESS_SET command assigns the symbolic name SERVERS to the process set consisting of FILE_SERVER and NETWORK_SERVER. The SHOW PROCESS SERVERS command displays information about the processes that make up the set SERVERS. 2.all> DEFINE/PROCESS_SET G1=%PROCESS_NUMBER 1,%VISIBLE_PROCESS all> SHOW SYMBOL/DEFINED G1 defined G1 bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS" was defined /process_set all> DELETE G1 This DEFINE/PROCESS_SET command assigns the symbolic name G1 to the process set consisting of process 1 and the visible process (process 3). The SHOW SYMBOL/DEFINED G1 command identifies the defined symbol G1. The DELETE G1 command deletes the symbol from the DEFINE symbol table. 3.all> DEFINE/PROCESS_SET A = B,C,D all> DEFINE/PROCESS_SET B = E,F,G all> DEFINE/PROCESS_SET E = I,J,A %DEBUG-E-NORECSYM, recursive PROCESS_SET symbol definition encountered at or near "A" This series of DEFINE/PROCESS_SET commands illustrate valid and invalid uses of the command. 2 DELETE Deletes a symbol definition that was established with the DEFINE command. Format DELETE [symbol-name[, . . . ]] 3 Parameters symbol-name Specifies a symbol whose definition is to be deleted from the DEFINE symbol table. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify a symbol name with /ALL. If you use the /LOCAL qualifier, the symbol specified must have been previously defined with the DEFINE/LOCAL command. If you do not specify /LOCAL, the symbol specified must have been previously defined with the DEFINE command without /LOCAL. 3 Qualifiers /ALL Deletes all global DEFINE definitions. Using /ALL/LOCAL deletes all local DEFINE definitions associated with the current command procedure (but not the global DEFINE definitions). /LOCAL Deletes the (local) definition of the specified symbol from the current command procedure. The symbol must have been previously defined with the DEFINE/LOCAL command. 3 Description The DELETE command deletes either a global DEFINE symbol or a local DEFINE symbol. A global DEFINE symbol is defined with the DEFINE command without the /LOCAL qualifier. A local DEFINE symbol is defined in a debugger command procedure with the DEFINE/LOCAL command, so that its definition is confined to that command procedure. Related commands: DECLARE DEFINE SHOW DEFINE SHOW SYMBOL/DEFINED 3 Examples 1.DBG> DEFINE X = INARR, Y = OUTARR DBG> DELETE X,Y In this example, the DEFINE command defines X and Y as global symbols corresponding to INARR and OUTARR, respectively. The DELETE command deletes these two symbol definitions from the global symbol table. 2.DBG> DELETE/ALL/LOCAL This command deletes all local symbol definitions from the current command procedure. 3 /KEY Deletes a key definition that was established with the DEFINE/KEY command or, by default, by the debugger. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format DELETE/KEY [key-name] 4 Parameters key-name Specifies a key whose definition is to be deleted. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify a key name with /ALL. Valid key names are as follows: Key LK201 Name Keyboard VT100-type VT52-type PF1 PF1 PF1 Blue PF2 PF2 PF2 Red PF3 PF3 PF3 Black PF4 PF4 PF4 KP0-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9 PERIOD Keypad Keypad period (.) period (.) COMMA Keypad comma Keypad comma (,) (,) ENTER Enter ENTER ENTER E1 Find E2 Insert Here E3 Remove E4 Select E5 Prev Screen E6 Next Screen HELP Help DO Do F6-F20 F6-F20 4 Qualifiers /ALL Deletes all key definitions in the specified state. If you do not specify a state, all key definitions in the current state are deleted. To specify one or more states, use /STATE=state-name. /LOG /LOG (default) /NOLOG Controls whether a message is displayed indicating that the specified key definitions have been deleted. The /LOG qualifier (which is the default) displays the message. The /NOLOG qualifier suppresses the message. /STATE /STATE=(state-name [, . . . ]) /NOSTATE (default) Selects one or more states for which a key definition is to be deleted. The /STATE qualifier deletes key definitions for the specified states. You can specify predefined key states, such as DEFAULT and GOLD, or user-defined states. A state name can be any appropriate alphanumeric string. The /NOSTATE qualifier deletes the key definition for the current state only. By default, the current key state is the DEFAULT state. The current state can be changed with the SET KEY/STATE command, or by pressing a key that causes a state change (a key that was defined with DEFINE/KEY/LOCK_STATE/SET_STATE). 4 Description The DELETE/KEY command is like the DCL command DELETE/KEY. Keypad mode must be enabled (SET MODE KEYPAD) before you can use this command. Keypad mode is enabled by default. Related commands: DEFINE/KEY (SET,SHOW) KEY 4 Examples 1.DBG> DELETE/KEY KP4 %DEBUG-I-DELKEY, DEFAULT key KP4 has been deleted This command deletes the key definition for KP4 in the state last set by the SET KEY command (by default, this is the DEFAULT state). 2.DBG> DELETE/KEY/STATE=(BLUE,RED) COMMA %DEBUG-I-DELKEY, BLUE key COMMA has been deleted %DEBUG-I-DELKEY, RED key COMMA has been deleted This command deletes the key definition for the COMMA key in the BLUE and RED states. 2 DEPOSIT Changes the value of a program variable. More generally, deposits a new value at the location denoted by an address expression. Format DEPOSIT address-expression = language-expression 3 Parameters address-expression Specifies the location into which the value of the language expression is to be deposited. With high-level languages, this is typically the name of a variable and can include a path name to specify the variable 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 debugger symbols for the registers and about the operators you can use in address expressions, see the Built_in_Symbols and Address_Expressions help topics. You cannot specify an entire aggregate variable (a composite data structure such as an array or a record). To specify an individual array element or a record component, follow the syntax of the current language. language-expression Specifies the value to be deposited. You can specify any language expression that is valid in the current language. For most languages, the expression can include the names of simple (noncomposite, single-valued) variables but not the names of aggregate variables (such as arrays or records). If the expression contains symbols with different compiler-generated types, the debugger uses the rules of the current language to evaluate the expression. If the expression is an ASCII string or an assembly-language instruction, you must enclose it in quotation marks (") or apostrophes ('). If the string contains quotation marks or apostrophes, use the other delimiter to enclose the string. If the string has more characters (1-byte ASCII) than can fit into the program location denoted by the address expression, the debugger truncates the extra characters from the right. If the string has fewer characters, the debugger pads the remaining characters to the right of the string by inserting ASCII space characters. 3 Qualifiers /ASCIC /ASCIC /AC Deposits a counted ASCII string into the specified location. You must specify a quoted string on the right-hand side of the equal sign. The deposited string is preceded by a 1-byte count field that gives the length of the string. /ASCID /ASCID /AD Deposits an ASCII string into the address given by a string descriptor that is at the specified location. You must specify a quoted string on the right-hand side of the equal sign. The specified location must contain a string descriptor. If the string lengths do not match, the string is either truncated on the right or padded with space characters on the right. /ASCII /ASCII:n Deposits n bytes of an ASCII string into the specified location. You must specify a quoted string on the right-hand side of the equal sign. If its length is not n, the string is truncated or padded with space characters on the right. If you omit n, the actual length of the data item at the specified location is used. /ASCIW /ASCIW /AW Deposits a counted ASCII string into the specified location. You must specify a quoted string on the right-hand side of the equal sign. The deposited string is preceded by a 2-byte count field that gives the length of the string. /ASCIZ /ASCIZ /AZ Deposits a zero-terminated ASCII string into the specified location. You must specify a quoted string on the right-hand side of the equal sign. The deposited string is terminated by a zero byte that indicates the end of the string. /BYTE Deposits a 1-byte integer into the specified location. /D_FLOAT Converts the expression on the right-hand side of the equal sign to the D_floating type (length 8 bytes) and deposits the result into the specified location. /DATE_TIME Converts a string representing a date and time (for example, 21-DEC-1988 21:08:47.15) to the internal format for date and time and deposits that value (length 8 bytes) into the specified location. Specify an absolute date and time in the following format: [dd-mmm-yyyy[:]] [hh:mm:ss.cc] /EXTENDED_FLOAT /EXTENDED_FLOAT /X_FLOAT (Alpha only) Converts the expression on the right-hand side of the equal sign to the IEEE X_floating type (length 16 bytes) and deposits the result into the specified location. /FLOAT On VAX processors, converts the expression on the right-hand side of the equal sign to the F_floating type (length 4 bytes) and deposits the result into the specified location. On Alpha processors, converts the expression on the right-hand side of the equal sign to the IEEE T_floating type (double precision, length 8 bytes) and deposits the result into the specified location. /F_FLOAT (VAX only) Converts the expression on the right-hand side of the equal sign to the F_floating type (length 4 bytes) and deposits the result into the specified location. /G_FLOAT Converts the expression on the right-hand side of the equal sign to the G_floating type (length 8 bytes) and deposits the result into the specified location. /H_FLOAT (VAX only) Converts the expression on the right-hand side of the equal sign to the H_floating type (length 16 bytes) and deposits the result into the specified location. /INSTRUCTION (VAX only) Deposits an instruction into the specified location. The expression on the right-hand side of the equal sign must be a quoted string representing an assembly-language instruction. /LONG_FLOAT /LONG_FLOAT /S_FLOAT (Alpha only) Converts the expression on the right-hand side of the equal sign to the IEEE S_floating type (single precision, length 4 bytes) and deposits the result into the specified location. /LONG_LONG_FLOAT /LONG_LONG_FLOAT /T_FLOAT (Alpha only) Converts the expression on the right-hand side of the equal sign to the IEEE T_floating type (double precision, length 8 bytes) and deposits the result into the specified location. /LONGWORD Deposits a longword integer (length 4 bytes) into the specified location. /OCTAWORD Deposits an octaword integer (length 16 bytes) into the specified location. /PACKED /PACKED:n Converts the expression on the right-hand side of the equal sign to a packed decimal representation and deposits the resulting value into the specified location. The value of n is the number of decimal digits. Each digit occupies one nibble (4 bits). /QUADWORD Deposits a quadword integer (length 8 bytes) into the specified location. /S_FLOAT /S_FLOAT /LONG_FLOAT (Alpha only) Converts the expression on the right-hand side of the equal sign to the IEEE S_floating type (single precision, length 4 bytes) and deposits the result into the specified location. /TASK Applies to tasking (multithread) programs. Deposits a task value (a task name or a task ID such as %TASK 3) into the specified location. The deposited value must be a valid task value. /T_FLOAT (Alpha only) Converts the expression on the right-hand side of the equal sign to the IEEE T_floating type (double precision, length 8 bytes) and deposits the result into the specified location. /TYPE /TYPE=(name) Converts the expression to be deposited to the type denoted by name (which must be the name of a variable or data type declared in the program), then deposits the resulting value into the specified location. This enables you to specify a user-declared type. You must use parentheses around the type expression. /WCHAR_T /WCHAR_T[:n] Deposits up to n longwords (n characters) of a converted multibyte file code sequence into the specified location. The default is 1 longword. You must specify a string on the right- hand side of the equal sign. When converting the specified string, the debugger uses the locale database of the process in which the debugger runs. The default is C locale. /WORD Deposits a word integer (length 2 bytes) into the specified location. /X_FLOAT (Alpha only) Converts the expression on the right-hand side of the equal sign to the IEEE X_floating type (length 16 bytes) and deposits the result into the specified location. 3 Description You can use the DEPOSIT command to change the contents of any memory location or register that is accessible in your program. For high-level languages the command is used mostly to change the value of a variable (an integer, real, string, array, record, and so on). The DEPOSIT command is like an assignment statement in most programming languages. The value of the expression specified to the right of the equal sign is assigned to the variable or other location specified to the left of the equal sign. For Ada and Pascal, you can use ":=" instead of "=" in the command syntax. The debugger recognizes the compiler-generated types associated with symbolic address expressions (symbolic names declared in your program). Symbolic address expressions include the following entities: o Variable names. When specifying a variable with the DEPOSIT command, use the same syntax that is used in the source code. o Routine names, labels, and line numbers. On VAX systems, these are associated with instructions. You can deposit instructions using basically the same techniques as when depositing into string variables. However, you must also use the /INSTRUCTION qualifier or first enter a SET TYPE INSTRUCTION or SET TYPE/OVERRIDE INSTRUCTION command. In general, when you enter a DEPOSIT command, the debugger takes the following actions: o It evaluates the address expression specified to the left of the equal sign, to yield a program location. o If the program location has a symbolic name, the debugger associates the location with the symbol's compiler-generated type. If the location does not have a symbolic name (and, therefore, no associated compiler-generated type) the debugger associates the location with the type longword integer by default. This means that, by default, you can deposit integer values that do not exceed 4 bytes into these locations. o It evaluates the language expression specified to the right of the equal sign, in the syntax of the current language and in the current radix, to yield a value. The current language is the language last established with the SET LANGUAGE command. By default, if you did not enter a SET LANGUAGE command, the current language is the language of the module containing the main program. o It checks that the value and type of the language expression is consistent with the type of the address expression. If you try to deposit a value that is incompatible with the type of the address expression, the debugger issues a diagnostic message. If the value is compatible, the debugger deposits the value into the location denoted by the address expression. 3 Description,_Continued... The debugger might do type conversion during a deposit operation if the language rules allow it. For example, a real value specified to the right of the equal sign might be converted to an integer value if it is being deposited into a location with an integer type. In general, the debugger tries to follow the assignment rules for the current language. There are several ways of changing the type associated with a program location so that you can deposit data of a different type into that location: o To change the default type for all locations that do not have a symbolic name, you can specify a new type with the SET TYPE command. o To change the default type for all locations (both those that do and do not have a symbolic name), you can specify a new type with the SET TYPE/OVERRIDE command. o To override the type currently associated with a particular location for the duration of a single DEPOSIT command, you can specify a new type by using a qualifier (/ASCII:n, /BYTE, /TYPE=(name), and so on). When debugging a C program, or a program in any case-specific language, you cannot use the DEPOSIT/TYPE command if the type specified is a mixed or lowercase name. For example, suppose the program has a function like the following: xyzzy_type foo () { xyzzy_type z; z = get_z (); return (z); } If you try to enter the following command, the debugger issues a message that it cannot find the type "xyzzy_type": DBG> DEPOSIT/TYPE=(xyzzy_type) z="whatever" The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, which have a default radix of hexadecimal. You can use the SET RADIX and SET RADIX/OVERRIDE commands to change the default radix. The DEPOSIT command sets the current entity built-in symbols %CURLOC and period (.) to the location denoted by the address expression specified. Logical predecessors (%PREVLOC or the circumflex character (^)) and successors (%NEXTLOC) are based on the value of the current entity. Related commands: CANCEL TYPE/OVERRIDE EVALUATE EXAMINE MONITOR (SET,SHOW,CANCEL) RADIX (SET,SHOW) TYPE 3 Examples 1.DBG> DEPOSIT I = 7 This command deposits the value 7 into the integer variable I. 2.DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 24.80 This command deposits the value of the expression CURRENT_WIDTH + 24.80 into the real variable WIDTH. 3.DBG> DEPOSIT STATUS = FALSE This command deposits the value FALSE into the Boolean variable STATUS. 4.DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84" This command deposits the string WG-7619.3-84 into the string variable PART_NUMBER. 5.DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 This command deposits the value 02172 into component ZIPCODE of record EMPLOYEE. 6.DBG> DEPOSIT ARR(8) = 35 DBG> DEPOSIT ^ = 14 In this example, the first DEPOSIT command deposits the value 35 into element 8 of array ARR. As a result, element 8 becomes the current entity. The second command deposits the value 14 into the logical predecessor of element 8, namely element 7. 7.DBG> FOR I = 1 TO 4 DO (DEPOSIT ARR(I) = 0) This command deposits the value 0 into elements 1 to 4 of array ARR. 8.DBG> DEPOSIT COLOR = 3 %DEBUG-E-OPTNOTALLOW, operator "DEPOSIT" not allowed on given data type The debugger alerts you when you try to deposit data of the wrong type into a variable (in this case, if you try to deposit an integer value into an enumerated type variable). The E (error) message severity indicates that the debugger does not make the assignment. 9.DBG> DEPOSIT VOLUME = - 100 %DEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near '-' The debugger alerts you when you try to deposit an out-of- bounds value into a variable (in this case a negative value). The I (informational) message severity indicates that the debugger does make the assignment. 10DBG> DEPOSIT/OCTAWORD BIGINT = 111222333444555 This command deposits the expression 111222333444555 into location BIGINT and converts it to an octaword integer. 11DBG> DEPOSIT/FLOAT BIGFLT = 1.11949*10**35 This command converts 1.11949*10**35 to an F_floating type value and deposits it into location BIGFLT. 2 DISABLE 3 AST Disables the delivery of asynchronous system traps (ASTs) in your program. Format DISABLE AST 4 Description The DISABLE AST command disables the delivery of ASTs in your program and thereby prevents interrupts from occurring while the program is running. If ASTs are delivered while the debugger is running (processing commands, and so on), they are queued and are delivered when control is returned to the program. The ENABLE AST command reenables the delivery of ASTs, including any pending ASTs (ASTs waiting to be delivered). NOTE Any call by your program to the $SETAST system service that enables ASTs overrides a previous DISABLE AST command. Related commands: (ENABLE,SHOW) AST 4 Example DBG> DISABLE AST DBG> SHOW AST ASTs are disabled DBG> The DISABLE AST command disables the delivery of ASTs in your program, as confirmed by the SHOW AST command. 2 DISCONNECT Releases a process from debugger control without terminating the process (kept debugger only). Format DISCONNECT process-spec 3 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. 3 Description (Kept debugger only.) The DISCONNECT command releases a specified process from debugger control without terminating the process. This is useful if, for example, you have brought a running program under debugger control with a CONNECT command and you now want to release it without terminating the image. (In contrast, when you specify a process with the EXIT or QUIT command, the process is terminated.) CAUTION The debugger kernel runs in the same process as the image being debugged. If you issue the DISCONNECT command for this process, you release your process, but the kernel remains activated. This activation continues until the program image finishes running. If you install a new version of the debugger while one or more disconnected but activated kernels inhabit user program space, you can experience problems with debugger behavior if you try to reconnect to one of those kernels. Related commands: EXIT QUIT CONNECT 3 Example DBG> DISCONNECT JONES This command releases process JONES from debugger control without terminating the process. 2 DISPLAY Creates a new screen display or modifies an existing display. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format DISPLAY display-name [AT window-spec] [display-kind] [, . . . ] 3 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 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. INSTRUCTION (VAX only) Specifies an automatically updated (command) instruction display. The command specified must be an EXAMINE/INSTRUCTION command. The instruction display is updated each time the debugger gains control. 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. 3 Qualifiers /CLEAR Erases the entire contents of a specified display. Do not use this qualifier with /GENERATE or when creating a new display. /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. /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. /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. /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. /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). /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] 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. 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. /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). /REFRESH Refreshes the terminal screen. Do not specify any command parameters with this qualifier. You can also use Ctrl/W to refresh the screen. /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. /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 3 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. 2 DUMP Displays the contents of memory. Format DUMP address-expression1 [:address-expression2] 3 Parameters address-expression1 Specifies the first memory location to be displayed. address-expression2 Specifies the last memory location to be displayed (default is address-expression1). 3 Qualifiers /BINARY Displays each examined entity as a binary integer. /BYTE Displays each examined entity as a byte integer (length 1 byte). /DECIMAL Displays each examined entity as a decimal integer. /HEXADECIMAL Displays each examined entity as a hexadecimal integer. /LONGWORD /LONGWORD (default) Displays each examined 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 examined entity as an octal integer. /QUADWORD Displays each examined entity in the quadword integer type (length 8 bytes). /WORD Displays each examined entity in the word integer type (length 2 bytes). 3 Description The DUMP command displays the contents of memory, including registers, variables, and arrays. The DUMP command formats its output in a manner similar to the DCL command DUMP. The debugger DUMP command makes no attempt to interpret the structure of aggregates. In general, when you enter a DUMP command, the debugger evaluates address-expression1 to yield a program location. The debugger then displays the entity stored at that location as follows: o If the entity has a symbolic name, the debugger uses the size of the entity to determine the address range to display. o If the entity does not have a symbolic name (and, therefore, no associated compiler-generated type) the debugger displays address-expression1 through address-expression2 (if specified). In either case, the DUMP command displays the contents of these locations as longword (by default) integer values in the current radix. The default radix for display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, which have a default radix of hexadecimal. Use one of the four radix qualifiers (/BINARY, /DECIMAL, /HEXADECIMAL, /OCTAL) to display data in another radix. You can also use the SET RADIX and SET RADIX/OVERRIDE commands to change the default radix. Use one of the size qualifiers (/BYTE, /WORD, /LONGWORD, /QUADWORD) to change the format of the display. The DUMP command sets the current entity built-in symbols %CURLOC and period (.) to the location denoted by the address expression specified. Logical predecessors (%PREVLOC or the circumflex character (^)) and successors (%NEXTLOC) are based on the value of the current entity. Related command: EXAMINE 3 Examples 1.DBG> DUMP/QUAD R16:R25 0000000000000078 0000000000030038 8.......x....... %R16 000000202020786B 0000000000030041 A.......kx ... %R18 0000000000030140 0000000000007800 .x......@....... %R20 0000000000010038 0000000000000007 ........8....... %R22 0000000000000006 0000000000000000 ................ %R24 DBG> This command displays general registers R16 through R25 in quadword format and hexadecimal radix. 2.DBG> DUMP/BYTE/DECIMAL 30000:30040 0 0 0 0 0 3 0 -80 °....... 0000000000030000 0 0 0 0 0 3 1 64 @....... 0000000000030008 0 0 0 0 0 3 0 48 0....... 0000000000030010 0 0 0 0 0 3 0 56 8....... 0000000000030018 0 0 0 0 0 3 0 -64 À....... 0000000000030020 0 0 0 0 0 3 0 -80 °....... 0000000000030028 0 0 0 0 0 0 7 -50 Î....... 0000000000030030 101 101 119 32 116 120 101 110 next wee 0000000000030038 107 k 0000000000030040 DBG> This command displays locations 30000 through 30040 in byte format and decimal radix. 2 EDIT Starts the editor established with the SET EDITOR command. If you did not enter a SET EDITOR command, starts the DEC Language- Sensitive Editor (LSEDIT), if that editor is installed on your system. Format EDIT [[module-name\] line-number] 3 Parameters module-name Specifies the name of the module whose source file is to be edited. If you specify a module name, you must also specify a line number. If you omit the module name parameter, the source file whose code appears in the current source display is chosen for editing. line-number A positive integer that specifies the source line on which the editor's cursor is initially placed. If you omit this parameter, the cursor is initially positioned at the beginning of the source line that is centered in the debugger's current source display, or at the beginning of line 1 if the editor was set to /NOSTART_ POSITION (see the SET EDITOR command.) 3 Qualifiers /EXIT /EXIT /NOEXIT (default) Controls whether you end the debugging session prior to starting the editor. If you specify /EXIT, the debugging session is terminated and the editor is then started. If you specify /NOEXIT, the editing session is started and you return to your debugging session after terminating the editing session. 3 Description If you have not specified an editor with the SET EDITOR command, the EDIT command starts the DEC Language-Sensitive Editor (LSEDIT) in a spawned subprocess (if LSEDIT is installed on your system). The typical (default) way to use the EDIT command is not to specify any parameters. In this case, the editing cursor is initially positioned at the beginning of the line that is centered in the currently selected debugger source display (the current source display). The SET EDITOR command provides options for starting different editors, either in a subprocess or through a callable interface. Related commands: (SET,SHOW) EDITOR (SET,SHOW,CANCEL) SOURCE 3 Examples 1.DBG> EDIT This command spawns the DEC Language-Sensitive Editor (LSEDIT) in a subprocess to edit the source file whose code appears in the current source display. The editing cursor is positioned at the beginning of the line that was centered in the source display. 2.DBG> EDIT SWAP\12 This command spawns the DEC Language-Sensitive Editor (LSEDIT) in a subprocess to edit the source file containing the module SWAP. The editing cursor is positioned at the beginning of source line 12. 3.DBG> SET EDITOR/CALLABLE_EDT DBG> EDIT In this example, the SET EDITOR/CALLABLE_EDT command establishes that EDT is the default editor and is started through its callable interface (rather than spawned in a subprocess). The EDIT command starts EDT to edit the source file whose code appears in the current source display. The editing cursor is positioned at the beginning of source line 1, because the default qualifier /NOSTART_POSITION applies to EDT. 2 ENABLE 3 AST Enables the delivery of asynchronous system traps (ASTs) in your program. Format ENABLE AST 4 Description The ENABLE AST command enables the delivery of ASTs while your program is running, including any pending ASTs (ASTs waiting to be delivered). If ASTs are delivered while the debugger is running (processing commands, and so on), they are queued and are delivered when control is returned to the program. Delivery of ASTs in your program is initially enabled by default. NOTE Any call by your program to the $SETAST system service that disables ASTs overrides a previous ENABLE AST command. Related commands: (DISABLE,SHOW) AST 4 Example DBG> ENABLE AST DBG> SHOW AST ASTs are enabled DBG> The ENABLE AST command enables the delivery of ASTs in your program, as confirmed with the SHOW AST command. 2 EVALUATE Displays the value of a language expression in the current language (by default, the language of the module containing the main program). Format EVALUATE language-expression[, . . . ] 3 Parameters language-expression Specifies any valid expression in the current language. 3 Qualifiers /BINARY Specifies that the result be displayed in binary radix. /CONDITION_VALUE Specifies that the expression be interpreted as a condition value (the kind of condition value you would specify using the condition-handling mechanism). The message text corresponding to that condition value is then displayed. The specified value must be an integer value. /DECIMAL Specifies that the result be displayed in decimal radix. /HEXADECIMAL Specifies that the result be displayed in hexadecimal radix. /OCTAL Specifies that the result be displayed in octal radix. 3 Description The debugger interprets the expression specified in an EVALUATE command as a language expression, evaluates it in the syntax of the current language and in the current radix, and displays its value as a literal (for example, an integer value) in the current language. The current language is the language last established with the SET LANGUAGE command. If you did not enter a SET LANGUAGE command, the current language is, by default, the language of the module containing the main program. If an expression contains symbols with different compiler- generated types, the debugger uses the type-conversion rules of the current language to evaluate the expression. The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The current radix is the radix last established with the SET RADIX command. If you did not enter a SET RADIX command, the default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, which have a default radix of hexadecimal. You can use a radix qualifier (/BINARY, /OCTAL, and so on) to display integer data in another radix. These qualifiers do not affect how the debugger interprets the data you specify; they override the current output radix, but not the input radix. The EVALUATE command sets the current value of built-in symbols %CURVAL and backslash (\) to the value denoted by the specified expression. You cannot evaluate a language expression that includes a function call. For example, if PRODUCT is a function that multiplies two integers, you cannot use the command EVALUATE PRODUCT(3,5). If your program assigns the returned value of a function to a variable, you can examine the resulting value of that variable. On Alpha processors, the command EVALUATE procedure-name displays the procedure descriptor address (not the code address) of a specified routine, entry point, or Ada package. For more information about debugger support for language-specific operators and constructs, see the Language_Support Help topic. Related commands: EVALUATE/ADDRESS MONITOR (SET,SHOW) LANGUAGE (SET,SHOW,CANCEL) RADIX (SET,SHOW) TYPE 3 Examples 1.DBG> EVALUATE 100.34 * (14.2 + 7.9) 2217.514 DBG> This command uses the debugger as a calculator by multiplying 100.34 by (14.2 + 7.9). 2.DBG> EVALUATE/OCTAL X 00000001512 DBG> This command evaluates the symbol X and displays the result in octal radix. 3.DBG> EVALUATE TOTAL + CURR_AMOUNT 8247.20 DBG> This command evaluates the sum of the values of two real variables, TOTAL and CURR_AMOUNT. 4.DBG> DEPOSIT WILLING = TRUE DBG> DEPOSIT ABLE = FALSE DBG> EVALUATE WILLING AND ABLE False DBG> In this example, the EVALUATE command evaluates the logical AND of the current values of two Boolean variables, WILLING and ABLE. 5.DBG> EVALUATE COLOR'FIRST RED DBG> In this Ada example, this command evaluates the first element of the enumeration type COLOR. 3 /ADDRESS Evaluates an address expression and displays the result as a memory address or a register name. Format EVALUATE/ADDRESS address-expression[, . . . ] 4 Parameters address-expression Specifies an address expression of any valid form (for example, a routine name, variable name, label, line number, and so on). 4 Qualifiers /BINARY Displays the memory address in binary radix. /DECIMAL Displays the memory address in decimal radix. /HEXADECIMAL Displays the memory address in hexadecimal radix. /OCTAL Displays the memory address in octal radix. 4 Description The EVALUATE/ADDRESS command enables you to determine the memory address or register associated with an address expression. The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, which have a default radix of hexadecimal. You can use a radix qualifier (/BINARY, /OCTAL, and so on) to display address values in another radix. These qualifiers do not affect how the debugger interprets the data you specify; that is, they override the current output radix, but not the input radix. If the value of a variable is currently stored in a register instead of memory, the EVALUATE/ADDRESS command identifies the register. The radix qualifiers have no effect in that case. The EVALUATE/ADDRESS command sets the current entity built-in symbols %CURLOC and period (.) to the location denoted by the address expression specified. Logical predecessors (%PREVLOC or the circumflex character (^)) and successors (%NEXTLOC) are based on the value of the current entity. On Alpha processors, the command EVALUATE/ADDRESS procedure-name displays the procedure descriptor address (not the code address) of a specified routine, entry point, or Ada package. Related commands: EVALUATE (SET,SHOW,CANCEL) RADIX SHOW SYMBOL/ADDRESS SYMBOLIZE 4 Examples 1.DBG> EVALUATE/ADDRESS MODNAME\%LINE 110 3942 DBG> This command displays the memory address denoted by the address expression MODNAME\%LINE 110. 2.DBG> EVALUATE/ADDRESS/HEX A,B,C 000004A4 000004AC 000004A0 DBG> This command displays the memory addresses denoted by the address expressions A, B, and C in hexadecimal radix. 3.DBG> EVALUATE/ADDRESS X MOD3\%R1 DBG> This command indicates that variable X is associated with register R1. X is a nonstatic (register) variable. 2 EXAMINE Displays the current value of a program variable. More generally, displays the value of the entity denoted by an address expression. Format EXAMINE [address-expression[:address-expression] [, . . . ]] 3 Parameters address-expression Specifies an entity to be examined. With high-level languages, this is typically the name of a variable and can include a path name to specify the variable 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 debugger symbols for the registers and about the operators you can use in address expressions, type Help Built_in_Symbols or Help Address_Expressions. If you specify the name of an aggregate variable (a composite data structure such as an array or record structure) the debugger displays the values of all elements. For an array, the display shows the subscript (index) and value of each array element. For a record, the display shows the name and value of each record component. To specify an individual array element, array slice, or record component, follow the syntax of the current language. If you specify a range of entities, the value of the address expression that denotes the first entity in the range must be less than the value of the address expression that denotes the last entity in the range. The debugger displays the entity specified by the first address expression, the logical successor of that address expression, the next logical successor, and so on, until it displays the entity specified by the last address expression. You can specify a list of ranges by separating ranges with a comma. For information specific to vector registers and vector instructions, see /TMASK, /FMASK, /VMR, and /OPERANDS qualifiers. 3 Qualifiers /ASCIC /ASCIC /AC Interprets each examined 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 /ASCID /AD Interprets each examined 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 /ASCII:n Interprets and displays each examined 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 /ASCIW /AW Interprets each examined 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 /ASCIZ /AZ Interprets each examined 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 examined entity as a binary integer. /BYTE Displays each examined entity in the byte integer type (length 1 byte). /CONDITION_VALUE Interprets each examined entity as a condition-value return status and displays the message associated with that return status. /D_FLOAT Displays each examined entity in the D_floating type (length 8 bytes). /DATE_TIME Interprets each examined entity as a quadword integer (length 8 bytes) containing the internal representation of date and time. Displays the value in the format dd-mmm-yyyy hh:mm:ss.cc. /DECIMAL Displays each examined entity as a decimal integer. /DEFAULT Displays each examined entity in the default radix. The minimum abbreviation is /DEFA. /DEFINITIONS /DEFINITIONS=n (Alpha only) When the code is optimized, displays n definition points for a split-lifetime variable. A definition point is a location in the program where the variable could have received its value. By default, up to five definition points are displayed. If more than the given number of definitions (explicit or default) are available, then the number of additional definitions is reported as well. (For more information on split- lifetime variables, see OpenVMS Debugger Manual.) The minimum abbreviation is /DEFI. /EXTENDED_FLOAT /EXTENDED_FLOAT /X_FLOAT (Alpha only) Displays each examined entity in the IEEE X_floating type (length 16 bytes). /FLOAT On VAX processors, same as /F_FLOAT. Displays each examined entity in the F_floating type (length 4 bytes). On Alpha processors, same as T_FLOAT. Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes). /F_FLOAT (VAX only) Displays each examined entity in the F_floating type (length 4 bytes). /FPCR (Alpha only) Displays each examined entity in FPCR (floating- point control register) format. /FMASK /FMASK[=(mask-address-expression)] Applies only to VAX vectorized programs. See the /TMASK qualifier. /G_FLOAT Displays each examined entity in the G_floating type (length 8 bytes). /H_FLOAT (VAX only) Displays each examined entity in the H_floating type (length 16 bytes). /HEXADECIMAL Displays each examined entity as a hexadecimal integer. /INSTRUCTION Displays each examined 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. In screen mode, the output of an EXAMINE/INSTRUCTION command is directed at the current instruction display, if any, not at an output or DO display. The arrow in the instruction display points to the examined instruction. On Alpha processors, the command EXAMINE/INSTRUCTION procedure- name displays the first instruction at the code address of a specified routine, entry point, or Ada package. /LINE /LINE (default) /NOLINE Controls whether program locations are displayed in terms of line numbers (%LINE x) or as routine-name + byte-offset. By default (/LINE), the debugger symbolizes program locations in terms of line numbers. /LONG_FLOAT /LONG_FLOAT /S_FLOAT (Alpha only) Displays each examined entity in the IEEE S_floating type (single precision, length 4 bytes). /LONG_LONG_FLOAT /LONG_LONG_FLOAT /T_FLOAT (Alpha only) Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes). /LONGWORD Displays each examined 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 examined entity as an octal integer. /OCTAWORD Displays each examined entity in the octaword integer type (length 16 bytes). /OPERANDS /OPERANDS[=keyword] (VAX only) Displays operand information associated with an examined instruction (displays each operand's address and its contents, using the operand's data type). The keywords BRIEF and FULL vary the amount of information displayed about any nonregister operands. The default is /OPERANDS=BRIEF. Use /OPERANDS only when examining the instruction at the current PC value (for example, EXAMINE/OPERANDS .0\%PC). Examining the operands of an instruction that is not at the current PC value can give erroneous results, because the state of the machine (the contents of the registers) is not set up for that instruction. In screen mode, operand information is directed at the current output display. When you examine the operands of a vector instruction, any operand-element masking that might be associated with that instruction is performed by default. The /TMASK and /FMASK qualifiers enable you to specify some other mask. The current value of the vector length register (VLR) limits the highest element of a vector register that you can examine. See also the SET MODE [NO]OPERANDS=keyword command, which lets you set a default level for the amount of operand information displayed when examining instructions. /PACKED /PACKED:n Interprets each examined entity as a packed decimal number. The value of n is the number of decimal digits. Each digit occupies one nibble (4 bits). /PS (Alpha only) Displays each examined entity in PS (processor status register) format. /PSL (VAX only) Displays each examined entity in PSL (processor status longword) format. /PSW (VAX only) Displays each examined entity in PSW (processor status word) format. The /PSW qualifier is like /PSL except that only the low-order word (2 bytes) is displayed. /QUADWORD Displays each examined entity in the quadword integer type (length 8 bytes). /S_FLOAT (Alpha only) Displays each examined entity in the IEEE S_floating type (single precision, length 4 bytes). /SFPCR (Alpha only) Displays each examined entity in SFPCR (software floating-point control register) format. /SOURCE NOTE This qualifier is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Displays the source line corresponding to the location of each examined entity. The examined entity must be associated with a machine code instruction and, therefore, must be a line number, a label, a routine name, or the memory address of an instruction. The examined entity cannot be a variable name or any other address expression that is associated with data. In screen mode, the output of an EXAMINE/SOURCE command is directed at the current source display, if any, not at an output or DO display. The arrow in the source display points to the source line associated with the last entity specified (or the last one specified in a list of entities). On Alpha processors, the command EXAMINE/SOURCE procedure-name displays the source code at the code address of a specified routine, entry point, or Ada package. /SYMBOLIC /SYMBOLIC (default) /NOSYMBOLIC Controls whether symbolization occurs. By default (/SYMBOLIC), the debugger symbolizes all addresses, if possible; that is, it converts numeric addresses into their symbolic representation. If you specify /NOSYMBOLIC, the debugger suppresses symbolization of entities you specify as absolute addresses. If you specify entities as variable names, symbolization still occurs. The /NOSYMBOLIC qualifier is useful if you are interested in identifying numeric addresses rather than their symbolic names (if symbolic names exist for those addresses). Using /NOSYMBOLIC may speed up command processing because the debugger does not need to convert numbers to names. /TASK Applies to tasking (multithread) programs. Interprets each examined entity as a task (thread) object and displays the task value (the name or task ID) of that task object. When examining a task object, use /TASK only if the programming language does not have built-in tasking services. /T_FLOAT (Alpha only) Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes). /TMASK /TMASK[=(mask-address-expression)] /FMASK[=(mask-address-expression)] These qualifiers apply only to VAX vectorized programs. They enable you to specify a mask in order to display certain elements of a vector register (V0 to V15), or of an array in memory, while not displaying other elements. For example, when you examine the operands of a vector instruction (by using the /OPERANDS qualifier), these qualifiers enable you to override any operand-element masking that might be associated with that instruction. The /TMASK qualifier applies the EXAMINE command only to the elements of the register or array that correspond to the set bits (bit value: 1) of the mask. The /FMASK qualifier applies the EXAMINE command only to the elements that correspond to the clear bits (bit value: 0) of the mask. The current value of the vector length register (VLR) limits the highest register element that you can examine but not the highest array element. By default, if you do not specify a mask address expression with /TMASK or /FMASK, the vector mask register (VMR) is used. That is, the EXAMINE command is applied only to the elements of the vector register or array that correspond to the set bits (in the case of /TMASK) or clear bits (in the case of /FMASK) of VMR. If you specify a mask address expression with /TMASK or /FMASK, the value at that address is used as the mask, subject to the following conventions: o You must use parentheses around the address expression. o The number of mask elements limits the number of register or array elements that you can examine. o If the mask address expression denotes a Boolean array, its values are used as the mask, in the same basic way that VMR is used in the default case. o If the mask address expression denotes a non-Boolean array, the least significant bit value of each array element is used as the mask for the corresponding element of the register or target array. o If the mask address expression denotes a Boolean scalar type, its value is used as the mask for the first element of the register or target array. No other elements are examined. o If the mask address expression denotes any other type, its least significant bit value is used as the mask for the first element of the register or target array. No other elements are examined. o For a multi-element mask, the lowest specified element of the mask is applied to the lowest specified element of the register or target array. /TYPE /TYPE=(name) Interprets and displays each examined entity according to the type specified by name (which must be the name of a variable or data type declared in the program). This enables you to specify a user-declared type. You must use parentheses around the type expression. /VARIANT /VARIANT=variant-selector address-expression /VARIANT=(variant-selector,...) address-expression Enables the debugger to display the correct item when it encounters an anonymous variant. In a C program, a union contains members, only one of which is valid at any one time. When displaying a union, the debugger does not know which member is currently valid. In a PASCAL program, a record with a variant part contains variants, only one of which is valid at any one time. When displaying a record with an anonymous variant part, the debugger does not know which variant is currently valid, and displays all variants by default. You can use the /VARIANT qualifier of the EXAMINE command to select which member of a union (C) or anonymous variant (PASCAL) to display. /VMR (VAX only) Applies only to VAX vectorized programs. Displays the Vector Mask Register. /WCHAR_T /WCHAR_T[:n] Interprets and displays each examined entity as a multibyte file code sequence of length n longwords (n characters). The default is 1 longword. When converting the examined string, the debugger uses the locale database of the process in which the debugger runs. The default is C locale. /WORD Displays each examined entity in the word integer type (length 2 bytes). /X_FLOAT (Alpha only) Displays each examined entity in the IEEE X_floating type (length 16 bytes). 3 Description The EXAMINE command displays the entity at the location denoted by an address expression. You can use the command to display the contents of any memory location or register that is accessible in your program. For high-level languages, the command is used mostly to obtain the current value of a variable (an integer, real, string, array, record, and so on). If you are debugging optimized code on Alpha systems, the EXAMINE command displays the definition points at which a split-lifetime variable could have received its value. Split-lifetime variables are discussed in OpenVMS Debugger Manual. By default, the EXAMINE command displays up to five definition points. With the /DEFINITIONS qualifier, you can specify the number of definition points. The debugger recognizes the compiler-generated types associated with symbolic address expressions (symbolic names declared in your program). Symbolic address expressions include the following entities: o Variable names. When specifying a variable with the EXAMINE command, use the same syntax that is used in the source code. o Routine names, labels, and line numbers. These are associated with instructions. You can examine instructions using the same techniques as when examining variables. In general, when you enter an EXAMINE command, the debugger evaluates the address expression specified to yield a program location. The debugger then displays the value stored at that location as follows: o If the location has a symbolic name, the debugger formats the value according to the compiler-generated type associated with that symbol (that is, as a variable of a particular type or as an instruction). o If the location does not have a symbolic name (and, therefore, no associated compiler-generated type) the debugger formats the value in the type longword integer by default. This means that, by default, the EXAMINE command displays the contents of these locations as longword (4-byte) integer values. For information specific to vector registers (VAX only) and vector instructions (VAX only), see the /TMASK, /FMASK, /VMR, and /OPERANDS qualifiers. 3 Description,_Continued... There are several ways of changing the type associated with a program location so that you can display the data at that location in another data format: o To change the default type for all locations that do not have a symbolic name, you can specify a new type with the SET TYPE command. o To change the default type for all locations (both those that do and do not have a symbolic name), you can specify a new type with the SET TYPE/OVERRIDE command. o To override the type currently associated with a particular location for the duration of a single EXAMINE command, you can specify a new type by using a type qualifier (/ASCII:n, /BYTE, /TYPE=(name), and so on). Most qualifiers for the EXAMINE command are type qualifiers. The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, which have a default radix of hexadecimal. The EXAMINE command has four radix qualifiers (/BINARY, /DECIMAL, /HEXADECIMAL, /OCTAL) that enable you to display data in another radix. You can also use the SET RADIX and SET RADIX/OVERRIDE commands to change the default radix. In addition to the type and radix qualifiers, the EXAMINE command has qualifiers for other purposes: o The /SOURCE qualifier enables you to identify the line of source code corresponding to a line number, routine name, label, or any other address expression that is associated with an instruction rather than data. o The /[NO]LINE and /[NO]SYMBOLIC qualifiers enable you to control the symbolization of address expressions. The EXAMINE command sets the current entity built-in symbols %CURLOC and period (.) to the location denoted by the address expression specified. Logical predecessors (%PREVLOC or the circumflex character (^)) and successors (%NEXTLOC) are based on the value of the current entity. The /VARIANT qualifier enables the debugger to display the correct item when it encounters an anonymous variant. In a C program, a union contains members, only one of which is valid at any one time. When displaying a union, the debugger does not know which member is currently valid. In a PASCAL program, a record with a variant part contains variants, only one of which is valid at any one time. When displaying a record with an anonymous variant part, the debugger does not know which variant is currently valid, and displays all variants by default. You can use the /VARIANT qualifier of the EXAMINE command to select which member of a union (C program) or anonymous variant (PASCAL program) to display. The format is as follows: DBG> EXAMINE /VARIANT=variant-selector address-expression DBG> EXAMINE /VARIANT=(variant-selector,...) address-expression The variant selector variant-selector specifies a name, a discriminant (PASCAL only), or a position; that is, one of the following: o NAME = name-string o DISCRIMINANT = expression o POSITION = expression The /VARIANT qualifier takes a list of zero or more variant selectors. /VARIANT without any variant selectors is the default: the first variant of all anonymous variant lists will be displayed. Each variant selector specifies either the name, the discriminant, or the position of the variant to be displayed. The debugger uses the variant selector as follows: 1. If the debugger encounters an anonymous variable list while displaying address-expression, the debugger uses the variant selector to choose which variant to display. 2. Each time the debugger encounters an anonymous variant list, it attempts to use the next variant selector to choose which variant to display. If the variant selector matches one of the variants of the variant list (union), the debugger displays that variant. 3. The debugger walks the structure top-to-bottom, depth first, so that children are encountered before siblings. 4. If the debugger encounters an anonymous variant list and does not have a variant selector to match it with, the debugger displays the first variant. 5. If the variant selector does not match any of the variants of an anonymous variant list, the debugger displays a single line to indicate that. This is similar to what the debugger does if the discriminant value fails to match any of the variants in a discriminated variant list. . For example: [Variant Record omitted - null or illegal Tag Value: 3] A name specifies a name string. A name matches a variant if that variant contains a field with the name specified by name. A discriminant specifies a language expression that must be type compatible with the tag type of the variant part it is meant to match. The discriminant expression matches a variant if it evaluates to a value in the variant's case-label list. Discriminants apply only to Pascal programs, because C and C++ unions do not have discriminants. A positional-selector specifies a language expression, which should evaluate to a integer between 1 and N, where N is the number of variants in a variant list. A positional-selector that evaluates to I specifies that the Ith variant is to be displayed. You can use asterisk (*) as a wildcard, which matches all variants of an anonymous variant list. Each of these variant selectors can be used to match all variants. In particular, each of the following variant selectors indicates that all of the variants of the first anonymous variant list are to be displayed. /VAR=D=* /VAR=N=* /VAR=P=* The variant selectors can themselves contain a list of selectors. For example, the following commands all mean the same thing. EXAMINE /VARIANT=(DIS=3,DIS=1,DIS=54) x EXAMINE /VARIANT=(DIS=(3,1,54)) x EXAMINE /VARIANT=DIS=(3,1,54) x You can specify a a single discriminant or position value without parentheses if the value is a simple decimal integer. To use a general expression to specify the value, you enclose the expression in parentheses. In the following list of commands, the first four are legal while the last three are not. EXAMINE /VARIANT=POS=3 EXAMINE /VARIANT=POS=(3) ! parentheses unnecessary EXAMINE /VARIANT=(POS=(3)) ! parentheses unnecessary EXAMINE /VARIANT=(POS=3) ! parentheses unnecessary EXAMINE /VARIANT=(POS=foo) ! parentheses necessary EXAMINE /VARIANT=POS=(foo) ! parentheses necessary EXAMINE /VARIANT=(POS=3-1) ! parentheses necessary Related Commands: CANCEL TYPE/OVERRIDE DEPOSIT DUMP EVALUATE SET MODE [NO]OPERANDS SET MODE [NO]SYMBOLIC (SET,SHOW,CANCEL) RADIX (SET,SHOW) TYPE 3 Examples 1.DBG> EXAMINE COUNT SUB2\COUNT: 27 DBG> This command displays the value of the integer variable COUNT in module SUB2. 2.DBG> EXAMINE PART_NUMBER INVENTORY\PART_NUMBER: "LP-3592.6-84" DBG> This command displays the value of the string variable PART_ NUMBER. 3.DBG> EXAMINE SUB1\ARR3 SUB1\ARR3 (1,1): 27.01000 (1,2): 31.01000 (1,3): 12.48000 (2,1): 15.08000 (2,2): 22.30000 (2,3): 18.73000 DBG> This command displays the value of all elements in array ARR3 in module SUB1. ARR3 is a 2 by 3 element array of real numbers. 4.DBG> EXAMINE SUB1\ARR3(2,1:3) SUB1\ARR3 (2,1): 15.08000 (2,2): 22.30000 (2,3): 18.73000 DBG> This command displays the value of the elements in a slice of array SUB1\ARR3. The slice includes "columns" 1 to 3 of "row" 2. 5.DBG> EXAMINE VALVES.INTAKE.STATUS MONITOR\VALVES.INTAKE.STATUS: OFF DBG> This command displays the value of the nested record component VALVES.INTAKE.STATUS in module MONITOR. 6.DBG> EXAMINE/SOURCE SWAP module MAIN 47: procedure SWAP(X,Y: in out INTEGER) is DBG> This command displays the source line in which routine SWAP is declared (the location of routine SWAP). 7.DBG> EXAMINE /VARIANT=(NAME=m,DIS=4,POS=1) x This command specifies that, for the first anonymous variant list encountered, display the variant part containing a field named "m", for the second anonymous variant list, display the part with the discriminant value 4, and, for the third anonymous variant list, display the first variant part. 2 EXIT Ends a debugging session, or terminates one or more processes of a multiprocess program, 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 EXIT [process-spec[, . . . ]] 3 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 all processes. 3 Description The EXIT command is one of the four debugger commands that can be used to execute your program (the others are CALL, GO, and STEP). Ending a Debugging Session: To end a debugging session, enter the EXIT command at the debugger prompt without specifying any parameters. This causes orderly termination of the session: the program's application- declared exit handlers (if any) are executed, the debugger exit handler is executed (closing log files, restoring the screen and keypad states, and so on), and control is returned to the command interpreter. You cannot then continue to debug your program by entering the DCL command DEBUG or CONTINUE (you must restart the debugger). Because EXIT runs any application-declared exit handlers, you can set breakpoints in such exit handlers, and the breakpoints are triggered upon typing EXIT. Thus, you can use EXIT to debug your exit handlers. To end a debugging session without running any application- declared exit handlers, use the QUIT command instead of EXIT. Using the EXIT Command in Command Procedures and DO Clauses: When the debugger executes an EXIT 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 an EXIT command (without any parameters) in a DO clause, it ignores any remaining commands in that clause and displays its prompt. 3 Description,_Continued... Terminating Specified Processes: If you are debugging a multiprocess program you can use the EXIT command to terminate specified processes without ending the debugging session. The same techniques and behavior apply, whether you enter the EXIT command at the prompt or use it within a command procedure or DO clause. To terminate one or more processes, enter the EXIT command, specifying these processes as parameters. This causes orderly termination of the images in these processes, executing any application-declared exit handlers associated with these images. Subsequently, the specified processes are no longer identified in a SHOW PROCESS/ALL display. If any specified processes were on hold as the result of a SET PROCESS command, the hold condition is ignored. When the specified processes begin to exit, any unspecified process that is not on hold begins execution. After execution is started, the way in which it continues depends on whether you entered a SET MODE [NO]INTERRUPT command. By default (SET MODE INTERRUPT), execution continues until it is suspended in any process. At that point, execution is interrupted in any other processes that were executing images, and the debugger prompts for input. To terminate specified processes without running any application- declared exit handlers or otherwise starting execution, use the QUIT command instead of EXIT. Related commands: DISCONNECT @ (Execute Procedure) Ctrl/C Ctrl/Y Ctrl/Z QUIT RERUN RUN SET ABORT_KEY SET MODE [NO]INTERRUPT SET PROCESS 3 Examples 1.DBG> EXIT $ This command ends the debugging session and returns you to DCL level. 2.all> EXIT %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. 2 EXITLOOP Exits one or more enclosing FOR, REPEAT, or WHILE loops. Format EXITLOOP [integer] 3 Parameters integer A decimal integer that specifies the number of nested loops to exit from. The default is 1. 3 Description Use the EXITLOOP command to exit one or more enclosing FOR, REPEAT, or WHILE loops. Related commands: FOR REPEAT WHILE 3 Example DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN EXITLOOP) The WHILE 1 command generates an endless loop that executes a STEP command with each iteration. After each STEP, the value of X is tested. If X is greater than 3, the EXITLOOP command terminates the loop (Fortran example). 2 EXPAND Expands or contracts the window associated with a screen display. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format EXPAND [display-name[, . . . ]] 3 Parameters display-name Specifies a display to be expanded or contracted. You can specify any of the following entities: o A predefined display: SRC OUT PROMPT INST REG FREG (Alpha only) IREG o A display previously created with the DISPLAY command o 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. 3 Qualifiers /DOWN /DOWN[:n] Moves the bottom border of the display down by n lines (if n is positive) or up by n lines (if n is negative). If you omit n, the border is moved down by 1 line. /LEFT /LEFT[:n] Moves the left border of the display to the left by n lines (if n is positive) or to the right by n lines (if n is negative). If you omit n, the border is moved to the left by 1 line. /RIGHT /RIGHT[:n] Moves the right border of the display to the right by n lines (if n is positive) or to the left by n lines (if n is negative). If you omit n, the border is moved to the right by 1 line. /UP /UP[:n] Moves the top border of the display up by n lines (if n is positive) or down by n lines (if n is negative). If you omit n, the border is moved up by 1 line. 3 Description You must specify at least one qualifier. The EXPAND command moves one or more display-window borders according to the qualifiers specified (/UP:[n], /DOWN:[n], RIGHT:[n], /LEFT:[n]). The EXPAND command does not affect the order of a display on the display pasteboard. Depending on the relative order of displays, the EXPAND command can cause the specified display to hide or uncover another display or be hidden by another display, partially or totally. Except for the PROMPT display, any display can be contracted to the point where it disappears (at which point it is marked as "removed"). It can then be expanded from that point. Contracting a display to the point where it disappears causes it to lose any attributes that were selected for it. The PROMPT display cannot be contracted or expanded horizontally but can be contracted vertically to a height of 2 lines. A window border can be expanded only up to the edge of the screen. The left and top window borders cannot be expanded beyond the left and top edges of the display, respectively. The right border can be expanded up to 255 columns from the left display edge. The bottom border of a source or instruction display can be expanded down only to the bottom edge of the display (to the end of the source module or routine's instructions). A register display cannot be expanded beyond its full size. For a list of the key definitions associated with the EXPAND command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions. Related commands: DISPLAY MOVE SELECT/SCROLL (SET,SHOW) TERMINAL 3 Examples 1.DBG> EXPAND/RIGHT:6 This command moves the right border of the current scrolling display to the right by 6 columns. 2.DBG> EXPAND/UP/RIGHT:-12 OUT2 This command moves the top border of display OUT2 up by 1 line, and the right border to the left by 12 columns. 3.DBG> EXPAND/DOWN:99 SRC This command moves the bottom border of display SRC down to the bottom edge of the screen. 2 EXTRACT Saves the contents of screen displays in a file or creates a debugger command procedure with all of the commands necessary to re-create the current screen state later on. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format EXTRACT [display-name[, . . . ]] [file-spec] 3 Parameters display-name Specifies a display to be extracted. You can specify any of the following entities: o A predefined display: SRC OUT PROMPT INST REG FREG (Alpha only) IREG o A display previously created with the DISPLAY command You can use the asterisk (*) wildcard character in a display name. Do not specify a display name with the /ALL qualifier. file-spec Specifies the file to which the information is written. You can specify a logical name. If you specify /SCREEN_LAYOUT, the default specification for the file is SYS$DISK:[]DBGSCREEN.COM. Otherwise, the default specification is SYS$DISK:[]DEBUG.TXT. 3 Qualifiers /ALL Extracts all displays. Do not specify /SCREEN_LAYOUT with this qualifier. /APPEND Appends the information at the end of the file, rather than creating a new file. By default, a new file is created. Do not specify /SCREEN_LAYOUT with this qualifier. /SCREEN_LAYOUT Writes a file that contains the debugger commands describing the current state of the screen. This information includes the screen height and width, message wrap setting, and the position, display kind, and display attributes of every existing display. This file can then be executed with the execute procedure (@) command to reconstruct the screen at a later time. Do not specify /ALL with this qualifier. 3 Description When you use the EXTRACT command to save the contents of a display into a file, only those lines that are currently stored in the display's memory buffer (as determined by the /SIZE qualifier on the DISPLAY command) are written to the file. You cannot extract the PROMPT display into a file. Related commands: DISPLAY SAVE 3 Examples 1.DBG> EXTRACT SRC This command writes all the lines in display SRC into file SYS$DISK:[]DEBUG.TXT. 2.DBG> EXTRACT/APPEND OUT [JONES.WORK]MYFILE This command appends all the lines in display OUT to the end of file [JONES.WORK]MYFILE.TXT. 3.DBG> EXTRACT/SCREEN_LAYOUT This command writes the debugger commands needed to reconstruct the screen into file SYS$DISK:[]DBGSCREEN.COM. 2 FOR Executes a sequence of commands while incrementing a variable a specified number of times. Format FOR name=expression1 TO expression2 [BY expression3] DO (command[; . . . ]) 3 Parameters name Specifies the name of a count variable. expression1 Specifies an integer or enumeration type value. The expression1 and expression2 parameters must be of the same type. expression2 Specifies an integer or enumeration type value. The expression1 and expression2 parameters must be of the same type. expression3 Specifies an integer. command Specifies a debugger command. If you specify more than one command, you must 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 behavior of the FOR command depends on the value of the expression3 parameter, as detailed in the following table: expression3Action of the FOR Command Positive name parameter is incremented from the value of expression1 by the value of expression3 until it is greater than the value of expression2 Negative name is decremented from the value of expression1 by the value of expression3 until it is less than the value of expression2 0 The debugger returns an error message Omitted The debugger assumes it to have the value +1 Related commands: EXITLOOP REPEAT WHILE 3 Examples 1.DBG> FOR I = 10 TO 1 BY -1 DO (EXAMINE A(I)) This command examines an array backwards. 2.DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0) This command initializes an array to zero. 2 GO Starts or resumes program execution. Format GO [address-expression] 3 Parameters address-expression Specifies that program execution resume at the location denoted by the address expression. If you do not specify an address expression, execution resumes at the point of suspension or, in the case of debugger startup, at the image transfer address. 3 Description The GO command starts program execution or resumes execution from the point at which it is currently suspended. GO is one of the four debugger commands that can be used to execute your program (the others are CALL, EXIT, and STEP). Specifying an address expression with the GO command can produce unexpected results because it alters the normal control flow of your program. For example, during a debugging session you can restart execution at the beginning of the program by entering the GO %LINE 1 command. However, because the program has executed, the contents of some variables might now be initialized differently from when you first ran the program. If an exception breakpoint is triggered (resulting from a SET BREAK/EXCEPTION or a STEP/EXCEPTION command), execution is suspended before any application-declared condition handler is invoked. If you then resume execution with the GO command, the behavior is as follows: o Entering a GO command to resume execution from the current location causes the debugger to resignal the exception. This enables you to observe which application-declared handler, if any, next handles the exception. o Entering a GO command to resume execution from a location other than the current location inhibits the execution of any application-declared handler for that exception. If you are debugging a multiprocess program, the GO command is executed in the context of the current process set. In addition, when debugging a multiprocess program, the way in which execution continues in your process depends on whether you entered a SET MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By default (SET MODE NOINTERRUPT), when one process stops, the debugger takes no action with regard to the other processes. Also by default (SET MODE WAIT), the debugger waits until all process in the current process set have stopped before prompting for a new command. Related commands: CALL EXIT RERUN SET BREAK SET MODE [NO]INTERRUPT SET MODE [NO]WAIT SET PROCESS SET STEP SET TRACE SET WATCH STEP WAIT 3 Examples 1.DBG> GO . . . 'Normal successful completion' DBG> This command starts program execution, which then completes successfully. 2.DBG> SET BREAK RESTORE DBG> GO ! start execution . . . break at routine INVENTORY\RESTORE 137: procedure RESTORE; DBG> GO ! resume execution . . . In this example, the SET BREAK command sets a breakpoint on routine RESTORE. The first GO command starts program execution, which is then suspended at the breakpoint on routine RESTORE. The second GO command resumes execution from the breakpoint. 3.DBG> GO %LINE 42 This command resumes program execution at line 42 of the module in which execution is currently suspended. 2 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 [ . . . ]] 3 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. 3 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, see help on 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. 3 Example DBG> HELP GO This command displays help for the GO command. 2 IF Executes a sequence of commands if a language expression (Boolean expression) is evaluated as true. Format IF Boolean-expression THEN (command[; . . . ]) [ELSE (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, you must separate the commands with semicolons (;). 3 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 3 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. 2 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 3 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 context-sensitive Help). To specify an individual array element, array slice, or record component, follow the syntax of the current language. 3 Qualifiers /ASCIC /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 /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 /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 /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 /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 /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 /WORD /SHORT Displays each monitored entity in the word integer type (length 2 bytes). 3 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 context-sensitive Help. Related commands: DEPOSIT EVALUATE EXAMINE SET WATCH 3 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. 2 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[, . . . ]] 3 Parameters display-name Specifies a display to be moved. You can specify any of the following entities: o A predefined display: SRC OUT PROMPT INST REG FREG (Alpha only) IREG o A display previously created with the DISPLAY command o 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. 3 Qualifiers /DOWN /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 /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 /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 /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. 3 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 3 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. 2 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 3 Parameters command A POSIX Threads debugger command. 3 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: o SET EVENT FACILITY o SET TASK|THREAD o SHOW EVENT FACILITY o SHOW TASK|THREAD 3 Example DBG_1> PTHREAD HELP conditions [-afhwqrs] [- N ] [id]...: list condition variables exit: exit from DECthreads debugger help [topic]: display help information keys [-v] [-N ] [id]...: list keys mutexes [-afhilqrs] [-N ] [id]...: list mutexes quit: exit from DECthreads debugger show [-csuv]: show stuff squeue [-c ] [-fhq] [-t ] [a]: format queue stacks [-fs] [sp]...: list stacks system: show system information threads [-1] [-N ] [-abcdfhklmnor] [-s ] [- tz] [id]...: list threads tset [-chna] [-s ] : set state of thread versions: display versions write : write a string All keywords may be abbreviated: if the abbreviation is ambiguous, the first match will be used. For more help, type 'help '. 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. 2 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[, . . . ]] 3 Parameters process-spec (Kept debugger only.) 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 all processes. 3 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 3 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. 2 REBOOT (Alpha only) When debugging Alpha operating system code with the OpenVMS Alpha System-Code Debugger, reboots the target machine running the Alpha operating system code and executes (or reexecutes) your system program. The REBOOT command, in other words, is similar to the RUN or RERUN commands when you are within the OpenVMS Alpha System-Code Debugger environment. (The OpenVMS Alpha System-Code Debugger is a kernel debugger that is activated through the OpenVMS Debugger.) Before you issue this command, you must have completed the instructions described in the Writing OpenVMS Alpha Device Drivers in C manual. These instructions include the creation of an Alpha device driver, the setup commands activating the OpenVMS Alpha System-Code Debugger, and the CONNECT command that allows you to debug. You must also have started the OpenVMS Debugger with the DEBUG/KEEP command. Format REBOOT 3 Description For complete information on using the OpenVMS Alpha System- Code Debugger, see the Writing OpenVMS Alpha Device Drivers in C manual. Related commands: CONNECT DISCONNECT 3 Example DBG> REBOOT This command reboots the target machine where you will be debugging the OpenVMS Alpha operating system and reruns your program. 2 REPEAT Executes a sequence of commands a specified number of times. Format REPEAT language-expression DO (command[; . . . ]) 3 Parameters language-expression Denotes any expression in the currently set language that evaluates to a positive integer. command Specifies a debugger command. If you specify more than one command, you must 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 REPEAT command is a simple form of the FOR command. The REPEAT command executes a sequence of commands repetitively a specified number of times, without providing the options for establishing count parameters that the FOR command does. Related commands: EXITLOOP FOR WHILE 3 Example DBG> REPEAT 10 DO (EXAMINE Y; STEP) This command line sets up a loop that issues a sequence of two commands (EXAMINE Y, then STEP) 10 times. 2 RERUN Reruns the program currently under debugger control. NOTE Requires that you started your debugging session with the DCL command DEBUG/KEEP and then executed the debugger RUN command. If you began your session with the DCL command RUN filespec instead, you cannot use the debugger RERUN command. Format RERUN 3 Qualifiers /ARGUMENTS /ARGUMENTS="arg-list" Specifies a list of arguments. If you specify a quoted string, you might have to add quotation marks because the debugger strips them when parsing the string. If you do not specify arguments, any arguments that were specified previously when running or rerunning that program are applied, by default. /HEAP_ANALYZER (Applies only to workstation users.) Invokes the Heap Analyzer, a debugger feature that helps you understand how memory is used by your application. For more information on using the Heap Analyzer, see the OpenVMS Debugger Manual. /SAVE /SAVE (default) /NOSAVE Controls whether to save the current state (activated or deactivated) of all breakpoints, tracepoints, and static watchpoints for the next run of the program. The /SAVE qualifier specifies that their state is saved, and /NOSAVE specifies that their state is not saved. /SAVE may or may not save the state of a particular nonstatic watchpoint depending on the scope of the variable being watched relative to the main program unit (where execution restarts). 3 Description If you invoked the debugger with the DCL command DEBUG/KEEP and subsequently used the debugger RUN command to begin debugging your program, you can then use the RERUN command to rerun the program currently under debugger control. The RERUN command terminates the image you were debugging and then restarts that image under debugger control. Execution is paused at the start of the main program unit, as if you had used the debugger RUN command or the DCL command RUN/DEBUG. The RERUN command uses the same version of the image that is currently under debugger control. To debug a different version of that program (or a different program) from the same debugging session, use the RUN command. Related commands: RUN (debugger command) RUN (DCL command) (ACTIVATE,DEACTIVATE) BREAK (ACTIVATE,DEACTIVATE) TRACE (ACTIVATE,DEACTIVATE) WATCH 3 Examples 1.DBG> RERUN This command reruns the current program. By default, the debugger saves the current state of all breakpoints, tracepoints, and static watchpoints (activated or deactivated). 2.DBG> RERUN/NOSAVE This command reruns the current program without saving the current state of breakpoints, tracepoints, and watchpoints-in effect, the same as using the RUN command and specifying the image name. 3.DBG> RERUN/ARGUMENTS="fee fii foo fum" This command reruns the current program with new arguments. 2 RUN Runs a program under debugger control. NOTE Requires that you started your debugging session with the DCL command DEBUG/KEEP. If you began your session with the DCL command RUN filespec instead, you cannot use the debugger RUN command. Format RUN [program-image] 3 Parameters program-image Specifies the executable image of the program to be debugged. Do not specify an image if you use the /COMMAND=cmd-symbol qualifier. 3 Qualifiers /ARGUMENTS /ARGUMENTS="arg-list" Specifies a list of arguments. If you specify a quoted string, you might have to add quotation marks because the debugger strips quotes when parsing the string. /COMMAND /COMMAND="cmd-symbol" Specifies a DCL foreign command for running the program. Do not use this qualifier if you specify a program-image parameter. Do not specify a DCL command or any other command definition that was created with the SET COMMAND command. /HEAP_ANALYZER (Applies only to workstation users.) Invokes the Heap Analyzer, a debugger feature that helps you understand how memory is used by your application. For more information on using the Heap Analyzer, see the OpenVMS Debugger Manual. /NEW Runs a new program under debugger control without terminating any programs already running. 3 Description If you invoked the debugger with the DCL command DEBUG/KEEP, you can use the debugger RUN command at any time during a debugging session to start a program under debugger control. If you are in the midst of debugging a program when you issue the RUN command, that program will first be terminated unless you use the /NEW qualifier. To run the same program again (that is, the same version of the program that is currently under debugger control), use the RERUN command. RERUN enables you to save the current state (activated or deactivated) of any breakpoints, tracepoints, and static watchpoints. Note the following restrictions about the debugger RUN command: o You can use the RUN command only if you started the debugger with the DCL command DEBUG/KEEP. o You cannot use the RUN command to connect the debugger to a running program. See the description of Ctrl/Y. o You cannot run a program under debugger control over a DECnet link. Both the image to be debugged and the debugger must reside on the same node. Related commands: RERUN RUN (DCL command) Ctrl/Y-DEBUG (DCL command) DEBUG (DCL command) 3 Examples 1.DBG> RUN EIGHTQUEENS Language: C, Module: EIGHTQUEENS This command brings the program EIGHTQUEENS under debugger control. 2.$ RUNPROG == "$ DISK3:[SMITH]MYPROG.EXE" $ DEBUG/KEEP . . . DBG> RUN/COMMAND="RUNPROG"/ARGUMENTS="X Y Z" The first line of this example creates a command symbol RUNPROG (at DCL level) to run an image named MYPROG.EXE. The second line starts the debugger. The debugger RUN command then brings the image MYPROG.EXE under debugger control. The /COMMAND qualifier specifies the command symbol previously created (in this case RUNPROG), and the /ARGUMENTS qualifier passes the arguments X Y Z to the image. 3.DBG> RUN/ARGUMENTS="X Y Z" MYPROG This command brings the program MYPROG.EXE under debugger control and passes the arguments X Y Z. 2 SAVE Preserves the contents of an existing screen display in a new display. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SAVE old-display AS new-display [, . . . ] 3 Parameters old-display Specifies the display whose contents are saved. You can specify any of the following entities: o A predefined display: SRC OUT PROMPT INST REG FREG (Alpha only) IREG o A display previously created with the DISPLAY command o A display built-in symbol: %CURDISP %CURSCROLL %NEXTDISP %NEXTINST %NEXTOUTPUT %NEXTSCROLL %NEXTSOURCE new-display Specifies the name of the new display to be created. This new display then receives the contents of the old-disp display. 3 Description The SAVE command enables you to save a snapshot copy of an existing display in a new display for later reference. The new display is created with the same text contents as the existing display. In general, the new display is given all the attributes or characteristics of the old display except that it is removed from the screen and is never automatically updated. You can later recall the saved display to the terminal screen with the DISPLAY command. When you use the SAVE command, only those lines that are currently stored in the display's memory buffer (as determined by the /SIZE qualifier on the DISPLAY command) are stored in the saved display. However, in the case of a saved source or instruction display, you can also see any other source lines associated with that module or any other instructions associated with that routine (by scrolling the saved display). You cannot save the PROMPT display. Related commands: DISPLAY EXITLOOP 3 Example DBG> SAVE REG AS OLDREG This command saves the contents of the display named REG into the newly created display named OLDREG. 2 SCROLL Scrolls a screen display to make other parts of the text visible through the display window. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SCROLL [display-name] 3 Parameters display-name Specifies a display to be scrolled. You can specify any of the following entities: o A predefined display: SRC OUT PROMPT INST REG FREG (Alpha only) IREG o A display previously created with the DISPLAY command o 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. 3 Qualifiers /BOTTOM Scrolls down to the bottom of the display's text. /DOWN /DOWN:[n] Scrolls down over the display's text by n lines to reveal text further down in the display. If you omit n, the display is scrolled by approximately 3/4 of its window height. /LEFT /LEFT:[n] Scrolls left over the display's text by n columns to reveal text beyond the left window border. You cannot scroll past column 1. If you omit n, the display is scrolled left by 8 columns. /RIGHT /RIGHT[:n] Scrolls right over the display's text by n columns to reveal text beyond the right window border. You cannot scroll past column 255. If you omit n, the display is scrolled right by 8 columns. /TOP Scrolls up to the top of the display's text. /UP /UP[:n] Scrolls up over the display's text by n lines to reveal text further up in the display. If you omit n, the display is scrolled by approximately 3/4 of its window height. 3 Description The SCROLL command moves a display up, down, right, or left relative to its window so that various parts of the display text can be made visible through the window. Use the SELECT/SCROLL command to select the target display for the SCROLL command (the current scrolling display). For a list of the key definitions associated with the SCROLL command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions. Related command: SELECT. 3 Examples 1.DBG> SCROLL/LEFT This command scrolls the current scrolling display to the left by 8 columns. 2.DBG> SCROLL/UP:4 ALPHA This command scrolls display ALPHA 4 lines up. 2 SEARCH Searches the source code for a specified string and displays source lines that contain an occurrence of the string. Format SEARCH [range] [string] 3 Parameters range Specifies a program region to be searched. Use any of the following formats: mod-name Searches the specified module from line 0 to the end of the module. mod-name\line-num Searches the specified module from the specified line number to the end of the module. mod-name\line- Searches the specified module from the line num:line-num number specified on the left of the colon to the line number specified on the right. line-num Uses the current scope to find a module and searches that module from the specified line number to the end of the module. The current scope is established by a previous SET SCOPE command, or the PC scope if you did not enter a SET SCOPE command. If you specify a scope search list with the SET SCOPE command, the debugger searches only the module associated with the first named scope. line-num:line-num Uses the current scope to find a module and searches that module from the line number specified on the left of the colon to the line number specified on the right. The current scope is established by a previous SET SCOPE command, or the PC scope if you did not enter a SET SCOPE command. If you specify a scope search list with the SET SCOPE command, the debugger searches only the module associated with the first named scope. null (no entry) Searches the same module as that from which a source line was most recently displayed (as a result of a TYPE, EXAMINE/SOURCE, or SEARCH command, for example), beginning at the first line following the line most recently displayed and continuing to the end of the module. string Specifies the source code characters for which to search. If you do not specify a string, the string specified in the last SEARCH command, if any, is used. You must enclose the string in quotation marks (") or apostrophes (') under the following conditions: o The string has any leading or ending space or tab characters o The string contains an embedded semicolon o The range parameter is null If the string is enclosed in quotation marks, use two consecutive quotation marks ("") to indicate an enclosed quotation mark. If the string is enclosed in apostrophes, use two consecutive apostrophes ('') to indicate an enclosed apostrophe. 3 Qualifiers /ALL Specifies that the debugger search for all occurrences of the string in the specified range and display every line containing an occurrence of the string. /IDENTIFIER Specifies that the debugger 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. /NEXT (Default) Specifies that the debugger search for the next occurrence of the string in the specified range and display only the line containing this occurrence. /STRING (Default) Specifies that the debugger search for and display the string as specified, and not interpret the context surrounding an occurrence of the string, as it does in the case of /IDENTIFIER. 3 Description The SEARCH command displays the lines of source code that contain an occurrence of a specified string. If you specify a module name with the SEARCH command, that module must be set. To determine whether a particular module is set, use the SHOW MODULE command, then use the SET MODULE command, if necessary. Qualifiers for the SEARCH command determine whether the debugger: (1) searches for all occurrences (/ALL) of the string 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). If you plan to enter several SEARCH commands with the same qualifier, you can first use the SET SEARCH command to establish a new default qualifier (for example, SET SEARCH ALL makes the SEARCH command behave like SEARCH/ALL). Then you do not have to use that qualifier with the SEARCH command. You can override the current default qualifiers for the duration of a single SEARCH command by specifying other qualifiers. Related commands: (SET,SHOW) LANGUAGE (SET,SHOW) MODULE (SET,SHOW) SCOPE (SET,SHOW) SEARCH 3 Examples 1.DBG> SEARCH/STRING/ALL 40:50 D module COBOLTEST 40: 02 D2N COMP-2 VALUE -234560000000. 41: 02 D COMP-2 VALUE 222222.33. 42: 02 DN COMP-2 VALUE -222222.333333. 47: 02 DR0 COMP-2 VALUE 0.1. 48: 02 DR5 COMP-2 VALUE 0.000001. 49: 02 DR10 COMP-2 VALUE 0.00000000001. 50: 02 DR15 COMP-2 VALUE 0.0000000000000001. DBG> This command searches for all occurrences of the letter D in lines 40 to 50 of the module COBOLTEST, the module that is in the current scope. 2.DBG> SEARCH/IDENTIFIER/ALL 40:50 D module COBOLTEST 41: 02 D COMP-2 VALUE 222222.33. DBG> This command searches for all occurrences of the letter D in lines 40 to 50 of the module COBOLTEST. The debugger displays the only line where the letter D (the search string) is not bounded on either side by a character that can be part of an identifier in the current language. 3.DBG> SEARCH/NEXT 40:50 D module COBOLTEST 40: 02 D2N COMP-2 VALUE -234560000000. DBG> This command searches for the next occurrence of the letter D in lines 40 to 50 of the module COBOLTEST. 4.DBG> SEARCH/NEXT module COBOLTEST 41: 02 D COMP-2 VALUE 222222.33. DBG> This command searches for the next occurrence of the letter D. The debugger assumes D to be the search string because D was the last one entered and no other search string was specified. 5.DBG> SEARCH 43 D module COBOLTEST 47: 02 DR0 COMP-2 VALUE 0.1. DBG> This command searches for the next occurrence (by default) of the letter D, starting with line 43. 2 SDA Invokes the System Dump Analyzer (SDA) from within the OpenVMS debugger without terminating a debugger session. Format SDA [sda-command] 3 Parameters sda-command One SDA command to be executed before returning control to the OpenVMS debugger. 3 Description The SDA command allows you to use the System Dump Analyzer (SDA) within the debugger for the following tasks: o o System code debugging with the System Code Debugger (SCD) (Alpha only) o System dump analysis with the System Dump Debugger (SDD) (Alpha only) o Process dump analysis with the System Dump Analyzer (SDA) (Alpha only) This gives you access to all SDA commands within the debugging session. When you exit SDA, you return to the same debugging session. Note that you do not have access to debugger commands within the SDA session. NOTE The SDA command is not available when debugging user-mode programs. Related commands ANALYZE/CRASH_DUMP ANALYZE/PROCESS_DUMP CONNECT %NODE 3 Example DBG> SDA OpenVMS (TM) Alpha process dump analyzer SDA> .. . . SDA> EXIT DBG> This example opens an SDA session within the OpenVMS debugger, performs some analysis, closes the SDA session and returns control to the debugger. DBG> SDA SHOW PROCESS . . DBG> This example show the execution of a single SDA command from within the debugger, followed by a return of control to the debugger. 2 SELECT Selects a screen display as the current error, input, instruction, output, program, prompt, scrolling, or source display. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SELECT [display-name] 3 Parameters display-name Specifies the display to be selected. You can specify any one of the following, with the restrictions noted in the qualifier descriptions: o A predefined display: SRC OUT PROMPT INST REG FREG (Alpha only) IREG o A display previously created with the DISPLAY command o A display built-in symbol: %CURDISP %CURSCROLL %NEXTDISP %NEXTINST %NEXTOUTPUT %NEXTSCROLL %NEXTSOURCE If you omit this parameter and do not specify a qualifier, you "unselect" the current scrolling display (no display then has the scrolling attribute). If you omit this parameter but specify a qualifier (/INPUT, /SOURCE, and so on), you unselect the current display with that attribute (see the qualifier descriptions). 3 Qualifiers /ERROR Selects the specified display as the current error display. This causes all debugger diagnostic messages to go to that display. The display specified must be either an output display or the PROMPT display. If you do not specify a display, this qualifier selects the PROMPT display current error display. By default, the PROMPT display has the error attribute. /INPUT Selects the specified display as the current input display. This causes that display to echo debugger input (which appears in the PROMPT display). The display specified must be an output display. If you do not specify a display, the current input display is unselected and debugger input is not echoed to any display (debugger input appears only in the PROMPT display). By default, no display has the input attribute. /INSTRUCTION Selects the specified display as the current instruction display. This causes the output of all EXAMINE/INSTRUCTION commands to go to that display. The display specified must be an instruction display. If you do not specify a display, the current instruction display is unselected and no display has the instruction attribute. By default, for all languages except MACRO-32, no display has the instruction attribute. If the language is set to MACRO-32, the INST display has the instruction attribute by default. /OUTPUT Selects the specified display as the current output display. This causes debugger output that is not already directed to another display to go to that display. The display specified must be either an output display or the PROMPT display. If you do not specify a display, the PROMPT display is selected as the current output display. By default, the OUT display has the output attribute. /PROGRAM Selects the specified display as the current program display. This causes the debugger to try to force program input and output to that display. Currently, only the PROMPT display can be specified. If you do not specify a display, the current program display is unselected and program input and output are no longer forced to the specified display. By default, the PROMPT display has the program attribute, except on workstations, where the program attribute is unselected. /PROMPT Selects the specified display as the current prompt display. This is where the debugger prompts for input. Currently, only the PROMPT display can be specified. Moreover, you cannot unselect the PROMPT display (the PROMPT display always has the prompt attribute). /SCROLL (Default) Selects the specified display as the current scrolling display. This is the default display for the SCROLL, MOVE, and EXPAND commands. Although any display can have the scroll attribute, you can use only the MOVE and EXPAND commands (not the SCROLL command) with the PROMPT display. If you do not specify a display, the current scrolling display is unselected and no display has the scroll attribute. By default, for all languages except MACRO-32, the SRC display has the scroll attribute. If the language is set to MACRO-32, the INST display has the scroll attribute by default. /SOURCE Selects the specified display as the current source display. This causes the output of all TYPE and EXAMINE/SOURCE commands to go to that display. The display specified must be a source display. If you do not specify a display, the current source display is unselected and no display has the source attribute. By default, for all languages except MACRO-32, the SRC display has the source attribute. If the language is set to MACRO-32, no display has the source attribute by default. 3 Description Attributes are used to select the current scrolling display and to direct various types of debugger output to particular displays. This gives you the option of mixing or isolating different types of information, such as debugger input, output, diagnostic messages, and so on in scrollable displays. Use the SELECT command with one or more qualifiers (/ERROR, /SOURCE, and so on) to assign one or more corresponding attributes to a display. By default, if you do not specify a qualifier, /SCROLL is assumed. If you use the SELECT command without specifying a display name, the attribute assignment indicated by the qualifier is canceled (unselected). To reassign display attributes, you must use another SELECT command. For more information, see the individual qualifier. For a list of the key definitions associated with the SELECT command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions. Related commands: DISPLAY EXPAND MOVE SCROLL SHOW SELECT 3 Examples 1.DBG> SELECT/SOURCE/SCROLL SRC2 This command selects display SRC2 as the current source and scrolling display. 2.DBG> SELECT/INPUT/ERROR OUT This command selects display OUT as the current input and error display. This causes debugger input, debugger output (assuming OUT is the current output display), and debugger diagnostic messages to be logged in the OUT display in the correct sequence. 3.DBG> SELECT/SOURCE This command unselects (deletes the source attribute from) the currently selected source display. The output of a TYPE or EXAMINE/SOURCE command then goes to the currently selected output display. 2 SET 3 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 Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SET ABORT_KEY = CTRL_character 4 Parameters character Specifies the key you press while holding down the Ctrl key. You can specify any alphabetic character. 4 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 4 Example DBG> SHOW ABORT_KEY Abort Command Key is CTRL_C DBG> GO . . . DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 1000: 0 1004: 0 1008: 0 1012: 0 1016: 0 %DEBUG-W-ABORTED, command aborted by user request DBG> SET ABORT_KEY = CTRL_P DBG> GO . . . DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 1000: 0 1004: 0 1008: 0 1012: 0 1016: 0 %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. 3 ATSIGN Establishes the default file specification that the debugger uses when searching for command procedures. Format SET ATSIGN file-spec 4 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. 4 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 4 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[; . . . ])] 4 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 /INSTRUCTION=(opcode[, . . . ]) (VAX only) /INTO /[NO]JSB (VAX only) /LINE /OVER /[NO]SHARE /[NO]SYSTEM /SYSEMULATE (Alpha only) /TERMINATING /UNALIGNED_DATA (Alpha only) /VECTOR_INSTRUCTION (VAX 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. On VAX systems, CALLS and CALLG routines start with an entry mask. 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. 4 Qualifiers /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. /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. /BRANCH Causes the debugger to break on every branch instruction encountered during program execution. See also the /INTO and /OVER qualifiers. /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. /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. /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. o On VAX, if you enter a STEP command, the debugger steps into any application-declared exception handler. If there is no application-declared handler for that exception, the debugger resignals the exception. 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. /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-defined handlers. On Alpha systems, many RTLs establish a jacket RTL handler on a frame where the user program has defined its own handler. This RTL jacket does some setup and argument manipulation before actually calling the handler defined by the user. When processing the exception, the debugger sets the breakpoint on the jacket RTL jacket handler, because that is the address on the call stack. If the debugger suspends program execution at a jacket RTL handler, you can usually reach the user-defined handler by entering a STEP/CALL command followed by a STEP/INTO command. Some cases might require that you enter additional sequences of STEP/CALL and STEP/INTO commands. 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. In this case, activate the RTL as a private image by defining the RTL as a logical name. For example: $DEFINE LIBOTS SYS$SHARE:LIBOTS.EXE; Note that the trailing semicolon (;) is required. /INSTRUCTION /INSTRUCTION /INSTRUCTION[=(opcode[, . . . ])] When you do not specify an opcode, causes the debugger to break on every instruction encountered during program execution. On VAX processors only, you can optionally specify one or more opcodes. This causes the debugger to break on every instruction with an opcode that is on the list. If you specify a vector instruction (VAX only), do not include an instruction qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION, /MODIFY, /0, or /1) with the instruction mnemonic. See also the /INTO and /OVER qualifiers. /INTO (Default) Applies only to breakpoints set with the following qualifiers (that is, when an address expression is not explicitly specified): /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /VECTOR_INSTRUCTION (VAX only) 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. /JSB /JSB /NOJSB (VAX only) Qualifies /INTO. Use with /INTO and one of the following qualifiers: /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) /LINE /VECTOR_INSTRUCTION The /JSB qualifier is the default for all languages except DIBOL. It lets the debugger break within routines that are called by the JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default) specifies that breakpoints not be set within routines called by JSB instructions. In DIBOL, application-declared routines are called by the CALL instruction and DIBOL Run-Time Library routines are called by the JSB instruction. /LINE Causes the debugger to break on the beginning of each source line encountered during program execution. See also the /INTO and /OVER qualifiers. /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. /OVER Applies only to breakpoints set with the following qualifiers (that is, when an address expression is not explicitly specified): /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /VECTOR_INSTRUCTION (VAX only) 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). /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 VAX processors, this qualifier can only be applied to routines called with a CALLS or CALLG instruction; it cannot be used with JSB routines. 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. /SHARE /SHARE (default) /NOSHARE Qualifies /INTO. Use with /INTO and one of the following qualifiers: /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /VECTOR_INSTRUCTION (VAX only) 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. /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. /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. /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. /SYSTEM /SYSTEM (default) /NOSYSTEM Qualifies /INTO. Use with /INTO and one of the following qualifiers: /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /VECTOR_INSTRUCTION (VAX only) 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. /TEMPORARY Causes the breakpoint to disappear after it is triggered (the breakpoint does not remain permanently set). /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. /UNALIGNED_DATA (Alpha only) Causes the 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). /VECTOR_INSTRUCTION (VAX only) Causes the debugger to break on every vector instruction encountered during program execution. See also the /INTO and /OVER qualifiers. 4 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 /INSTRUCTION=(opcode[, . . . ]) (VAX only) /RETURN /VECTOR_INSTRUCTION (VAX only) The following qualifiers set breakpoints on classes of events: /ACTIVATING /EVENT=event-name /EXCEPTION /SYSEMULATE (Alpha only) /TERMINATING /UNALIGNED_DATA (Alpha only) The following qualifiers affect what happens at a routine call: /INTO /[NO]JSB (VAX only) /OVER /[NO]SHARE /[NO]SYSTEM 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 systems, 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 4 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. 3 DEFINE Establishes a default qualifier (/ADDRESS, /COMMAND, /PROCESS_ GROUP, or /VALUE) for the DEFINE command. Format SET DEFINE define-default 4 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 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 Example DBG> SET DEFINE VALUE The SET DEFINE VALUE command specifies that subsequent DEFINE commands are treated as DEFINE/VALUE. 3 EDITOR Establishes the editor that is started by the EDIT command. Format SET EDITOR [command-line] 4 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. 4 Qualifiers /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). /CALLABLE_LSEDIT (VAX only) Specifies that the callable version of the DEC Language-Sensitive Editor (LSEDIT) is started when you use the EDIT command. If you also specify a command line, it is passed to callable LSEDIT. If you do not specify a command line, the default command line is LSEDIT. /CALLABLE_TPU Specifies that the callable version of the DEC Text Processing Utility (DECTPU) is started when you use the EDIT command. If you also specify a command line, it is passed to callable DECTPU. If you do not specify a command line, the default command line is TPU. /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 DECTPU and the DEC 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. 4 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 VAX processors, if you use EDT, LSEDIT, or DECTPU, you can start these editors in a more efficient way. You can specify /CALLABLE_EDT, /CALLABLE_LSEDIT, or /CALLABLE_TPU, which causes the callable versions of EDT, LSEDIT, and DECTPU, respectively, to be invoked by the EDIT command. In the case of LSEDIT and DECTPU, 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 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 DECTPU 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 DECTPU 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. 3 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 4 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). SCAN (VAX only) If the event facility is set to SCAN, the (SET,CANCEL) BREAK and (SET,CANCEL) TRACE commands recognize SCAN (pattern-matching) events. You can set the event facility to SCAN only if the main program is written in SCAN or if the program calls a SCAN routine. 4 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. On VAX processors, you cannot use both Ada and POSIX Threads tasking services in the same program. This implies that you can change the event facility only from ADA to SCAN or from POSIX Threads to SCAN, or conversely. 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 4 Example DBG> SET EVENT_FACILITY THREADS This command establishes THREADS (POSIX Threads) as the current event facility. 3 IMAGE Loads symbol information for one or more shareable images and establishes the current image. Format SET IMAGE [image-name[, . . . ]] 4 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. 4 Qualifiers /ALL Specifies that all shareable images are set. 4 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 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. 3 KEY Establishes the current key state. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SET KEY 4 Qualifiers /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. /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. 4 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 4 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. 3 LANGUAGE Establishes the current language. Format SET LANGUAGE language-name 4 Parameters language-name Specifies a language. On VAX processors, valid keywords are: ADA BASIC BLISS C C_PLUS_PLUS COBOL DIBOL FORTRAN MACRO PASCAL PLI RPG SCAN UNKNOWN On Alpha processors, valid keywords are: ADA AMACRO BASIC BLISS C C_PLUS_PLUS COBOL FORTRAN MACRO MACRO64 PASCAL PLI UNKNOWN 4 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. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, 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 might be advisable to change the default type to quadword for debugging applications that use the 64-bit address space. 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 4 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. 4 /DYNAMIC Toggles the state of automatic language setting. Format SET LANGUAGE/DYNAMIC 5 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 5 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. 3 LOG Specifies a log file to which the debugger writes after a SET OUTPUT LOG command has been entered. Format SET LOG file-spec 4 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. 4 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 4 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. 3 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 Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SET MARGINS rm lm:rm lm: :rm 4 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). 4 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 4 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. 3 MODE Enables or disables a debugger mode. Format SET MODE mode[, . . . ] 4 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 Compaq 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 Compaq 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 Compaq 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 Compaq DECwindows Motif for OpenVMS user interface to the debugger. (Default) Disables screen mode. SCROLL NOTE This parameter is not available in the Compaq 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 Compaq 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. 4 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 4 Example DBG> SET MODE SCREEN This command puts the debugger in screen mode. 3 MODULE Loads the symbol records of a module in the current image into the run-time symbol table (RST) of that image. NOTE The current image is either the main image (by default) or the image established as the current image by a previous SET IMAGE command. Format SET MODULE [module-name[, . . . ]] 4 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. 4 Qualifiers /ALL Specifies that the symbol records of all modules in the current image be loaded into the RST. /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. /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. 4 Description 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. 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. 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. Whether dynamic mode is enabled or disabled, if performance becomes a problem as more modules are set, use the CANCEL MODULE command to reduce the number of set modules. 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,CANCEL) MODULE 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. 3 OUTPUT Enables or disables a debugger output option. Format SET OUTPUT output-option[, . . . ] 4 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 Compaq 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 Compaq 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. 4 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 4 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) 3 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[, . . . ]] 4 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. 4 Qualifiers /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. /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. 4 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 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. 3 PROMPT Changes the debugger prompt string to your personal preference. Format SET PROMPT [prompt-parameter] 4 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. 4 Qualifiers /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). 4 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 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>". 3 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 4 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 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 only). 4 Qualifiers /INPUT Sets only the input radix (the radix for entering integer data) to the specified radix. /OUTPUT Sets only the output radix (the radix for displaying integer data) to the specified radix. /OVERRIDE Causes all data to be displayed as integer data of the specified radix. 4 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. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, 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 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. 3 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[, . . . ] 4 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. 4 Qualifiers /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. /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. 4 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 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. 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 4 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. 3 SEARCH Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) for the SEARCH command. Format SET SEARCH search-default[, . . . ] 4 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. 4 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 4 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. 3 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[, . . . ] 4 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. 4 Qualifiers /DISPLAY Specifies the directory search list used when the debugger displays source code. The default display search directory is the compilation directory. /EDIT Specifies the directory search list used during execution of the debugger's EDIT command. The default edit search directory is the compilation directory. /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. /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. /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. /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. 4 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 On OpenVMS Version 6.1 and later, a complete 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 the default version of DECnet 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 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. 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 4 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. 3 STEP Establishes default qualifiers (/LINE, /INTO, and so on) for the STEP command. Format SET STEP step-default[, . . . ] 4 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, /VECTOR_ INSTRUCTION, /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). JSB (VAX only) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/JSB (step into routines called by a JSB instruction as well as those called by a CALL instruction). This is the default for all languages except DIBOL. NOJSB (VAX only; Default.) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/NOJSB (step over routines called by a JSB instruction, but step into routines called by a CALL instruction). This is the default for DIBOL. 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). VECTOR_INSTRUCTION (VAX only) On VAX processors, subsequent STEP commands are treated as STEP/VECTOR_INSTRUCTION (step to the next vector instruction). 4 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 INSTRUCTION=(opcode[, . . . ]) (VAX only) LINE RETURN SEMANTIC_EVENT (Alpha only) VECTOR_INSTRUCTION (VAX 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 [NO]JSB (VAX only) 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. On VAX systems, the STEP/OVER command may sometimes result in stepping into, not over, Fortran Run-Time Library routines. For more information, see the OpenVMS Debugger Manual. Related commands: SHOW STEP STEP 4 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. 3 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[, . . . ]] 4 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. 4 Qualifiers /ABORT Marks the specified tasks for termination. Termination occurs at the next allowable point after a specified task resumes execution. For Compaq 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 POSIX Threads Library for more information about using the POSIX Threads debugger. /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. The SET TASK/ACTIVE command is supported for Compaq Ada on VAX only. For POSIX Threads programs or Compaq 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 POSIX Threads Library for more information about using the POSIX Threads debugger. /ALL Applies the SET TASK command to all tasks. /HOLD /HOLD /NOHOLD (default) When the event facility is THREADS, use the PTHREAD tset -h thread-number or the PTHREAD tset -n thread-number 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. 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 POSIX Threads Library for more information about using the POSIX Threads debugger. /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 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 POSIX Threads Library for more information about using the POSIX Threads debugger. /RESTORE (Compaq Ada on VAX only) Restores the priority of a specified task to the priority it had when it was created. Does not affect the scheduling priority of the task. /TIME_SLICE /TIME_SLICE=t Supported for Compaq Ada on VAX only. Sets the time-slice duration to the value t, where t is a decimal integer or real value representing seconds. The set value overrides the time- slice value specified in the program, if any. To disable time slicing, use /TIME_SLICE=0.0. /TIME_SLICE is valid only when the event facility is ADA. /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. 4 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 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. 3 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 Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SET TERMINAL 4 Qualifiers /PAGE /PAGE:n Specifies that the terminal screen height should be set to n lines. You can use any value from 18 to 100. /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. /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. 4 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 4 Example DBG> SET TERMINAL/WIDTH:132 This command specifies that the terminal screen width be set to 132 columns. 3 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[, . . . ]] 4 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. 4 Qualifiers /ABORT Marks the specified tasks for termination. Termination occurs at the next allowable point after a specified task resumes execution. For Compaq 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 POSIX Threads Library for more information about using the POSIX Threads debugger. /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. The SET TASK/ACTIVE command is supported for Compaq Ada on VAX only. For POSIX Threads programs or Compaq 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 POSIX Threads Library for more information about using the POSIX Threads debugger. /ALL Applies the SET TASK command to all tasks. /HOLD /HOLD /NOHOLD (default) When the event facility is THREADS, use the PTHREAD tset -h thread-number or the PTHREAD tset -n thread-number 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. 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 POSIX Threads Library for more information about using the POSIX Threads debugger. /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 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 POSIX Threads Library for more information about using the POSIX Threads debugger. /RESTORE (Compaq Ada on VAX only) Restores the priority of a specified task to the priority it had when it was created. Does not affect the scheduling priority of the task. /TIME_SLICE /TIME_SLICE=t Supported for Compaq Ada on VAX only. Sets the time-slice duration to the value t, where t is a decimal integer or real value representing seconds. The set value overrides the time- slice value specified in the program, if any. To disable time slicing, use /TIME_SLICE=0.0. /TIME_SLICE is valid only when the event facility is ADA. /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. 4 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 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. 3 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[; . . . ])] 4 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 /INSTRUCTION=(opcode[, . . . ]) (VAX only) /INTO /[NO]JSB (VAX only) /LINE /OVER /[NO]SHARE /[NO]SYSTEM /TERMINATING /VECTOR_INSTRUCTION (VAX 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 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. On VAX processors, CALLS and CALLG routines start with an entry mask. 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. 4 Qualifiers /ACTIVATING Causes the debugger to trace when a new process comes under debugger control. See also the /TERMINATING qualifier. /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. /BRANCH Causes the debugger to trace every branch instruction encountered during program execution. See also the /INTO and /OVER qualifiers. /CALL Causes the debugger to trace every call instruction encountered during program execution, including the return instruction. See also the /INTO and /OVER qualifiers. /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. /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. /INSTRUCTION /INSTRUCTION /INSTRUCTION[=(opcode[, . . . ])] (VAX only) When you do not specify an opcode, causes the debugger to trace every instruction encountered during program execution. (VAX only) If you specify one or more opcodes, causes the debugger to trace every instruction whose opcode is in the list. If you specify a vector instruction, do not include an instruction qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION, /MODIFY, /0, or /1) with the instruction mnemonic. See also the /INTO and /OVER qualifiers. /INTO (Default) Applies only to tracepoints set with the following qualifiers (that is, when an address expression is not explicitly specified): /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /VECTOR_INSTRUCTION (VAX only) 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. /JSB /JSB /NOJSB (VAX only) Qualifies /INTO. Use with /INTO and one of the following qualifiers: /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) /LINE /VECTOR_INSTRUCTION The /JSB qualifier is the default for all languages except DIBOL. It lets the debugger set tracepoints within routines that are called by the JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default) specifies that tracepoints not be set within routines called by JSB instructions. In DIBOL, application- declared routines are called by the CALL instruction and DIBOL Run-Time Library routines are called by the JSB instruction. /LINE Causes the debugger to trace the beginning of each source line encountered during program execution. See also the /INTO and /OVER qualifiers. /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. /OVER Applies only to tracepoints set with the following qualifiers (that is, when an address expression is not explicitly specified): /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /VECTOR_INSTRUCTION (VAX only) 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). /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 VAX processors, this qualifier can only be applied to routines called with a CALLS or CALLG instruction; it cannot be used with JSB routines. 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. /SHARE /SHARE (default) /NOSHARE Qualifies /INTO. Use with /INTO and one of the following qualifiers: /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /VECTOR_INSTRUCTION (VAX only) 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. /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. /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. /SYSTEM /SYSTEM (default) /NOSYSTEM Qualifies /INTO. Use with /INTO and one of the following qualifiers: /BRANCH /CALL /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /VECTOR_INSTRUCTION (VAX only) 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. /TEMPORARY Causes the tracepoint to disappear after it is triggered (the tracepoint does not remain permanently set). /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. /VECTOR_INSTRUCTION (VAX only) Causes the debugger to trace every vector instruction encountered during execution. See also the /INTO and /OVER qualifiers. 4 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 /INSTRUCTION=(opcode[, . . . ]) (VAX only) /RETURN /SYSEMULATE (Alpha only) /VECTOR_INSTRUCTION (VAX only) The following qualifiers set tracepoints on classes of events: /ACTIVATING /EVENT=event-name /EXCEPTION /TERMINATING 4 Description_(Continued...) The following qualifiers affect what happens at a routine call: /INTO /[NO]JSB (VAX only) /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 4 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. 3 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 4 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). FLOAT On VAX systems, sets the default type to F_floating (length 4 bytes). On Alpha systems, sets the default type to IEEE T_floating (double precision, length 8 bytes). G_FLOAT Sets the default type to G_floating (length 8 bytes). H_FLOAT (VAX only) Sets the default type to H_floating (length 16 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). 4 Qualifiers /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). 4 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. 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 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. 3 VECTOR_MODE Enables or disables a debugger vector mode option. Applies only to VAX vectorized programs. Format SET VECTOR_MODE vector-mode-option 4 Parameters vector-mode-option Specifies the vector mode option. Valid keywords are as follows: SYNCHRONIZED Specifies that the debugger force automatic synchronization between the scalar and vector processors whenever a vector instruction is executed. Specifically, the debugger issues a SYNC instruction after every vector instruction and, in addition, an MSYNC instruction after any vector instruction that accesses memory. This forces the completion of all activities associated with the vector instruction that is being synchronized: o Any exception that was caused by a vector instruction is delivered before the next scalar instruction is executed. Forcing the delivery of a pending exception triggers an exception breakpoint or tracepoint (if one was set) or invokes an exception handler (if one is available at that location in the program). o Any read or write operation between vector registers and either the general registers or memory is completed before the next scalar instruction is executed. The SET VECTOR_MODE SYNCHRONIZED command does not issue an immediate SYNC or MSYNC instruction at the time it is issued. To force immediate synchronization, use the SYNCHRONIZE VECTOR_MODE command. NOSYNCHRONIZED (Default) Specifies that the debugger not force synchronization between the scalar and vector processors except for internal debugger purposes. As a result, any synchronization is controlled entirely by the program, and the program runs as if it were not under debugger control. 4 Description Vector mode options control the way in which the debugger interacts with the vector processor. For details about the SET VECTOR_MODE command, see the parameter descriptions. Related commands: (SHOW,SYNCHRONIZE) VECTOR_MODE 4 Examples 1.DBG> SET VECTOR_MODE SYNCHRONIZED This command causes the debugger to force synchronization between the scalar and vector processors after each vector instruction is executed. 2.DBG> SHOW VECTOR_MODE Vector mode is nonsynchronized DBG> SET VECTOR_MODE SYNCHRONIZED 1 DBG> SHOW VECTOR_MODE Vector mode is synchronized DBG> STEP 2 stepped to .MAIN.\SUB\%LINE 99 99: VVDIVD V1,V0,V2 DBG> STEP 3 %SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, mask=00000004, PC=000002E1, PSL=03C00010 break on unhandled exception preceding .MAIN.\SUB\%LINE 100 100: CLRL R0 DBG> The comments that follow refer to the callouts in the previous example: 1 The SET VECTOR_MODE SYNCHRONIZED command causes the debugger to force automatic synchronization between the scalar and vector processors whenever a vector instruction is executed. 2 This STEP command suspends program execution on line 99, just before a VVDIVD instruction is executed. Assume that, in this example, the instruction will trigger a floating- point divide-by-zero exception. 3 This STEP command executes the VVDIVD instruction, which triggers the exception. The vector exception is delivered immediately because the debugger is being operated in synchronized vector mode. 3 WATCH Establishes a watchpoint at the location denoted by an address expression. Format SET WATCH address-expression[, . . . ] [WHEN(conditional-expression)] [DO(command[; . . . ])] 4 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. 4 Qualifiers /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. /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. /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. /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. /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. /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. /TEMPORARY Causes the watchpoint to disappear after it is triggered (the watchpoint does not remain permanently set). 4 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 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. 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 On VAX systems, watchpoints set on variables whose addresses are in global sections do not work. Attempting to set a watchpoint on a location in a global section results in a %DEBUG-E-BADWATCH message. Related commands: (ACTIVATE,DEACTIVATE,SHOW,CANCEL) WATCH MONITOR SET BREAK SET STEP [NO]SOURCE SET TRACE 4 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 both Alpha and VAX 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 (DBGSSISHR on OpenVMS VAX systems and 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 4 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. 4 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. 3 WINDOW Creates a screen window definition. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SET WINDOW window-name AT (start-line,line-count [,start-column,column-count]) 4 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. 4 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 4 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). 2 SHOW 3 ABORT_KEY Identifies the Ctrl-key sequence currently defined to abort the execution of a debugger command or to interrupt program execution. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SHOW ABORT_KEY 4 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. The SHOW ABORT_KEY command identifies the Ctrl-key sequence currently in effect for the abort function. Related commands: Ctrl/C SET ABORT_KEY 4 Example DBG> SHOW ABORT_KEY Abort Command Key is CTRL_C DBG> SET ABORT_KEY = CTRL_P DBG> SHOW ABORT_KEY Abort Command Key is CTRL_P DBG> In this example, the first SHOW ABORT_KEY command identifies the default abort command key sequence, Ctrl/C. The SET ABORT_ KEY = CTRL_P command assigns the abort-command function to Ctrl/P, as confirmed by the second SHOW ABORT_KEY command. 3 AST Indicates whether delivery of asynchronous system traps (ASTs) is enabled or disabled. Format SHOW AST 4 Description The SHOW AST command indicates whether delivery of ASTs is enabled or disabled. The command does not identify an AST whose delivery is pending. The delivery of ASTs is enabled by default and with the ENABLE AST command. The delivery of ASTs is disabled with the DISABLE AST command. Related commands: (ENABLE,DISABLE) AST 4 Example DBG> SHOW AST ASTs are enabled DBG> DISABLE AST DBG> SHOW AST ASTs are disabled DBG> The SHOW AST command indicates whether the delivery of ASTs is enabled. 3 ATSIGN Identifies the default file specification established with the last SET ATSIGN command. The debugger uses this file specification when processing the execute procedure (@) command. Format SHOW ATSIGN 4 Description Related commands: @ (Execute Procedure) SET ATSIGN 4 Examples 1.DBG> SHOW ATSIGN No indirect command file default in effect, using DEBUG.COM DBG> This example shows that if you did not use the SET ATSIGN command, the debugger assumes command procedures have the default file specification SYS$DISK:[]DEBUG.COM. 2.DBG> SET ATSIGN USER:[JONES.DEBUG].DBG DBG> SHOW ATSIGN Indirect command file default is USER:[JONES.DEBUG].DBG DBG> In this example, the SHOW ATSIGN command indicates the default file specification for command procedures, as previously established with the SET ATSIGN command. 3 BREAK Displays information about breakpoints. Format SHOW BREAK 4 Qualifiers /PREDEFINED Displays information about predefined breakpoints. /USER Displays information about user-defined breakpoints. 4 Description The SHOW BREAK command displays information about breakpoints that are currently set, including any options such as WHEN or DO clauses, /AFTER counts, and so on, and whether the breakpoints are deactivated. By default, SHOW BREAK displays information about both user- defined and predefined breakpoints (if any). This is equivalent to entering the SHOW BREAK/USER/PREDEFINED command. User-defined breakpoints are set with the SET BREAK command. Predefined breakpoints are set automatically when you start the debugger, and they depend on the type of program you are debugging. If you established a breakpoint using SET BREAK/AFTER:n, the SHOW BREAK command displays the current value of the decimal integer n, that is, the originally specified integer value minus 1 for each time the breakpoint location was reached. (The debugger decrements n each time the breakpoint location is reached until the value of n is 0, at which time the debugger takes break action.) On Alpha systems, the SHOW BREAK command does not display individual instructions when the break is on a particular class of instruction (as with SET BREAK/CALL or SET BREAK/RETURN). Related commands: (ACTIVATE,CANCEL,DEACTIVATE,SET) BREAK 4 Examples 1.DBG> SHOW BREAK breakpoint at SUB1\LOOP breakpoint at MAIN\MAIN+1F do (EX SUB1\D ; EX/SYMBOLIC PSL; GO) breakpoint at routine SUB2\SUB2 /after: 2 DBG> The SHOW BREAK command identifies all breakpoints that are currently set. This example indicates user-defined breakpoints that are triggered whenever execution reaches SUB1\LOOP, MAIN\MAIN, and SUB2\SUB2, respectively. 2.DBG> SHOW BREAK/PREDEFINED predefined breakpoint on Ada event "DEPENDENTS_EXCEPTION" for any value predefined breakpoint on Ada event "EXCEPTION_TERMINATED" for any value DBG> This command identifies the predefined breakpoints that are currently set. The example shows two predefined breakpoints, which are associated with Ada tasking exception events. These breakpoints are set automatically by the debugger for all Ada programs and for any mixed language program that is linked with an Ada module. 3 CALLS Identifies the currently active routine calls. Format SHOW CALLS [integer] 4 Parameters integer A decimal integer that specifies the number of routine calls to be identified. If you omit the parameter, the debugger identifies all routine calls for which it has information. 4 Qualifiers /IMAGE Displays the image name for each active call on the call stack. 4 Description The SHOW CALLS command shows a traceback that lists the sequence of active routine calls that lead to the routine in which execution is currently suspended. Any recursive routine calls are shown in the display, so you can use the SHOW CALLS command to examine the chain of recursion. SHOW CALLS displays one line of information for each call frame on the call stack, starting with the most recent call. The top line identifies the currently executing routine, the next line identifies its caller, the following line identifies the caller of the caller, and so on. Even if your program contains no routine calls, the SHOW CALLS command displays an active call. The reason for this is that your program has a stack frame built for it when it is first activated. Thus, if the SHOW CALLS display shows no active calls, either your program has terminated or the call stack has been corrupted. On VAX processors, the sequence of routine calls corresponds to the sequence of call frames on the call stack. Whenever a call is made to a routine as your program executes, the operating system creates a separate call frame on the call stack. Each call frame stores information about the calling routine, for example, the PC value that enables the SHOW CALLS command to symbolize module and routine information. On Alpha processors, a routine invocation can result in a stack frame procedure (with a call frame on the stack), a register frame procedure (with a call frame stored in the register set), or a null frame procedure (without a call frame). SHOW CALLS provides one line of information on all three: stack frame procedures, register frame procedures, and null frame procedures. (See the Alpha example below.) 4 Description,_Continued... The following information is provided for each line of the SHOW CALLS display: o The name of the enclosing module. An asterisk (*) to the left of a module name indicates that the module is set. o The name of the calling routine, provided the module is set (the first line shows the currently executing routine). o The line number where the call was made in that routine, provided the module is set (the first line shows the line number at which execution is suspended). o The value of the PC in the calling routine at the time that control was transferred to the called routine. On VAX processors, the PC value is shown as a memory address relative to the nearest preceding symbol value (for example, a routine) and also as an absolute address. On Alpha processors, the PC is shown as a memory address relative to the first code address in the module and also as an absolute address. 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 CALLS/IMAGE command. The debugger restores the set image state when the SHOW CALLS/IMAGE command is complete. Related commands: SHOW SCOPE SHOW STACK 4 Examples 1.DBG> SHOW CALLS module name routine name line rel PC abs PC SUB2 SUB2 00000002 0000085A *SUB1 SUB1 5 00000014 00000854 *MAIN MAIN 10 0000002C 0000082C DBG> This command displays information about the sequence of currently active procedure calls on a VAX system. 2.DBG> SHOW CALLS module name routine name line rel PC abs PC *MAIN FFFF 31 00000000000002B8 00000000000203C4 -the above appears to be a null frame in the same scope as the frame below *MAIN MAIN 13 00000000000000A8 00000000000200A8 0000000000000000 FFFFFFFF8255A1F8 This example has been reformatted for Help, and may appear slightly different from the actual output display. This example is on an Alpha system. Note that sections of routine prologues and epilogues appear to the debugger to be null frames. The portion of the prologue before the change in the frame pointer (FP) and the portion of the epilogue after restoration of the FP each look like a null frame, and are reported accordingly. 3 DEFINE Identifies the default (/ADDRESS, /COMMAND, /PROCESS_GROUP, or /VALUE) currently in effect for the DEFINE command. Format SHOW DEFINE 4 Description The default qualifier for the DEFINE command is the one last established with the SET DEFINE command. If you did not enter a SET DEFINE command, the default qualifier is /ADDRESS. To identify a symbol defined with the DEFINE command, use the SHOW SYMBOL/DEFINED command. Related commands: DEFINE DEFINE/PROCESS_SET DELETE SET DEFINE SHOW SYMBOL/DEFINED 4 Example DBG> SHOW DEFINE Current setting is: DEFINE/ADDRESS DBG> This command indicates that the DEFINE command is set for definition by address. 3 DISPLAY Identifies one or more existing screen displays. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SHOW DISPLAY [display-name[, . . . ]] 4 Parameters display-name Specifies the name of a display. If you do not specify a name, or if you specify the asterisk (*) wildcard character by itself, all display definitions are listed. You can use the wildcard within a display name. Do not specify a display name with the /ALL qualifier. 4 Qualifiers /ALL Lists all display definitions. 4 Description The SHOW DISPLAY command lists all displays according to their order in the display list. The most hidden display is listed first, and the display that is on top of the display pasteboard is listed last. For each display, the SHOW DISPLAY command lists its name, maximum size, screen window, and display kind (including any debug command list). It also identifies whether the display is removed from the pasteboard or is dynamic (a dynamic display automatically adjusts its window dimensions if the screen size is changed with the SET TERMINAL command). Related commands: DISPLAY EXTRACT/SCREEN_LAYOUT (CANCEL) DISPLAY (SET,CANCEL,SHOW) WINDOW SHOW SELECT 4 Example DBG> SHOW DISPLAY display SRC at H1, size = 64, dynamic kind = SOURCE (EXAMINE/SOURCE .%SOURCE_SCOPE\%PC) display INST at H1, size = 64, removed, dynamic kind = INSTRUCTION (EXAMINE/INSTRUCTION .0\%PC) display REG at RH1, size = 64, removed, dynamic, kind = REGISTER display OUT at S45, size = 100, dynamic, kind = OUTPUT display EXSUM at Q3, size = 64, dynamic, kind = DO (EXAMINE SUM) display PROMPT at S6, size = 64, dynamic, kind = PROGRAM DBG> The SHOW DISPLAY command lists all displays currently defined. In this example, they include the five predefined displays (SRC, INST, REG, OUT, and PROMPT), and the user-defined DO display EXSUM. Displays INST and REG are removed from the display pasteboard: the DISPLAY command must be used to display them on the screen. 3 EDITOR Indicates the action taken by the EDIT command, as established by the SET EDITOR command. Format SHOW EDITOR 4 Description Related commands: EDIT SET EDITOR 4 Examples 1.DBG> SHOW EDITOR The editor is SPAWNed, with command line "EDT/START_POSITION=(n,1)" DBG> In this example, the EDIT command spawns the EDT editor in a subprocess. The /START_POSITION qualifier appended to the command line indicates that the editing cursor is initially positioned at the beginning of the line that is centered in the debugger's current source display. 2.DBG> SET EDITOR/CALLABLE_TPU DBG> SHOW EDITOR The editor is CALLABLE_TPU, with command line "TPU" DBG> In this example, the SHOW EDITOR command indicates that the EDIT command invokes the callable version of the DEC Text Processing Utility (DECTPU). The editing cursor is initially positioned at the beginning of source line 1. 3 EVENT_FACILITY Identifies the current event facility and the associated event names. Event facilities are available for programs that call Ada routines or that use POSIX Threads services. On VAX processors, event facilities are also available for programs that call SCAN routines. Format SHOW EVENT_FACILITY 4 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. The SHOW EVENT_FACILITY command identifies 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 EVENT_FACILITY (SET,CANCEL) TRACE/EVENT SHOW BREAK SHOW TASK SHOW TRACE 4 Example DBG> SHOW EVENT_FACILITY event facility is THREADS . . . This command identifies the current event facility to be THREADS (POSIX Threads) and lists the associated event names that can be used with SET BREAK/EVENT or SET TRACE/EVENT commands. 3 EXIT_HANDLERS Identifies the exit handlers that have been declared in your program. Format SHOW EXIT_HANDLERS 4 Description The exit handler routines are displayed in the order that they are called (that is, last in, first out). The routine name is displayed symbolically, if possible. Otherwise, its address is displayed. The debugger's exit handlers are not displayed. 4 Example DBG> SHOW EXIT_HANDLERS exit handler at STACKS\CLEANUP DBG> This command identifies the exit handler routine CLEANUP, which is declared in module STACKS. 3 IMAGE Displays information about one or more images that are part of your running program. Format SHOW IMAGE [image-name] 4 Parameters image-name Specifies the name of an image to be included in the display. If you do not specify a name, or if you specify the asterisk (*) wildcard character by itself, all images are listed. You can use the wildcard within an image name. 4 Description The SHOW IMAGE command displays the following information: o Name of the image o Start and end addresses of the image o Whether the image has been set with the SET IMAGE command (loaded into the run-time symbol table, RST) o Current image that is your debugging context (marked with an asterisk (*)) o Total number of images selected in the display o Number of bytes allocated for the RST and other internal structures SHOW IMAGE does not display all of the memory ranges of an image installed using the /RESIDENT qualifier. Instead, this command displays only the process data region. Related commands: (SET,CANCEL) IMAGE (SET,SHOW,CANCEL) MODULE 4 Example DBG> SHOW IMAGE SHARE* image name set base address end address *SHARE yes 00000200 00000FFF SHARE1 no 00001000 000017FF SHARE2 yes 00018C00 000191FF SHARE3 no 00019200 000195FF SHARE4 no 00019600 0001B7FF total images: 5 bytes allocated: 33032 DBG> This SHOW IMAGE command identifies all of the images whose names start with SHARE and which are associated with the program. Images SHARE and SHARE2 are set. The asterisk (*) identifies SHARE as the current image. 3 KEY Displays the debugger predefined key definitions and those created by the DEFINE/KEY command. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SHOW KEY [key-name] 4 Parameters key-name Specifies a function key whose definition is displayed. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify a key name with /ALL or /DIRECTORY. Valid key names are as follows: Key LK201 Name Keyboard VT100-type VT52-type PF1 PF1 PF1 Blue PF2 PF2 PF2 Red PF3 PF3 PF3 Black PF4 PF4 PF4 KP0-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9 PERIOD Keypad Keypad period (.) period (.) COMMA Keypad comma Keypad comma (,) (,) ENTER Enter ENTER ENTER E1 Find E2 Insert Here E3 Remove E4 Select E5 Prev Screen E6 Next Screen HELP Help DO Do F6-F20 F6-F20 4 Qualifiers /ALL Displays all key definitions for the current state, by default, or for the states specified with /STATE. /BRIEF Displays only the key definitions (by default, all qualifiers associated with a key definition are also shown, including any specified state). /DIRECTORY Displays the names of all the states for which keys have been defined. Do not specify other qualifiers with this qualifier. /STATE /STATE=(state-name [, . . . ]) /NOSTATE (default) Selects one or more states for which a key definition is displayed. The /STATE qualifier displays key definitions for the specified states. You can specify predefined key states, such as DEFAULT and GOLD, or user-defined states. A state name can be any appropriate alphanumeric string. The /NOSTATE qualifier displays key definitions for the current state only. 4 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. You can change the current state by using the SET KEY/STATE command or by pressing a key that causes a state change (that is, a key that was defined with DEFINE/KEY/LOCK_STATE or /SET_STATE). Related commands: DEFINE/KEY DELETE/KEY SET KEY 4 Examples 1.DBG> SHOW KEY/ALL This command displays all the key definitions for the current state. 2.DBG> SHOW KEY/STATE=BLUE KP8 GOLD keypad definitions: KP8 = "Scroll/Top" (noecho,terminate,nolock) DBG> This command displays the definition for keypad key 8 in the BLUE state. 3.DBG> SHOW KEY/BRIEF KP8 DEFAULT keypad definitions: KP8 = "Scroll/Up" DBG> This command displays the definition for keypad key 8 in the current state. 4.DBG> SHOW KEY/DIRECTORY MOVE_GOLD MOVE_BLUE MOVE GOLD EXPAND_GOLD EXPAND_BLUE EXPAND DEFAULT CONTRACT_GOLD CONTRACT_BLUE CONTRACT BLUE DBG> This command displays the names of the states for which keys have been defined. 3 LANGUAGE Identifies the current language. Format SHOW LANGUAGE 4 Description The current language is the language last established with the SET LANGUAGE command. If you did not enter a SET LANGUAGE command, the current language is, by default, the language of the module containing the main program. Related command: SET LANGUAGE 4 Example DBG> SHOW LANGUAGE language: BASIC DBG> This command displays the name of the current language as BASIC. 3 LOG Indicates whether the debugger is writing to a log file and identifies the current log file. Format SHOW LOG 4 Description The current log file is the log file last established by a SET LOG command. By default, if you did not enter a SET LOG command, the current log file is the file SYS$DISK:[]DEBUG.LOG. Related commands: SET LOG SET OUTPUT [NO]LOG SET OUTPUT [NO]SCREEN_LOG 4 Examples 1.DBG> SHOW LOG not logging to DEBUG.LOG DBG> This command displays the name of the current log file as DEBUG.LOG (the default log file) and reports that the debugger is not writing to it. 2.DBG> SET LOG PROG4 DBG> SET OUTPUT LOG DBG> SHOW LOG logging to USER$:[JONES.WORK]PROG4.LOG DBG> In this example, the SET LOG command establishes that the current log file is PROG4.LOG (in the current default directory). The SET OUTPUT LOG command causes the debugger to log debugger input and output into that file. The SHOW LOG command confirms that the debugger is writing to the log file PROG4.COM in your current default directory. 3 MARGINS Identifies the current source-line margin settings for displaying source code. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SHOW MARGINS 4 Description The current margin settings are the margin settings last established with the SET MARGINS command. By default, if you did not enter a SET MARGINS command, the left margin is set to 1 and the right margin is set to 255. Related command: SET MARGINS 4 Examples 1.DBG> SHOW MARGINS left margin: 1 , right margin: 255 DBG> This command displays the default margin settings of 1 and 255. 2.DBG> SET MARGINS 50 DBG> SHOW MARGINS left margin: 1 , right margin: 50 DBG> This command displays the default left margin setting of 1 and the modified right margin setting of 50. 3.DBG> SET MARGINS 10:60 DBG> SHOW MARGINS left margin: 10 , right margin: 60 DBG> This command displays both margin settings modified to 10 and 60. 3 MODE Identifies the current debugger modes (screen or no screen, keypad or nokeypad, and so on) and the current radix. Format SHOW MODE 4 Description The current debugger modes are the modes last established with the SET MODE command. By default, if you did not enter a SET MODE command, the current modes are the following: DYNAMIC NOG_FLOAT (D_float) INTERRUPT KEYPAD LINE NOSCREEN SCROLL NOSEPARATE SYMBOLIC Related commands: (SET,CANCEL) MODE (SET,SHOW,CANCEL) RADIX 4 Example DBG> SHOW MODE modes: symbolic, line, d_float, screen, scroll, keypad, dynamic, interrupt, no separate window input radix :decimal output radix:decimal DBG> The SHOW MODE command displays the current modes and current input and output radix. 3 MODULE Displays information about the modules in the current image. Format SHOW MODULE [module-name] 4 Parameters module-name Specifies the name of a module to be included in the display. If you do not specify a name, or if you specify the asterisk (*) wildcard character by itself, all modules are listed. You can use a wildcard within a module name. Shareable image modules are selected only if you specify /SHARE. 4 Qualifiers /RELATED /RELATED /NORELATED (default) (Applies to Ada programs.) Controls whether the debugger includes, in the SHOW MODULE display, any module that is related to a specified module through a with-clause or subunit relationship. The SHOW MODULE/RELATED command displays related modules as well as those specified. The display identifies the exact relationship. By default (/NORELATED), no related modules are selected for display (only the modules specified are selected). /SHARE /SHARE /NOSHARE (default) Controls whether the debugger includes, in the SHOW MODULE display, any shareable images that have been linked with your program. By default (/NOSHARE) no shareable image modules are selected for display. The debugger creates dummy modules for each shareable image in your program. The names of these shareable "image modules" have the prefix SHARE$. The SHOW MODULE/SHARE command identifies these shareable image modules, as well as the modules in the current image. Setting a shareable image module loads the universal symbols for that image into the run-time symbol table so that you can reference these symbols from the current image. However, you cannot reference other (local or global) symbols in that image from the current image. This feature overlaps the effect of the newer SET IMAGE and SHOW IMAGE commands. 4 Description The SHOW MODULE command displays the following information about one or more modules selected for display: o Name of the module o Programming language in which the module is coded, unless all modules are coded in the same language o Whether the module has been set with the SET MODULE command. That is, whether the symbol records of the module have been loaded into the debugger's run-time symbol table (RST) o Space (in bytes) required in the RST for symbol records in that module o Total number of modules selected in the display o Number of bytes allocated for the RST and other internal structures (the amount of heap space in use in the main debugger's process) NOTE The current image is either the main image (by default) or the image established as the current image by a previous SET IMAGE command. For information specific to Ada programs, type Help Language_Support Ada. Related commands: (SET,SHOW,CANCEL) IMAGE SET MODE [NO]DYNAMIC (SET,CANCEL) MODULE (SET,SHOW,CANCEL) SCOPE SHOW SYMBOL 4 Examples 1.DBG> SHOW MODULE module name symbols size TEST yes 432 SCREEN_IO no 280 total PASCAL modules: 2. bytes allocated: 2740. DBG> In this example, the SHOW MODULE command, without a parameter, displays information about all of the modules in the current image, which is the main image by default. This example shows the display format when all modules have the same source language. The symbols column shows that module TEST has been set, but module SCREEN_IO has not. 2.DBG> SHOW MODULE FOO,MAIN,SUB* module name symbols language size FOO yes MACRO 432 MAIN no FORTRAN 280 SUB1 no FORTRAN 164 SUB2 no FORTRAN 204 total modules: 4. bytes allocated: 60720. DBG> In this example, the SHOW MODULE command displays information about the modules FOO and MAIN, and all modules having the prefix SUB. This example shows the display format when the modules do not have the same source language. 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 of the modules in the current image and all of the 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. 3 OUTPUT Identifies the current output options. Format SHOW OUTPUT 4 Description The current output options are the options last established with the SET OUTPUT command. By default, if you did not enter a SET OUTPUT command, the output options are: NOLOG, NOSCREEN_LOG, TERMINAL, NOVERIFY. Related commands: SET LOG SET MODE SCREEN SET OUTPUT 4 Example DBG> SHOW OUTPUT noverify, terminal, screen_log, logging to USER$:[JONES.WORK]DEBUG.LOG;9 DBG> This command shows the following current output options: o Debugger commands read from debugger command procedures are not echoed on the terminal. o Debugger output is being displayed on the terminal. o The debugging session is being logged to the log file USER$:[JONES.WORK]DEBUG.LOG;9. o The screen contents are logged as they are updated in screen mode. 3 PROCESS Displays information about processes that are currently under debugger control. Format SHOW PROCESS [process-spec[, . . . ]] 4 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 or the /ALL qualifier to specify all processes. Do not specify a process with /ALL or /DYNAMIC. If you do not specify a process or /ALL with /BRIEF, /FULL, or /[NO]HOLD, the visible process is selected. 4 Qualifiers /ALL Selects all processes known to the debugger for display. /BRIEF (Default) Displays only one line of information for each process selected for display. /DYNAMIC Shows whether dynamic process setting is enabled or disabled. Dynamic process setting is enabled by default and is controlled with the SET PROCESS/[NO]DYNAMIC command. /FULL Displays maximum information for each process selected for display. /VISIBLE (Default). Selects the visible process for display. 4 Description The SHOW PROCESS command displays information about specified processes and any images running in those processes. The SHOW PROCESS/FULL command also displays information about the availability and use of the vector processor. This information is useful if you are debugging a program that uses vector instructions. A process can first appear in a SHOW PROCESS display as soon as it comes under debugger control. A process can no longer appear in a SHOW PROCESS display if it is terminated through an EXIT or QUIT command. By default (/BRIEF), one line of information is displayed for each process, including the following: o The process number assigned by the debugger. A process number is assigned sequentially, starting with process 1, to each process that comes under debugger control. If a process is terminated by an EXIT or QUIT command, its process number is not reused during that debugging session. The visible process is marked with an asterisk (*) in the leftmost column. o The process name. o The current debugging state for that process. o The location (symbolized, if possible) at which execution of the image is suspended in that process. The SHOW PROCESS/FULL command gives additional information about processes (see the examples). Related commands: CONNECT Ctrl/C DEFINE/PROCESS_SET EXIT QUIT SET PROCESS 4 Examples 1.all> SHOW PROCESS Number Name State Current PC * 2 _WTA3: break SCREEN\%LINE 47 all> By default, the SHOW PROCESS command displays one line of information about the visible process (which is identified with an asterisk (*) in the leftmost column). The process has the process name _WTA3:. It is the second process brought under debugger control (process number 2). It is on hold, and the image's execution is suspended at a breakpoint at line 47 of module SCREEN. 2.all> SHOW PROCESS TEST_3 Number Name State Current PC 7 TEST_3 watch of TEST_3\ROUT4\COUNT TEST_3\%LINE 54 all> This SHOW PROCESS command displays one line of information about process TEST_3. The image is suspended at a watchpoint of variable COUNT. 3.all> SHOW PROCESS/DYNAMIC Dynamic process setting is enabled all> This command indicates that dynamic process setting is enabled. 3 RADIX Identifies the current radix for the entry and display of integer data or, if you specify /OVERRIDE, the current override radix. Format SHOW RADIX 4 Qualifiers /OVERRIDE Identifies the current override radix. 4 Description The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The current radix for the entry and display of integer data is the radix last established with the SET RADIX command. If you did not enter a SET RADIX command, the default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO-32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, which have a default radix of hexadecimal. The current override radix for the display of all data is the override radix last established with the SET RADIX/OVERRIDE command. If you did not enter a SET RADIX/OVERRIDE command, the override radix is "none". Related commands: DEPOSIT EVALUATE EXAMINE (SET,CANCEL) RADIX 4 Examples 1.DBG> SHOW RADIX input radix: decimal output radix: decimal DBG> This command identifies the input radix and output radix as decimal. 2.DBG> SET RADIX/OVERRIDE HEX DBG> SHOW RADIX/OVERRIDE output override radix: hexadecimal DBG> In this example, the SET RADIX/OVERRIDE command sets the override radix to hexadecimal and the SHOW RADIX/OVERRIDE command indicates the override radix. This means that commands such as EXAMINE display all data as hexadecimal integer data. 3 SCOPE Identifies the current scope search list for symbol lookup. Format SHOW SCOPE 4 Description The current scope search list designates one or more program locations (specified by path names or other special characters) to be used in the interpretation of symbols that are specified without path-name prefixes in debugger commands. The current scope search list is the scope search list last established with the SET SCOPE command. By default, if you did not enter a SET SCOPE command, the current scope search list is 0,1,2, . . . ,n. The default scope search list specifies that, for a symbol without a path-name prefix, a symbol lookup such as EXAMINE X first looks for X in the routine that is currently executing (scope 0); 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. If you used a decimal integer in the SET SCOPE command to represent a routine in the call stack, the SHOW SCOPE command displays the name of the routine represented by the integer, if possible. Related commands: (SET,CANCEL) SCOPE 4 Examples 1.DBG> CANCEL SCOPE DBG> SHOW SCOPE scope: * 0 [ = EIGHTQUEENS\TRYCOL\REMOVEQUEEN ], 1 [ = EIGHTQUEENS\TRYCOL ], 2 [ = EIGHTQUEENS\TRYCOL 1 ], 3 [ = EIGHTQUEENS\TRYCOL 2 ], 4 [ = EIGHTQUEENS\TRYCOL 3 ], 5 [ = EIGHTQUEENS\TRYCOL 4 ], 6 [ = EIGHTQUEENS ] DBG> SET SCOPE/CURRENT 2 DBG> SHOW SCOPE scope: 0 [ = EIGHTQUEENS\TRYCOL\REMOVEQUEEN ], 1 [ = EIGHTQUEENS\TRYCOL ], * 2 [ = EIGHTQUEENS\TRYCOL 1 ], 3 [ = EIGHTQUEENS\TRYCOL 2 ], 4 [ = EIGHTQUEENS\TRYCOL 3 ], 5 [ = EIGHTQUEENS\TRYCOL 4 ], 6 [ = EIGHTQUEENS ] DBG> The CANCEL SCOPE command restores the default scope search list, which is displayed by the (first) SHOW SCOPE command. In this example, execution is suspended at routine REMOVEQUEEN, after several recursive calls to routine TRYCOL. The asterisk (*) indicates that the scope search list starts with scope 0, the scope of the routine in which execution is suspended. The SET SCOPE/CURRENT command resets the start of the scope search list to scope 2. Scope 2 is the scope of the caller of the routine in which execution is suspended. The asterisk in the output of the (second) SHOW SCOPE command indicates that the scope search list now starts with scope 2. 2.DBG> SET SCOPE 0,STACKS\R2,SCREEN_IO,\ DBG> SHOW SCOPE scope: 0, [= TEST ], STACKS\R2, SCREEN_IO, \ DBG> In this example, the SET SCOPE command directs the debugger to look for symbols without path-name prefixes according to the following scope search list. First the debugger looks in the PC scope (denoted by 0, which is in module TEST). If the debugger cannot find a specified symbol in the PC scope, it then looks in routine R2 of module STACKS; if necessary, it then looks in module SCREEN_IO, and then finally in the global symbol table (denoted by the global scope (\)). The SHOW SCOPE command identifies the current scope search list for symbol lookup. No asterisk is shown in the SHOW SCOPE display unless the default scope search list is in effect or you have entered a SET SCOPE/CURRENT command. 3 SEARCH Identifies the default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) currently in effect for the SEARCH command. Format SHOW SEARCH 4 Description The default qualifiers for the SEARCH command are the default qualifiers last established with the SET SEARCH command. If you did not enter a SET SEARCH command, the default qualifiers are /NEXT and /STRING. Related commands: SEARCH (SET,SHOW) LANGUAGE SET SEARCH 4 Example DBG> SHOW SEARCH search settings: search for next occurrence, as a string DBG> SET SEARCH IDENT 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 first SHOW SEARCH command displays the default settings for the SET SEARCH command. By default, the debugger searches for and displays the next occurrence of the string. The second SHOW SEARCH command indicates that the debugger searches for the next occurrence of the string, but displays 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 third SHOW SEARCH command indicates that the debugger searches for all occurrences of the string, but displays the strings only if they are not bounded on either side by a character that can be part of an identifier in the current language. 3 SELECT Identifies the displays currently selected for each of the display attributes: error, input, instruction, output, program, prompt, scroll, and source. NOTE This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger. Format SHOW SELECT 4 Description The display attributes have the following properties: o A display that has the error attribute displays debugger diagnostic messages. o A display that has the input attribute echoes your debugger input. o A display that has the instruction attribute displays the decoded instruction stream of the routine being debugged. The display is updated when you enter an EXAMINE/INSTRUCTION command. o A display that has the output attribute displays any debugger output that is not directed to another display. o A display that has the program attribute displays program input and output. Currently only the PROMPT display can have the program attribute. o A display that has the prompt attribute is where the debugger prompts for input. Currently, only the PROMPT display can have the PROMPT attribute. o A display that has the scroll attribute is the default display for the SCROLL, MOVE, and EXPAND commands. o A display that has the source attribute displays the source code of the module being debugged, if available. The display is updated when you enter a TYPE or EXAMINE/SOURCE command. Related commands: SELECT SHOW DISPLAY 4 Example DBG> SHOW SELECT display selections: scroll = SRC input = none output = OUT error = PROMPT source = SRC instruction = none program = PROMPT prompt = PROMPT DBG> The SHOW SELECT command identifies the displays currently selected for each of the display attributes. These selections are the defaults for languages. 3 SOURCE Identifies the source directory search lists and search methods currently in effect. Format SHOW SOURCE 4 Qualifiers /DISPLAY Identifies the search list used when the debugger displays source code. /EDIT Identifies the search list to be used during execution of the debugger's EDIT command. 4 Description The SET SOURCE/MODULE=module-name command establishes a source directory search list for a particular module. The SET SOURCE command establishes a source directory search list for all modules not explicitly mentioned in a SET SOURCE/MODULE=module- name command. When you have used those commands, SHOW SOURCE identifies the source directory search list associated with each search category. If a source directory search list has not been established by using the SET SOURCE or SET SOURCE/MODULE=module-name command, the SHOW SOURCE command indicates that no directory search list is currently in effect. In this case, the debugger expects each source file to be in the same directory that it was in at compile time (the debugger also checks that the version number and the creation date and time of a source file match the information in the debugger's symbol table). 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 SHOW SOURCE command identifies the search list of files used for source display (the copied source files in Ada program libraries); the SHOW SOURCE/EDIT command identifies the search list for the source files you edit when using the EDIT command. For information specific to Ada programs, see the Language_Support Ada help topic. Related commands: (SET,CANCEL) SOURCE 4 Examples 1.DBG> SHOW SOURCE no directory search list in effect, match the latest source file version DBG> SET SOURCE [PROJA],[PROJB],DISK:[PETER.PROJC] DBG> SHOW SOURCE source directory search list for all modules, match the latest source file version: [PROJA] [PROJB] DISK:[PETER.PROJC] DBG> In this example, the SET SOURCE command directs the debugger to search the directories [PROJA],[PROJB], and DISK:[PETER.PROJC]. By default, the debugger searches for the latest version of source files. 2.DBG> SET SOURCE/MODULE=CTEST/EXACT [], DISK$2:[PROJD] DBG> SHOW SOURCE source directory search list for CTEST, match the exact source file version: [] DISK$2:[PROJD] source directory search list for all other modules, match the latest source file version: [PROJA] [PROJB] DISK:[PETER.PROJC] DBG> In this example, the SET SOURCE command directs the debugger to search the current default directory ([]) and directory DISK$2:[PROJD] for source files to use with the module CTEST. The /EXACT qualifier specifies that the search will locate the exact version of the CTEST source files found in the debug symbol table. 3 STACK Displays information on the currently active routine calls. Format SHOW STACK [integer] 4 Parameters integer Specifies the number of frames to display. If you omit the parameter, the debugger displays information about all call frames. 4 Description For each call frame, the SHOW STACK command displays information such as the condition handler, saved register values, and the argument list, if any. The latter is the list of arguments passed to the subroutine with that call. In some cases the argument list can contain the addresses of actual arguments. In such cases, use the EXAMINE address-expression command to display the values of these arguments. On VAX processors, each routine invocation results in a call frame on the call stack. On Alpha processors, a routine invocation can result in a stack frame procedure (with a call frame on the stack), a register frame procedure (with a call frame stored in the register set), or a null frame procedure (without a call frame). SHOW STACK provides information on all three: stack frame procedures, register frame procedures, and null frame procedures. (See Example 2 below.) Related command: SHOW CALLS 4 Examples 1.DBG> SHOW STACK stack frame 0 (2146814812) condition handler: 0 SPA: 0 S: 0 mask: ^M PSW: 0000 (hexadecimal) saved AP: 7 saved FP: 2146814852 saved PC: EIGHTQUEENS\%LINE 69 saved R2: 0 argument list:(1) EIGHTQUEENS\%LINE 68+2 stack frame 1 (2146814852) condition handler: SHARE$PASRTL+888 SPA: 0 S: 0 mask: none saved PSW: 0000 (hexadecimal) saved AP: 2146814924 saved FP: 2146814904 saved PC: SHARE$DEBUG+667 DBG> In this example for VAX systems, the SHOW STACK command displays information about all call stack frames at the current PC location. 3 STEP Identifies the default qualifiers (/INTO, /INSTRUCTION, /NOSILENT and so on) currently in effect for the STEP command. Format SHOW STEP 4 Description The default qualifiers for the STEP command are the default qualifiers last established by the SET STEP command. If you did not enter a SET STEP command, the default qualifiers are /LINE, /OVER, /NOSILENT, and /SOURCE. Enabling screen mode by pressing PF1-PF3 enters the SET STEP NOSOURCE command as well as the SET MODE SCREEN command (to eliminate redundant source display in output and DO displays). In that case, the default qualifiers are /LINE, /OVER, /NOSILENT, and /NOSOURCE. Related commands: STEP SET STEP 4 Example DBG> SET STEP INTO,NOSYSTEM,NOSHARE,INSTRUCTION,NOSOURCE DBG> SHOW STEP step type: nosystem, noshare, nosource, nosilent, into routine calls, by instruction DBG> In this example, the SHOW STEP command indicates that the debugger take the following actions: o Steps into called routines, but not those in system space or in shareable images o Steps by instruction o Does not display lines of source code while stepping 3 SYMBOL Displays information about the symbols in the debugger's run-time symbol table (RST) for the current image. NOTE The current image is either the main image (by default) or the image established as the current image by a previous SET IMAGE command. Format SHOW SYMBOL symbol-name[, . . . ] [IN scope[, . . . ]] 4 Parameters symbol-name Specifies a symbol to be identified. A valid symbol name is a single identifier or a label name of the form %LABEL n, where n is an integer. Compound names such as RECORD.FIELD or ARRAY[1,2] are not valid. If you specify the asterisk (*) wildcard character by itself, all symbols are listed. You can use the wildcard within a symbol name. scope Specifies the name of a module, routine, or lexical block, or a numeric scope. It has the same syntax as the scope specification in a SET SCOPE command and can include path-name qualification. All specified scopes must be in set modules in the current image. The SHOW SYMBOL command displays only those symbols in the RST for the current image that both match the specified name and are declared within the lexical entity specified by the scope parameter. If you omit this parameter, all set modules and the global symbol table (GST) for the current image are searched for symbols that match the name specified by the symbol-name parameter. 4 Qualifiers /ADDRESS Displays the address specification for each selected symbol. The address specification is the method of computing the symbol's address. It can merely be the symbol's memory address, but it can also involve indirection or an offset from a register value. Some symbols have address specifications too complicated to present in any understandable way. These address specifications are labeled "complex address specifications." On Alpha processors, the command SHOW SYMBOL/ADDRESS procedure- name displays both the code address and procedure descriptor address of a specified routine, entry point, or Ada package. /DEFINED Displays symbols you have defined with the DEFINE command (symbol definitions that are in the DEFINE symbol table). /DIRECT Displays only those symbols that are declared directly in the scope parameter. Symbols declared in lexical entities nested within the scope specified by the scope parameters are not shown. /FULL Displays all information associated with the /ADDRESS, /TYPE, and /USE_CLAUSE qualifiers. For C++ modules, if symbol-name is a class, SHOW SYMBOL/FULL also displays information about the class. /LOCAL Displays symbols that are defined with the DEFINE/LOCAL command (symbol definitions that are in the DEFINE symbol table). /TYPE Displays data type information for each selected symbol. /USE_CLAUSE (Applies to Ada programs.) Identifies any Ada package that a specified block, subprogram, or package names in a use clause. If the symbol specified is a package, also identifies any block, subprogram, package, and so on, that names the specified symbol in a use clause. 4 Description The SHOW SYMBOL command displays information that the debugger has about a given symbol in the current image. This information might not be the same as what the compiler had or even what you see in your source code. Nonetheless, it is useful for understanding why the debugger might act as it does when handling symbols. If you do not specify a qualifier, the SHOW SYMBOL command lists all of the possible declarations or definitions of a specified symbol that exist in the RST for the current image (that is, in all set modules and in the GST for that image). Symbols are displayed with their path names. A path name identifies the search scope (module, nested routines, blocks, and so on) that the debugger must follow to reach a particular declaration of a symbol. When specifying symbolic address expressions in debugger commands, use path names only if a symbol is defined multiple times and the debugger cannot resolve the ambiguity. The /DEFINED and /LOCAL qualifiers display information about symbols defined with the DEFINE command (not the symbols that are derived from your program). The other qualifiers display information about symbols defined within your program. For information specific to Ada programs, type Help Language_Support Ada. Related commands: DEFINE DELETE SET MODE [NO]LINE SET MODE [NO]SYMBOLIC SHOW DEFINE SYMBOLIZE 4 Examples 1.DBG> SHOW SYMBOL I data FORARRAY\I DBG> This command shows that symbol I is defined in module FORARRAY and is a variable (data) rather than a routine. 2.DBG> SHOW SYMBOL/ADDRESS INTARRAY1 data FORARRAY\INTARRAY1 descriptor address: 0009DE8B DBG> This command shows that symbol INTARRAY1 is defined in module FORARRAY and has a memory address of 0009DE8B. 3.DBG> SHOW SYMBOL *PL* This command lists all the symbols whose names contain the string "PL". 4.DBG> SHOW SYMBOL/TYPE COLOR data SCALARS\MAIN\COLOR enumeration type (primary, 3 elements), size: 4 bytes This command shows that the variable COLOR is an enumeration type. 5.DBG> SHOW SYMBOL/TYPE/ADDRESS * This command displays all information about all symbols. 6.DBG> SHOW SYMBOL * IN MOD3\COUNTER routine MOD3\COUNTER data MOD3\COUNTER\X data MOD3\COUNTER\Y DBG> This command lists all the symbols that are defined in the scope denoted by the path name MOD3\COUNTER. 7.DBG> DEFINE/COMMAND SB=SET BREAK DBG> SHOW SYMBOL/DEFINED SB defined SB bound to: SET BREAK was defined /command DBG> In this example, the DEFINE/COMMAND command defines SB as a symbol for the SET BREAK command. The SHOW SYMBOL/DEFINED command displays that definition. 3 TASK 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 PTHREAD thread -f thread-number 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 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 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 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. /STATISTICS (Compaq Ada on VAX only) Displays task statistics for the entire tasking system. This information enables you to measure the performance of your tasking program. The larger the number of total schedulings (also known as context switches), the more tasking overhead there is. /TIME_SLICE (VAX only) Displays the current time-slice value, in seconds, as specified by a previous SET TASK/TIME_SLICE command. If no SET TASK/TIME_SLICE command was previously entered, displays the time-slice value, if any, that was specified in the program. If no time-slice value was previously established, the value is 0.0-that is, time slicing is disabled. /TIME_SLICE is valid only when the event facility is ADA. 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 TERMINAL Identifies the current terminal screen height (page) and width being used to format output. NOTE This command is not available in the Compaq 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 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 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 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. /STATISTICS (Compaq Ada on VAX only) Displays task statistics for the entire tasking system. This information enables you to measure the performance of your tasking program. The larger the number of total schedulings (also known as context switches), the more tasking overhead there is. /TIME_SLICE (VAX only) Displays the current time-slice value, in seconds, as specified by a previous SET TASK/TIME_SLICE command. If no SET TASK/TIME_SLICE command was previously entered, displays the time-slice value, if any, that was specified in the program. If no time-slice value was previously established, the value is 0.0-that is, time slicing is disabled. /TIME_SLICE is valid only when the event facility is ADA. 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 VECTOR_MODE Identifies the current vector mode (synchronized or nonsynchronized). Applies to VAX vectorized programs. Format SHOW VECTOR_MODE 4 Description The current vector mode is the mode established with the SET VECTOR_MODE command. If you did not enter a SET VECTOR_MODE command, the default vector mode is NONSYNCHRONIZED. Related commands: SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only) SYNCHRONIZE VECTOR_MODE (VAX only) 4 Example DBG> SHOW VECTOR_MODE Vector mode is nonsynchronized DBG> SET VECTOR_MODE SYNCHRONIZED DBG> SHOW VECTOR_MODE Vector mode is synchronized DBG> The SHOW VECTOR_MODE command indicates the effect of the SET VECTOR_MODE command. 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 Compaq 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 Compaq 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 Compaq 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 STEP Executes the program up to the next line, instruction, or other specified location. Format STEP [integer] 3 Parameters integer A decimal integer that specifies the number of step units (lines, instructions, and so on) to be executed. If you omit the parameter, the debugger executes one step unit. 3 Qualifiers /BRANCH Executes the program to the next branch instruction. STEP/BRANCH has the same effect as SET BREAK/TEMPORARY/BRANCH;GO. /CALL Executes the program to the next call or return instruction. STEP/CALL has the same effect as SET BREAK/TEMPORARY/CALL;GO. /EXCEPTION Executes the program to the next exception, if any. STEP/EXCEPTION has the same effect as SET BREAK/TEMPORARY/EXCEPTION;GO. If no exception occurs, STEP/EXCEPTION has the same effect as GO. /INSTRUCTION /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) When you do not specify an opcode, executes the program to the next instruction. STEP/INSTRUCTION has the same effect as SET BREAK/TEMPORARY/INSTRUCTION;GO. On VAX processors, you can specify one or more opcodes; the debugger executes the program to the next instruction whose opcode is in the list. The following commands are equivalent: DBG> STEP/INSTRUCTION=(opcode[, . . . ]) DBG> SET BREAK/TEMPORARY/INSTRUCTION=(opcode[, . . . ]);GO On VAX processors, you can specify vector instructions; do not include an instruction qualifier (/UNALIGNED_DATA, /VECTOR_ INSTRUCTION, /MODIFY, /0, or /1) with the instruction mnemonic. /INTO If execution is currently suspended at a routine call, STEP/INTO executes the program up to the beginning of that routine (steps into that routine). Otherwise, STEP/INTO has the same effect as STEP without a qualifier. The /INTO qualifier is the opposite of /OVER (the default behavior). NOTE On Alpha processors, when execution is stopped at an exception break, STEP/INTO does not transfer control to a user exception handler. Stop execution within the handler by setting a breakpoint in the handler. The STEP/INTO behavior can be changed by also using the /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers. /JSB /JSB /NOJSB (VAX only) Qualifies a previous SET STEP INTO command or a current STEP/INTO command. If execution is currently suspended at a routine call and the routine is called by a JSB instruction, STEP/INTO/NOJSB has the same effect as STEP/OVER. Otherwise, STEP/INTO/NOJSB has the same effect as STEP/INTO. Use STEP/INTO/JSB to override a previous SET STEP NOJSB command. STEP/INTO/JSB enables STEP/INTO to step into routines called by a JSB instruction, as well as into routines called by a CALL instruction. The /JSB qualifier is the default for all languages except DIBOL. The /NOJSB qualifier is the default for DIBOL. In DIBOL, application-declared routines are called by the CALL instruction and DIBOL Run-Time Library routines are called by the JSB instruction. /LINE Executes the program to the next line of source code. However, the debugger skips over any source lines that do not result in executable code when compiled (for example, comment lines). STEP/LINE has the same effect as SET BREAK/TEMPORARY/LINE;GO. This is the default behavior for all languages. /OVER If execution is currently suspended at a routine call, STEP/OVER executes the routine up to and including the routine's return instruction (steps over that routine). The /OVER qualifier is the default behavior and is the opposite of /INTO. NOTE On Alpha processors, when execution is suspended at a source line that contains a loop with a routine call, STEP/OVER steps into the called routine. To step to the next program statement, set a temporary breakpoint at the statement and enter GO. /RETURN Executes the routine in which execution is currently suspended up to its return instruction (that is, up to the point just prior to transferring control back to the calling routine). This enables you to inspect the local environment (for example, obtain the values of local variables) before the return instruction deletes the routine's call frame from the call stack. STEP/RETURN has the same effect as SET BREAK/TEMPORARY/RETURN;GO. STEP/RETURN n executes the program up n levels of the call stack. /SEMANTIC_EVENT (Alpha only) Executes the program to the next semantic event. STEP/SEMANTIC_EVENT simplifies debugging optimized code. (See the Description section.) /SHARE /SHARE (default) /NOSHARE Qualifies a previous SET STEP INTO command or a current STEP/INTO command. If execution is currently suspended at a call to a shareable image routine, STEP/INTO/NOSHARE has the same effect as STEP/OVER. Otherwise, STEP/INTO/NOSHARE has the same effect as STEP/INTO. Use STEP/INTO/SHARE to override a previous SET STEP NOSHARE command. STEP/INTO/SHARE enables STEP/INTO to step into shareable image routines, as well as into other kinds of routines. /SILENT /SILENT /NOSILENT (default) Controls whether the "stepped to . . . " message and the source line for the current location are displayed after the STEP has completed. 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. /SOURCE /SOURCE (default) /NOSOURCE Controls whether the source line for the current location is displayed after the STEP has completed. 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. /SYSTEM /SYSTEM (default) /NOSYSTEM Qualifies a previous SET STEP INTO command or a current STEP/INTO command. If execution is currently suspended at a call to a system routine (in P1 space), STEP/INTO/NOSYSTEM has the same effect as STEP/OVER. Otherwise, STEP/INTO/NOSYSTEM has the same effect as STEP/INTO. Use STEP/INTO/SYSTEM to override a previous SET STEP NOSYSTEM command. STEP/INTO/SYSTEM enables STEP/INTO to step into system routines, as well as into other kinds of routines. /VECTOR_INSTRUCTION (VAX only) Executes the program to the next vector instruction. STEP/VECTOR_INSTRUCTION has the same effect as SET BREAK/TEMPORARY/VECTOR_INSTRUCTION;GO. 3 Description The STEP command is one of the four debugger commands that can be used to execute your program (the others are CALL, EXIT, and GO). The behavior of the STEP command depends on the following factors: o The default STEP mode previously established with a SET STEP command, if any o The qualifier specified with the STEP command, if any o The number of step units specified as the parameter to the STEP command, if any If no SET STEP command was previously entered, the debugger takes the following default actions when you enter a STEP command without specifying a qualifier or parameter: 1. Executes a line of source code (the default is STEP/LINE). 2. Reports that execution has completed by issuing a "stepped to . . . " message (the default is STEP/NOSILENT). 3. Displays the line of source code at which execution is suspended (the default is STEP/SOURCE). 4. Issues the prompt. The following qualifiers affect the location to which you step: /BRANCH /CALL /EXCEPTION /INSTRUCTION /INSTRUCTION=(opcode[, . . . ]) (VAX only) /LINE /RETURN /SEMANTIC_EVENT (Alpha only) /VECTOR_INSTRUCTION (VAX only) The following qualifiers affect what output is seen upon completion of a step: /[NO]SILENT /[NO]SOURCE The following qualifiers affect what happens at a routine call: /INTO /[NO]JSB (VAX only) /OVER /[NO]SHARE /[NO]SYSTEM If you plan to enter several STEP commands with the same qualifiers, you can first use the SET STEP command to establish new default qualifiers (for example, SET STEP INTO, NOSYSTEM makes the STEP command behave like STEP/INTO/NOSYSTEM). Then you do not have to use those qualifiers with the STEP command. You can override the current default qualifiers for the duration of a single STEP command by specifying other qualifiers. Use the SHOW STEP command to identify the current STEP defaults. 3 Description,_Continued... If an exception breakpoint is triggered (resulting from a SET BREAK/EXCEPTION or a STEP/EXCEPTION command), execution is suspended before any application-declared condition handler is started. If you then resume execution with the STEP command, the debugger resignals the exception and the program executes to the beginning of (steps into) the condition handler, if any. On Alpha systems, if your program has been compiled with the /OPTIMIZE qualifier, semantic stepping mode is available, with the STEP/SEMANTIC_EVENT and SET STEP SEMANTIC_EVENT commands. When you are debugging optimized code, the apparent source program location tends to bounce back and forth, with the same line appearing repeatedly. In semantic stepping mode, the program executes to the next point in the program where a significant effect (semantic event) occurs. A semantic event is one of the following: o Data event - An assignment to a user variable o Control event - A control flow decision, with a conditional or unconditional transfer of control, other than a call o Call event - A call (to a routine that is not stepped over) or a return from a call Not every assignment, transfer of control, or call is a semantic event. The major exceptions are as follows: o When two instructions are required to assign to a complex or X_floating value, only the first instruction is treated as a semantic event. o When there are multiple branches that are part of a single higher-level construct, such as a decision tree of branches that implement a case or select construct, then only the first is treated as a semantic event. o When a call is made to a routine that is a compiler-specific helper routine, such as a call to OTS$MOVE, which handles certain kinds of string or storage copy operations, the call is not considered a semantic event. Control will not stop at the call. To step into such a routine, you must do either of the following: - Set a breakpoint at the routine entry point. - Use a series of STEP/INSTRUCTION commands to reach the call of interest and then use STEP/INSTRUCTION/INTO to enter the called routine. o When there is more than one potential semantic event in a row with the same line number, only the first is treated as a semantic event. The STEP/SEMANTIC_EVENT command causes a breakpoint to be set at the next semantic event. Execution proceeds to that next event. Parts of any number of different lines and statements may be executed along the way, without interfering with progress. When the semantic event is reached (that is, when the instruction associated with that event is reached but not yet executed), execution is suspended (similar to reaching the next line when STEP/LINE is used). If you are debugging a multiprocess program, the STEP command is executed in the context of the current process set. In addition, when debugging a multiprocess program, the way in which execution continues in your process depends on whether you entered a SET MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By default (SET MODE NOINTERRUPT), when one process stops, the debugger takes no action with regard to the other processes. Also by default (SET MODE WAIT), the debugger waits until all process in the current process set have stopped before prompting for a new command. On VAX systems, the STEP/OVER command results in stepping into, not over, Fortran Run-Time Library routines. For more information, see the OpenVMS Debugger Manual. Related commands: CALL EXIT GO SET BREAK/EXCEPTION SET MODE [NO]INTERRUPT SET PROCESS (SET,SHOW) STEP 3 Examples 1.DBG> SHOW STEP step type: source, nosilent, by line, over routine calls DBG> STEP stepped to SQUARES$MAIN\%LINE 4 4: OPEN(UNIT=8, FILE='DATAFILE.DAT', STATUS='OLD') DBG> In this example, the SHOW STEP command identifies the default qualifiers currently in effect for the STEP command. In this case, the STEP command, without any parameters or qualifiers, executes the next line of source code. After the STEP command has completed, execution is suspended at the beginning of line 4. 2.DBG> STEP 5 stepped to MAIN\%LINE 47 47: SWAP(X,Y); DBG> This command executes the next 5 lines of source code. After the STEP command has completed, execution is suspended at the beginning of line 47. 3.DBG> STEP/INTO stepped to routine SWAP 23: procedure SWAP (A,B: in out integer) is DBG> STEP stepped to MAIN\SWAP\%LINE 24 24: TEMP: integer := 0; DBG> STEP/RETURN stepped on return from MAIN\SWAP\%LINE 24 to MAIN\SWAP\%LINE 29 29: end SWAP; DBG> In this example, execution is paused at a call to routine SWAP, and the STEP/INTO command executes the program up to the beginning of the called routine. The STEP command executes the next line of source code. The STEP/RETURN command executes the rest of routine SWAP up to its RET instruction (that is, up to the point just prior to transferring control back to the calling routine). 2 STOP Interrupts all specified processes that are running. Format STOP [process-spec[, . . . ] 3 Parameters process-spec This parameter specifies the process set to be stopped. The default is the current process set. 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 all processes. 3 Description The STOP command interrupts the specified processes. You can use the STOP command in nowait mode to stop processes that are still running. 3 Examples 1.all> SHOW PROCESS Number Name State Current PC 1 DBGK$$2727282C break SERVER\main\%LINE 18834 2 USER1_2 running not available * 3 USER1_3 running not available all> CLIENTS> STOP all> show process Number Name State Current PC 1 DBGK$$2727282C break SERVER\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,CANCEL) 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 SYNCHRONIZE 3 VECTOR_MODE Forces immediate synchronization between the scalar and vector processors. Applies to VAX vectorized programs. Format SYNCHRONIZE VECTOR_MODE 4 Description The SYNCHRONIZE VECTOR_MODE command forces immediate synchronization between the scalar and vector processors by issuing SYNC and MSYNC instructions. The effect is as follows: o Any exception that was caused by a vector instruction and was still pending delivery is immediately delivered. Forcing the delivery of a pending exception triggers an exception breakpoint or tracepoint (if one was set) or invokes an exception handler (if one is available at that location in the program). o Any read or write operation between vector registers and either the general registers or memory is completed immediately. That is, any vector memory instruction that was still being executed completes execution. Entering the SYNCHRONIZE VECTOR_MODE command is equivalent to issuing SYNC and MSYNC instructions at the location in the program at which execution is suspended. By default, the debugger does not force synchronization between the scalar and vector processors during program execution (SET VECTOR_MODE NOSYNCHRONIZED). To force such synchronization, use the SET VECTOR_MODE SYNCHRONIZED command. Related commands: SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only) SHOW VECTOR_MODE (VAX only) 4 Examples 1.DBG> SYNCHRONIZE VECTOR_MODE %DEBUG-I-SYNCREPCOM, Synchronize reporting complete This command forces immediate synchronization between the scalar and vector processors. In this example, the diagnostic message indicates that the synchronization operation has completed and that all pending vector exceptions have been delivered and reported. 2.DBG> STEP 1 stepped to .MAIN.\SUB\%LINE 99 99: VVDIVD V1,V0,V2 DBG> STEP 2 stepped to .MAIN.\SUB\%LINE 100 100: CLRL R0 DBG> EXAMINE/FLOAT %V2 3 0\%V2 [0]: 13.53400 [1]: Reserved operand, encoded as floating divide by zero [2]: 247.2450 . . . DBG> SYNCHRONIZE VECTOR_MODE 4 %SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, mask=00000004, PC=000002E1, PSL=03C00010 break on unhandled exception preceding .MAIN.\SUB\%LINE 100 100: CLRL R0) DBG> The comments that follow refer to the callouts in the previous example: 1 This STEP command suspends program execution on line 99, just before a VVDIVD instruction is executed. Assume that, in this example, the instruction will trigger a floating- point divide-by-zero exception. 2 This STEP command executes the VVDIVD instruction. Note, however, that the exception is not delivered at this point in the execution of the program. 3 The EXAMINE/FLOAT command displays a decoded exception message in element 1 of the destination register, V2. This confirms that a floating-point divide-by-zero exception was triggered and is pending delivery. 4 The SYNCHRONIZE VECTOR_MODE command forces the immediate delivery of the pending vector exception. 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).