OpenVMS DCL Dictionary

In this example, the user has defined keys PF1 to PF4 in the default state. The DELETE/KEY command deletes all key definitions in the current state, which is the default state. #2

$ DEFINE/KEY PF3 "SHOW TIME" /TERMINATE
%DCL-I-DEFKEY, DEFAULT key PF3 has been defined
$ [PF3]
$ SHOW TIME
 14-DEC-1994 14:43:59 
   .
   .
   .
$ DELETE/KEY PF3
%DCL-I-DELKEY, DEFAULT key PF3 has been deleted
$ [PF3]
$

In this example, the DEFINE/KEY command defines the PF3 key on the keypad as SHOW TIME. To delete the definition for the PF3 key, use the DELETE/KEY command. When the user presses PF3, only the system prompt is displayed.

DELETE/QUEUE

Deletes a print or batch queue created by the INITIALIZE/QUEUE command, and deletes all the jobs in the queue. The /QUEUE qualifier is required.
Requires manage (M) access to the queue.

Format

DELETE/QUEUE queue-name[:]

PARAMETER

queue-name[:]
Specifies the name of the queue to be deleted.

DESCRIPTION

To delete a queue, use the following procedure:

Stop the specified queue by using the STOP/QUEUE/NEXT command.
The STOP/QUEUE/NEXT command stops the specified queue after all executing jobs have completed processing. Wait for any executing jobs to complete processing.
Make sure that there are no outstanding references to the specified queue.
If a generic queue refers to the specified queue as a target execution queue, you must remove the specified queue from the list of target execution queues.
If a logical queue refers to the specified queue, you must deassign the logical queue.
If the specified queue is a generic queue, jobs that were entered initially on the generic queue and still exist on any of its target queues count as references to the specified queue. Before you can delete the specified queue, you must delete any jobs that were submitted originally to the specified queue and are executing on its target queues, or you must wait until these jobs have completed processing.
To move jobs from the specified queue to another queue, use the SET ENTRY/REQUEUE or ASSIGN/MERGE commands. Any jobs that remain in the specified queue are deleted when the queue is deleted.
Enter the DELETE/QUEUE command.

QUALIFIER

/LOG

/NOLOG (default)
Controls whether the DELETE/QUEUE command displays the name of each queue after it is deleted.

Example

$ INITIALIZE/QUEUE/DEFAULT=FLAG/START/ON=LPA0 LPA0_QUEUE
   .
   .
   .
$ STOP/QUEUE/NEXT LPA0_QUEUE
$ DELETE/QUEUE LPA0_QUEUE

In this example, the first command initializes and starts the printer queue LPA0_QUEUE. The STOP/QUEUE/NEXT command stops the queue. The DELETE/QUEUE command deletes the queue.

DELETE/QUEUE/MANAGER

Deletes a queue manager on a node or VAXcluster system. All queues and jobs managed by the specified queue manager are also deleted. You must first stop the queue manager. The /NAME_OF_MANAGER qualifier is required.
Requires OPER (operator) and SYSNAM (system logical name) privileges.

Format

DELETE/QUEUE/MANAGER/NAME_OF_MANAGER=name

PARAMETER

None.

DESCRIPTION

To delete a queue manager, use the following procedure:

Stop the specified queue manager by using the STOP/QUEUE/MANAGER/CLUSTER/NAME_OF_MANAGER=name command.
Enter the DELETE/QUEUE/MANAGER/NAME_OF_MANAGER command, specifying the queue manager name.

QUALIFIER

/NAME_OF_MANAGER=string
Identifies the name of the queue manager to be deleted. The /NAME_OF_MANAGER qualifier is required. The required name value can be up to 31 characters long and can be a logical name.

Example

$ DELETE/QUEUE/MANAGER/NAME_OF_MANAGER=BATCH_MANAGER

The DELETE/QUEUE/MANAGER/NAME_OF_MANAGER command in this example deletes the queue manager named BATCH_MANAGER. The command removes all references to the specified queue manager from the shared master file of the queue database and deletes the queue and journal files associated with the BATCH_MANAGER's database.

