Updated: 11 December 1998

Guide to OpenVMS File Applications

The device can be identified with either a physical name or a logical name. You can terminate a physical device name or a logical device name with a colon and place one or more file specification components (directory name, file name, file type, and version) after it.

A logical device name may translate to another logical name, a physical device name, or a physical device name with additional file specification components. The logical name may translate to a combined device name, which may be a logical name itself, and root name. The logical name can be a search list, which specifies multiple file locations where the file can be found. (See Section 5.7.)

You have to include only the device name when specifying a record-oriented device, such as a terminal. However, if you choose to include other file specification components, you must follow the naming conventions described previously.

See also section Section 5.3.

The following file specification format is used only for ANSI-formatted magnetic tape volumes:

device:[directory-name]"quoted-ascii-a-string".;nn

The OpenVMS User's Manual lists the characters from the DEC Multinational character set and the ASCII "a" characters that can be used in a quoted string for naming ANSI-formatted magnetic tape files.

5.2.3 On-Disk Components

The following sections describe the file specification components that apply to files residing on disks. The details of the components are determined by whether the application is running on an Alpha system or a VAX system and on the structure level of the disk.

5.2.3.1 Character Set for On-Disk Components

As of OpenVMS V7.2 on Alpha systems, RMS supports a larger character set than was supported in previous versions; it is also larger than the set that is supported under V7.2 on VAX systems. Creating such files is supported only on disks of ODS-5 (or greater) structure level.

5.2.3.1.1 Base Character Set

On OpenVMS Alpha and VAX systems, on ODS-5 and ODS-2 devices, a basic set of simple characters is valid for the node, device, root, directory, and file name and type components of a file specification. These characters include the following:

• Upper and lowercase alphanumeric characters:

  A - Z, a - z, 0 - 9

• Special ASCII (7-bit) characters:

  $ - _ ~

In addition, OpenVMS V7.2 on Alpha systems and ODS-5 disks includes support for the use of file names, and subdirectory and root subdirectory names, that include all possible 8-bit characters, excluding values 00 through 1F (hexadecimal) and excluding the following characters:

< > : / \ | ? * "

Note that the character set includes both the ISO Latin-1 C1 character set (hexadecimal 80 - 9F) as well as graphical and other characters between 9F and FF. This allows the entire ISO Latin-1 character set (with the exclusions noted above). In addition, there is support for names that include any of the defined 16-bit Unicode characters (except for the character exclusions noted above).

5.2.4 RMS and On-Disk Representation

The extended character set includes characters that have special significance to RMS (for example, delimiters, such as ']'), that have significance to DCL (for example, the comment character, '!'), and that cannot be easily entered or displayed via keyboards and display devices that are commonly available (for example, the Unicode characters and the ISO Latin-1 C1 control characters). To accommodate the use of these characters, RMS accepts and displays them in a format that uses a sequence of common ASCII characters to represent a single one of these special characters. These sequences are known as compound characters. For example, the sequence of six simple characters "^U1234" comprise a compound character to represent the Unicode character that corresponds to the hexadecimal value 1234. Likewise, the compound character "^[" is used to include the bracket as a character in a file or directory name rather than as the root or directory component delimiter. And, the compound character "^." is used to represent the period as a character in a file or directory name rather than as the file type or the subdirectory delimiter.

The RMS escape character ('^') is always used to begin one of these compound characters.

Certain characters can be represented in more than one way as input to RMS. Each character, however, will always be represented the same way in RMS's output, no matter which representation was used for input. The standard representation for each character is known as its canonical form.

For example, the input specifications:

File^37.Txt and File^U0037.Txt

would appear in output as:

File7.Txt

(The ASCII encoding of the numeral '7' is the hexadecimal value 37.)

The set of characters valid through the RMS interface in a file specification (without any special escape character) includes the following. Note that these characters must not be preceded by the escape character ^.

• Upper and lowercase alphanumeric characters:

  A - Z, a - z, 0 - 9

• Special ASCII (7-bit) characters:

  $ - ` _ ~

• ISO Latin-1 (graphic) characters in the range (hexadecimal) A0 to FF.

Escape followed by a pair of hexadecimal digits is interpreted as a hexadecimal value for an arbitrary (and otherwise legal) 1-byte character.

For example, ^20 represents a space. (The ASCII code for space is hexadecimal 20.)

Escape followed by "_" or by a space represents a space.

Escape followed by "U" followed by 4 hexadecimal digits are interpreted as a 2-byte Unicode character.

Escape followed by any of the following characters means that the character is to be used as part of a file name rather than having any special meaning that it might otherwise have in a file specification:

. , ; [ ] % ^ &

The following characters may be preceded by an escape, but need not be on input to RMS.

. ! # $ & ' ( ) + - @ ` { } ~

Sequences consisting of the escape character followed by any character not mentioned previously are reserved.

