OpenVMS DCL Dictionary

If you specify the /PROCESS qualifier without a process name, a unique process name is assigned with the same base name as the parent process and a unique number. The default process name format is username_n. If you specify a process name that already exists, an error message is displayed. This qualifier is used with either the /DETACH or the /NODETACH qualifier.

/PROMPT=prompt

Specifies the prompt string of the created terminal window. This qualifier is used only with the /NODETACH qualifier.

/READSYNC

/NOREADSYNC

Sets or clears the READSYNC terminal characteristic in the created terminal window. The default is to inherit the characteristic from the parent.

/RESOURCE_FILE=filespec

Specifies that the created terminal window use the resource file "filespec" instead of the default resource file, DECW$USER_DEFAULTS:DECW$TERMINAL_DEFAULT.DAT.

/SYMBOLS (default)

/NOSYMBOLS

Determines whether the subprocess inherits the parent's DCL symbols. This qualifier is used only with the /NODETACH qualifier.

/TABLE=command-table

Specifies the name of an alternate command table to be used by the subprocess. This qualifier is used only with the /NODETACH qualifier.

/TTSYNC

/NOTTSYNC

Sets or clears the TTSYNC terminal characteristic in the created terminal window; the default is to inherit the characteristic of the parent.

/TYPE_AHEAD

/NOTYPE_AHEAD

Sets or clears the TYPE_AHEAD terminal characteristic in the created terminal window. The default is to inherit the characteristic of the parent.

/WAIT

/NOWAIT (default)

Requires that you wait for the subprocess to terminate before you enter another DCL command. The /NOWAIT qualifier allows you to enter new commands while the subprocess is running. This qualifier is used only with the /NODETACH qualifier.

/WINDOW_ATTRIBUTES=(parameter [,...])

Specifies initial attributes for the created terminal window to override the defaults read from the resource file. These parameters include:

Parameter	Description
BACKGROUND	The background color.
FOREGROUND	The foreground color.
WIDTH	The width, in pixels.
HEIGHT	The height, in pixels.
X_POSITION	The x-position, in pixels.
Y_POSITION	The y-position, in pixels.
ROWS	The number of rows in the window, in character cells. If the Auto Resize Window option is enabled, the ROWS and COLUMNS parameters override the size specified by the WIDTH and HEIGHT parameters.
COLUMNS	The number of columns in the window, in character cells. If the Auto Resize Window option is enabled, the ROWS and COLUMNS parameters override the size specified by the WIDTH and HEIGHT parameters.
INITIAL_STATE	The initial state of the window, either ICON or WINDOW.
TITLE	A character string specifying the window title.
ICON_NAME	A character string specifying the window icon name.
FONT	The name of the font to be used in the window. If you specify the /LITTLE_FONT qualifier, or omit both the /LITTLE_FONT and /BIG_FONT qualifiers, this overrides the name of the little font that is set in the resource files; otherwise it overrides the name of the big font. The font name can be a logical name, and it can be (but does not have to be) the base font in a complete font set.

Examples

$ CREATE/TERMINAL=DECTERM/DETACH -
_$ /DISPLAY=MYNODE::0 -
_$ /WINDOW_ATTRIBUTES=( -
_$ ROWS=36, -
_$ COLUMNS=80, - 
_$ TITLE="REMOTE TERMINAL", -
_$ ICON_NAME="REMOTE TERMINAL" )

In this example, the command creates a detached process in a DECterm window on node MYNODE:: that is 36 rows by 80 columns and has its title and icon name set to "Remote terminal".

$ CREATE/TERMINAL=DECTERM -
$_ /NOPROCESS -
$_ /DEFINE_LOGICAL=(TABLE=LNM$GROUP,DBG$INPUT,DBG$OUTPUT)

In this example, the command creates a DECterm with no associated process. The command defines DBG$INPUT and DBG$OUTPUT in the group table as the new terminal for the purposes of debugging a problem with a detached process that is subsequently created.

DEALLOCATE

Makes an allocated device available to other processes (but does not deassign any logical name associated with the device). DEALLOCATE does not deallocate devices that are in use.

Format

DEALLOCATE device-name[:]

PARAMETER

device-name[:]
Name of the device to be deallocated. The device name can be a physical device name or a logical name that is not in use. On a physical device name, the controller defaults to A and the unit to 0. This parameter is incompatible with the /ALL qualifier.

QUALIFIER

/ALL
Deallocates all devices currently allocated by your process that are not in use. This qualifier is incompatible with the device-name parameter.

Examples

$ DEALLOCATE  DMB1:

In this example, the DEALLOCATE command deallocates unit 1 of the RK06/RK07 devices on controller B.

$ ALLOCATE   MT:   TAPE
%DCL-I-ALLOC, _MTB1:  allocated
   .
   .
   .
$ DEALLOCATE  TAPE:

In this example, the ALLOCATE command requests that any magnetic tape drive be allocated and assigns the logical name TAPE to the device. The response to the ALLOCATE command indicates the successful allocation of the device MTB1. The DEALLOCATE command specifies the logical name TAPE to release the tape drive.

$ DEALLOCATE/ALL

In this example, the DEALLOCATE command deallocates all devices that are currently allocated.

DEASSIGN

Cancels a logical name assignment that was made with one of the following commands: ALLOCATE, ASSIGN, DEFINE, or MOUNT. The DEASSIGN command also deletes a logical name table that was created with the CREATE/NAME_TABLE command.

Format

DEASSIGN [logical-name[:]]

PARAMETER

logical-name[:]
Specifies the logical name to be deassigned. Logical names can have from 1 to 255 characters. If the logical name contains any characters other than alphanumerics, dollar signs ($), or underscores (_), enclose it in quotation marks (" "). The logical-name parameter is required unless you use the /ALL qualifier.
If the logical-name parameter ends with a colon (:), the command interpreter ignores the colon. (Note that the ASSIGN and ALLOCATE commands remove a trailing colon, if present, from a logical name before placing the name in a logical name table.) If a colon is present in the logical name, you must type two colons in the logical-name parameter of the DEASSIGN command (for example, DEASSIGN FILE::).
To delete a logical name table, specify the table name as the logical-name parameter. You must also use the /TABLE qualifier to indicate the logical name directory table where the table name is entered.

DESCRIPTION

The DEASSIGN command cancels a logical name assignment that was made with one of the following commands: ALLOCATE, ASSIGN, DEFINE, or MOUNT. The DEASSIGN command also deletes a logical name table that was created with the CREATE/NAME_TABLE command. You can use the /ALL qualifier with DEASSIGN to cancel all logical names in a specified table. If you use the /ALL qualifier and do not specify a table, then all names in the process table (except names created by the command interpreter) are deassigned; that is, all names entered at the indicated access mode or an outer access mode are deassigned.
To specify the logical name table from which you want to deassign a logical name, use the /PROCESS, the /JOB, the /GROUP, the /SYSTEM, or the /TABLE qualifier. If you enter more than one of these qualifiers, only the last one entered is accepted. If entries exist for the specified logical name in more than one logical name table, the name is deleted from only the last logical name table specified on the command line. If you do not specify a logical name table, the default is the /TABLE=LNM$PROCESS qualifier.
To delete a shareable logical name, you need write (W) access to the logical name table. To delete a shareable logical name table, you need write (W) access to the parent table and delete (D) access to the target logical name table.
To specify the access mode of the logical name you want to deassign, use the /USER_MODE, the /SUPERVISOR_MODE, or the /EXECUTIVE_MODE qualifier. If you enter more than one of these qualifiers, only the last one is accepted. If you do not specify a mode, the DEASSIGN command deletes a supervisor-mode name. When you deassign a logical name, any identical names created with outer access modes in the same logical name table are also deleted.
You must have SYSNAM (system logical name) privilege to deassign an executive-mode logical name.
If you specify the /EXECUTIVE_MODE qualifier and you do not have SYSNAM privilege, then the DEASSIGN command ignores the qualifier and attempts to deassign a supervisor-mode logical name.
All process-private logical names and logical name tables are deleted when you log out of the system. User-mode entries within the process logical name table are deassigned when any image exits. The logical names in the job table, and the job table itself, are deleted when you log off the system.
Names in all other shareable logical name tables remain there until they are explicitly deassigned, regardless of whether they are user-, supervisor-, or executive-mode names. You must have write (W) access to a shareable logical name table to delete any name in that table.
If you delete a logical name table, all the logical names in the table are also deleted. Also, any descendant tables are deleted. To delete a shareable logical name table, you must have delete (D) access to the table.

QUALIFIERS