DELETE/SYMBOL

Deletes one or all symbol definitions from a local or global symbol table. The /SYMBOL qualifier is required.

Format

DELETE/SYMBOL [symbol-name]

PARAMETER

symbol-name
Specifies the name of the symbol to be deleted. A name is required unless the /ALL qualifier is specified. The symbol-name parameter is incompatible with the /ALL qualifier. Symbol names can have from 1 to 255 characters. By default, the DELETE/SYMBOL command assumes that the symbol is in the local symbol table for the current command procedure.

DESCRIPTION

The DELETE/SYMBOL command deletes a symbol definition from a symbol table. If you do not specify either the global or local symbol table, the symbol is deleted from the local table. If you specify both the /GLOBAL and /LOCAL qualifiers, only the last specified qualifier is accepted. The /SYMBOL qualifier must always immediately follow the DELETE command name.

QUALIFIERS

/ALL
Deletes all symbols from the specified table. If you do not specify either the /LOCAL or the /GLOBAL qualifier, all symbols defined at the current command level are deleted. The /ALL qualifier is incompatible with the symbol-name parameter.
/GLOBAL
Deletes the symbol from the global symbol table of the current process.
/LOCAL (default)
Deletes the symbol from the local symbol table of the current process.
/LOG

/NOLOG (default)
Controls whether an informational message listing each symbol being deleted is displayed.

Examples

$ DELETE/SYMBOL/ALL

In this example, the DELETE/SYMBOL command deletes all symbol definitions at the current command level.

$ DELETE/SYMBOL/LOG KUDOS
%DCL-I-DELSYM, LOCAL symbol KUDOS has been deleted

In this example, the DELETE/SYMBOL command deletes the symbol KUDOS from the local symbol table for the current process. In addition, the /LOG qualifier causes an informational message, listing the symbol being deleted, to be displayed.

$ DELETE/SYMBOL/GLOBAL PDEL

In this example, the DELETE/SYMBOL command deletes the symbol named PDEL from the global symbol table for the current process.

DEPOSIT

Replaces the contents of the specified locations in virtual memory and displays the new contents.
The DEPOSIT command, together with the EXAMINE command, aids in debugging programs interactively. The DCL command DEPOSIT is similar to the DEPOSIT command of the OpenVMS Debugger.
Requires user-mode read (R) and write (W) access to the virtual memory location whose contents you wish to change.

Format

DEPOSIT location=data[,...]

PARAMETERS

location
Specifies the starting virtual address or range of virtual addresses (where the second address is larger than the first) whose contents are to be changed. A location can be any valid integer expression containing an integer value, a symbol name, a lexical function, or a combination of these entities. Radix qualifiers determine the radix in which the address is interpreted; hexadecimal is the initial default radix. Symbol names are always interpreted in the radix in which they were defined. The radix operators %X, %D, or %O can precede the location. A hexadecimal value must begin with a number (or be preceded by %X).
The specified location must be within the virtual address space of the image currently running in the process.
The DEPOSIT and EXAMINE commands maintain a pointer to a current memory location. The DEPOSIT command sets this pointer to the byte following the last byte modified; you can refer to this pointer by using a period (.) in subsequent EXAMINE and DEPOSIT commands. If the DEPOSIT command cannot deposit the specified data, the pointer does not change. The EXAMINE command does not change the value of the pointer.
data[,...]
Specifies the data to be deposited into the specified locations. By default, the data is assumed to be in hexadecimal format; it is then converted to binary format and is written into the specified location.
If you specify more than one item, separate the items with commas (,). The DEPOSIT command writes the data in consecutive locations, beginning with the address specified.
When non-ASCII data is deposited, you can specify each item of data using any valid integer expression.
When ASCII data is deposited, only one item of data is allowed. All characters to the right of the equal sign are considered to be part of a single string. The characters are converted to uppercase, and all spaces are compressed.

DESCRIPTION

