Document revision date: 30 March 2001

If the open-by-name-block option is specified (FAB$V_NAM), RMS examines the name (NAM or NAML) block for a valid device identification field (NAM$T_DVI or NAML$T_DVI), directory identification field (NAM$W_DID or NAML$W_DID), and file identification field (NAM$W_FID or NAML$W_FID). If these fields are present, RMS uses them to locate the file; all other components are ignored because they are not needed. If the open-by-name block succeeds, no expanded or resultant string is produced.

If these fields are not present in the name block or if an open-by-name block is not specified (for example, an Open service not preceded by a Parse service), RMS performs the translation and application of defaults. A file can also be created using the name block device and directory identification fields, but RMS does not use the file identification.

If an open-by-name block is requested for remote DECnet for OpenVMS file access between two OpenVMS systems, RMS does not check the device identification, directory identification, or file identification to determine whether the requested open-by-name block operation can be performed. Instead, RMS checks to see if a qualified resultant string is present. If a qualified resultant string is not present, RMS translates logical names and applies defaults as if an open-by-name block operation was not requested (see Section 6.2.2).

6.2.2 File Specification Formats and Translating Logical Names

To form the file specification, RMS examines and attempts to translate each program-supplied file specification, beginning with the primary file specification string indicated by the contents of the FAB$L_FNA and FAB$B_FNS fields, or by the contents of the NAML$L_LONG_FILENAME and NAML$L_LONG_FILENAME_SIZE fields.

A file specification may have one of three formats:

• The first file specification is in the following format:

  node::"foreign-filespec" node::"task-spec-string"

  
  RMS attempts to translate the node name so that it can determine whether a logical node name is present. Only a logical or physical node name (including an access control string, if present) is allowed if the translation is successful. If a logical node name is found, the translation is repeated. When translation cannot be performed, the file specification is copied directly into the expanded string. The quoted string is not parsed except to determine if it refers to a file or a task on the remote system. For additional information about these formats, see the DECnet for OpenVMS Networking Manual.

• If the file specification contains only a name (without a terminating period or colon), RMS attempts to translate it as a logical name. If the file name field is translated successfully, the entire translation operation restarts, using the equivalence string as input. If the file name field is not translated successfully, RMS uses it as the file name component.
• If the file specification is not in either of the formats described previously, RMS assumes it to be in the following file specification format:

  node::device:[root.][directory]filename.type;version

  Note that in the context of a file specification, brackets do not imply optional components. The only optional components are the node component and the root component.
  RMS isolates the components, checks them for proper syntax, and copies them to the expanded string. If a node name is present, RMS attempts to translate it as a logical node name as described previously. If a name in the device component is present and the node name is omitted, RMS attempts to translate the device name as a logical name.
  After translating a logical name, RMS determines whether the translation contains a duplicate component. If RMS finds a duplicate component in the primary file specification translation, it signals an error. Conversely, if RMS finds a duplicated component in the default string file specification translation or in the related string file specification translation, it ignores (discards) the duplicate component.
  If the node name is omitted and the device component does not translate successfully, RMS treats the name in the device component as a device name.
  If the logical name translates successfully, RMS makes several checks and then performs the appropriate task:

  • Checks the equivalence string to determine whether it refers to a process-permanent file. If the equivalence string refers to a process-permanent file, defaults are not needed so RMS stops processing the file specification and copies the logical name to the expanded string. Process-permanent files are described in Section 6.6.
  • Checks the equivalence string to determine whether the logical name is a concealed-device logical name. If the logical name is a concealed-device logical name, and if no concealed-device logical names have been encountered previously in the device file specification, the source string is used as the device name.
  • Restarts the translation operation using the equivalence string as input, if the equivalence string does not contain a process-permanent file and does not have the terminal attribute.
  
  If a node name is present, RMS passes the entire file specification (without the node name) to the remote node for interpretation, using the DECnet data access protocol (DAP) to communicate with the DECnet file access listener (FAL) at the remote node.

The logical name translation procedure reveals two conventions. First, if the file specification has been parsed previously by an RMS file service, it uses the open-by-name-block option to save processing time. Second, a logical device name must be placed at the beginning of a file specification, unless it is preceded by a node name that indicates the node where the logical name should be translated.

6.2.3 Special Parsing Conventions

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.

File Specification Component	Null Field Specification	Wildcard (*) Field Specification
Node	Use related file specification	Illegal
Device	Use related file specification	Illegal
Directory	Use related file specification	Remains wild
Filename	Use related file specification	Remains wild
Type	Use related file specification	Remains wild
Version	Remains null	Remains wild

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:

File Specification Component	Null Field Specification	Wildcard (*) Field Specification
Device	Remains null	Illegal
Directory	Remains null	Remains wild
Filename	Use related file specification	Remains wild
Type	Use related file specification	Remains wild
Version	Remains null	Remains wild

6.2.3.4 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:

File Specification Component	Null Field Specification	Wildcard (*) Field Specification
Node	Remains null	Illegal
Device	Remains null	Illegal
Directory	Remains null	Substitute from related file specification with restrictions
Filename	Use related file specification	Substitute from related file specification
Type	Use related file specification	Substitute from related file specification
Version	Remains null	Substitute from related file specification

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:

File Specification Component	Null Field Specification	Wildcard (*) Field Specification
Device	Remains null	Illegal
Directory	Remains null	Substitute from related file specification with restrictions
Filename	Use related file specification	Substitute from related file specification
Type	Use related file specification	Substitute from related file specification
Version	Remains null	Substitute from related file specification

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.

	privacy and legal statement
4506PRO_017.HTML