OpenVMS DCL Dictionary

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-DEC-1994 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-1994 15:47:45.57 
FEBRUARY.TXT;7        14-DEC-1994 15:43:16.20 
MARCH.TXT;6           14-DEC-1994 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

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

$ @MASTER/OUTPUT=MASTER.LOG

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

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

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

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

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

ACCOUNTING

Runs the Accounting utility, which produces reports of resource use. For a complete description of the Accounting utility, see the OpenVMS System Management Utilities Reference Manual.

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.

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

Examples

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

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

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

The ALLOCATE command in this example requests the allocation of any RL02 disk device and assigns the logical name WORK to the device. The completion message identifies the allocated device and indicates that the assignment of the logical name WORK supersedes a previous assignment of that name.

$ ALLOCATE $TAPE1
%DCL-I-ALLOC, _MUA0: allocated

The ALLOCATE command in this example allocates the tape device MUA0, which is associated with the logical name $TAPE1.

$ ALLOCATE /GENERIC RX50 ACCOUNTS

The ALLOCATE command in this example allocates the first free floppy disk drive and makes its name equivalent to the process logical name ACCOUNTS.

ANALYZE/AUDIT

Invokes the Audit Analysis utility, which selectively extracts and displays information from security audit log files or security archive files. For a complete description of the Audit Analysis utility, see the OpenVMS System Management Utilities Reference Manual.

Format

ANALYZE/AUDIT [filespec]

ANALYZE/CRASH_DUMP

Invokes the System Dump Analyzer utility, which analyzes a system dump file. The /CRASH_DUMP qualifier is required.
For a complete description of the System Dump Analyzer utility on Alpha, see the OpenVMS Alpha System Dump Analyzer Utility Manual. For a complete description of the System Dump Analyzer utility on VAX, see the OpenVMS VAX System Dump Analyzer Utility Manual.

Format

ANALYZE/CRASH_DUMP filespec

ANALYZE/DISK_STRUCTURE

Invokes the Analyze/Disk_Structure utility, which does the following:

Checks the readability and validity of Files-11 On-Disk Structure Level 1 and Files-11 On-Disk Structure Level 2 disk volumes.
Reports errors and inconsistencies.

The /DISK_STRUCTURE qualifier is required. For a complete description of the Analyze/Disk_Structure utility, see the OpenVMS System Management Utilities Reference Manual.

Format

ANALYZE/DISK_STRUCTURE device-name[:]

ANALYZE/ERROR_LOG

Invokes the Errorlog Report Formatter, which selectively reports the contents of an error log file. The /ERROR_LOG qualifier is required. For a complete description of the Error Log utility, see the OpenVMS System Management Utilities Reference Manual.

Format

ANALYZE/ERROR_LOG [filespec[,...]]

ANALYZE/IMAGE

Analyzes the contents of an executable image file or a shareable image file on Alpha, VAX, and translated VAX images, and checks for obvious errors in the image file. The /IMAGE qualifier is required. For general information about image files, see the description of the linker in the OpenVMS Linker Utility Manual. (Use the ANALYZE/OBJECT command to analyze the contents of an object file.)

Note
The OpenVMS VAX Version 6.1 and 6.2 ANALYZE/IMAGE command cannot analyze an OpenVMS Alpha image.

Format

ANALYZE/IMAGE filespec[,...]

PARAMETER

filespec[,...]
Specifies the name of one or more image files that you want analyzed. You must specify at least one file name. If you specify more than one file, separate the file specifications with either commas (,) or plus signs (+). The default file type is .EXE.
The asterisk (*) and percent sign (%) wildcard characters are allowed in the file specification.

DESCRIPTION

The ANALYZE/IMAGE command provides a description of the components of an executable image file or shareable image file. It also verifies that the structure of the major parts of the image file is correct. However, the ANALYZE/IMAGE command cannot ensure that program execution is error free.
If errors are found, the first error of the worst severity is returned. For example, if a warning (A) and two errors (B and C) are found, the first error (B) is returned as the image exit status. The image exit status is placed in the DCL symbol $STATUS at image exit.
The ANALYZE/IMAGE command distinguishes Alpha system image files from VAX system image files by examining the extended image header (EIHD).
The ANALYZE/IMAGE command provides the following information:

Image type---Identifies whether the image is executable or shareable.
Image transfer addresses---Identify the addresses to which control is passed at image execution time.
Image version---Identifies the revision level (major ID and minor ID) of the image.
Location and size of the image's symbol vector (Alpha only)
Location of the debugger symbol table (DST)---Identifies the location of the DST in the image file. DST information is present only in executable images that have been linked with the /DEBUG or the /TRACEBACK command qualifier.
Location of the global symbol table (GST)---Identifies the location of the GST in the image file. GST information is present only in shareable image files.
Patch information---Indicates whether the image has been patched (changed without having been recompiled or reassembled and relinked). If a patch is present, the actual patch code can be displayed.
Image section descriptors (ISD)---Identify portions of the image binary contents that are grouped in OpenVMS Cluster systems according to their attributes. An ISD contains information that the image activator needs when it initializes the address space for an image. For example, an ISD tells whether the ISD is shareable, whether it is readable or writable, whether it is based or position independent, and how much memory should be allocated.
Fixup vectors---Contain information that the image activator needs to ensure the position independence of shareable image references.
System version categories---For an image that is linked against the executive (the system shareable image on Alpha or the system symbol table on VAX), displays both the values of the system version categories for which the image was linked originally and the values for the system that is currently running. You can use these values to identify changes in the system since the image was linked last.

The ANALYZE/IMAGE command has command qualifiers and positional qualifiers. By default, if you do not specify any positional qualifiers (for example, /GST or /HEADER), the entire image is analyzed. If you do specify a positional qualifier, the analysis excludes all other positional qualifiers except the /HEADER qualifier (which is always enabled) and any qualifier that you request explicitly.

QUALIFIERS

/FIXUP_SECTION
Positional qualifier.
Specifies that the analysis should include all information in the fixup section of the image.

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

Legal