When the DEPOSIT command completes, it displays both the virtual memory address into which data is deposited and the new contents of the location, as follows:
address:  contents 
If the specified address can be read from but not written to by the current access mode, the DEPOSIT command displays the original contents of the location. If the specified address can be neither read from nor written to, the DEPOSIT command displays asterisks (*) in the data field. The DEPOSIT command maintains a pointer at that location (at the byte following the last byte modified).
If you specify a list of numeric values, some but not all of the values may be successfully deposited before an access violation occurs. If an access violation occurs while ASCII data is being deposited, nothing is deposited.
Radix Qualifiers: The radix default for a DEPOSIT or EXAMINE command determines how the command interpreter interprets numeric literals. The initial default radix is hexadecimal; all numeric literals in the command line are assumed to be hexadecimal values. If a radix qualifier modifies the command, that radix becomes the default for subsequent EXAMINE and DEPOSIT commands, until another qualifier overrides it. For example:
$ DEPOSIT/DECIMAL 900=256
00000384:  256
The DEPOSIT command interprets both the location 900 and the value 256 as decimal. All subsequent DEPOSIT and EXAMINE commands assume that numbers you enter for addresses and data are decimal. Note that the DEPOSIT command always displays the address location in hexadecimal.
Symbol values defined by = (assignment statement) commands are always interpreted in the radix in which they were defined.
Note that hexadecimal values entered as deposit locations or as data to be deposited must begin with a numeric character (0 to 9). Otherwise, the command interpreter assumes that you have entered a symbol name and attempts symbol substitution.
You can use the radix operators %X, %D, or %O to override the current default when you enter the DEPOSIT command. For example:
$ DEPOSIT/DECIMAL %X900=10
This command deposits the decimal value 10 in the location specified as hexadecimal 900.
Length Qualifiers: The initial default length unit for the DEPOSIT command is a longword. If a list of data values is specified, the data is deposited into consecutive longwords beginning at the specified location. If a length qualifier modifies the command, that length becomes the default for subsequent EXAMINE and DEPOSIT commands, until another qualifier overrides it. If you specify data values that are longer than the specified length, an error occurs.
Length qualifiers are ignored when ASCII values are deposited.
Restriction on Placement of Qualifiers: The DEPOSIT command analyzes expressions arithmetically. Therefore, qualifiers, which must be preceded by a slash (/), must appear immediately after the command name to be interpreted correctly.

QUALIFIERS

/ASCII
Indicates that the specified data is ASCII.
Only one data item is allowed; all characters to the right of the equal sign (=) are considered to be part of a single string. Unless they are enclosed within quotation marks (" "), characters are converted to uppercase and multiple spaces are compressed to a single space before the data is written in memory.
The DEPOSIT command converts the data to its binary equivalent before placing it in virtual memory. When you specify /ASCII, or when ASCII mode is the default, the location you specify is assumed to be hexadecimal.
/BYTE
Requests that data be deposited 1 byte at a time.
/DECIMAL
Indicates that the data is decimal. The DEPOSIT command converts the data to its binary equivalent before placing it in virtual memory.
/HEXADECIMAL
Indicates that the data is hexadecimal. The DEPOSIT command converts the data to its binary equivalent before placing it in virtual memory.
/LONGWORD
Requests that data be deposited a longword at a time.
/OCTAL
Indicates that the data is octal. The DEPOSIT command converts the data to its binary equivalent before placing it in virtual memory.
/WORD
Requests that the data be deposited one word at a time.

Examples

$ RUN MYPROG
   .
   .
   .
 
[Ctrl/Y]
$ EXAMINE %D2145876444
7FE779DC:  0000000000
$ DEPOSIT .=17
7FE779DC:  0000000017
$ CONTINUE

The RUN command executes the image MYPROG.EXE; subsequently, Ctrl/Y interrupts the program. Assuming that the initial defaults of the /HEXADECIMAL and /LONGWORD qualifiers are in effect, the DEPOSIT command places a longword value 17 (23 decimal) in virtual memory location 2145876444.
Because the EXAMINE command sets up a pointer to the current memory location, which in this case is virtual address 2145876444, you can refer to this location with a period (.) in the DEPOSIT command.
The CONTINUE command resumes execution of the image.

$ DEPOSIT/ASCII   2C00=FILE: NAME: TYPE:
00002C00:  FILE: NAME: TYPE:...

In this example, the DEPOSIT command deposits character data at hexadecimal location 2C00 and displays the contents of the location after modifying it. Because the current default length is a longword, the response from the DEPOSIT command displays full longwords. The ellipsis (...) indicates that the remainder of the last longword of data contains information that was not modified by the DEPOSIT command.

$ EXAMINE 9C0             !  Look at Hex location 9C0
000009C0:  8C037DB3
$ DEPOSIT .=0             !  Deposit longword of 0
000009C0:  00000000
$ DEPOSIT/BYTE .=1        !  Put 1 byte at next location
000009C4:  01
$ DEPOSIT .+2=55          !  Deposit 55 next
000009C7:  55
$ DEPOSIT/LONG .=0C,0D,0E !  Deposit longwords
000009C8:  0000000C 0000000D 0000000E

The sequence of DEPOSIT commands in the above example illustrates how the DEPOSIT command changes the current position pointer. Note that after you specify the /BYTE qualifier, all data is deposited and displayed in bytes, until the /LONGWORD qualifier restores the system default.

$ BASE=%X200               !  Define a base address
$ LIST=BASE+%X40           !  Define offset from base
$ DEPOSIT/DECIMAL LIST=1,22,333,4444
00000240:  00000001 00000022 00000333 00004444
$ EXAMINE/HEX LIST:LIST+0C !  Display results in hex
00000240:  00000001 00000016 0000014D 0000115C

The assignment statements define a base address in hexadecimal and a label at a hexadecimal offset from the base address. The DEPOSIT command reads the list of values and deposits each value into a longword, beginning at the specified location. The EXAMINE command requests a hexadecimal display of these values.

DIAGNOSE (Alpha Only)

On Alpha, the DIAGNOSE command invokes the DECevent management utility and selectively reports the contents of one or more event log files. For a complete description of the DECevent utility, see the OpenVMS System Management Utilities Reference Manual.

Format

DIAGNOSE [qualifier...] [filespec][,...]

DIFFERENCES

Compares the contents of two disk files and displays a listing of the records that do not match.

Format

DIFFERENCES input1-filespec [input2-filespec]

PARAMETERS

input1-filespec
Specifies the first file to be compared. The file specification must include a file name and a file type. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.
input2-filespec
Specifies the second file to be compared. Unspecified fields default to the corresponding fields in the input1-filespec parameter. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.
If you do not specify a secondary input file, the DIFFERENCES command uses the next lower version of the primary input file.

DESCRIPTION

Use the DIFFERENCES command to determine whether two files are identical and, if not, how they differ. The DIFFERENCES command compares the two specified files on a record-by-record basis and produces an output file that lists the DIFFERENCES, if any.
The qualifiers for the DIFFERENCES command can be categorized according to their functions, as follows:

Qualifiers that request the DIFFERENCES command to ignore data in each record:

/COMMENT_DELIMITERS
/IGNORE

These qualifiers allow you to define characters that denote comments or to designate characters or classes of characters to ignore when comparing files. For example, you can have the DIFFERENCES command ignore extra blank lines or extra spaces within lines.
By default, the DIFFERENCES command compares every character in each record.
Qualifiers that control the format of the information contained in the list of differences:

/CHANGE_BAR
/IGNORE
/MERGED
/MODE
/PARALLEL
/SEPARATED
/SLP
/WIDTH

By default, the DIFFERENCES command merges the differences it finds in the files being compared. It lists each record in the file that has no match in the other input file and then lists the next record that it finds that does have a match.
By default, the DIFFERENCES command also supplies a line number with each listed record, and it lists the records with all designated ignore characters deleted.
You can specify combinations of qualifiers to request an output listing that includes the comparison in more than one format. Note that SLP output is incompatible with all other types of output; parallel output can be generated only in ASCII mode.
Qualifiers that control the extent of the comparison:

