[an error occurred while processing this directive]
HP OpenVMS Systems Documentation |
Guide to OpenVMS File Applications
Chapter 5
|
This chapter documents file specifications as presented at the RMS interface such as RMS services SYS$OPEN and SYS$SEARCH. For details on specifications at the ACP-XQP interface, such as the system service SYS$QIO, refer to the OpenVMS I/O User's Reference Manual. As of OpenVMS V7.2, RMS on Alpha systems has been extended to support disk file specifications of greater length and with a larger character set than was supported on prior versions and than is supported on VAX platforms. Some of the extended features can be used on existing ODS-2 structure-level disks. Many features are available only on ODS-5 structure-level disks. Throughout this chapter, behaviors that differ depending upon the architecture, Alpha or VAX, or upon the target device, ODS-5 disk or ODS-2 disk, are so marked in the text. |
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 |
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.
In this chapter, discussions that refer to OpenVMS Cluster environments apply to both VAXcluster systems that include only VAX nodes and OpenVMS Cluster systems that include at least one Alpha node unless indicated otherwise. |
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:
A - Z, a - z, 0 - 9 |
$ - _ ~ |
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.)
The use of compound characters in RMS is allowed only on Alpha systems running OpenVMS Version 7.2. The use of ODS-5 characters that are not also ODS-2 characters is allowed only on ODS-5 disks accessed from Alpha systems running OpenVMS Version 7.2. |
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) |
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 ^.
A - Z a - z 0 - 9 |
Dollar sign ($) Minus sign (-) Underscore (_) |
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 (.)1 and tilde (~)2, 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.> |
An alternate form of root subdirectory name, supported by RMS only on Alpha systems (on both ODS-5 and ODS-2 disks), is that of a directory ID (referred to as "DID"). This form is described in Chapter 6. |
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> |
An alternate form of subdirectory name, supported by RMS only on Alpha systems (on both ODS-5 and ODS-2 disks), is that of a directory ID (referred to as "DID"). This form is described in Chapter 6. |
A subdirectory name may contain a period ("."). To be distinguishable from the delimiter periods, it must be specified to RMS as "^.".
1 The escape character is required before a period in a directory name, is optional before a period in a file name, and must not be used for the period that delimits the file type. A period is not permitted in a file type.2 The tilde that is the leading character in a file name or directory may require an escape character. |
Previous | Next | Contents | Index |