Document revision date: 30 March 2001

There is a master file directory (MFD) on each volume. Within each MFD, top-level directories are cataloged using the DCL command CREATE/DIRECTORY (or equivalent record management services). Beneath each top-level directory, you can create subdirectories referenced from the top-level directory.

Once the subdirectories are created, you can create subdirectories referenced from each subdirectory. You can create a large number of levels of subdirectories beneath a top-level directory. The subdirectories created beneath a directory and the subdirectories within the subdirectories (and so forth) are called collectively a directory tree. The base point for normal directory syntax access can be relative to the current position in the directory tree or an absolute reference that explicitly or by default states any higher-level directories or subdirectories needed to identify the appropriate directory or subdirectory. An absolute directory reference begins with a directory name; a relative directory reference begins with a hyphen (-) or a period (.). An absolute reference might include the name of the top-level directory and one or more subdirectories. A relative directory reference relies on the use of the process-default directory and device, which are set using the DCL command SET DEFAULT. Refer to the OpenVMS DCL Dictionary for additional information and examples.

A relative directory reference can be in one of several forms. Assume the current directory position (process-default directory) is [SMITH.JONES].

• You can specify a lower level in the directory tree with a period (.) to indicate that the current directory position ([SMITH.JONES]) is prefixed to the specified directory as shown in the following command:

  $ SET DEFAULT [.DATA]

  This directory specification is combined with the current directory position to form [SMITH.JONES.DATA].

• You can specify higher levels in the directory tree by beginning the directory specification with a hyphen (-) to indicate that the directory specification is the next level up from the current directory level. If you are currently at directory level [SMITH.JONES], the following command directs RMS to use the directory SMITH:

  $ SET DEFAULT [-]

  
  If you include more than one hyphen, RMS ascends the directory tree by a corresponding number of levels. For example, if you use the following command from directory level [RED.WHITE.BLUE], RMS moves up the tree to level [RED]:

  $ SET DEFAULT [- -]

• You can use combinations of hyphens and periods to traverse a directory tree. For example, assume the following directory tree structure:

  ONE / \ TWO THREE / \ FOUR FIVE / \ SIX SEVEN

  Assume that your process is in directory [ONE.TWO.FOUR.SIX] and you want to access a file in [ONE.THREE.FIVE]. You can do this with the following DCL command:

  $ SET DEFAULT [- - -.THREE.FIVE]

• You can refer to the default directory explicitly by specifying an empty directory specification at the DCL prompt. This feature is useful when you want to use a single DCL command to perform directory operations in your default directory and one other directory.
  For example, assume you have a directory on device USERDISK named [CUSTOMERS.LOCAL] that contains three files: ABERCROMBIE, FITCH, and GOULD. Another directory named [CUSTOMERS.INTERNATIONAL] also contains three files: MERRILL, LYNCH, and PIERCE. Assume that your default directory is [CUSTOMERS.LOCAL] but you need a directory listing that contains the sizes of all customer files. You can list both directories using the following command line:

  $ DIRECTORY/SIZE [CUSTOMERS.INTERNATIONAL],[]

  DCL responds to this command with the following display:

  Directory USERDISK:[CUSTOMERS.INTERNATIONAL] MERRILL 1100 LYNCH 155 PIERCE 645 Directory USERDISK:[CUSTOMERS.LOCAL] ABERCROMBIE 230 FITCH 100 GOULD 355 Total of 6 files, 2585 blocks

Conversely, a period or a hyphen before a directory name is always associated with a relative directory reference.

Note that because only one directory can be directly above any other directory, you can use a hyphen without explicitly naming the next higher directory. But, because many directories can be directly beneath the current directory, you must explicitly specify the directory at the next lower level by following the period with the name of the selected directory.

If the program omits either the device or the directory component in a file specification, RMS accepts the value of the current device and directory from the logical translation of SYS$DISK. Therefore, any directory fields yielded by translation of SYS$DISK override the process default directory. If translation of SYS$DISK does not yield the directory element, RMS uses the process default directory. Note that you can change the process default directory with the SET DEFAULT command or by invoking the SYS$SETDDIR system service.

6.3.2 Rooted-Directory Syntax Applications

Rooted-directory syntax allows you to refer to directory trees as logical devices and top-level directories. A reference to a top-level directory actually accesses existing subdirectories without program modification; thus, rooted-directory syntax extends the flexibility associated with logical names. Similarly, rooted-directory syntax can reduce the number of top-level directories needed for a volume. Rooted-directory syntax allows multiple system directory trees to exist on a single system volume.

You specify rooted-directory syntax using a logical name in a program-specified file specification or in the device and directory for a SET DEFAULT command. If a program specifies a logical device name in the file specification, the logical device name can be redefined to specify a rooted-directory logical name. Redefining the logical device name to specify a rooted directory changes the directory (and the file or files) accessed by the program without modifying the program.

If a program does not specify a logical device name in the file specification, the user (or a command procedure) can issue DEFINE commands and the SET DEFAULT command before running the program to indicate the use of rooted-directory syntax and to specify the process-default device/directory. Using the SET DEFAULT command changes the directory accessed by the program without requiring that you modify the program. When the program finishes, use the SET DEFAULT command again to specify the new process-default device/directory and to resume the use of normal directory syntax (if desired).

Using rooted-directory syntax as illustrated in the preceding text provides several advantages. Because you did not modify the program, you avoided having to recompile (or reassemble), relink, or retest it. Another advantage is that because you were able to run the program from its resident directory, you eliminated the overhead of having to move the file several times.

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.

The root directory is the directory you specify during logical name definition that serves as a base from which you can access the directories beneath it.

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 [000000] refers to the root directory. When you execute the SHOW DEFAULT and other direct commands, the system displays the root directory as [000000]. 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:

$ DEFINE BASE DUA7:[ROOT1.]

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:

Actual Directory	Rooted Syntax	Comments
DUA7:[ROOT1]	BASE:[000000]	[ROOT1] appears as the MFD
DUA7:[ROOT1.SUB]	BASE:[SUB]	[ROOT1.SUB] appears as a top-level directory

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.

$ DEFINE/TRANSLATION_ATTR=CONCEALED BASE DUA7:[ROOT1.] $ SET DEFAULT BASE:[SUB] $ DIRECTORY *.DIR,[-]*.DIR

The system responds with the following display:

BASE:[SUB] SUBSUB.DIR BASE:[000000] SUB.DIR

In the preceding example, the SET DEFAULT command defines the process-default directory as [ROOT1.SUB] using the rooted-device logical name BASE. The DIRECTORY command looks for directory files in the current directory ([ROOT1.SUB]) and then in the directory directly above it ([ROOT1]). The directory [ROOT1.SUB] is listed (by the DIRECTORY command) as a top-level directory (BASE:[SUB]) and the root directory is listed using the syntax of the MFD, BASE:[000000].

6.3.4 Concatenating Rooted-Directory Specifications

When it concatenates specifications for rooted directories, RMS uses different syntax rules than it uses when it concatenates directory specifications for normal directory syntax.

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:

• You can refer to the root directory itself. The syntax of [000000] and relative directory references refer to the root directory.
  You can never refer to a directory above the specified root directory because the root directory is the logical MFD whenever a directory specification is used. When the process-default directory is the root directory, a reference to [-] results in an error, as shown in the following example:

  $ DEFINE/TRANSLATION_ATTR=CONCEALED BASE DUA7:[ROOT1.] $ SET DEFAULT BASE:[000000] $ DIRECTORY *.DIR

  The system responds to this command sequence with the following display:

  BASE:[000000] No files found

  The user then tries to check the contents of the next higher directory with the following command:

  $ DIRECTORY [-]*.DIR

  The system responds with the following messages:

  %DIRECT-E-OPENING, error opening [-]*.DIR as input -RMS-E-DIR, error in directory name

