OpenVMS DCL Dictionary

The four DEFINE statements create logical names for the four user-defined help libraries that the Help facility is to search after it has searched the root library. The first three entries are help libraries in the current default directory. By default, the Help facility searches for user-defined help libraries in the directory defined by the logical name SYS$HELP. The fourth entry is the help library FLIP.HLB in the directory DISK2:[MALCOLM]. Note that the logical names that you use to define these help libraries must be numbered consecutively; that is, you cannot skip any numbers.

The Help facility first searches the root library for REM. It then searches the libraries HLP$LIBRARY, HLP$LIBRARY_1, HLP$LIBRARY_2, and so on, until it finds REM or exhausts the libraries it knows it can search. When it finds REM in the BASIC.HLB library, the Help facility displays the appropriate help information and prompts you for a subtopic in that library. If you request information on a topic not in the BASIC.HLB library, the Help facility once again searches the help libraries you have defined.

HELP/MESSAGE

Displays descriptions of system messages.

Format

HELP/MESSAGE [/qualifier [...]] [search-string]

PARAMETER

search-string
Specifies a message identifier or one or more words from a message's text. By default, HELP/MESSAGE displays a description of the message produced by the last executed command (that is, the message corresponding to the value currently stored in the CLI symbol $STATUS).
The Help Message utility (MSGHLP) operates on the search string using the following conventions:

Words containing fewer than three alphanumeric characters are ignored.
Words can be specified in any order.
You can minimize search time by specifying the most unusual word first.
Nonalphanumeric characters are ignored in the search. Exceptions are the percent sign (%) and hyphen (-) when they prefix a message. Therefore, you can paste a full message into the search string, provided you include these special characters and delete any variables (such as file names) that were inserted into the message.
If Help Message fails to find a pasted message in the database, submit the command again and omit the leading special character, facility, and severity. Some common messages are documented as "shared" messages rather than facility-specific messages.
Help Message matches all words that begin with the characters specified in the search string. Use /WORD_MATCH=WHOLE_WORD to specify that only whole words be matched.

DESCRIPTION

The Help Message utility accesses message descriptions in a text file. This text file is derived from the latest OpenVMS system messages documentation, and, optionally, from other source files, including user-supplied message documentation. By default, Help Message provides information on how the last executed command completed.
You can extract all messages produced by one or more specified facilities. By directing this output to a file, you can create and print your own customized message documentation.
For full details about adding comments or messages to the Help Message database, refer to the OpenVMS System Messages: Companion Guide for Help Message Users.

QUALIFIERS

/BRIEF
Outputs the message text only.
/DELETE=filename.MSGHLP
Deletes all messages contained in the specified .MSGHLP file from whichever of the following files is found first:

A .MSGHLP$DATA file specified with the /LIBRARY qualifier
The first .MSGHLP$DATA file in a search path specified by the /LIBRARY qualifier
The first .MSGHLP$DATA file in the default search path (defined by logical name MSGHLP$LIBRARY)
SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA (the default .MSGHLP$DATA file)

You must have write access to Digital-supplied .MSGHLP$DATA files to delete messages from the Digital-supplied database.

Note
If you create a .MSGHLP file by specifying a search string, check the output .MSGHLP file to be sure the search did not pick up any unexpected messages that you do not want to delete from the database. Edit any such messages out of the .MSGHLP file before you perform the delete operation.

/EXTRACT=filename.MSGHLP
Extracts messages from the database and generates a .MSGHLP file that can be edited, if desired, and used as input for /INSERT and /DELETE operations. /EXTRACT retrieves data from a .MSGHLP$DATA file or logical search path specified by /LIBRARY or, by default, from files in the search path defined by logical name MSGHLP$LIBRARY. When /EXTRACT is not specified, Help Message produces output in standard text format by default (see /OUTPUT).
/FACILITY=?

/FACILITY=(facility-name [,...])

/FACILITY=ALL
Specifies which facilities in the database are to be searched for a match.
Enter /FACILITY=? to output a list of all facilities in the default database or in a database specified by /LIBRARY.
To narrow your search, specify one or more facility names with /FACILITY. (Multiple facilities must be enclosed in parentheses and be separated by commas.) Help Message then outputs only matching messages produced by the specified facility or facilities.
Specify /FACILITY=ALL to output messages for all facilities in the database. /FACILITY=ALL is the default unless another facility is implied; for example, specifying /STATUS or defaulting to the value of the CLI symbol $STATUS automatically identifies a specific facility. Similarly, cutting and pasting a message that includes a facility name invalidates use of the /FACILITY qualifier.
See the OpenVMS System Messages: Companion Guide for Help Message Users for more details about using the /FACILITY qualifier.
/FULL (default)
Outputs the complete message description, including message text, facility name, explanation, user action, and user-supplied comment, if any.
/INSERT=filename.MSGHLP

/INSERT=TT:
Updates the first of the following files to be found with new or changed information from the specified .MSGHLP file, or, if TT: is specified, with the data entered immediately at the terminal:

A .MSGHLP$DATA file specified with the /LIBRARY qualifier
The first .MSGHLP$DATA file in a search path specified by the /LIBRARY qualifier
The first .MSGHLP$DATA file in the default search path (defined by logical logical name MSGHLP$LIBRARY)
SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA (the default .MSGHLP$DATA file)

