HP OpenVMS Systems Documentation

Guide to OpenVMS File Applications

Additional parsing conventions for advanced file specifications include search lists, related file specifications, and the way RMS handles directory specifications.

6.2.3.1 Parsing Conventions for a Search List

RMS uses several conventions when processing a search list logical name.

• When RMS encounters a search list, it searches internally for the file using search list file specifications previously specified. RMS treats each file specification in the search list as a new file specification. That is, RMS does not use components of one file specification element in the search list as the default for subsequent elements in the search list.
• When it uses search lists, RMS ignores the following errors:

  Invalid device name (RMS$_DEV)
  Device not ready or not mounted (RMS$_DNR)
  Directory not found (RMS$_DNF)
  File not found (RMS$_FNF)
  Privilege violation (RMS$_PRV)

  
  All other errors terminate search list processing.
• When a search list is embedded (nested) in another search list, all file specifications of the nested search list are processed before the file specifications in the next-higher search list level. Therefore, RMS permits iterative substitution in nested search lists as it does with other logical names. For example, consider the following search lists, X and Y:

  $ DEFINE X DISK1:[RED],DISK2:[WHITE] $ DEFINE Y X,DISK1:[BLUE]

  
  The following search order is derived from search list Y:
  1. DISK1:[RED]
  2. DISK2:[WHITE]
  3. DISK1:[BLUE]
• When opening a file, RMS tries all search list possibilities before it signals an error completion status. If RMS cannot find the file, it displays, where applicable, the final search list file specification and the error message.
• When RMS tries to locate a file using multiple search lists, it uses all combinations of the elements in the search lists. First it combines the first entry in the first list with the first entry in the second list. Then it combines the first entry in the first list with the second entry in the second list. After trying all combinations of the first entry in the first list with all entries in the second list, RMS repeats the exercise using the entries in the second list with the second entry in the first list. This continues until RMS locates the file or until it tries all combinations of all lists.
  For example, assume the program is looking for FILE.DAT, which may be in one of two directories, [BIG] or [BEST], on one of two disks, DISK1: or DISK2:. First, the program defines two search lists, a disk search list (PRIM) and a directory search list (DEF):

  $ DEFINE PRIM DISK1,DISK2 $ DEFINE DEF [BIG],[BEST]

  
  Next, the program provides a primary file specification that includes the search list (PRIM) for the disk together with the file name component:

  PRIM:FILE

  Finally, the program must provide the default specification that includes the search list (DEF) for the directory together with the file type component:

  DEF:.DAT

  Given this information, RMS looks for FILE.DAT using the file specification data in the following order:

  Primary File Specification	Default File Specification	Expanded String
  DISK1	[BIG]	DISK1:[BIG]TEST.DAT;
  DISK2	[BIG]	DISK2:[BIG]TEST.DAT;
  DISK1	[BEST]	DISK1:[BEST]TEST.DAT;
  DISK2	[BEST]	DISK2:[BEST]TEST.DAT;

  
  Now, assume the program provides a related file specification with a search list for FILE.DAT.
  1. RMS uses all combinations of the search list elements in the primary and default file specifications with the first component (device) of the related file specification.
  2. RMS uses all combinations of the search list elements in the primary and default file specifications with the second component (directory) of the related file specification.
  3. RMS repeats steps 1 and 2 with each search list element in the related file specification.

This section describes the special processing needed to implement sticky defaults when a search list is used in a related file specification for an input file parse. The term sticky default means that file specification components from the first file specification are applied as defaults to the next file specification component, eliminating the need, for instance, to specify the device specification for each file specification when all the files are located on the same device.

The related file specification provides defaults when a related file name block is present. To use the related file specification, the file access block must specify the address of the primary file's name block (in the FAB$L_NAM or FAB$L_NAML field), and that name block must specify the address of the related file's name block (in the NAM$L_RLF or NAML$L_RLF field). The related file's name block must specify the address of a valid file specification in the resultant string (NAM$L_RSA/NAM$B_RSS or NAML$L_LONG_RESULT/NAML$L_LONG_RESULT_ALLOC) field. Typically, an RMS file service (other than Parse) places the file specification in the resultant string.

