[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS DCL Dictionary


Previous Contents Index

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

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

#6

$ 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 Compaq-supplied .MSGHLP$DATA files can add a comment to a Compaq-supplied 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:

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.

#2

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

After the volume is initialized and mounted, the SET SECURITY command may be used to modify the security profile.

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:

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.

/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 one-hundredth the size of the volume.

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

The /DENSITY qualifier is not applicable to any TF tape device.

Valid density values are as follows:
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.
TK85 DLT Tx85: 10625 BPI - Cmpt III
TK86 DLT Tx86: 10626 BPI - Cmpt III
TK87 DLT Tx87: 62500 BPI - Cmpt III
TK88 DLT Tx88: (Quantum 4000) - Cmpt IV
TK89 DLT Tx89: (Quantum 7000) - Cmpt IV
QIC All QIC drives are drive-settable only
8200 Exa-Byte 8200
8500 Exa-Byte 8500
DDS1 Digital Data Storage 1 - 2G
DDS2 Digital Data Storage 2 - 4G
DDS3 Digital Data Storage 3 - 8-10G
DDS4 Digital Data Storage 4
AIT1 Sony Advanced Intelligent Tapes

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.

For magnetic tape volumes, specifies the density in bits per inch (bpi) at which the magnetic tape is to be written.

For magnetic tape volumes, 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.

/DIRECTORIES=number-of-entries

The effect of this qualifier depends on the disk structure:

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 disk 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. Over-estimating 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:

/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

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
9996PRO_022.HTML