HP OpenVMS Systems Documentation
Guide to OpenVMS File Applications
6.2.3 Special Parsing Conventions
Additional parsing conventions for advanced file specifications include
search lists, related file specifications, and the way RMS handles
126.96.36.199 Special Processing for a 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:
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.
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:
188.8.131.52 Output File Specification Parsing
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:
RMS processes wildcard characters in an output directory specification as follows:
6.3 Directory Syntax Conventions and Directory Concatenation
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.
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].
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.
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.