/MATCH
/MAXIMUM_DIFFERENCES
/WINDOW

By default, the DIFFERENCES command reads every record in the master input file and looks for a matching record in the revision input file. A search for a match between the two input files continues until either a match is found or the ends of the two files are reached. Sections of the two files are considered a match only if three sequential records are found to be identical in each file.

By default, DIFFERENCES command output is written to the current SYS$OUTPUT device. Use the /OUTPUT qualifier to request that the DIFFERENCES command write the output to an alternate file or device.
The DIFFERENCES command terminates with an exit status. The following severity levels indicate the result of the comparison:

SUCCESS Files are identical.

INFORMATIONAL Files are different.

WARNING User-specified maximum number of DIFFERENCES has been exceeded.

ERROR Insufficient virtual memory to complete comparison.

All severity levels other than SUCCESS indicate that the two input files are different.

QUALIFIERS

/CHANGE_BAR[=([change-char][,[NO]NUMBER])]
Marks differences using the specified character. The /CHANGE_BAR qualifier displays output that depends on where the qualifier is placed. The following examples describe the result of /CHANGE_BAR qualifier placement.
The following placement displays the latest version of input.file with the pound sign (#) preceding any lines that differ from the preceding version of input.file:
$ DIFFERENCES input.file/CHANGE_BAR=#
The following placement displays input.file;2 with the pound sign (#) preceding any lines that differ from input.file;1:
$ DIFFERENCES input.file;1  input.file;2 /CHANGE_BAR=#
The following placement displays input.file;1 with the pound sign (#) preceding any lines that differ from input.file;2:
$ DIFFERENCES input.file;1/CHANGE_BAR=#  input.file;2
The following placement displays input.file;1 with the percent sign (%) preceding any lines that differ from input.file;2, and also displays input.file;2 with the pound sign (#) preceding any lines that differ from input.file;1:
$ DIFFERENCES input.file;1/CHANGE_BAR=% input.file;2/CHANGE_BAR=#
If you do not specify a change bar character, the default is an exclamation point (!) for ASCII output.
If you specify hexadecimal or octal output (see the description of the /MODE qualifier), the change bar character is ignored and differences are marked by a "***CHANGE***" string in the record header. The keyword NONUMBER suppresses line numbers in the listing.
If neither the NUMBER nor the NONUMBER keyword is specified, the default is controlled by the /[NO]NUMBER command qualifier.
If you specify only one option, you can omit the parentheses.
If you use an exclamation point (!) as the specified character, you must enclose it in quotation marks (" "); for example, /CHANGE_BAR=("!",NUMBER).

/COMMENT_DELIMITER[=(character[,...])]
Ignores characters on a line to the right of (and including) a specified comment character.
If you specify just one character, you can omit the parentheses. Lowercase characters are automatically converted to uppercase unless they are enclosed in quotation marks. Nonalphanumeric characters (such as ! and ,) must be enclosed in quotation marks. Multicharacter comment characters are not allowed. You can specify up to 32 comment characters by typing the character itself or one of the following keywords. (Keywords can be abbreviated provided that the resultant keyword is not ambiguous and has at least 2 characters; single letters are treated as delimiters.)

Keyword Character

COLON Colon (:)

COMMA Comma (,)

EXCLAMATION Exclamation point (!)

FORM_FEED Form feed

LEFT Left bracket ([)

RIGHT Right bracket (])

SEMI_COLON Semicolon (;)

SLASH Slash (/)

SPACE Space

TAB Tab

If you specify the /COMMENT_DELIMITER qualifier, the /IGNORE=COMMENTS qualifier is implicitly also included.
If both the uppercase and lowercase forms of a letter are to be used as comment characters, the letter must be specified twice, once in uppercase and once in lowercase. If you do not include either a comment character or a keyword with the /COMMENT_DELIMITER qualifier, the DIFFERENCES command assumes a default comment character based on the file type. For some file types (.COB and .FOR), the default comment characters are considered valid delimiters only if they appear in the first column of a line.
The following characters are the default comment delimiters for files with the specified file types:

File Type Default Comment Character

.B2S, .B32, .BAS, .BLI !

.CBL, .CMD ! and ;

.COB * or / in the first column

.COM, .COR !

.FOR ! anywhere and C, D, c, d in the first column

.HLP !

.MAC, .MAR ;

.R32, .REQ !

/EXACT
Use with the /PAGE=SAVE and /SEARCH qualifiers to specify a search string that must match the search string exactly and must be enclosed with quotation marks (" ").
If you specify the /EXACT qualifier without the /SEARCH qualifier, exact search mode is enabled when you set the search string with the Find (E1) key.
/HIGHLIGHT[=keyword]

/NOHIGHLIGHT (default)
Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of highlighting you want when a search string is found. When a string is found, the entire line is highlighted. You can use the following keywords: BOLD, BLINK, REVERSE, and UNDERLINE. BOLD is the default highlighting.
/IGNORE=(keyword[,...])
Inhibits the comparison of the specified characters, strings, or records; also controls whether the comparison records are output to the listing file as edited records or exactly as they appeared in the input file. If you specify only one keyword, you can omit the parentheses. The keyword parameter refers to either a character or a keyword. The first set of keywords determines what, if anything, is ignored during file comparison; the second set of keywords determines whether or not ignored characters are included in the output. The following keywords are valid options for the /IGNORE qualifier:

Keyword Item Ignored

BLANK_LINES Blank lines between data lines.

CASE Case of the text being compared.

COMMENTS Data following a comment character. (Use the /COMMENT_DELIMITER qualifier to designate one or more nondefault comment delimiters.)

FORM_FEEDS Form feed character.

HEADER[=n] First n records of the file, beginning with a record whose first character is a form feed. The first record is not ignored if the only character it contains is a form feed. ( N indicates the number of records and defaults to 2. A record with a single form feed is not counted.)

SPACING Extra blank spaces or tabs within data lines.

TRAILING_SPACES Space and tab characters at the end of a data line.

Keyword Status of Ignored Items in Output

EDITED Omits ignored characters from the output records.

EXACT Includes ignored characters in the output records.

PRETTY Formats output records.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  9996P011.HTM
  OSSG Documentation
  26-NOV-1996 11:17:08.96
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

SUCCESS	Files are identical.
INFORMATIONAL	Files are different.
WARNING	User-specified maximum number of DIFFERENCES has been exceeded.
ERROR	Insufficient virtual memory to complete comparison.

Keyword	Character
COLON	Colon (:)
COMMA	Comma (,)
EXCLAMATION	Exclamation point (!)
FORM_FEED	Form feed
LEFT	Left bracket ([)
RIGHT	Right bracket (])
SEMI_COLON	Semicolon (;)
SLASH	Slash (/)
SPACE	Space
TAB	Tab

File Type	Default Comment Character
.B2S, .B32, .BAS, .BLI	!
.CBL, .CMD	! and ;
.COB	* or / in the first column
.COM, .COR	!
.FOR	! anywhere and C, D, c, d in the first column
.HLP	!
.MAC, .MAR	;
.R32, .REQ	!

Keyword	Item Ignored
BLANK_LINES	Blank lines between data lines.
CASE	Case of the text being compared.
COMMENTS	Data following a comment character. (Use the /COMMENT_DELIMITER qualifier to designate one or more nondefault comment delimiters.)
FORM_FEEDS	Form feed character.
HEADER[=n]	First n records of the file, beginning with a record whose first character is a form feed. The first record is not ignored if the only character it contains is a form feed. ( N indicates the number of records and defaults to 2. A record with a single form feed is not counted.)
SPACING	Extra blank spaces or tabs within data lines.
TRAILING_SPACES	Space and tab characters at the end of a data line.
Keyword	Status of Ignored Items in Output
EDITED	Omits ignored characters from the output records.
EXACT	Includes ignored characters in the output records.
PRETTY	Formats output records.