Spaces not preceded by the RMS escape character are removed from the specification by RMS (on Alpha and VAX).

Note that the extended character set applies only to directory names and filenames. Device names and node names must conform to ODS-2 requirements.

5.2.4.3 Uppercase and Lowercase Letters

On ODS-5 disks on Alpha systems, case (as in uppercase and lowercase letters) is preserved. If a file is created with lowercase letters, the name, as stored on disk, is lowercase.

File look-ups, however, are case-blind. For example, the filename "File.Txt" could be accessed with a reference to "FILE.TXT" or "file.txt".

5.2.4.4 Case and Multiple File Versions

On ODS-5 disks, if a file already exists whose name matches that of a file being created except for its case, the new file will be created with the same case as the existing file (rather than with the case as entered).

5.2.4.5 Convert System Service

On Alpha systems, a system service, SYS$CVT_FILENAME, is available to convert names between their RMS-interface form and their ACP-XQP on-disk form. See the OpenVMS System Services Reference Manual: A--GETMSG for details on its use.

5.2.5 The Root Component

The root component of a file specification begins with an open square bracket ("[") or an open angle bracket ("<") and ends with a period (".") followed by a closing square bracket ("]") or a closing angle bracket (">"). A root that begins with a square bracket must end with a square bracket, and a root that begins with an angle bracket must end with an angle bracket.

The root component contains a series of root subdirectory names, separated by periods.

Examples of legal root components are:

[RLEVEL0.] [RLEVEL0.RLEVEL1.] [RLEVEL0.RLEVEL1.RLEVEL2.] <RLEVEL0.RLEVEL1.>

A root subdirectory name may contain a period ("."). To be distinguishable from the delimiter periods, it must be specified to RMS as "^.".

5.2.6 The Directory Component

The directory component of a file specification begins with an open square bracket ("[") or an open angle bracket ("<") and ends with a closing square bracket ("]") or a closing angle bracket (">"). A directory component that begins with a square bracket must end with a square bracket, and a directory component that begins with an angle bracket must end with an angle bracket.

The directory component contains a series of subdirectory names, separated by periods.

Examples of legal directory components are:

[DLEVEL0] [DLEVEL0.DLEVEL1] [DLEVEL0.DLEVEL1.DLEVEL2] <DLEVEL0.DLEVEL1>

A subdirectory name may contain a period ("."). To be distinguishable from the delimiter periods, it must be specified to RMS as "^.".

5.2.7 The File Name, Type, and Version Components

On Alpha systems, RMS identifies the file name, file type, and file version components from the portion of a file specification that follows any node, device, root and directory components as follows:

The right-most semicolon or period followed by legal version characters begins the version component. A semicolon (unescaped) followed by characters that are not legal for a version component is illegal. The right-most period to the left of the version (if any) begins the type component. The characters to the left of the type are the file name.

Legal forms of a version component are:

;<decimal digit(s)> ;-<decimal digit(s)> ;* (multiple-character wildcard)

On ODS-2 and ODS-5 disks, the numerals in a version component, interpreted as a decimal number, may not exceed 32727.

Note that, although RMS accepts a period as a version delimiter, in output specifications, RMS always uses the semicolon as the delimiter.

The following are some examples of name, type, and version:

Name+Type+Version Name Type Version A.B;1 A .B ;1 A.B.C A.B .C (none) A.B;C (illegal) A.B.1 A .B .1 A.B.-1 A .B .-1 A.B.-32767 A .B .-32767 A^.B A^.B (none) (none) A.B^.C (illegal) A.B;1234567 (illegal)

Note that, although RMS on Alpha systems allows periods in a file name, files with such names can be created only on ODS-5 disks.

On VAX systems and on Alpha systems with versions previous to OpenVMS V7.2, RMS identifies the file name, file type, and file version components from the portion of a file specification that follows any node, device, root, and directory components as follows:

• A semicolon or the right-most period followed by legal version characters begins the version component.
• A semicolon followed by characters that are not legal for a version is illegal.
• A period to the left of the version (if any) begins the type component.
• No periods, other than the type and version delimiters, are allowed.

On Alpha systems, OpenVMS V7.2 supports the use of file names and subdirectory names that begin with hyphens. This is supported on ODS-5 and ODS-2 disks.

No special action is required for specifying a name that begins with a hyphen, with the following exception: A reference to a subdirectory whose name consists only of hyphens must include at least one escaped hyphen (so that RMS can distinguish the reference from a relative directory specification). On output, RMS always displays such a subdirectory name with the first hyphen escaped.

For example:

$CREATE/DIRECTORY DISK$:[^---] $CREATE/DIRECTORY DISK$:[FLARKY.LEVEL1.LEVEL2.LEVEL3] $SET DEFAULT DISK$:[FLARKY.LEVEL1.LEVEL2.LEVEL3] $WRITE SYS$OUTPUT F$PARSE("[---]") ! (relative spec.) DISK$:[FLARKY].; $WRITE SYS$OUTPUT F$PARSE("[^---]") ! (directory ---) DISK$:[^---].; $$ WRITE SYS$OUTPUT F$PARSE("[-^--]") ! (directory ---) DISK$:[^---].; $DIRECTORY/NOHEADING/NOTRAILING DISK$:[000000]---.DIR DISK$:[000000]---.DIR;1 ! (file ---.DIR)

RMS translates a logical name present in a file specification at run time. The use of logical names can be desirable for several reasons, including program simplification, device independence, file independence, and ease of use.

You can specify the file specification at compile (or assembly) time, or the program can prompt for it at run time. By specifying a logical name when you compile a program, you eliminate having to program a terminal input request, and you preserve the flexibility of being able to specify the input file at run time.

Device independence is more readily attainable if a logical name is used for the device name component. By using a logical name rather than explicitly specifying a physical device, an alternate device (usually containing a recent backup copy of the device) can be substituted by changing the definition of the logical name. Typically, device independence can reduce or eliminate the downtime caused by media failure or scheduled preventive maintenance.

Similarly, when you use a logical name, and the current copy of a file is not available, an alternate file can be used. To locate several files in a defined search order, you can use a search list, which is a form of logical name. Alternatively, you can use wildcard characters to locate several files using one file specification; however, wildcard characters do not allow you to specify a search order.

Using a logical name to represent a complex file specification or a file specification component reduces keystrokes to save time and reduces the chance of error. For example, you could define a logical node name that translates to an actual node name and access control string for use when locating remote files. To keep the password a secret when you use this technique, the logical name should be defined interactively rather than in a command procedure.

RMS attempts to treat the file name component as a logical name if the file name is the only component in the file specification. Refer to the OpenVMS User's Manual for additional information on defining logical names. No logical name translation is done on any logical name that contains a compound character (containing the RMS escape character: "^").

5.4 File Specification and Component Length Limits

The following section describes a file specification on ODS-2 and ODS-5 disks.

5.4.1 VAX Systems and ODS-2 Disks on Alpha Systems

The maximum length of a file specification string is 255 characters, including all separator characters. The following table lists the length limits for each of the component parts of a file specification. Note that although the collective limit exceeds 255 characters, the overriding limitation is on the length of the file specification.

Component	Number of Characters
Node	Up to 59 bytes including an access control string (physical node names are up to 6 bytes; logical node names are up to 15 bytes)
Device	Up to 15 bytes for a physical device name; up to 64 bytes for a logical device name
Root	Up to 39 bytes for each root name
Directory	Up to 39 bytes for each subdirectory and subdirectory name
Filename	Up to 39 bytes
Type	Up to 39 bytes
Version	Up to 5 digits, which optionally may be preceded by a hyphen (-)

5.4.2 ODS-5 on Alpha Systems

The maximum length of a file specification string is 4095 characters, including all delimiters. The following table lists the length limits for each of the component parts of a file specification.

Component	Number of Characters
Node	Up to 59 bytes including an access control string (physical node names are up to 6 bytes; logical node names are up to 15 bytes)
Device	Up to 15 bytes for a physical device name; up to 64 bytes for a logical device name
Root	RMS supports root specifications for which the sum of all of the characters in all of the subdirectory names (not counting the brackets or the delimiter periods) does not exceed 512 (compound) characters. In addition, individual subdirectory names have the same constraints as those for the file name, type, and version components, taking into account the fact that subdirectories are stored on disk in the form of files with the names <subdirectory>.DIR;1.
Directory	RMS supports directory specifications for which the sum of all of the characters in all of the subdirectory names (not counting the brackets or the delimiter periods) does not exceed 512 (compound) characters. In addition, individual subdirectory names have the same constraints as those for the file name, type, and version components, taking into account the fact that subdirectories are stored on disk in the form of files with the names <subdirectory>.DIR;1.
File Name	RMS supports file names of up to 255 bytes, subject to the constraint on the sum of the lengths of the file name, the file type, and the file version, as described below.
Type	RMS supports file types of up to 255 bytes, subject to the constraint on the sum of the lengths of the file name, the file type, and the file version, as described below.
Version	Up to 5 digits, which optionally may be preceded by a hyphen (-) (plus the delimiter), subject to the constraint on the sum of the lengths of the file name, the file type, and the file version, as described below.

RMS supports file names for which the sum of the lengths of the file name, the file type, and the file version does not exceed 255 (simple) characters. ODS-5 disks support file names for which the sum of the lengths of the file name and the file type does not exceed 236 bytes.

Be careful when naming files that will be copied or accessed by remote systems. File name restrictions are generally determined by the file naming capabilities of the networked systems that require access to them. These restrictions must be considered part of the overall application design when network access is required.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4506PRO_014.HTML