OpenVMS DCL Dictionary

Document revision date: 19 July 1999

OpenVMS DCL Dictionary

Contents

Index

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.

#7

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

#7
$ 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

/CLIENT
Invokes the DEBUG client MOTIF interface. From the client, use the network binding string displayed by the server at startup to establish the connection. The first client to connect to the server is the primary client, and controls the number of secondary clients allowed to connect to the server.
/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.
/SERVER [=( [BINDING_INFO=filespec] [,PROTOCOLS=(protocol[,...])] )]
Invokes the DEBUG server. The DEBUG server allows up to 30 simultaneous connections from clients on the same or remote OpenVMS nodes, or from PC nodes running Microsoft Windows 95 or Microsoft Windows NT.
(Optional) If specified, the BINDING_INFO keyword specifies that the server binding identification strings are to be written to filespec. If not specified, no file is created.
(Optional) If specified, the PROTOCOLS keyword specifies which network protocols should be enabled for connection to the DEBUG server. Only the specified protocols are enabled. If not specified, all protocols are enabled The protocol argument can be one or more of the following keywords:

ALL
[NO]DECNET
[NO]TCP_IP
[NO]UDP

The first client to connect to the server is the primary client. A client that connects to the server after the primary client establishes the connection is a secondary client. The primary client controls the number of secondary clients allowed to connect to the server.
The server displays a series of RPC binding strings that identify the port numbers through which the client can connect to the server. The port number appears in square brackets ([]) at the end of the identification strings. When connecting from the client, the simplest port identification string consists of the node name of the server followed by the port number in square brackets. The following are all valid binding identification strings:

NODNAM[1234]
NCACN_IP_TCP:16.32.16.25[1112]
16.32.16.25[1112]
NCACN_DNET_NSP:63.1004[RPC20A020DD0001]

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.

Examples

#1
$ 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.

#2
$ 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>

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

#3
$ 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>

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

#4
$ 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.

#5
$ DEBUG/SERVER=(PROTOCOLS=(TCP_IP,DECNET)) %DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: NO %DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.25[1112] %DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:63.1004[RPC20A020DD0001] %DEBUG-I-AWAIT: Ready for client connection...

$ DEBUG/SERVER=(PROTOCOLS=(TCP_IP,DECNET))
 
%DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: NO 
%DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.25[1112] 
%DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:63.1004[RPC20A020DD0001] 
%DEBUG-I-AWAIT: Ready for client connection...

The DEBUG/SERVER command establishes a connection to the debug server, requesting network protocols TCP/IP and DECnet. Note that the binding strings are saved in file TEMP.TMP. Yiou can use the TYPE command to display the contents of TEMP.TMP.

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

#1

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

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

The DEFINE command allows you to assign multiple equivalence names to a single logical name. For example, you can use the same logical name to access different directories on different disks or to access different files in different directories.

Description

The DEFINE command creates a logical name that represents one or more equivalence names. An equivalence name can be a device name, another logical name, a file specification, or any other string.
You can limit the use of a logical name to a process, a job, a group, an entire system, or an entire OpenVMS Cluster system. How you use a logical name depends on the table you created in it. You can specify a table with one of the following qualifiers: /PROCESS, /JOB, /GROUP, /SYSTEM, or /TABLE.
The first four qualifiers represent the process, job, group, or system logical name tables, respectively, whereas the /TABLE qualifier is used to specify any type of table. Furthermore, the /TABLE qualifier is the only one to use when specifying a clusterwide logical name table.
If you enter more than one of the qualifiers, only the last one entered is accepted. If you do not specify a table with one of the qualifiers, the logical name is added to your process logical name table.
To specify the access mode of the logical name you are creating, 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 entered is accepted. If you do not specify an access mode, a supervisor-mode name is created. You can create a logical name in the same mode as the table in which you are placing the name, or in an outer mode. (User mode is the outermost mode; executive mode is the innermost mode.)
You can enter more than one logical name with the same name in the same table, as long as each name has a different access mode. (However, if an existing logical name within a table has the NO_ALIAS attribute, you cannot use the same name to create a logical name in an outer mode in this table.)
If you create a logical name with the same name, in the same table, and in the same mode as an existing name, the new logical name assignment replaces the existing assignment.
You can also use the ASSIGN command to create logical names. To delete a logical name from a table, use the DEASSIGN command.

Note
Avoid assigning a logical name that matches the file name of an executable image in SYS$SYSTEM:. Such an assignment prohibits you from invoking that image.

To create a logical name with no equivalence name (and therefore no indices), use the $CRELNM system service.
If you want to specify an ODS-5 file name as an equivalence name, refer to the OpenVMS Guide to Extended File Specifications.
For a complete description of logical names and logical name tables, except for their use in applications, refer to the OpenVMS User's Manual. For the use of logical names in applications, refer to the OpenVMS Programming Concepts Manual. For managing clusterwide logical names, refer to the OpenVMS Cluster Systems manual. In this manual, see also the description of the lexical function F$TRNLNM, which is used to translate logical names.

Qualifiers

/EXECUTIVE_MODE
Requires SYSNAM (system logical name) privilege to create an executive-mode logical name.
Creates an executive-mode logical name in the specified table.
If you specify the /EXECUTIVE_MODE qualifier and you do not have SYSNAM privilege, the DEFINE command ignores the qualifier and creates a supervisor-mode logical name. The mode of the logical name must be the same or less privileged than the mode of the table in which you are placing the name.
/GROUP
Requires GRPNAM (group logical name) or SYSNAM (system logical name) privilege to place a name in the group logical name table.
Places the logical name in the group logical name table. Other users who have the same group number in their user identification codes (UICs) can access the logical name. The /GROUP qualifier is synonymous with the /TABLE=LNM$GROUP qualifier.
/JOB
Places the logical name in the jobwide logical name table. All processes in the same job tree as the process that created the logical name can access the logical name. The /JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier.
/LOG (default)

