Document revision date: 30 March 2001

## OpenVMS DCL Dictionary

Previous | Contents | Index

When you subsequently enter STAT, the command interpreter executes the image.

#3
    $ A = "this is a big     space."
    $ SHOW SYMBOL A
      A = "this is a big     space."
    $ B := 'A'
    $ SHOW SYMBOL B
      B = "THIS IS A BIG SPACE."

> This example compares the assignment and the string assignment statements. The symbol A is defined using the assignment statement, so lowercase letters and multiple spaces are retained. The symbol B is defined using the string assignment statement. Note that the single quotation marks (` ') are required; otherwise, the symbol name B would have been equated to the literal string A. However, when symbol A's value is assigned to symbol B, the letters are converted to uppercase and multiple spaces are compressed.

#4
    $ FILE_NAME := MYFILE
    $ FILE_NAME[0,2]:= OL
    $ SHOW SYMBOL FILE_NAME
      FILE_NAME = "OLFILE"

> In this example, the substring expression in the assignment statement overlays the first 2 characters of the string assigned to the symbol FILE_NAME with the letters OL. The offset of 0 requests that the overlay begin with the first character in the string, and the size specification of 2 indicates the number of characters to overlay.

#5
    $ FILE_NAME := MYFILE
    $ FILE_TYPE := .TST
    $ FILE_NAME[F$LENGTH(FILE_NAME),4] := 'FILE_TYPE'
    $ SHOW SYMBOL FILE_NAME
      FILE_NAME = "MYFILE.TST"

> In this example, the symbol name FILE_NAME is equated to the string MYFILE and the symbol name FILE_TYPE is equated to the string .TST. The third assignment statement uses the lexical function F$LENGTH to define the offset value where the overlay is to begin. The symbol name FILE_TYPE is used to refer to the replacement string (.TST). Note that you must use single quotation marks (` ') to request symbol substitution.

> The F$LENGTH lexical function returns the length of the string equated to the symbol FILE_NAME; this length is used as the offset. The expression requests that 4 characters of the string currently equated to the symbol FILE_TYPE be placed at the end of the string currently equated to FILE_NAME. The resultant value of the symbol FILE_NAME is MYFILE.TST.

## @ (Execute Procedure)

> Executes a command procedure or requests the command interpreter to read subsequent command input from a specific file or device.

### Format

> @ filespec [parameter[,...]]

### Parameters

> #### filespec

> Specifies either the input device or the file for the preceding command, or the command procedure to be executed. The default file type is .COM. The asterisk (*) and the percent sign (%) wildcard characters are not allowed in the file specification.

> #### parameter[,...]

> Specifies from one to eight optional parameters to pass to the command procedure. The symbols (P1, P2, ... P8) are assigned character string values in the order of entry. The symbols are local to the specified command procedure. Separate each parameter with one or more blanks. Use two consecutive quotation marks ("") to specify a null parameter. You can specify a parameter with a character string value containing alphanumeric or special characters, with the following restrictions:
> - The command interpreter converts alphabetic characters to uppercase and uses blanks to delimit each parameter. To pass a parameter that contains embedded blanks or literal lowercase letters, place the parameter in quotation marks.
> - If the first parameter begins with a slash (/), you must enclose the parameter in quotation marks (" ").
> - To pass a parameter that contains literal quotation marks and spaces, enclose the entire string in quotation marks and use two consecutive quotation marks within the string. For example, the command procedure TEST.COM contains the following line:

>       $ WRITE SYS$OUTPUT P1

>   Enter the following at the DCL prompt ($):

>       $ @TEST "Never say ""quit"""

>   When the procedure TEST.COM executes, the parameter P1 is equated to the following string:

>   `Never say "quit"`

>   If a string contains quotation marks and does not contain spaces, the quotation marks are preserved in the string and the letters within the quotation marks remain in lowercase. For example, enter the following at the DCL prompt:

>       $ @TEST abc"def"ghi

>   When the procedure TEST.COM executes, the parameter P1 is equated to the following string:

>   `ABC"def"GHI`

> To use a symbol as a parameter, enclose the symbol in single quotation marks (` ') to force symbol substitution. For example:

>     $ NAME = "JOHNSON"
>     $ @INFO 'NAME'

> The single quotation marks cause the value "JOHNSON" to be substituted for the symbol NAME. Therefore, the parameter "JOHNSON" is passed as P1 to INFO.COM.

### Description

> Use the @ command to execute a command procedure that contains the following:
> - DCL command lines or data, or both
> - Qualifiers or parameters, or both, for a specific command line

> To execute a command procedure containing commands or data, or both, place the @ command at the beginning of a command line and then specify the name of the command procedure file. The command procedure can contain DCL commands and input data for a command or program that is currently executing. All DCL commands in a command procedure must begin with a dollar sign ($). If a command is continued with a hyphen (-), the subsequent lines must not begin with a dollar sign.

> Any line in a command procedure that does not contain a dollar sign in the first character position (and is not a continuation line) is treated as input data for the command or program that is currently executing. The DECK command allows you to specify that data contains dollar signs in record position one.

> A command procedure can also contain the @ command to execute another command procedure. The maximum command level you can achieve by nesting command procedures is 16, including the top-level command procedure. Command procedures can also be queued for processing as batch jobs, either by using the SUBMIT command or by placing a deck of cards containing the command procedure in the system card reader.

> To execute a command procedure that contains qualifiers or parameters, or both, for a specific command line, place the @ command where the qualifiers or parameters normally would be in the command line. Then specify the name of the command procedure file containing the qualifiers or parameters.

> If the command procedure file begins with parameters for the command, the @ command must be preceded by a space. For example:

>     $ CREATE TEST.COM
>     TIME
>     [Ctrl/Z]
>     $ SHOW @TEST
>       14-SEP-2001 17:20:26

> If the file begins with qualifiers for the command, do not precede the @ command with a space. For example:

>     $ CREATE TEST_2.COM
>     /SIZE
>     [Ctrl/Z]
>     $ DIR@TEST_2

>     Directory WORK$:[SCHEDULE]

>     JANUARY.TXT;8         14-DEC-2001 15:47:45.57
>     FEBRUARY.TXT;7        14-DEC-2001 15:43:16.20
>     MARCH.TXT;6           14-DEC-2001 11:11:45.74
>        .
>        .
>        .
>     Total of 11 files.

> If the file contains parameters or qualifiers, or both, do not begin the lines in the file with dollar signs. Any additional data on the command line following @filespec is treated as parameters for the procedure.

### Qualifier

> #### /OUTPUT=filespec

> Specifies the name of the file to which the command procedure output is written. By default, the output is written to the current SYS$OUTPUT device. The default output file type is .LIS. The asterisk (*) and the percent sign (%) wildcard characters are not allowed in the output file specification. System responses and error messages are written to SYS$COMMAND as well as to the specified file. The /OUTPUT qualifier must immediately follow the file specification of the command procedure; otherwise, the qualifier is interpreted as a parameter to pass to the command procedure.

> You can also redefine SYS$OUTPUT to redirect the output from a command procedure. If you place the following command as the first line in a command procedure, output will be directed to the file you specify:

>     $ DEFINE SYS$OUTPUT filespec

> When the procedure exits, SYS$OUTPUT will be restored to its original equivalence string. This produces the same result as using the /OUTPUT qualifier when you execute the command procedure.

### Examples

#1
    $ CREATE DOFOR.COM
    $ ON WARNING THEN EXIT
    $ IF P1.EQS."" THEN INQUIRE P1 FILE
    $ FORTRAN/LIST 'P1'
    $ LINK 'P1'
    $ RUN 'P1'
    $ PRINT 'P1'
    [Ctrl/Z]
    $ @DOFOR AVERAGE

> This example shows a command procedure, named DOFOR.COM, that executes the FORTRAN, LINK, and RUN commands to compile, link, and execute a program. The ON command requests that the procedure not continue if any of the commands result in warnings or errors.

> When you execute DOFOR.COM, you can pass the file specification of the FORTRAN program as the parameter P1. If you do not specify a value for P1 when you execute the procedure, the INQUIRE command issues a prompting message to the terminal and equates what you enter with the symbol P1. In this example, the file name AVERAGE is assigned to P1. The file type is not included because the commands FORTRAN, LINK, RUN, and PRINT provide default file types.

#2
    $ @MASTER/OUTPUT=MASTER.LOG

> This command executes a procedure named MASTER.COM; all output is written to the file MASTER.LOG.

#3
    $ CREATE FILES.COM
    *.FOR, *.OBJ
    [Ctrl/Z]
    $ DIRECTORY @FILES

> This example shows a command procedure, FILES.COM, that contains parameters for a DCL command line. The entire file is treated by DCL as command input. You can execute this procedure after the DIRECTORY command to get a listing of all FORTRAN source and object files in your current default directory.

#4
    $ CREATE QUALIFIERS.COM
    /DEBUG/SYMBOL_TABLE/MAP/FULL/CROSS_REFERENCE
    [Ctrl/Z]
    $ LINK SYNAPSE@QUALIFIERS

> This example shows a command procedure, QUALIFIERS.COM, that contains qualifiers for the LINK command. When you enter the LINK command, specify the command procedure immediately after the file specification of the file you are linking. Do not type a space between the file specification and the @ command.

#5
    $ CREATE SUBPROCES.COM
    $ RUN 'P1' -
      /BUFFER_LIMIT=1024 -
      /FILE_LIMIT=4 -
      /PAGE_FILES=256 -
      /QUEUE_LIMIT=2 -
      /SUBPROCESS_LIMIT=2 -
      'P2'  'P3'  'P4'  'P5'  'P6'  'P7'  'P8'
    [Ctrl/Z]
    $ @SUBPROCES  LIBRA  /PROCESS_NAME=LIBRA

> This example shows a command procedure named SUBPROCES.COM. This procedure issues the RUN command to create a subprocess to execute an image and also contains qualifiers defining quotas for subprocess creation. The name of the image to be run is passed as the parameter P1. Parameters P2 to P8 can be used to specify additional qualifiers.

> In this example, the file name LIBRA is equated to P1; it is the name of an image to execute in the subprocess. The qualifier /PROCESS_NAME=LIBRA is equated to P2; it is an additional qualifier for the RUN command.

#6
    $ CREATE EDOC.COM
    $ ASSIGN SYS$COMMAND:  SYS$INPUT
    $ NEXT:
    $      INQUIRE NAME "File name"
    $      IF NAME.EQS."" THEN EXIT
    $      EDIT/TPU 'NAME'.DOC
    $      GOTO NEXT
    [Ctrl/Z]
    $ @EDOC

> This procedure, named EDOC.COM, invokes the EVE editor. When an edit session is terminated, the procedure loops to the label NEXT. Each time through the loop, the procedure requests another file name for the editor and supplies the default file type .DOC. When a null line is entered in response to the INQUIRE command, the procedure terminates with the EXIT command.

> The ASSIGN command changes the equivalence name of SYS$INPUT for the duration of the procedure. This change allows the EVE editor to read input data from the terminal, rather than from the command procedure file (the default input data stream if SYS$INPUT had not been changed). When the command procedure exits, SYS$INPUT is reassigned to its original value.

#7
    ! PEOPLE.DAT
    ! A set of data with embedded key qualifiers for the SORT command.
    !
    ! Usage: SORT@PEOPLE.DAT
    !
    /KEY=(POS:10,SIZE:10) sys$input people.out
    Fred     Flintstone    555-1234
    Barney   Rubble        555-2244
    Wilma    Flintstone    555-1234
    Betty    Rubble        555-2244
    George   Slate         555-8911
    Dino     Dinosaur      555-1234
    $!
    $ purge people.out
    $ type people.out

> Creates a sorted list of people in file PEOPLE.OUT and displays it. This demonstrates when using "@" in the middle of a DCL command, DCL redirects the entire file as command input.

## ACCOUNTING

> Runs the Accounting utility, which produces reports of resource use.

> For more information about the Accounting utility, refer to the OpenVMS System Management Utilities Reference Manual or online help.

### Format

> ACCOUNTING [filespec[,...]]

## ALLOCATE

> Provides your process with exclusive access to a device until you deallocate the device or terminate your process. Optionally associates a logical name with the device.

> Requires read (R), write (W), or control access.

### Format

> ALLOCATE device-name[:][,...] [logical-name[:]]

### Parameters

> #### device-name[:][,...]

> Specifies the name of a physical device or a logical name that translates to the name of a physical device. The device name can be generic: if no controller or unit number is specified, any device that satisfies the specified part of the name is allocated. If more than one device is specified, the first available device is allocated.

> #### logical-name[:]

> Specifies a string of 1 to 255 alphanumeric characters. Enclose the string in single quotation marks (` ') if it contains blanks. Trailing colons (:) are not used. The name becomes a process logical name with the device name as the equivalence name. The logical name remains defined until it is explicitly deleted or your process terminates.

### Qualifiers

> #### /GENERIC

> #### /NOGENERIC (default)

> Indicates that the first parameter is a device type rather than a device name. Example device types are: RX50, RD52, TK50, RC25, RCF25, and RL02. The first free, nonallocated device of the specified name and type is allocated.

> The /[NO]GENERIC qualifier is placed before the device-name parameter in the ALLOCATE command line. For example, you can allocate an RK07 device by entering the following command at the DCL prompt ($):

>     $ ALLOCATE/GENERIC RK07 DISK

> The following table shows some device types that you can specify with the /GENERIC qualifier. To see what devices are available, refer to your SPD for the OpenVMS version they are currently using.

> Devices by Classification
> Disk Devices
> EF51 | EF52 | EF53 | EF54 | EF58
> ESE20 | ESE25 | ESE52 | ESE56 | ESE58
> EZ31 | EZ31L | EZ32 | EZ32L | EZ33
> EZ33L | EZ34 | EZ35 | EZ51 | EZ52
> EZ53 | EZ54 | EZ56R | EZ58 | HSZ10
> HSZ15 | HSZ20 | HSZ40 | ML11 | RA60
> RA70 | RA71 | RA72 | RA73 | RA80
> RA81 | RA82 | RA90 | RA92 | RAH72
> RB02 | RB80 | RC25 | RCF25 | RD26
> RD31 | RD32 | RD33 | RD51 | RD52
> RD53 | RD54 | RF30 | RF31 | RF31F
> RF32 | RF35 | RF36 | RF37 | RF70
> RF71 | RF72 | RF73 | RF74 | RF75
> RFF31 | RFH31 | RFH32 | RFH35 | RFH72
> RFH73 | RK06 | RK07 | RL01 | RL02
> RM03 | RM05 | RM80 | RP04 | RP05
> RP06 | RP07 | RP07HT | RX01 | RX02
> RX04 | RX18 | RX23 | RX23S | RX26
> RX33 | RX33S | RX35 | RX50 | RZ01
> RZ13 | RZ14 | RZ15 | RZ16 | RZ17
> RZ18 | RZ22 | RZ23 | RZ23L | RZ24
> RZ24L | RZ25 | RZ25L | RZ26 | RZ26B
> RZ26L | RZ26M | RZ27 | RZ27B | RZ27L
> RZ28 | RZ28B | RZ28L | RZ29 | RZ29B
> RZ31 | RZ34L | RZ35 | RZ35L | RZ36
> RZ36L | RZ37 | RZ38 | RZ55 | RZ55L
> RZ56 | RZ56L | RZ57 | RZ57I | RZ57L
> RZ58 | RZ59 | RZ72 | RZ73 | RZ73B
> RZ74 | RZ74B | RZ75 | RZ75B | RZF01
> Compact Disk Devices
> RRD40 | RRD40S | RRD42 | RRD43 | RRD44
> RRD50 | RV20 | RV60 | RV80 | RW504
> RW510 | RW514 | RW516 | RWZ01 | RWZ21
> RWZ31 | RWZ51 | RWZ52 | RWZ53 | RWZ54
> Tape Devices
> TA78 | TA79 | TA81 | TA85 | TA86
> TA87 | TA90 | TA90E | TA91 | TAD85
> TAPE9 | TD34 | TD44 | TE16 | TF30
> TF70 | TF85 | TF86 | TK50 | TK50S
> TK60 | TK70 | TK70L | TKZ09 | TKZ60
> TL810 | TL820 | TLZ04 | TLZ06 | TLZ07
> TLZ6 | TLZ7 | TM32 | TS11 | TSZ05
> TSZ07 | TSZ08 | TU45 | TU56 | TU58
> TU77 | TU78 | TU80 | TU81 | TZ30
> TZ30S | TZ85 | TZ857 | TZ86 | TZ865
> TZ867 | TZ87 | TZ875 | TZ877 | TZ88
> TZ885 | TZ887 | TZ89 | TZ895 | TZ897
> TZK10 | TZK11 | TZX0 |  |

> #### /LOG (default)

> #### /NOLOG

> Displays a message indicating the name of the device allocated. If the operation specifies a logical name that is currently assigned to another device, then the superseded value is displayed.

###

#### Examples

#1
    $ ALLOCATE  DMB2:
    %DCL-I-ALLOC, _DMB2: allocated

> The ALLOCATE command in this example requests the allocation of a specific RK06/RK07 disk drive, that is, unit 2 on controller B. The system response indicates that the device was allocated successfully.

#2
    $ ALLOCATE  MT,MF:   TAPE:
    %DCL-I-ALLOC, _MTB2: allocated
    .
    .
    .
    $ SHOW LOGICAL TAPE:
    TAPE: = _MTB2:    (process)
    $ DEALLOCATE TAPE:
    $ DEASSIGN TAPE:

> The ALLOCATE command in this example requests the allocation of a tape device whose name begins with MT or MF and assigns it the logical name TAPE. The ALLOCATE command locates an available tape device whose name begins with MT, and responds with the name of the device allocated. (If no tape device beginning with MT had been found, the ALLOCATE command would have searched for a device beginning with MF.) Subsequent references to the device TAPE in user programs or command strings are translated to the device name MTB2.

> When the tape device is no longer needed, the DEALLOCATE command deallocates it and the DEASSIGN command deletes the logical name. Note that the logical name TAPE was specified with a colon on the ALLOCATE command, but that the logical name table entry does not have a colon.

#3
    $ ALLOCATE/GENERIC RL02 WORK
    %DCL-I-ALLOC, _DLA1: allocated
    %DCL-I-SUPERSEDE, previous value of WORK has been superseded

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 9996PRO_001.HTML