Updated: 11 December 1998

Guide to OpenVMS File Applications

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 directory specified during logical name definition serves as a base from which directories beneath it can be accessed and is called the root directory. Root directories must be specified using alphanumeric UICs; octal numbering for group and member designations is not allowed.

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

Another difference between the conventions RMS uses for rooted-directory syntax and standard directory syntax is the number of permissible nested directory levels. With rooted-directory logical names you can hide eight additional levels in the rooted-directory logical name and effectively nest 16 levels of directories.

Note that you must access these files using the rooted-directory logical name and that the system rejects any attempt to access these files using normal directory syntax. 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]name.type

But if you try to access this file using the following directory syntax, RMS returns a status code indicating the file specification is illegal:

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

Another problem occurs when you try to back up the directory tree using conventional directory syntax, because the Backup utility only backs up the first eight levels of the directory tree.

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.4 DID-Abbreviated Directories (Alpha Only)

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:

DKA200:[24,42,0] DKA200:[1223,4,0.a] DKA200:[134,59,0...] DKA200:[1223,4,0.][134,59,0]

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:

$SET PROCESS/PARSE_STYLE=EXTENDED $WRITE SYS$OUTPUT F$PARSE("DKA200:[system.test.134,59,0...]*.*;*") DKA200:[134,59,0...]*.*;* $WRITE SYS$OUTPUT F$PARSE("DKA200:[system.test.134,59,0.BTEST2]*.*;*") DKA200:[134,59,0.BTEST2]*.*;*

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:

$DIRECTORY/FILE_ID/NOHEADER/NOTRAILING/WIDTH=(FILE=45) .DIR;1 DKA200:[SYSTEM]1.DIR;1 (24,42,0) DKA200:[SYSTEM]a.DIR;1 (1223,4,0) DKA200:[SYSTEM]BTEST1.DIR;1 (134,59,0) DKA200:[SYSTEM]DIR^^_1.DIR;1 (609,22,0) DKA200:[SYSTEM]lowercase.DIR;1 (655,49,0) DKA200:[SYSTEM]te^[mp.DIR;1 (20,37,0) DKA200:[SYSTEM]tmp^.tmp.DIR;1 (355,20,0) DKA200:[SYSTEM]UNICODE.DIR;1 (1968,10,0) DKA200:[SYSTEM]UPPERCASE.DIR;1 (656,45,0) DKA200:[SYSTEM]with^.dot.DIR;1 (768,28,0)

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.

6.5 FID-Abbreviated Names (Alpha Only)

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:

DKA200:[SYSTEM]leadingfilenamechars~[384,35200,0].txt;1

Such a file specification can be used as input to RMS, with some limitations.

6.5.1 Restrictions on FID-Abbreviated Names

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:

$COPY/LOG ^U6666^U7777^U8888^U9999^U5555^U6666~[449,35295,0].txt;1 *.xxx %COPY-S-COPIED, DKA200:[SYSTEM]^U6666^U7777^U8888^U9999^U5555^U6666~ [449,35295,0].txt;1 copied to DKA200:[SYSTEM].xxx;1

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.

6.6 Using Process-Permanent Files

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:

1. The LOGINOUT command image, or at a later point the command interpreter, opens or creates a file corresponding to the process's command, input, output, and error message streams. Logical names are created in the process logical name table for SYS$COMMAND, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR, respectively. The equivalence string for the logical name has a special format that indicates the correspondence between the logical name and the related process-permanent file. For more detail concerning the equivalence-string format for logical names, see the discussion of logical name services in the OpenVMS System Services Reference Manual. For example, for an interactive user, these single process-permanent files are opened for the terminal.
2. When an indirect accessor opens or creates a file specifying a logical name that has one of these special equivalence strings, RMS recognizes this and therefore does not open or create a new file. Instead, the returned value for the internal file identifier (and later the value for the internal stream identifier from a Connect service) is set to indicate that access to the associated process-permanent file is with the indirect subset of allowable functions.

The implications for the indirect accessor are described in the following list:

• A Create service for a process-permanent file becomes an Open service; the fields of the FAB are output according to the description of the Open service, not the Create service.
• The Open and Create services require no I/O operations.
• Any number of indirect Open and Create operations are allowed.
• There is only one position context for the file; each sequence of the Open or Create service accesses the same record stream, not an independent stream.
• If the process-permanent file was initially opened with the sequential-processing-only (FAB$V_SQO) bit set in the FAB$L_FOP field, neither random access nor the Rewind service is permitted. This is the case for SYS$COMMAND, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR.
• Certain options to various services produce errors. For example, you cannot set the non-file-structured (FAB$V_NFS), process-permanent file (FAB$V_PPF), and user-file-open (FAB$V_UFO) bits of the FAB$L_FOP field for the Open and Create services. Other options are ignored, such as: the spool (FAB$V_SPL), submit-command-file (FAB$V_SCF), delete (FAB$V_DLT) bits of the FAB$L_FOP field for the Close service; the asynchronous (RAB$V_ASY) bit of the RAB$L_ROP field; the multiblock count field (RAB$B_MBC) and the multibuffer count field (RAB$B_MBF; or optionally, the XAB$_MULTIBUFFER_COUNT XABITM).
• If a name block is used and either an expanded or resultant file specification string is returned, the string consists solely of the process logical name followed by a colon (such as SYS$INPUT:).
• The file access (FAB$B_FAC) field is ignored by the Open service; instead, operations are checked against the FAB$B_FAC field specified for the original Open or Create service.
• Information from the record attributes field is saved on each Open service and subsequent Connect service in the values returned in the internal file identifier and internal stream identifier fields. If the output file is a print file (VFC record format and the FAB$V_PRN bit set in the record attributes field), mapping is performed for each Put service from the user-specified carriage control to the print file carriage control format. Thus, different carriage control types from different indirect Open services all work correctly.
• You cannot use the Erase service.
• Checking is performed for $DECK, $EOD, and other dollar-sign ($) records on the SYS$INPUT stream if the SYS$INPUT stream is from a file. Checking is not done if SYS$INPUT comes from a record-oriented device, such as a terminal or a mailbox. (See the OpenVMS DCL Dictionary.)
• At image exit time, the run-down control routine ensures that the indirect I/O on process-permanent files terminates; however, these files are not closed.
• All file organizations may be opened directly as process-permanent files (for example, through the DCL command OPEN), but only those files with a sequential organization may be indirectly accessed.

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

4506PRO_018.HTML