/NOLOG
Displays a message when a new logical name supersedes an existing name.
/NAME_ATTRIBUTES[=(keyword[,...])]
Specifies attributes for a logical name. By default, no attributes are set. Possible keywords are as follows:

CONFINE The logical name is not copied into a spawned subprocess. This qualifier is relevant only for logical names in a private table.
The logical name inherits the CONFINE attribute from the logical name table where it is entered; if the logical name table is "confined," then all names in the table are "confined."

NO_ALIAS A logical name cannot be duplicated in the specified table in a less privileged access mode; any previously created identical names in an outer (less privileged) access mode within the specified table are deleted.

If you specify only one keyword, you can omit the parentheses. Only the attributes you specify are set.
/PROCESS (default)
Places the logical name in the process logical name table. The /PROCESS qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier.
/SUPERVISOR_MODE (default)
Creates a supervisor-mode logical name in the specified table. The mode of the logical name must be the same as or less privileged than the mode of the table in which you are placing the name.
/SYSTEM
Requires write (W) access or SYSNAM (system logical name) privilege to place a name in the system logical name table.
Places the logical name in the system logical name table. All system users can access the logical name. The /SYSTEM qualifier is synonymous with the /TABLE=LNM$SYSTEM qualifier.
/TABLE=name
Requires write (W) access to the table to specify the name of a shareable logical name table.
Specifies the name of the logical name table in which the logical name is to be entered. You can use the /TABLE qualifier to specify a user-defined logical name table (created with the CREATE/NAME_TABLE command); to specify the process, job, group, system, or clusterwide logical name tables; or to specify the process or system logical name directory tables.
If you specify the table name using a logical name that has more than one translation, the logical name is placed in the first table found. For example, if you specify DEFINE/TABLE=LNM$FILE_DEV and LNM$FILE_DEV is equated to LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, then the logical name is placed in LNM$PROCESS.
The default is the /TABLE=LNM$PROCESS qualifier.
/TRANSLATION_ATTRIBUTES[=(keyword[,...])]
Equivalence-name qualifier.
Specifies one or more attributes that modify an equivalence string of the logical name. Possible keywords are as follows:

CONCEALED Indicates that the equivalence string is the name of a concealed device. When a concealed device name is defined, the system displays the logical name, rather than the equivalence string, in messages that refer to the device.

TERMINAL Logical name translation should terminate with the current equivalence string; indicates that the equivalence string should not be translated iteratively.

If you specify only one keyword, you can omit the parentheses. Only the attributes you specify are set.
Note that different equivalence strings of a logical name can have different translation attributes.
/USER_MODE
Creates a user-mode logical name in the specified table.
User-mode logical names created within the process logical name tables are used for the execution of a single image; for example, you can create a user-mode logical name to allow an image executing in a command procedure to redefine SYS$INPUT. User-mode entries are deleted from the process logical name table when any image executing in the process exits (that is, after a DCL command or user program that executes an image completes execution). Also, user-mode logical names are automatically deleted when invoking and exiting a command procedure.

Examples

#1
$ DEFINE/USER_MODE TM1 $DISK1:[ACCOUNTS.MEMOS]WATER.TXT

In this example, the DEFINE command defines TM1 as equivalent to a file specification. After the next image runs, the logical name TM1 is automatically deassigned.

#2
$ DEFINE CHARLIE XXX1:[CHARLES] $ PRINT CHARLIE:TEST.DAT Job 274 entered on queue SYS$PRINT

In this example, the DEFINE command associates the logical name CHARLIE with the directory name [CHARLES] on the disk XXX1. The PRINT command queues a copy of the file XXX1:[CHARLES]TEST.DAT to the system printer.

#3
$ DEFINE PROCESS_NAME LIBRA $ RUN WAKE

In this example, the DEFINE command places the logical name PROCESS_NAME in the process logical name table with an equivalence name of LIBRA. The logical name is created in supervisor mode. The program WAKE translates the logical name PROCESS_NAME to perform some special action on the process named LIBRA.

#4
$ DEFINE TEMP: XXX1: . . . $ DEASSIGN TEMP::

In this example, the DEFINE command creates an equivalence name for the logical name TEMP: and places the name in the process logical name table. The colon is retained as part of the logical name. The DEASSIGN command deletes the logical name. Note that two colons are required on the logical name in the DEASSIGN command. One colon is deleted by the DEASSIGN command. The other colon is kept as part of the logical name.

#5
$ DEFINE PORTLAND PRTLND::YYY0:[DECNET.DEMO.COM]

Previous Next Contents Index

privacy and legal statement

9996PRO_010.HTML

CONFINE	The logical name is not copied into a spawned subprocess. This qualifier is relevant only for logical names in a private table. The logical name inherits the CONFINE attribute from the logical name table where it is entered; if the logical name table is "confined," then all names in the table are "confined."
NO_ALIAS	A logical name cannot be duplicated in the specified table in a less privileged access mode; any previously created identical names in an outer (less privileged) access mode within the specified table are deleted.

CONCEALED	Indicates that the equivalence string is the name of a concealed device. When a concealed device name is defined, the system displays the logical name, rather than the equivalence string, in messages that refer to the device.
TERMINAL	Logical name translation should terminate with the current equivalence string; indicates that the equivalence string should not be translated iteratively.