HP OpenVMS Systems Documentation
Guide to OpenVMS File Applications
6.3.3 Using Rooted-Directory Syntax
Rooted-directory syntax provides a way of making a directory or subdirectory appear to the user as the master file directory (MFD) for the logical disk volume. Subdirectories of the rooted directory appear as top-level directories (user file directories) for the logical volume.
A concealed-device logical name that defines a hidden root directory is called a rooted-device logical name.
When you define the rooted-device logical name for use in a program in a SET DEFAULT command, you specify that the logical name is a concealed-device logical name by using the /TRANSLATION_ATTRIBUTES=CONCEALED qualifier with the DCL command DEFINE or ASSIGN. To define the concealed-device logical name as a rooted-device logical name, the root directory must contain a trailing period (.), such as DUA22:[ROOT.]. When specifying a directory, you can only use a trailing period for the root directory.
When you define a root directory, all directory references refer to the specified root directory or directories beneath it in the directory tree. A reference to a top-level directory refers to a subdirectory of the specified root directory when using rooted-directory syntax. This is consistent with the fact that the root directory appears as the MFD because a reference to directory  refers to the root directory. When you execute the SHOW DEFAULT and other direct commands, the system displays the root directory as . Note that the directory specification form [0,0] for the MFD is not valid when using rooted-directory syntax.
For example, assume the top-level directory [ROOT1] on disk DUA7 contains a subdirectory [ROOT1.SUB]. The directory [ROOT1] is defined as the root directory associated with the logical name BASE as follows:
When you associate the root directory with the logical name base, you can refer to the logical top level directory [ROOT1.SUB] using the syntax BASE:[SUB]. The following chart provides a summary of the actual directory accessed and the equivalent rooted-directory syntax that applies to this example:
The next example shows how to define the root logical name described in the previous chart and how to access a subdirectory of the specified root directory. Note that the trailing period [ROOT1.] indicates that a root directory is present.
6.3.4 Concatenating Rooted-Directory Specifications
One difference between the two conventions is associated with the trailing period in the root directory definition. For example, consider how a top-level directory reference is handled. With rooted-directory syntax, the root directory's trailing period is implied as a leading period in subsequent rooted-directory references.
Directory concatenation within the same file specification occurs only with a rooted-device logical name. Normal directory concatenation occurs only through the application of defaults. Rooted-directory concatenation can occur within the same file specification and through the application of defaults. Rooted-device logical names specify a device name and a root directory. RMS translates a rooted-device logical name into the device and root directory before it merges any other parts of a file specification (if present) into the equivalence file specification.
When you use a rooted-device logical name together with a directory specification, the following rules apply:
With rooted-directory syntax, RMS uses the process-default device and directory indirectly as defaults. This occurs because RMS uses the expanded rooted-device logical name device and root directory before applying the process-default device and directory.
With rooted-directory syntax, you can use relative directory syntax, such as the hyphen (-) and leading period (.name). When a directory component is missing, RMS attempts to obtain the missing components from the process-default directory.
Consider the rooted-device logical name X defined as shown in the following DCL command:
Now assume you set the default directory to JONES:
The following table lists the file specifications involving the rooted-device logical name X and the directory that is accessed with each specification:
Note that RMS uses the default directory with relative directory
references when the specified directory name contains a leading period
or a hyphen, or if no directory name is specified.
Consider an application made up of several programs that refer to the same file using a file specification IN:[INVENTORY]FILE.DAT. Assume that all of the programs invoke the following command procedure to define the logical name IN as device DUA29:
The programs show the current inventory level and the stockroom used for a particular item and are dispersed among many users in the company. As the business grows, the number of items in the inventory grows and the number of inventory records makes the file extremely large and difficult to access. Because the items can be classified as belonging to one of four groups, the data management department decides to split the file into four parts. A special-purpose program reads each record in the master file, determines the record type, and routes the record to the appropriate file group. All output files are named FILE.DAT, but each is distinguished by putting it in a top-level directory associated with the appropriate group category. For example, computer supplies files are cataloged in the directory [COMPUTER.INVENTORY].
This is done by modifying the command procedure to conditionally define the value of IN to be a rooted-device logical name with four subdirectories. The modified command procedure is shown in Example 6-1.
6.3.6 Using a Rooted Directory to Extend RMS's Subdirectory Limit
On Alpha systems running OpenVMS versions prior to V7.2 and on VAX systems, RMS limits the number of subdirectory levels that can be accessed to eight.1 Rooted directory syntax can be used to allow access to subdirectories up to fifteen levels below the volume's MFD. RMS allows up to seven levels in the root, with eight in the normal (non-root) directory.
You must access the files using rooted-directory syntax, whether or not a logical name is used for the rooted directory. For example, you can legally define the rooted-directory logical name MYROOT to be DUA0:[D1.D2.D3.D4.D5.D6.] and nest six subdirectories beneath it using the following directory syntax:
You can also refer to it as the following:
But if you try to access this file using the following directory syntax, RMS returns a status code that indicates that the file specification is illegal:
To support Extended File Specifications, RMS's user interface was extended to include capacities for the larger specifications that are sometimes necessary to access ODS-5-named files. (See the OpenVMS Record Management Services Reference Manual.) To take full advantage of all of the new features, applications would have to be updated to use the interface extensions. To provide extended capabilities (such as access to deep directories) to applications that continue to use the older interface, RMS supports the generation and acceptance of file specifications with an abbreviated form of root or directory specification, known as a DID (for Directory ID) abbreviation.
The DID is an alternate form of subdirectory specification that is not relative to the MFD. It takes the form (for ODS-2 and ODS-5 disks) of three decimal numbers separated by commas and can be used in the MFD position in a root or directory component specification.
Examples of valid root and directory components with DIDs are as follow:
A DID can also be used in place of a subdirectory in a root or directory component, but subdirectories located to its left in the specification (above it in the directory tree) are elided by RMS, as shown in the following example:
If a specification contains both a root with a DID and a directory with a DID, the root will be ignored (though not elided) by RMS.
The directory ID numbers are those that are displayed for a directory with the DIRECTORY/FILE_ID DCL command, as shown in the following:
When RMS attempts to generate a file specification that is too long for the application's output buffer, pointed to by the NAM block expanded or resultant string field, NAM$L_ESA or NAM$L_RSA; or by the NAML block short expanded or short resultant string file, NAML$L_ESA or NAML$L_RSA, it replaces the root and directory component with one that has the DID for the lowest level subdirectory of the replaced component(s). The specification that results can then be used as input to RMS.
It should be noted that not all RMS features are available with DIDs.
For example, attempts to use sticky defaulting with a root or directory
with a DID will result in an error. And you cannot create a directory
using a DID.
On Alpha systems, when a file specification, even with DID abbreviation, is too long to fit into a resultant name buffer (NAM block NAM$L_RSA field or NAML block NAML$L_RSA field), RMS attempts to generate a short-enough file specification by identifying the file with its file ID (three decimal numbers separated by commas, surrounded by brackets) in the file name component.
In cases in which the file type component would otherwise be presented, a generated file specification will either include the entire type or will not include any type (including the "." delimiter), depending upon whether or not there is space.
In cases in which the version component would otherwise be presented, a generated file specification will include the version component.
As a human-readable aid in recognizing files, when a FID is generated, the name component also contains a DCL-legal initial subset of the actual file name. The subset consists of the first 38 simple characters (where "^U1234" is six simple characters) of the actual file name, followed by "~".
No attempt is made to resolve ambiguities for files that differ only after the first 38 simple characters of their names.
An example of a generated name with a FID is as follows:
Such a file specification can be used as input to RMS, with some
A FID can be used for input to RMS, but only the FID is significant. The subset portion of the name component, the type component, and the version component are ignored by RMS.
As input, the FID-abbreviated file name component is not used as a default (as from a related file specification to replace a wildcard in an output specification). Instead, the output specification will get a null file name, as shown in the following:
Note that generated names with FIDs are possible only for resultant
specifications, which refer to specific files, and not for expanded
specifications, which do not necessarily refer to one file.
Process-permanent files are files that remain open independent of image activation and rundown. Process-permanent files are created by setting the process-permanent file bit (FAB$V_PPF) in the file-processing options field (FAB$L_FOP). When the bit is set, RMS-maintained internal data structures are allocated in the process control region of memory for the life of the process. Thus, process-permanent files can remain open across image activations. SYS$COMMAND, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR are all opened in this manner by the LOGINOUT command image.
The DCL command OPEN also opens files in this manner. With user mode code, you can access process-permanent files only indirectly. RMS provides a subset of the total available operations to the indirect accessor.
Indirect accessors gain access to process-permanent files through the logical name mechanism, as follows: