OpenVMS Debugger Manual

Document revision date: 19 July 1999

OpenVMS Debugger Manual

Contents

Index

DEFINE/PROCESS_GROUP

Assigns a symbolic name to a list of process specifications.
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS).

Format

DEFINE/PROCESS_GROUP process-group-name =process-spec[,...]

Parameters

process-group-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] proc-name The process name, if that name contains no space or lowercase characters. The process name can include the asterisk (*) wildcard character.

[%PROCESS_NAME] " proc-name" The process name, if that name contains space characters or lowercase characters. You can also use apostrophes (') instead of quotation marks (").

%PROCESS_PID proc-id The process identifier (PID, a hexadecimal number).

%PROCESS_NUMBER proc-number
(or %PROC proc-number) The number assigned to a process when it comes under debugger control. Process numbers appear in a SHOW PROCESS display.

proc-group-name A symbol defined with the DEFINE/PROCESS_GROUP command to represent a group of processes. Do not specify a recursive symbol definition.

%NEXT_PROCESS The process after the visible process in the debugger's circular process list.

%PREVIOUS_PROCESS The process previous to the visible process in the debugger's circular process list.

%VISIBLE_PROCESS The process whose call stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.

If you do not specify a process, the symbolic name is created but contains no process entries.

Description

The DEFINE/PROCESS_GROUP 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_GROUP 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_GROUP command, use the SHOW SYMBOL/DEFINED command. To delete a symbol that was defined with the DEFINE/PROCESS_GROUP command, use the DELETE command.
Related commands:

DELETE
(SET,SHOW) DEFINE
SHOW SYMBOL/DEFINED

Examples

#1
DBG_1> DEFINE/PROCESS_GROUP SERVERS=FILE_SERVER,NETWORK_SERVER DBG_1> SHOW PROCESS SERVERS Number Name Hold State Current PC * 1 FILE_SERVER step FS_PROG\%LINE 37 2 NETWORK_SERVER break NET_PROG\%LINE 24 DBG_1>

DBG_1> DEFINE/PROCESS_GROUP SERVERS=FILE_SERVER,NETWORK_SERVER
DBG_1> SHOW PROCESS SERVERS
 Number  Name         Hold  State   Current PC 
*    1 FILE_SERVER          step    FS_PROG\%LINE 37 
     2 NETWORK_SERVER       break   NET_PROG\%LINE 24
DBG_1>

This DEFINE/PROCESS_GROUP command assigns the symbolic name SERVERS to the process group consisting of FILE_SERVER and NETWORK_SERVER. The SHOW PROCESS SERVERS command displays information about the processes that make up the group SERVERS.

#2
USER_3> DEFINE/PROCESS_GROUP G1=%PROCESS_NUMBER 1,%VISIBLE_PROCESS USER_3> SHOW SYMBOL/DEFINED G1 defined G1 bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS" was defined /process_group USER_3> DELETE G1

USER_3> DEFINE/PROCESS_GROUP G1=%PROCESS_NUMBER 1,%VISIBLE_PROCESS
USER_3> SHOW SYMBOL/DEFINED G1
defined G1 
    bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS" 
    was defined /process_group
USER_3> DELETE G1

This DEFINE/PROCESS_GROUP command assigns the symbolic name G1 to the process group 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
DBG_2> DEFINE/PROCESS_GROUP A = B,C,D DBG_2> DEFINE/PROCESS_GROUP B = E,F,G DBG_2> DEFINE/PROCESS_GROUP E = I,J,A %DEBUG-E-NORECSYM, recursive PROCESS_GROUP symbol definition encountered at or near "A"

DBG_2> DEFINE/PROCESS_GROUP A = B,C,D
DBG_2> DEFINE/PROCESS_GROUP B = E,F,G
DBG_2> DEFINE/PROCESS_GROUP E = I,J,A
%DEBUG-E-NORECSYM, recursive PROCESS_GROUP symbol definition 
     encountered at or near "A"

This series of DEFINE/PROCESS_GROUP commands illustrate valid and invalid uses of the command.

DELETE

Deletes a symbol definition that was established with the DEFINE command.

Format

DELETE [symbol-name[,...]]

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.

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.

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

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.

DELETE/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 DECwindows Motif interface to the debugger.

Format

DELETE/KEY [key-name]

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 Name LK201 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 period (.) Keypad period (.)

COMMA Keypad comma (,) Keypad comma (,)

MINUS Keypad minus (-) Keypad minus (-)

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

Key Name	LK201 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 period (.)	Keypad period (.)
COMMA	Keypad comma (,)	Keypad comma (,)
MINUS	Keypad minus (-)	Keypad minus (-)
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

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

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

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.

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

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.

Qualifiers

/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

/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: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

/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

/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

/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

/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

/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: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

/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=(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[: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.

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:

Variable names. When specifying a variable with the DEPOSIT command, use the same syntax that is used in the source code.
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:

It evaluates the address expression specified to the left of the equal sign, to yield a program location.
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.
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.
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.

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:

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

Previous Next Contents Index

privacy and legal statement

4538PRO_044.HTML

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