/ALL
Deletes all logical names in the same or an outer (less privileged) access mode. If no logical name table is specified, the default is the process table, LNM$PROCESS. If you specify the /ALL qualifier, you cannot enter a logical-name parameter.
/EXECUTIVE_MODE
Requires SYSNAM (system logical name) privilege to deassign executive-mode logical names.
Deletes only entries that were created in the specified mode or an outer (less privileged) mode. If you do not have SYSPRV (system privilege) privilege for executive mode, a supervisor-mode operation is assumed.
/GROUP
Requires GRPNAM (group logical name) or SYSPRV privilege to delete entries from the group logical name table.
Indicates that the specified logical name is in the group logical name table. The /GROUP qualifier is synonymous with the /TABLE=LNM$GROUP qualifier.
/JOB
Indicates that the specified logical name is in the jobwide logical name table. The /JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier. If you do not explicitly specify a logical name table, the default is the /PROCESS qualifier.
You should not deassign jobwide logical name entries that were made by the system at login time, for example, SYS$LOGIN, SYS$LOGIN_DEVICE, and SYS$SCRATCH. However, if you assign new equivalence names for these logical names (that is, create new logical names in outer access modes), you can deassign the names you explicitly created.
/PROCESS (default)
Indicates that the specified logical name is in the process logical name table. The /PROCESS qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier.
You cannot deassign logical name table entries that were made by the command interpreter, for example, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR. However, if you assign new equivalence names for these logical names (that is, you create new logical names in outer access modes), you can deassign the names you explicitly created.
/SUPERVISOR_MODE (default)
Deletes entries in the specified logical name table that were created in supervisor mode. If you specify the /SUPERVISOR_MODE qualifier, the DEASSIGN command also deassigns user-mode entries with the same name.
/SYSTEM
Indicates that the specified logical name is in the system logical name table. The /SYSTEM qualifier is synonymous with the /TABLE=LNM$SYSTEM qualifier.
/TABLE=name
Specifies the table from which the logical name is to be deleted. Defaults to LNM$PROCESS. The table can be the process, group, job, or system table, one of the directory tables, or the name of a user-created table. (The process, job, group, and system logical name tables should be referred to by the logical names LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, respectively.)
The /TABLE qualifier also can be used to delete a logical name table. To delete a process-private table, enter the following command:
$ DEASSIGN/TABLE=LNM$PROCESS_DIRECTORY table-name
To delete a shareable table, enter the following command:
$ DEASSIGN/TABLE=LNM$SYSTEM_DIRECTORY table-name
To delete a shareable logical name table, you must have delete (D) access to the table or write (W) access to the directory table in which the name of the shareable table is cataloged.
If you do not explicitly specify the /TABLE qualifier, the default is the /TABLE=LNM$PROCESS qualifier.
/USER_MODE
Deletes entries in the process logical name table that were created in user mode. If you specify the /USER_MODE qualifier, the DEASSIGN command can deassign only user-mode entries. Also, user-mode logical names are automatically deleted when invoking and exiting a command procedure.

Examples

$ DEASSIGN MEMO

The DEASSIGN command in this example deassigns the process logical name MEMO.

$ DEASSIGN/ALL

The DEASSIGN command in this example deassigns all process logical names that were created in user and supervisor mode. This command does not, however, delete the names that were placed in the process logical name table in executive mode by the command interpreter (for example, SYS$INPUT, SYS$OUTPUT, SYS$ERROR, SYS$DISK, and SYS$COMMAND).

$ DEASSIGN/TABLE=LNM$PROCESS_DIRECTORY TAX

The DEASSIGN command in this example deletes the logical name table TAX, and any descendant tables. When you delete a logical name table, you must specify either the /TABLE=LNM$PROCESS_DIRECTORY or the /TABLE=LNM$SYSTEM_DIRECTORY qualifier, because the names of all tables are contained in these directories.

$ ASSIGN USER_DISK:   COPY
$ SHOW LOGICAL COPY
   "COPY" = "USER_DISK:" (LNM$PROCESS_TABLE)
$ DEASSIGN COPY

The ASSIGN command in this example equates the logical name COPY with the device USER_DISK and places the names in the process logical name table. The DEASSIGN command deletes the logical name.

$ DEFINE SWITCH:  TEMP
$ DEASSIGN SWITCH::

The DEFINE command in this example places the logical name SWITCH: in the process logical name table. The trailing colon is retained as part of the logical name. Two colons are required on the DEASSIGN command to delete this logical name because the DEASSIGN command removes one trailing colon, and the other colon is needed to match the characters in the logical name.

$ ASSIGN/TABLE=LNM$GROUP DBA1: GROUP_DISK
$ DEASSIGN/PROCESS/GROUP GROUP_DISK

The ASSIGN command in this example places the logical name GROUP_DISK in the group logical name table. The DEASSIGN command specifies conflicting qualifiers; because the /GROUP qualifier is last, the name is successfully deassigned.

$ ASSIGN DALLAS::USER_DISK:   DATA
   .
   .
   .
$ DEASSIGN DATA