You can specify whether the related file is used as an input file specification or an output file specification by setting (output file specification parsing) or resetting (input file specification parsing) the output-file parse (FAB$V_OFP) bit in the file-processing options (FAB$L_FOP) field .

When an input file specification is being parsed, you can have multiple related name blocks by specifying the second related file's name block address in the NAM$L_RLF or NAML$L_RLF field of the first related name block, the address of the third related name block in the NAM$L_RLF or NAML$L_RLF field of the second name block, and so forth. The use of multiple related name blocks is especially useful for search lists; one related name block might contain a file type that can be used by any file specification in a search list, another might contain the full file specification that was produced by the first search list file specification, and another might contain the full file specification produced by the second search list file specification. This method allows the file specifications in a search list to provide sticky defaults, a characteristic associated with DCL command lines that contain multiple file specifications.

For a search list to be applied as a related file specification, the related file specification must not be a resultant string but must include the search list logical name. The related file specification in this case must describe the original primary file specification. For example, consider the following search list definition:

$ DEFINE WORK DISK1:[MINE],DISK2:[GROUP]

To process lists of input files---such as WORK:A,B,C,---your program must supply the string WORK:A as the related file specification, not DISK2:[GROUP]A.DAT. The routines LIB$FIND_FILE and LIB$FILE_SCAN are provided to perform this special processing; consult the OpenVMS RTL Library (LIB$) Manual for additional information; also refer to Example 5-2, which shows how to call the LIB$FIND_FILE routine.

6.2.3.3 Input File Specification Parsing

When the output-file parsing bit (FAB$V_OFP) is reset and the node name is omitted, RMS processes the related file specification as an input file specification. This is shown in the following table. Note that the only wildcard character allowed is a single asterisk.

When the FAB$V_OFP bit is reset and a node name is present, RMS processes the related file specification as an input file specification, as shown in the following table:

When the FAB$V_OFP bit is set and a node name is not present, RMS processes the related file specification as an output file specification, as shown in the following table:

When the FAB$V_OFP bit is set and a node name is present, RMS processes the related file specification as an output file specification, as shown in the following table:

As shown in the previous table, a wildcard character in an output directory specification is subject to the following syntax restrictions:

• Only the asterisk and the ellipsis are permitted in the output directory specification. In the case of a related file specification, you may choose either the asterisk or the ellipsis (but not both) in the output directory specification unless you use the following form:

  [*...]

• A subdirectory specification that contains wildcard characters cannot be followed by a subdirectory specification that does not contain wildcard characters.
• Specifications in the UIC directory format may receive defaults only from directories in the UIC directory format.
• Specifications in the non-UIC directory format may receive defaults only from directories in the non-UIC directory format.
• Specifications in the non-UIC directory format that consist entirely of wildcard characters may receive related file specification defaults from directories in UIC or non-UIC format.

RMS processes wildcard characters in an output directory specification as follows:

• If you specify an output directory using a specification that consists entirely of wildcard characters (only [*] and [*...] are allowed), RMS accepts the complete directory component from the related file specification. This permits you to duplicate an entire directory specification.
• If you specify an output directory with a trailing asterisk (for example, [A.B.*]), RMS substitutes the first "wild" subdirectory from the related file specification. This substitution permits you to move files from one directory tree to another directory tree that is not as deep as the first one.
• If you specify an output directory with a trailing ellipsis (for example, [A.B...]), RMS substitutes the entire "wild" subdirectory from the related file specification. This substitution permits you to move entire subdirectory trees.
• The related name block must have the appropriate file name status bits set in the NAM$L_FNB or NAML$L_FNB field set according to the resultant string to allow RMS to identify the "wild" portion of the resultant string.

One of the components of a file specification is the directory specification. RMS supports two conventions or types of directory specifications, one of which is used more often than the other.

When RMS applies defaults to a directory specification in a file specification, the rules differ depending on what type of a directory specification is present. Two directory syntax conventions are available to access directories: normal and rooted. The default directory access is normal syntax. That is, you can specify the directory desired using the directory syntax described in the OpenVMS DCL Dictionary.

6.3.1 Using Normal Directory Syntax

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.