HP OpenVMS Systems Documentation

OpenVMS DCL Dictionary

This command selects all messages issued by the BACKUP facility and those messages documented as "Shared by several facilities," alphabetizes them, and outputs them to a printable file called MESSAGES.TXT.

By selecting the messages you want and directing them to a file, you can create and print your own customized messages documentation.

$ HELP/MESSAGE/EXTRACT=BADMESSAGE.MSGHLP BADMESSAGE
$ HELP/MESSAGE/DELETE=BADMESSAGE.MSGHLP-
_$ /LIBRARY=SYS$LOGIN:MYMESSAGES.MSGHLP$DATA
$ CONVERT SYS$LOGIN:MYMESSAGES.MSGHLP$DATA-
_$ SYS$LOGIN:MYMESSAGES.MSGHLP$DATA
$ PURGE SYS$LOGIN:MYMESSAGES.MSGHLP$DATA
$ HELP/MESSAGE/INSERT=BADMESSAGE.MSGHLP

The first command in this sequence extracts the hypothetical message BADMESSAGE from the default database and outputs it to file BADMESSAGE.MSGHLP.
The second command uses the BADMESSAGE.MSGHLP file to delete the BADMESSAGE description from the MYMESSAGES.MSGHLP$DATA file specified by the /LIBRARY qualifier.
The next two commands compress the MYMESSAGES.MSGHLP$DATA file to save disk space after the deletion.
The last command uses the BADMESSAGE.MSGHLP file (possibly an edited version at a later time) to insert the BADMESSAGE message into the default .MSGHLP$DATA file.

$ HELP/MESSAGE/EXTRACT=NOSNO.MSGHLP NOSNO
$ EDIT/EDT NOSNO.MSGHLP
1NOSNO, can't ski; no snow
2XCSKI, XCSKI Program
3Your attempt to ski failed because there is no snow.
4Wait until there is snow and attempt the operation again.
5If you don't want to wait, go to a location where there is
5snow and ski there.
5
5Or, try ice skating instead!
[EXIT]
$ HELP/MESSAGE/INSERT=NOSNO.MSGHLP

This command sequence shows how users with write access to .MSGHLP$DATA files supplied by Compaq can add a comment to a message.
The first command extracts hypothetical message NOSNO to file NOSNO.MSGHLP. The second command edits the .MSGHLP file to add a comment at the end of the message. Each comment line, even blank lines, includes a "5" prefix. The next command updates the database by using NOSNO.MSGHLP to insert the updated message into the default .MSGHLP$DATA file.

IF

Tests the value of an expression and, depending on the syntax specified, executes the following:

One command following the THEN keyword if the expression is true
Multiple commands following the $THEN command if the expression is true
One or more commands following the $ELSE command if the expression is false

Format

$ IF expression THEN [$] command
or
$ IF expression
$ THEN [command]
command

. . .
$ [ELSE] [command]
command

. . .
$ ENDIF

Note

Compaq advises against assigning a symbolic name that is already a DCL command name. Compaq especially discourages the assignment of symbols such as IF, THEN, ELSE, and GOTO, which can affect the interpretation of command procedures.

Parameters