The ASSIGN command in this example associates the logical name DATA with the device specification USER_DISK on remote node DALLAS. Subsequent references to the logical name DATA result in references to the disk on the remote node. The DEASSIGN command cancels the logical name assignment.

DEASSIGN/QUEUE

Deassigns a logical queue from a printer or terminal queue and stops the logical queue. Cannot be used with batch queues.
Requires manage (M) access to the queue.

Format

DEASSIGN/QUEUE logical-queue-name[:]

PARAMETER

logical-queue-name[:]
Specifies the name of the logical queue that you want to deassign from a specific printer or terminal queue.

DESCRIPTION

Once you enter the DEASSIGN/QUEUE command, the jobs in the logical queue remain pending until the queue is reassigned to another printer queue or device with the ASSIGN/QUEUE command.

Example

$ ASSIGN/QUEUE LPA0  ASTER
   .
   .
   .
$ DEASSIGN/QUEUE  ASTER
$ ASSIGN/MERGE LPB0  ASTER

The ASSIGN/QUEUE command in this example associates the logical queue ASTER with the print queue LPA0. Later, you deassign the logical queue with the DEASSIGN/QUEUE command. The ASSIGN/MERGE command reassigns the jobs from ASTER to the print queue LPB0.

DEBUG

Invokes the OpenVMS Debugger.
For a complete description of the OpenVMS Debugger, see the OpenVMS Debugger Manual.
To get help on debugger commands from DCL level, type the following command:
$ HELP/LIBRARY=SYS$HELP:DBG$HELP DEBUG

Format

DEBUG

HEAP ANALYZER

The Heap Analyzer provides a graphical representation of memory use in real time. This allows you to quickly identify inefficient memory usage in your application such as allocations that are made too often, memory blocks that are too large, fragmentation, or memory leaks.
For details on running the Heap Analyzer from within the debugger, see the OpenVMS Debugger Manual.
To run the standalone Heap Analyzer, issue the following commands:
$ DEFINE/USER/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED
$ RUN/NODEBUG program

QUALIFIERS

/KEEP
Invokes the kept debugger. The kept debugger includes a Run/Rerun capability that allows you to debug an image multiple times or debug a series of distinct images without exiting the debugger.
Issuing the DEBUG/KEEP command is the only way to invoke the kept debugger.
/RESUME (default)
Reinvokes the non-kept debugger after a Ctrl/Y key sequence has interrupted the execution of a program you are debugging. (The interrupted program must not have been linked with a /NOTRACEBACK qualifier on the LINK command.)
If you issue the DEBUG/RESUME command without a previous Ctrl/Y key sequence, no action occurs.

Examples

$ FORTRAN/DEBUG/NOOPTIMIZE WIDGET
$ LINK/DEBUG WIDGET
$ RUN WIDGET
                [ Debugger Banner and Version ] 
 
%DEBUG-I-INITIAL, language is FORTRAN, module set to WIDGET 
DBG>

The FORTRAN and LINK commands both specify the /DEBUG qualifier to compile the program WIDGET.FOR with debugger symbol table information. Because the program has been compiled and linked with debug information, the debugger is automatically invoked by the image activator upon starting the program with the RUN command. No program code has yet been executed when the debugger is invoked.

$ FORTRAN/DEBUG/NOOPTIMIZE WIDGET
$ LINK/DEBUG WIDGET
$ RUN/NODEBUG WIDGET
  NAME: 
  NAME: 
  NAME:
^Y
$ DEBUG/RESUME
 
             [ Debugger Banner and Version ] 
 
  %DEBUG-I-INITIAL, language is FORTRAN, module set to WIDGET 
  DBG>

The FORTRAN and LINK commands both specify the /DEBUG qualifier to compile the program WIDGET.FOR with debugger symbol table information. The RUN command begins execution of the image WIDGET.EXE, which loops uncontrollably. Ctrl/Y interrupts the program, and the DEBUG/RESUME command gives control to the debugger.

$ CC/DEBUG/NOOPTIMIZE ECHOARGS
$ LINK/DEBUG ECHOARGS
$ ECHO == "$ sys$disk:[]echoargs.exe"
$ DEBUG/KEEP
                   [ Debugger Banner and Version ] 
 
DBG> RUN/COMMAND="ECHO"/ARGUMENTS="fa sol la mi"
%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 
   .
   .
   .
DBG> RERUN/ARGUMENTS="fee fii foo fum"
%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 
   .
   .
   .
DBG> RUN/ARGUMENTS="a b c" ECHOARGS
%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG>

