Document revision date: 15 July 2002

When creating or opening a file, your program must identify it with an appropriate file specification. Typically, high-level languages require a file specification argument for an OPEN statement that names a file being created or locates a file being opened.

The most direct way for an application to provide a file specification is to accept a complete specification from the user and to pass it to the OPEN statement.

Another way is to have the application program supply specifications to RMS so that RMS can combine these, as defaults, with a partial user specification to compose a fully qualified file specification. Or, to have RMS resolve a partial specification by searching the disk for an existing file that matches the specification.

This chapter describes the components that make up a complete file specification and how RMS is used to name and locate files on disks. Chapter 6 describes in more detail the process that RMS uses to compose fully qualified file specifications from user input and from application input.

A disk file specification on an OpenVMS system consists of up to seven components, several of which assume default values when they are not specified. To allow RMS to identify the boundaries of each component, certain characters separate the components in a file specification. These characters mark the beginning or the end of a file specification component and allow RMS to identify missing components for which defaults can be substituted. A complete file specification takes the following form:

node::device:[root.][directory-name]filename.type;version

The following table lists the characters that separate components of a file specification:

Component	Separator Character(s)
Node	Double colon (::) ends a node name.
Device	Single colon (:) ends a device name.
Root	Square brackets ([]) or angle brackets (<>) delimit the root name. Within the root component, a period (.) separates subdirectory names. A period (.) before the closing bracket distinguishes a root component from a directory.
Directory	Square brackets ([]) or angle brackets (<>) delimit the directory name. Within the directory component, a period (.) separates subdirectory names.
File Name	The rightmost period (.) that is not the version delimiter begins the type component and ends the file name.
File Type	The rightmost period (.) that is not the version delimiter begins the type component. A version delimiter ends the type component.
File Version	Period (.) or semicolon (;) followed by legal version characters begins the version. Section 5.2.7 describes a legal version component. The end of the file specification ends the file version.

Some examples of valid file specifications follow:

DISK1:[MYROOT.][MYDIR]FILE.DAT DISK1:[MYDIR]FILE.DAT [MYDIR]FILE.DAT FILE.DAT;10 NODE::DISK5:[REMOTE.ACCESS]FILE.DAT

5.2 File Specification Components

The following sections describe the particular file specification components.

5.2.1 The Node Component

Whether or not you should include the optional node component in a file specification depends on whether you confine file activity to the local node, or you conduct file activity on remote nodes. To locate a file on the local node, or in an OpenVMS Cluster environment, you do not have to include the node name in the file specification.

Conversely, to locate a file on a remote node, you must present the name of the remote node either as the physical node name or as a logical name whose translation contains the physical node name. A logical node name can also contain access control information used to log in to the remote system.

5.2.1.1 Local Node

The following file specification format does not include a node name:

device:[root.][directory-name]filename.type;version

This is the general format of a file specification used to locate a file on the local node, or in an OpenVMS Cluster.

Note that a null node name of the form "::" specifies the local node; this form overrides any default node names.

5.2.1.2 Remote Node

The following file specification formats are used for accessing files on remote nodes:

node::filespec

node"access-control-string"::filespec

The second file specification format includes an access control string. If an access control string is specified or if the process seeking to gain access to a remote file has a proxy login account on the remote node, the specified remote process uses its access rights to locate the file. If an access control string is not specified and a proxy account does not exist on the remote system, the local process may use the default DECnet account, if there is one, to locate the file.

The following file specification format, known as a foreign file specification, is used to locate files on remote nodes that might have file specification formats that differ from those of the local node:

node::"foreign-filespec"

The only action RMS takes with the foreign file specification is to translate the logical node name, if applicable. This format is especially useful when the remote system is not an OpenVMS system and the file specification does not conform to OpenVMS file specification syntax conventions. Refer to the DECnet for OpenVMS Networking Manual for more information.

The following file specification format does not specify a file directly. Instead, it specifies a task on the remote system.

node::"task-spec-string"

For more information about specifying a logical node name or using any of the file specification formats and their associated syntax rules, refer to the OpenVMS User's Manual.

5.2.2 The Device Component

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:

< > : / \ | ? * "

