HP OpenVMS Systems Documentation
Guide to OpenVMS File Applications
An application may also need to process either one file or many files,
depending on the file specification that the terminal user enters or
the logical name that is provided (if the program uses a logical name
in its file specification). Each of these cases is discussed in the
When only a single file needs to be processed, but more than one location for the file may need to be searched, you can usually find the file by specifying a file specification that contains a search list.
For example, consider the case of a directory that contains the file PAY.DAT and a backup copy of the file named PAY_BUP.DAT. You could specify a file name of PAY*.DAT in the file specification and invoke the Parse service once and the Search service once to locate either of the two files; this method will locate PAY.DAT before PAY_BUP.DAT.
A potential problem arises if the file PAY.DAT has been deleted or renamed. In this case, unless the program determines that the file specification is one of several that are acceptable, any file named PAY that has the file type .DAT could be accessed: for example, PAY_ACC.DAT. You can avoid such problems by defining a search list logical name that specifies a search for PAY.DAT and PAY_BUP.DAT. A search list named SEARCH could be defined as follows for the directory [SMITH]:
To locate the file, specify SEARCH as the primary file specification.
When the file locations to be searched reside in different directories of a directory tree, you can use the ellipsis wildcard character in the directory field to search all subdirectories. Alternatively, you could define a search list that searches for the file PAY.DAT in one directory, the same file name in a subdirectory, and PAY_BUP.DAT in any directory in the directory tree by using the following DEFINE command:
You use the file specification SEARCH:.DAT to locate the desired file. In this example, note that one of the search list file specifications contains wildcard characters. Wildcard characters can be used in a search list if they are needed, just as with any other logical names and file specifications. However, the Parse and Search services must be used to locate the correct file.
When you need to locate files in different directory trees (or top-level directories), include complete directory specifications in your search list definition. For example, to locate the file TEST_DATA.DAT in the device/directory combinations of DISK1:[SMITH], DISK2:[STATS], or DISK2:[SMITH] you could use the following command to define the search list TST:
You can also use search lists to locate files on different devices. To locate this file, you specify TST:TEST_DATA.DAT.
To find the same directory and the same file name on different devices, you could use the following command to define TST:
When you define the search list TST in this manner, you can locate the
file by using the search list to specify the device name. In this way,
you can use a single search list to locate files that would otherwise
require multiple file specifications, even if wildcard characters were
To process many files using a single file specification, you always need to use the Parse and Search services to locate the files.
The application requirements and the directory location of the files generally determine whether one or more search lists, wildcard characters, or search lists containing wildcard characters are used in the file specification. When files must be accessed in nonalphabetical order, use a search list.
To process multiple files using a single file specification, invoke the Parse service (or its equivalent) once to interpret the file specification and to create the file specification pattern to be searched. After the file specification is parsed, you can invoke the Search service to locate each file that matches the original file specification. In some cases, you can examine (or display) the resultant file specification string returned by the Search service to determine if you (or the interactive user) want to process (open) the file.
If you want to list all file specifications that match a particular file specification and let the terminal user choose each file to be processed, wildcard characters can be used safely, possibly in a search list that contains wildcard characters in one or more of its file specifications. To reduce the number of files that the user might choose to process, use a search list without wildcard characters or rely less on wildcard characters. For example, to locate all files in a directory tree on different devices with a file type of .DAT, you could define the search list TREE as follows:
The primary file specification that would be used for the Parse service would be TREE:*.DAT. A great number of files might match this.
For applications that will need to locate certain files, search lists with limited use of wildcard characters might be needed. Consider a file that contains a prefix of RESULTS followed by the date for which the data applies. You could use the file name RESULTS*JUN*.DAT to locate a record that was entered in the month of June by executing a Search service followed by an Open service for each file, reading all records until the correct one is found, and invoking the Close service after processing each file.
A search list should be used when a predefined group of files is
processed by a program that is not intended to be interactive. Using a
search list is particularly desirable if the files have unrelated file
names or if they are located on different directories or devices. A
search list also minimizes processing time by searching for a definite
group of files.
For general-purpose applications, when the user enters a file specification that may indicate one file or many files, there is a means of testing whether one file or many files are to be processed, or to explicitly disallow the use of wildcard characters for applications where only a single file should be processed. To test for wildcard characters or search lists, or both, invoke the Parse service and test the appropriate bits in the NAM$L_FNB or NAML$L_FNB field.
The presence of a wildcard character usually indicates that many files should be processed, depending on program conventions. If a search list is present, it may or may not indicate that only one file should be processed and a convention is needed for users of that program. Thus, by testing whether a wildcard is present, the program can either invoke the Parse service once and the Search service repeatedly for each file to be opened, or it can disallow wildcard characters and request that the file specification be reentered. In some cases, the program may need to disallow the use of a search list or allow one or many files to be accessed, depending upon application conventions.
If you want to disallow wildcard characters, invoke the Open service. The Open service fails when it encounters a wildcard character.
|Primary||If the device field is a logical name, RMS translates the logical device name to its component parts. The resulting device name may be a physical device name, a process-permanent file name, or another logical name.|
|Default||If the device field is a logical name, RMS translates it before defaults are applied. If any of the fields in the file specification from the previous step are missing, they are supplied from the corresponding fields in the translated default file specification, where applicable.|
|Related||If the device field is a logical name, RMS translates it and applies the default values before it uses the related file specification to add missing component fields. If fields contain wildcard characters, the wildcard characters remain in the fields. When RMS uses the related file specification to complete an output file specification, the file name field and the file type field are replaced by the corresponding related file specification fields, where applicable. For more information, including the use of multiple related file specifications, see Section 6.2.3.|
|If the device name is omitted, the device field and, optionally, the directory field accept the system logical name SYS$DISK. If RMS cannot translate the logical name SYS$DISK to a physical device name, an error occurs. If the directory field does not accept the logical name SYS$DISK, it accepts the name of the current process default directory.|
Primary, default, and related file specifications can use logical names. RMS translates the primary file specification before it applies defaults and missing components. RMS also translates the default file specification before using the default values. Finally, RMS translates the related file specification before it uses missing components supplied by the related file specification. If the file specification is still missing the device or directory name components, the process executing the program supplies default device and directory values.
The algorithm used in determining the appropriate translation is as follows:
if node name present then translate node name else if device name present then translate device name else if only file name present then translate file name
Table 6-2 shows the sequence in which defaults are applied to a file specification (primary file specification string) and the resulting file specification (resultant string). In Table 6-2, the program specifies the primary file specification string FILE, omitting all other components of the file specification. The default file specification string .DAT provides the file type component. The related file specification string does not provide any component strings, but the default device string (logically SYS$DISK) provides the device string DISK1: and the directory string, [INV_C], is provided by the default directory string. Finally, because the resultant string is used to specify a new file, RMS applies the version number 1 to complete the new file specification.
|String Name||String Applied||Expanded String|
|Primary file specification||FILE||FILE|
|Default file specification||.DAT||FILE.DAT;|
|Related file specification||None.||FILE.DAT;|
|Default device (SYS$DISK)||DISK1:||DISK1:FILE.DAT;|
RMS appends the version number to the expanded string to convert it into the resultant string. The resultant string is the resultant file specification that RMS uses to locate the file.
When coding the file specification information in a program, you can use the language keyword for the OPEN (or CREATE) statement. Then you use the FDL Editor to enter the file specification characteristics. Finally, you call the FDL$CREATE routine to create a file, or you call the FDL$PARSE routine and the FDL$RELEASE routine to open a file.
Consider a program that does not explicitly specify the device and directory in any of the file specifications and does not have a related file specification. RMS adds the current process default device and the current process default directory to the expanded string after it applies components provided by the default file specification. However, if the program looks for a data file that is not in the current process default device and directory, it does not find the file. In this case, the solution is to specify the data file's device and directory either in the primary file specification, the default file specification, or the related file specification.
The program-supplied file specifications can be specified using the methods summarized in the following chart:
|How You Can Specify It|
|Primary||Use the FDL attribute FILE_NAME; use the file name or the name following the FILE, FILE_ID, or FILENAME keywords in the OPEN statement in some high-level languages; or use the string pointed to by the FAB field FAB$L_FNA.|
|Default||Use the FDL attribute FILE DEFAULT_NAME; use the default file specification or the name following the DEFAULTNAME or DEFAULT_FILE_ID keyword in the OPEN statement in some high-level languages; or use the string pointed to by the FAB field FAB$L_DNA.|
|Related||Use the name block (NAM) pointed to by the NAM$L_RLF field; the related name block must specify the location of a file specification, which must be pointed to by the NAM field NAM$L_RSA.|
See the appropriate languages documentation for information about
language statements and their keywords. Consult the OpenVMS Record Management Utilities Reference Manual for
information about the FDL Editor, and refer to the OpenVMS Utility Routines Manual for
information about the FDL$PARSE and FDL$RELEASE routines. For detailed
information about RMS control blocks and services, see the
OpenVMS Record Management Services Reference Manual.
6.2 Understanding RMS Parsing
In the following text, the term expanded string buffer refers to the user-allocated buffer that is pointed to by the NAM block expanded string address field (NAM$L_ESA), by the NAML block short expanded string address field (NAML$L_ESA), or by the NAML block long expanded string address field (NAML$L_LONG_EXPAND).
As it processes each program-supplied file specification, RMS identifies each specification's component parts. Components present in the primary, default, or related, and process-default file specifications are used to form the expanded file specification. The expanded file specification can then be used to locate one or more files. If a name block (NAM or NAML) is present, and the address and size of the expanded string buffer are specified, the file specification is copied into the expanded string buffer.
Note that the Parse service operates differently from other services with regard to the expanded string. With the Parse service, the expanded string contains all wildcard characters present in the file specification. RMS does not generate the resultant string until the program invokes a related service, such as SYS$SEARCH, which uses the expanded string from the Parse service as input.
When you use a search list, the expanded string contains the first location to be searched. RMS stores internally the information that specifies the remaining search list equivalence strings. Note that the equivalence string from a $PARSE is not guaranteed to point to an actual file. As different file locations are examined, RMS updates the expanded string to reflect the current location, and the resultant string contains the actual file specification of the file.
With the Create, Display, Erase, Open, and Search services, defaults are applied to the expanded string to select the actual file used. The resultant string can be used by the program to indicate which file was located. When the file is located, the version number found (or created) is appended to the resultant file specification string (not the expanded file specification string). When a search list is used, the resultant string contains the file specification where the file was actually found.
The following sections describe the steps that RMS uses to create a
complete file specification.
6.2.1 Checking for Open-by-Name Block
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:
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.
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:
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.