The CC and LINK commands both specify the /DEBUG qualifier to compile the program ECHOARGS.C with debugger symbol table information.
The symbol definition command defines a foreign command for use during the debugging session.
The DEBUG/KEEP command invokes the kept debugger.
The first RUN command uses the /COMMAND qualifier to specify a foreign command to invoke the image file and the /ARGUMENTS qualifier to specify a string of arguments.
The RERUN command reinvokes the same image file and uses the /ARGUMENTS qualifier to specify a new string of arguments.
The second RUN command specifies a new image file and a new string of arguments.

$ PASCAL/DEBUG/NOOPTIMIZE 8QUEENS
$ LINK/DEBUG 8QUEENS
$ DEFINE/USER/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED
$ RUN/NODEBUG 8QUEENS
 
        [Heap Analyzer window is displayed]

The PASCAL and LINK commands both specify the /DEBUG qualifier to compile the program 8QUEENS.PAS with debugger symbol table information.
The DEFINE command causes the Heap Analyzer to access a version of LIBRTL designed to collect memory allocation and deallocation information.
The RUN/NODEBUG command invokes the Heap Analyzer but not the Debugger.

DECK

Marks the beginning of an input stream for a command or program.

Format

DECK

DESCRIPTION

The DECK command marks the data that follows it as input for a command or program. The DECK command can be used only after a request to execute a command or program that requires input data.
In command procedures, this command is required when the first nonblank character in any data record in the input stream is a dollar sign. Also in command procedures, the DECK command must be preceded by a dollar sign; the dollar sign must be in the first character position (column 1) of the input record.
The DECK command defines an end-of-file (EOF) indicator only for a single data stream. Using the DECK command enables you to place data records beginning with dollar signs in the input stream. You can place one or more sets of data in the input stream following a DECK command, if each is terminated by an EOF indicator.
After an EOF indicator specified with the /DOLLARS qualifier is encountered, the EOF indicator is reset to the default, that is, to any record beginning with a dollar sign. The default is also reset if an actual EOF indicator occurs for the current command level.

QUALIFIER

/DOLLARS[=string]
Sets the EOF indicator to the specified string of 1 to 15 characters. Specify a string if the input data contains one or more records beginning with the string $EOD. Enclose the string in quotation marks (" ") if it contains literal lowercase letters, multiple blanks, or tabs. If you do not specify /DOLLARS or if you specify /DOLLARS without specifying a string, you must use the EOD command to signal the end-of-file (EOF).

Examples

In this example, the FORTRAN and LINK commands compile and link program A. When the program is run, any data the program reads from the logical device SYS$INPUT is read from the command stream. The DECK command indicates that the input stream can contain dollar signs in column 1 of the record. The EOD command signals end-of-file (EOF) for the data.

The CREATE command in this example creates the command procedure file TEST.COM from lines entered into the input stream. The DECK/DOLLARS command indicates that the percent sign (%) is the EOF indicator for the CREATE command. This allows the string $EOD to be read as an input record, signaling the end of the input for the RUN command.

DEFINE

Associates an equivalence name with a logical name.

Format

DEFINE logical-name equivalence-name[,...]

PARAMETERS

logical-name
Specifies the logical name string, which is a character string containing from 1 to 255 characters. The following rules apply:

If you specify an existing logical name, the new equivalence names replace the existing equivalence name.
If the logical name is to be entered into the process or system directory logical name tables (LNM$PROCESS_DIRECTORY, LNM$SYSTEM_DIRECTORY), then the name can only have from 1 to 31 alphanumeric characters, including the dollar sign ($) and underscore (_).
If you specify a colon (:) at the end of a logical name, the DEFINE command saves the colon as part of the logical name. (This is in contrast to the ASSIGN command, which removes the colon before placing the name in a logical name table.) By default, the logical name is placed in the process logical name table.
If the string contains any characters other than uppercase alphanumerics, the dollar sign, or the underscore character, enclose the string in quotation marks (" "). Use two sets of quotation marks ("" "") to denote actual quotation marks. When you enclose a name in quotation marks, the case of alphabetic characters is preserved.

equivalence-name[,...]
Specifies a character string containing from 1 to 255 characters. The following rules apply:

If the string contains any characters other than uppercase alphanumerics, the dollar sign, or the underscore character, enclose the string in quotation marks. Use two sets of quotation marks to denote an actual quotation mark. Specifying more than one equivalence name for a logical name creates a search list.
When you specify an equivalence name that will be used as a file specification, you must include the punctuation marks (colons, brackets, periods) that would be required if the equivalence name were used directly as a file specification. Therefore, if you specify a device name as an equivalence name, you must terminate the equivalence name with a colon.

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

Legal