OpenVMS 7.3-1 on Alpha systems and ODS--5 disks includes enhanced support for the use of file names, and subdirectory and root subdirectory names. It supports all possible 8-bit characters, excluding only the following two 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.)

When RMS outputs a file specification (as a resultant name, for example), it follows the rule that other ISO Latin-1 8-bit characters that have no graphical representation or which are used for control functions by other OpenVMS software or by terminals is represented by an escape character followed by two hexadecimal digits (^xx). Otherwise, it is represented by its own character. The following 8-bit values are output as an escape character followed by two hexadecimal digits.

7F (rubout) 80-9F (C1 control characters) A0 (nonbreaking space) A0 (nonbreaking space) FF (Latin small letter y diaeresis)

5.2.4.1 Simple Characters

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:

  Dollar sign ($) Minus sign (-) Underscore (_)

• 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 is 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 as a character that has a special meaning in a file specification. For the period (.)¹ and tilde (~)², the escape character is required only under some circumstances, detailed in their respective footnotes.

Period (.)1 Comma (,) Semilcolon (;) Left bracket ([) Right bracket (]) Percent (%) Circumflex (^) Amperesand (&) Exclamation point (!) Pound sign (#) Apostrophe (') Left parenthesis (() Right parenthesis ()) Plus sign (+) Atsign (@) Grave accent (`) Left brace ({) Right brace (}) Equal sign (=) Tilde (~)2

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

Period (.)1 Dollar sign ($) Minus sign (-) Tilde (~)2

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 file names. Device names and node names must conform to ODS-2 requirements.

5.2.4.3 Uppercase and Lowercase Letters and Multiple File Versions

On ODS-5 disks on Alpha systems, the Extended File Specifications changes added support in OpenVMS Version 7.2 for preserving case (as in uppercase and lowercase letters). If a file is created with lowercase letters from program control, the name, as stored on disk, is lowercase.

From the DCL command interface, file names that are entered at the command prompt with lowercase letters will be translated by default to uppercase before they are passed to RMS. Case may be preserved from the DCL command interface by using the DCL command SET PROCESS/PARSE_STYLE=EXTENDED (also see the SYS$SET_PROCESS_PROPERTIESW system service).

File look-ups, however, are case-blind. For example, the filename "File.Txt" (as stored on an ODS--5 disk) could be accessed with a reference to "FILE.TXT" or "file.txt".

As of OpenVMS Version 7.3-1, an option may be set for file look-ups at either the process or file level to request RMS to either ignore or notice the case sensitivity of file names on ODS--5 disks.

At the process level, the user may request RMS to ignore case by using SET PROCESS/CASE_LOOKUP=BLIND. If a file on an ODS--5 disk 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). This is the default behavior. In contrast, the user may request RMS to notice case by using SET PROCESS/CASE_LOOKUP=SENSITIVE (also see the SYS$SET_PROCESS_PROPERTIESW system service). If the SENSITIVE option is in effect and the user creates more than one file on an ODS--5 disk with the same name differing only in case, each file is treated as a new file.

At the file level, the NAML$V_CASE_LOOKUP flag can be used to instruct RMS to ignore or notice case for a file on an ODS--5 disk (see the NAM$L_INPUT_FLAGS field in the NAML structure in the OpenVMS Record Management Services Reference Manual). NAML$C_CASE_BLIND is set to tell RMS to ignore case or NAML$C_CASE_LOOKUP_SENSITIVE to notice case when creating, deleting or searching for a file on an ODS--5 disk. If the NAML structure is not used or this flag is zero, the current process setting for CASE_LOOKUP is used.

The SET PROCESS/PARSE_STYLE qualifier is independent of the /CASE_LOOKUP qualifier. If the creation, deletion, or search of files on an ODS--5 disk is being done using the DCL command interface and case is relevant, /PARSE_STYLE=EXTENDED must be used to inform the DCL interface to preserve the case specified in the DCL command. The /CASE_LOOKUP qualifier instructs RMS whether to ignore or notice the case (either preserved or not).

5.2.4.4 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--GETUAI 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 "^.".

	privacy and legal statement
4506PRO_014.HTML