• You can refer to a specific subdirectory of the root directory in the same way that you refer to a top-level directory using normal directory syntax, as shown in the following example:

  $ DEFINE BASE DUA7:[ROOT1.] $ SET DEFAULT BASE:[SUBDIR]

• You can refer to any subdirectory beneath the root directory using wildcard characters to vertically traverse the directory tree. You can refer to all directories below the root directory [*...], all directories one level below the root directory [*], all directories two levels below the root directory [*.*], and other reference combinations, as shown in the following example:

  $ DEFINE/TRANSLATION_ATTR=CONCEALED BASE DUA7:[ROOT1.] $ DIR BASE:[*...]*.DIR

  The system responds with the following display:

  BASE:[SUBDIR] SUBSUBDIR.DIR BASE:[SUBDIR.SUBSUBDIR] SUBSUBSUBDIR.DIR BASE:[OTHERSUB] OTHERSUBSUB.DIR

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:

$ DEFINE X DJB3:[SMITH.]

Now assume you set the default directory to JONES:

$ SET DEFAULT [JONES]

When the rooted-device logical name X is used with a directory specification, all directory references are relative to the root directory [SMITH.]. Most wildcard characters that apply to normal directory syntax also apply to rooted-directory syntax.

The following table lists the file specifications involving the rooted-device logical name X and the directory that is accessed with each specification:

File Specification	Directories Accessed
X:	[SMITH.JONES]
X:[000000]	Root directory, [SMITH.]
X:[]	[SMITH.JONES]
X:[-]	Root directory [SMITH.], listed as X:[000000]
X:[- -]	Invalid (error)
X:[name]	[SMITH.name]
X:[.name]	[SMITH.JONES.name]
X:[name.*...]	All directories in all directory trees below [SMITH.name]
X:[*]	All directories one level below [SMITH.]
X:[*...]	All directories in all directory trees below [SMITH.]
X:[...]	All directories in all directory trees below [SMITH.JONES]

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.

6.3.5 An Example of Using a Rooted Directory

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:

$ ON CONTROL_Y THEN GOTO ENDIT $ DEFINE IN DUA29: $ RUN XYZPROG $ ENDIT: $ EXIT

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.

Example 6-1 Rooted-Directory Syntax

$ ON CONTROL_Y THEN GOTO END $ GOTO ASK $ RETRY: $ WRITE SYS$OUTPUT "Enter a number from 1 to 4 for the type of part" $ ASK: $ WRITE SYS$OUTPUT - "Select Parts Group: 1-COMPUTER 2-TYPEWRITER 3-DESK 4-OTHER 5-END" $ INQUIRE ANS $ IF ANS .GT. 5 .OR. ANS .LT. 1 THEN GOTO RETRY $ IF ANS .EQ. 5 THEN EXIT $ IF ANS .EQ. 1 THEN DEFINE/TRANS=CONCEAL IN DUA29:[COMPUTER.] $ IF ANS .EQ. 2 THEN DEFINE/TRANS=CONCEAL IN DUA29:[TYPEWRITER.] $ IF ANS .EQ. 3 THEN DEFINE/TRANS=CONCEAL IN DUA29:[DESK.] $ IF ANS .EQ. 4 THEN DEFINE/TRANS=CONCEAL IN DUA29:[OTHER.] $ RUN XYZPROG $ END: $ EXIT

With the enhanced command procedure, none of the programs has to be modified, recompiled (or reassembled), relinked, or copied to a different directory.

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.¹ 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:

MYROOT:[D7.D8.D9.D10.D11.D12]

You can also refer to it as the following:

DUA0:[D1.D2.D3.D4.D5.D6.][D7.D8.D9.D10.D11.D12]

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:

DUA0:[D1.D2.D3.D4.D5.D6.D7.D8.D9.D10.D11.D12]

	privacy and legal statement
4506PRO_018.HTML