You must have write access for the Digital-supplied .MSGHLP$DATA files to insert data into these files. User-supplied data is identified by change bars in Help Message output.
/LIBRARY=disk:[directory]filename.MSGHLP$DATA

/LIBRARY=disk:[directory]

/LIBRARY=logical-name
Defines the messages database for the current command to be a particular .MSGHLP$DATA file, all the .MSGHLP$DATA files in a specified directory, or all the files in a search path defined by a logical name.
For most operations, the default database is either SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA or a search path of .MSGHLP$DATA files defined by the logical name MSGHLP$LIBRARY.
For /DELETE and /INSERT operations, the default database is either SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA or the first file in a search path defined by the logical name MSGHLP$LIBRARY.
/OUTPUT=filespec
Writes output to the specified file. By default, Help Message writes output to SYS$OUTPUT, which is normally the terminal. (Use of /OUTPUT=filespec is incompatible with /PAGE.)
/PAGE (default for screen display)

/NOPAGE
Displays terminal output one screen at a time. The page length is automatically set to 1 line less than the value specified by SET TERMINAL/PAGE. (Use of /PAGE is incompatible with /OUTPUT=filespec.)
/SECTION_FILE=*

/SECTION_FILE=file-spec
Identifies the specified message section file to the system so that Help Message can interpret the $STATUS values for the messages in that file. The default file specification is SYS$MESSAGE:.EXE. Specifying /SECTION_FILE=* automatically includes all OpenVMS-supplied message section files. For more information, see OpenVMS System Messages: Companion Guide for Help Message Users.

Note
The results of using this qualifier are entirely independent from those created by the SET MESSAGE command. The Help Message utility and Message utility do not interact. You must separately code each utility to obtain the results you want.

/SORT

/NOSORT (default)
Sorts output in alphabetical order. If a sort fails, retry the operation using the /WORK_FILES qualifier.
/STATUS=status-code

/STATUS='symbol'

/STATUS='$STATUS' (default)
Outputs the message corresponding to the specified status code. You can specify the status code with a decimal or hexadecimal number or a symbol enclosed in apostrophes. You can omit leading zeros, but you must prefix any hexadecimal number with "%X".
If a HELP/MESSAGE command does not include a search string, Help Message by default outputs the message corresponding to the CLI symbol $STATUS; that is, Help Message displays information on how the last executed command completed.
You cannot specify a search string or /FACILITY with /STATUS. /FACILITY is also illegal if you omit the search string and default to /STATUS='$STATUS'.
/WORD_MATCH=INITIAL_SUBSTRING (default)

/WORD_MATCH=WHOLE_WORD
/WORD_MATCH=INITIAL_SUBSTRING matches all words that begin with a word specified in the search string. The search string can contain multiple words to be matched. Only messages that match every word in the search string (in any order) are output.
/WORD_MATCH=WHOLE_WORD matches whole words only and refines your search to the exact words specified. For example, an exact search on ACC screens out dozens of other messages containing words that begin with the letters ACC.
/WORK_FILES=nn

/WORK_FILES=0 (default if qualifier is omitted)

/WORK_FILES=2 (default if qualifier is entered with no value)
Specifies that work files are to be used if the /SORT qualifier is specified. You can specify a value from 0 to 10 for nn. This qualifier has no effect if /SORT is not specified.

Examples

$ SHOW DEVICE KUDOS
%SYSTEM-W-NOSUCHDEV, no such device available
$ HELP/MESSAGE

The first command creates an error. The default HELP/MESSAGE command (with no qualifiers) displays a description of the SYSTEM facility message NOSUCHDEV.

$ HELP/MESSAGE ACCVIO
$ HELP/MESSAGE/BRIEF ACCVIO
$ HELP/MESSAGE/FACILITY=SYSTEM ACCVIO
$ HELP/MESSAGE VIRTUAL ACCESS
$ HELP/MESSAGE/STATUS=12
$ HELP/MESSAGE/STATUS=%XC

These commands demonstrate how you can use various qualifiers to access and display the ACCVIO message (sometimes several!) in different formats.

$ HELP/MESSAGE/BRIEF ACC
$ HELP/MESSAGE/BRIEF/WORD_MATCH=WHOLE_WORD ACC

In the first command, Help Message by default matches dozens of words beginning with the string "ACC." The /WORD_MATCH=WHOLE_WORD qualifier dramatically refines the search to match the exact word only.

$ HELP/MESSAGE/FACILITY=(BACKUP,SHARED)/SORT/OUTPUT=MESSAGES.TXT

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

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
Digital advises against assigning a symbolic name that is already a DCL command name. Digital 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

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

$  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. DIGITAL 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 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 Digital 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, see 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; the minimum size you can specify is calculated with the following formula:
disk size (number of blocks)
255 * 4096

For Files-11 On-Disk Structure Level 2 disks, the OpenVMS Cluster size default 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 3, unless this default would break the formula. In this case the minimum value allowed by the equation above is applied.
For Files-11 On-Disk Structure Level 1 disks, the cluster size must always be 1.
/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 TK or TF tape device.
Valid density values are as follows:

800 6250 HD SINGLE

1600 DD ED DOUBLE

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:

Diskette Density value

RX02 SINGLE or DOUBLE

RX33 DOUBLE

RX26 ED

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
Specifies, for disk volumes, the number of entries to preallocate for user directories. The number of entries 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.

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

Legal

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

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