expression
Defines the test to be performed. The expression can consist of one or more numeric constants, string literals, symbolic names, or lexical functions separated by logical, arithmetic, or string operators.
Expressions in IF commands are automatically evaluated during the execution of the command. Character strings beginning with alphabetic characters that are not enclosed in quotation marks (" ") are assumed to be symbol names or lexical functions. The command language interpreter (CLI) replaces these strings with their current values.
Symbol substitution in expressions in IF commands is not iterative; that is, each symbol is replaced only once. However, if you want iterative substitution, precede a symbol name with an apostrophe (') or ampersand (&).
The command interpreter does not execute an IF command when it contains an undefined symbol. Instead, the command interpreter issues a warning message and executes the next command in the procedure.
For a summary of operators and details on how to specify expressions, see the OpenVMS User's Manual.
command
Specifies the DCL command or commands to be executed, depending on the syntax specified, when the result of the expression is true or false.

Description

The IF command tests the value of an expression and executes a given command if the result of the expression is true. The expression is true if the result has an odd integer value, a character string value that begins with the letters Y, y, T, or t, or an odd numeric string value.
The expression is false if the result has an even integer value, a character string value that begins with any letter except Y, y, T, or t, or an even numeric string value.

Examples

#1
$ COUNT = 0 $ LOOP: $ COUNT = COUNT + 1 . . . $ IF COUNT .LE. 10 THEN GOTO LOOP $ EXIT

This example shows how to establish a loop in a command procedure, using a symbol named COUNT and an IF statement. The IF statement checks the value of COUNT and performs an EXIT command when the value of COUNT is greater than 10.

$ IF P1 .EQS. "" THEN GOTO DEFAULT
$ IF (P1 .EQS. "A") .OR. (P1 .EQS. "B") THEN GOTO 'P1'
$ WRITE SYS$OUTPUT "Unrecognized parameter option ''P1' "
$ EXIT
$ A:       !  Process option a
 .
 .
 .
$ EXIT
$ B:       !  Process option b
 .
 .
 .
$ EXIT
$ DEFAULT: !  Default processing
 .
 .
 .
$ EXIT

This example shows a command procedure that tests whether a parameter was passed. The GOTO command passes control to the label specified as the parameter.
If the procedure is executed with a parameter, the procedure uses that parameter to determine the label to branch to. For example:
@TESTCOM A
When the procedure executes, it determines that P1 is not null, and branches to the label A. Note that the EXIT command causes an exit from the procedure before the label B.

#3
$ SET NOON . . . $ LINK CYGNUS,DRACO,SERVICE/LIBRARY $ IF $STATUS $ THEN $ RUN CYGNUS $ ELSE $ WRITE SYS$OUTPUT "LINK FAILED" $ ENDIF $ EXIT

This command procedure uses the SET NOON command to disable error checking by the command procedure. After the LINK command, the IF command tests the value of the reserved global symbol $STATUS. If the value of $STATUS indicates that the LINK command succeeded, then the program CYGNUS is run. If the LINK command returns an error status value, the command procedure issues a message and exits.

INITIALIZE

Formats a disk or magnetic tape volume, writes a label on the volume, and leaves the disk empty except for the system files containing the structure information. All former contents of the disk are lost.
Requires VOLPRO (volume protection) privilege for most INITIALIZE command operations.

Format

INITIALIZE device-name[:] volume-label

Parameters

device-name[:]
Specifies the name of the device on which the volume to be initialized is physically mounted.
The device does not have to be allocated currently; however, allocating the device before initializing it is the recommended practice.
volume-label
Specifies the identification to be encoded on the volume. For a disk volume, you can specify a maximum of 12 ANSI characters; for a magnetic tape volume, you can specify a maximum of 6 alphanumeric characters. Letters are automatically changed to uppercase. Compaq strongly recommends that a disk volume label should only consist of alphanumeric characters, dollar signs ($), underscores (_), and hyphens (-).
To use ANSI "a" characters on the volume label on magnetic tape, you must enclose the volume name in quotation marks (" "). For an explanation of ANSI "a" characters, see the description of the /LABEL qualifier.

Description

The default format for disk volumes in the OpenVMS operating system is called the Files-11 On-Disk Structure Level 2. The default for magnetic tape volumes is based on Level 3 of the ANSI standard for magnetic tape labels and file structure for informational interchange (ANSI X3.27-1978).
The INITIALIZE command can also initialize disk volumes in the Files-11 On-Disk Structure Level 1 format.
You must have VOLPRO privilege to initialize a volume, except in the following cases:

A blank disk or magnetic tape volume; that is, a volume that has never been written
A disk volume that is owned by your current user identification code (UIC) or by the UIC [0,0]
A magnetic tape volume that allows write (W) access to your current UIC that was not protected when it was initialized

After the volume is initialized and mounted, the SET SECURITY command may be used to modify the security profile. When you initialize a disk volume, the caching attribute of its root directory (000000.DIR;1) is set to write-through. This means that by default, all the files and directories that you create in the volume will inherit a caching attribute of write-through. To change the caching attribute, use the SET FILE command with the /CACHING_ATTRIBUTE qualifier.
When the INITIALIZE command initializes a magnetic tape volume, it always attempts to read the volume. A blank magnetic tape can sometimes cause unrecoverable errors, such as the following:
An invalid volume number error message:
%INIT-F-VOLINV, volume is invalid
A runaway magnetic tape (this frequently occurs with new magnetic tapes that have never been written or that have been run through verifying machines). You can stop a runaway magnetic tape only by setting the magnetic tape drive off line and by then putting it back on line.
If this type of unrecoverable error occurs, you can initialize a magnetic tape successfully by repeating the INITIALIZE command from an account that has VOLPRO (volume protection) privilege and by specifying the following qualifier in the command:

/OVERRIDE=(ACCESSIBILITY,EXPIRATION)

This qualifier ensures that the INITIALIZE command does not attempt to verify any labels on the magnetic tape.
If you have VOLPRO privilege, the INITIALIZE command initializes a disk without reading the ownership information. If you do not have VOLPRO privilege, the INITIALIZE command checks the ownership of the volume before initializing the disk. A blank disk or a disk with an incorrect format can sometimes cause a fatal drive error. If a blank disk or a disk with an incorrect format causes this type of error, you can initialize a disk successfully by repeating the INITIALIZE command with the /DENSITY qualifier from an account that has VOLPRO privilege.
Many of the INITIALIZE command qualifiers allow you to specify parameters that can maximize input/output (I/O) efficiency.

Qualifiers

/ACCESSED=number-of-directories
Affects Files-11 On-Disk Structure Level 1 disks only.
Specifies that, for disk volumes, the number of directories allowed in system space must be a value from 0 to 255. The default value is 3.
/BADBLOCKS=(area[,...])
Specifies, for disk volumes, faulty areas on the volume. The INITIALIZE command marks the areas as allocated so that no data is written in them.
Possible formats for area are as follows:

lbn[:count] Logical block number (LBN) of the first block and optionally a block count beginning with the first block, to be marked as allocated

sec.trk.cyl[:cnt] Sector, track, and cylinder of the first block, and optionally a block count beginning with the first block, to be marked as allocated

All media supplied by Compaq and supported on the OpenVMS operating system, except diskettes and TU58 cartridges, are factory formatted and contain bad block data. The Bad Block Locator utility (BAD) or the diagnostic formatter EVRAC can be used to refresh the bad block data or to construct it for the media exceptions above. The /BADBLOCKS qualifier is necessary only to enter bad blocks that are not identified in the volume's bad block data.
DIGITAL Storage Architecture (DSA) disks (for example, disks attached to UDA-50 and HSC50 controllers) have bad blocks handled by the controller, and appear logically perfect to the file system.
For information on how to run BAD, refer to the OpenVMS Bad Block Locator Utility Manual (available on the Documentation CD-ROM).
/CLUSTER_SIZE=number-of-blocks
Defines, for disk volumes, the minimum allocation unit in blocks. The maximum size you can specify for a volume is 16382 blocks, or 1/50th the volume size, whichever is smaller.
For Files-11 On-Disk Structure Level 5 (ODS-5) disks, the default cluster size is 3. In this case the minimum value allowed by the following equation is applied:
(disk size in number of blocks)/(65535 * 4096)
Any fractional values must be rounded up to the nearest integer.
For Files-11 On-Disk Structure Level 2 (ODS-2) disks, the default cluster size depends on the disk capacity; disks with less than 50,000 have a default of 1. Disks that are larger than 50,000 have a default of either 3 or the result of the following formula, whichever is greater:
(disk size in number of blocks)/(255 * 4096)
Any fractional values must be rounded up to the nearest integer.
For Files-11 On-Disk Structure Level 1 (ODS-1) disks, the cluster size must always be 1.

Note
For Version 7.2, you can specify a cluster size for ODS-2 volumes smaller than allowed by the ODS-2 formula; however, if you try to mount this volume on a system running a version prior to 7.2, the mount fails with the following error:

%MOUNT-F-FILESTRUCT, unsupported file structure level

If you choose the default during the initialization of a Files-11 On-Disk Structure Level 2 (ODS-2) disk, your disk can be mounted on prior versions of OpenVMS.

/DATA_CHECK[=(option[,...])]
Checks all read and write operations on the disk. By default, no data checks are made. Specify one or both of the following options:

READ Checks all read operations.

WRITE Checks all write operations; default if only the /DATA_CHECK qualifier is specified.

To override the checking you specify at initialization for disks, enter a MOUNT command to mount the volume.
/DENSITY=density-value
Allows you to specify the format density value for certain tapes and disks.
For magnetic tape volumes, specifies the density in bits per inch (bpi) at which the magnetic tape is to be written. The density value specified can be 800 bpi, 1600 bpi, or 6250 bpi, as long as the density is supported by the magnetic tape drive.
If you do not specify a density value for a blank magnetic tape, the system uses a default density of the highest value allowed by the tape drive. If the drive allows 6250-, 1600-, and 800-bpi operation, the default density is 6250 bpi.
If you do not specify a density value for a magnetic tape that has been previously written, the system uses the density of the first record on the volume. If the record is unusually short, the density value will not default.
The /DENSITY qualifier does not apply to any TF tape device.
Valid tape density values are:

Keyword Meaning

DEFAULT Default density

800 NRZI 800 bits per inch (BPI)

1600 PE 1600 BPI

6250 GRC 6250 BPI

3480 IBM 3480 HPC 39872 BPI

3490E IBM 3480 compressed

833 DLT TK50: 833 BPI

TK50 DLT TK50: 833 BPI

TK70 DLT TK70: 1250 BPI

6250 RV80 6250 BPI EQUIVALENT

NOTE: Only the keywords above are understood by TMSCP/TUDRIVER code prior to OpenVMS Version 7.2. The remaining keywords in this table are supported only on Alpha systems.

TK85 DLT Tx85: 10625 BPI - Cmpt III - Alpha only

TK86 DLT Tx86: 10626 BPI - Cmpt III - Alpha only

TK87 DLT Tx87: 62500 BPI - Cmpt III - Alpha only

TK88 DLT Tx88: (Quantum 4000) - Cmpt IV - Alpha only

TK89 DLT Tx89: (Quantum 7000) - Cmpt IV - Alpha only

QIC All QIC drives are drive-settable only - Alpha only

8200 Exa-Byte 8200 - Alpha only

8500 Exa-Byte 8500 - Alpha only

DDS1 Digital Data Storage 1 - 2G - Alpha only

DDS2 Digital Data Storage 2 - 4G - Alpha only

DDS3 Digital Data Storage 3 - 8-10G - Alpha only

DDS4 Digital Data Storage 4 - Alpha only

AIT1 Sony Advanced Intelligent Tapes - Alpha only

To format a diskette on RXnn diskette drives, use the INITIALIZE/DENSITY command. Specify the density at which the diskette is to be formatted as follows:

Keyword Meaning

single RX01 - 8 inch

double RX02 - 8 inch

dd double density: 720K - 3 1/2 inch

hd high density: 1.44MB - 3 1/2 inch

ed extended density: 2.88MB - 3 1/2 inch

If you do not specify a density value for a diskette being initialized on a drive, the system leaves the volume at the density to which the volume was last formatted.

Note
Diskettes formatted in double density cannot be read or written by the console block storage device (an RX01 drive) of a VAX-11/780 until they have been reformatted in single density.
RX33 diskettes cannot be read from or written to by RX50 disk drives. RX50 diskettes can be read from and written to by RX33 disk drives; they cannot be formatted by RX33 disk drives.

/DIRECTORIES=number-of-entries
The effect of this qualifier depends on the disk structure:

For ODS-1, /DIRECTORIES allows space for the specified number of directory entries to be reserved in 000000.DIR (the MFD).
For ODS-2 and ODS-5, /DIRECTORIES allows the initial size of the MFD to be set. The specified number is divided by 16, to produce the number of blocks to preallocate. This number is then rounded up to a whole number of clusters.

The number-of-entries value must be an integer between 16 and 16000. The default value is 16.
/ERASE

/NOERASE (default)
Physically destroys deleted data by writing over it. Controls the data security erase (DSE) operation on the volume before initializing it. The /ERASE qualifier applies to Files-11 On-Disk Structure Level 2 and 5 disks and ANSI magnetic tape volumes, and is valid for magnetic tape devices that support the hardware erase function, such as TU78 and MSCP magnetic tapes.
If you specify the /ERASE qualifier, a DSE operation is performed on the volume. For disk devices, the ERASE volume attribute is set. In effect, each file on the volume is erased when it is deleted.
Note that the amount of time taken by the DSE operation depends on the volume size; the INITIALIZE/ERASE command is always slower than the INITIALIZE/NOERASE command.
/EXTENSION=number-of-blocks
Specifies, for disk volumes, the number of blocks to use as a default extension size for all files on the volume. The extension default is used when a file increases to a size greater than its initial default allocation during an update. For Files-11 On-Disk Structure Level 2 disks, the value for the number-of-blocks parameter can range from 0 to 65,535. The default value is 5. For Files-11 On-Disk Structure Level 1 disks, the value can range from 0 to 255.
The OpenVMS operating system uses the default volume extension only if no different extension has been set for the file and no default extension has been set for the process by using the SET RMS_DEFAULT command.
/FILE_PROTECTION=code
Affects Files-11 On-Disk Structure Level 1 disks only.
Defines for disk volumes the default protection to be applied to all files on the volume.
Specify the code according to the standard syntax rules described in the OpenVMS Guide to System Security. Any attributes not specified are taken from the current default protection.
Note that this attribute is not used when the volume is being used on an OpenVMS system, but is provided to control the process's use of the volume on RSX-11M systems. OpenVMS systems always use the default file protection. Use the SET PROTECTION/DEFAULT command to change the default file protection.
/GROUP
Used in conjunction with the /NOSHARE qualifier to create a group volume. The group volume allows access by system (S), owner (O), and group (G) accessors. The protection is (S:RWCD,O:RWCD,G:RWCD,W).
The owner user identification code (UIC) of the volume defaults to your group number and a member number of 0.
/HEADERS=number-of-headers
Specifies, for disk volumes, the number of file headers to be allocated for the index file. The minimum and default value is 16. The maximum is the value set with the /MAXIMUM_FILES qualifier.
This qualifier is useful when you want to create a number of files and want to streamline the process of allocating space for that number of file headers. If you do not specify this qualifier, the file system dynamically allocates space as it is needed for new headers on the volume.

Note
The default value for the /HEADERS qualifier is generally insufficient for ODS-2 disks. To improve performance and avoid SYSTEM-F-HEADERFULL errors, Compaq recommends that you set this value to be approximately the number of files that you anticipate having on your disk; however, grossly overestimating this value will result in wasted disk space.

The /HEADERS qualifier controls how much space is initially allocated to INDEXF.SYS for headers. Each file on a disk requires at least one file header and each header occupies one block within INDEXF.SYS. Files that have many Access Control Entries (ACE) or are very fragmented may use more than one header.
The default value of 16 leaves room for less than 10 files to be created before INDEXF.SYS must extend; therefore, try to estimate the total number of files that will be created on the disk and specify it here. This will improve disk access performance. Overestimating the value may lead to wasted disk space. This value cannot be changed without reinitializing the volume.
INDEXF.SYS is limited as to how many times it may extend. When the map area in its header (where the retrieval pointers are stored) becomes full, file creation fails with the message "SYSTEM-W-HEADERFULL."
/HIGHWATER (default)

/NOHIGHWATER
Affects Files-11 On-Disk Structure Level 2 disks only.
Sets the file high-water mark (FHM) volume attribute, which guarantees that users cannot read data that they have not written. You cannot specify the /NOHIGHWATER qualifier for magnetic tape.
The /NOHIGHWATER qualifier disables FHM for a disk volume.
/HOMEBLOCKS=option
This qualifier applies only to Files-11 ODS-2 volumes.
It specifies where the volume's homeblock and spare copy of the homeblock are placed on disk. The value of option can be one of the following:

GEOMETRY
Causes the homeblocks to be placed at separate locations on disk, to protect against failure of a disk block. Placement depends on the reported geometry of the disk.
FIXED
Causes the homeblocks to be placed at separate fixed locations on the disk; this is the default. Placement is independent of the reported geometry of the disk. This caters for disks that report different geometries according to which type of controller they are attached to.
CONTIGUOUS
Causes the homeblocks to be placed contiguously at the start of the disk. This allows container file systems to maximize the amount of contiguous space on the disk, when used with the /INDEX=BEGINNING qualifier.

/INDEX=position
Specifies the location of the index file for the volume's directory structure. Possible positions are as follows:

BEGINNING Beginning of the volume

MIDDLE Middle of the volume (default)

END End of the volume

BLOCK: n Beginning of the logical block specified by n

/INTERCHANGE
Specifies that the magnetic tape will be used for interchange in a heterogeneous vendor environment. The /INTERCHANGE qualifier omits the ANSI VOL2 labels. Under OpenVMS, the ANSI VOL2 labels contain OpenVMS specific security attributes.

Previous Next Contents Index