HP OpenVMS Systems Documentation
Guide to OpenVMS File Applications
5.5 Image Activation Using Logical Names
When an OpenVMS system activates an image, it uses RMS to open the image file. If the program specifies the image file with a logical name, RMS uses the equivalence name to look up the image in the known file list, unless the file specification includes a version number delimiter (a semicolon [;] or a period [.]). Known files are files that are installed using the Install utility, and the known file list provides a listing of these files by name and by number (file ID).
If RMS finds the file in the known file list, it uses the file number to access the file directly on disk and bring it into memory for execution. If the specified image file is not in the known file list, RMS goes through the time-consuming process of looking through the disk directories to find the file.
If you create a new version of an image but do not install it as a known image and do not remove the old version of the image from the known file list, the new image will not run.
Similarly, when you use a search list to specify the image, the known file lookup takes precedence. Until a lookup is successful or until the search list is exhausted, RMS executes a known file lookup for each element on the search list that does not include a file version delimiter. If it exhausts the search list, RMS uses the search list again, this time trying to locate and open the image file on disk.
If an older version of the image is included in the search list and if
RMS finds the older version first, it will execute the older version
and never look for the new version. Be sure to consider this when using
Regardless of the programming language, you can use a logical name to provide components of a file specification. The following program example shows how to access a remote file. You access a remote file in the same way that you access a local file, except that the remote file specification includes a node name.
Example 5-1 is a simple Fortran program that transfers a remote file on node TRNTO to the line printer on node BOSTON, using the logical names SRC and DST. You must define the logical name for the process before you run the program, using the following sequence of commands:
In Example 5-1, standard I/O calls transfer the file's records from one device to another. Note the use of the OpenVMS file specification format with a remote node name. (If the remote node is running a system other than OpenVMS, the format of the file specification may differ.)
After opening the files and copying all the records, the program closes the channels, thereby terminating network operations. These operations are similar for applications in the other high-level languages.
You can substitute the system logical name defined on a remote system as one or more of the components in the remote file specification, as follows:
A logical name that includes the device, directory, and filename components but does not include the node, as illustrated in the following example, is not supported in a remote file specification:
Note that a foreign file specification would work:
5.7 Types of Logical Names
When a logical name is defined, you can assign it various translation attributes including the concealed attribute and the terminal attribute. By default, a logical name is neither concealed nor terminal.
To specify a logical name as either concealed or terminal, use the /TRANSLATION_ATTRIBUTES qualifier for the DCL commands DEFINE or ASSIGN.
The concealed attribute ensures that RMS uses the device logical name when communicating with the application program. If the device logical name does not have the concealed attribute, any file specification information returned to the application program includes the device's physical name rather than its logical name. To illustrate, enter the following command sequence:
The system responds with the following display, which identifies the device by its physical name (DUA5):
Now enter the following command sequence:
The system responds with the following display, which identifies the device by its logical name (USERDISK).
A search list is a logical name that contains more than one file specification. Typically a search list is used to search multiple file locations looking for a file. RMS attempts to locate the file by using the first file specification in the search list, then the next, and so forth until the file is found or the search list is exhausted. Like other logical names, a search list is usually defined using the ASSIGN or DEFINE commands; however, in a search list logical name, the multiple file specifications (equivalence names) must be separated by commas.
Any of the equivalence names in the search list may be specified
individually as being terminal or being concealed. Section 6.2
describes the use of search lists and wildcard characters for multiple
file processing and parsing. For general information about using
logical names, refer to the OpenVMS User's Manual.
RMS allows an application program to specify defaults for the device and directory components of a file specification as well as other components of a file specification. The method RMS uses to apply defaults and translate any logical names present is called file parsing. In effect, RMS merges the various default strings (after translating any logical names) to generate the file specification used to locate the file.
One of the functions of file parsing is to determine when a logical name is present and whether the file specification describes a file on the local node. If a node name is not present in the file specification (the file is located on the local system), RMS translates any logical names, applies defaults to any missing components, and then attempts to locate the file.
If a node name is present, RMS does not process the file specification on the local node. Instead, it merges any program-specified defaults without translation and passes the defaulted, untranslated file specification to the file access listener (FAL) at the remote node; the operating system on the remote node interprets it.
With advanced file parsing, a single file specification can be used to locate a single file or multiple files. To locate a single file, multiple file locations or file names can be searched to ensure that the file is found. The multiple file locations or file names can be located in the same or in different directories, on different devices, on different nodes, or a combination thereof. Using wildcard characters and search lists, you can locate multiple files with a single file specification.
When a wildcard character or a search list is included in a file specification, the application program may need to preprocess the file specification before attempting to locate the file. An RMS file service that operates on an unopened file (such as the Create service and the Open service) performs the following file-parsing tasks:
If a name block is present, the service may also do the following file-parsing tasks:
Some file services, including the Open and Create services, cannot process a file specification that contains wildcard characters. If a file specification contains wildcard characters, you must use the Search service to resolve the wildcard characters before you invoke the Open service or the Create service.
The Parse service determines whether wildcard characters or search lists are present, and it initializes control block fields that are necessary to search for multiple files using the Search service. To use the Search service, a name block (NAM or NAML) must be present when the Parse service is invoked.
Alternatively, you can use the SYS$FILESCAN system service (scan string for file specification) to scan a file specification for validity and optionally return the lengths of the individual file specification components without translating logical names or applying defaults. Two Run-Time Library routines, LIB$FIND_FILE and LIB$FILE_SCAN, perform functions that are similar to the SYS$SEARCH system service.
For more information about how RMS parses a file specification, see
Section 6.1. For additional information about using directory
specifications, including directory syntax conventions, see
Five services can translate and apply defaults to a file specification to produce a fully qualified file specification: the Create, Open, Erase, Parse, and Rename services. Other file services must be preceded by one of these services to parse the file specification and, in some cases, to open the file.
If a file specification contains one or more wildcard characters, it must be preprocessed using the Parse and Search services before the file can be located. The Parse service sets bit values in the name block file name status bits field (NAM$L_FNB or NAML$L_FNB). This field can be tested to determine whether a wildcard character or a search list logical name is present. The Search service locates a file and specifies its name (without wildcard characters). If wildcard characters are present, you must first invoke the Search service before processing (opening or creating) the file; if wildcard characters are not present, the file can be processed without invoking the Search service.
To process a single file, you need to invoke the Search service only once; to process many files, invoke the Search service as many times as needed to return the next full file specification. When no more files match the file specification, the Search service returns a no-more-files-found message (RMS$_NMF).
In summary, the Parse and Search services work together to provide a fully qualified file specification that the Search service uses to locate the file.
Your program can process a single file without using the Search service if neither the file specification nor the search list contain wildcard characters. If any of the file specifications in a search list contain wildcard characters, the Search service must be invoked before processing the file to prevent an invalid wildcard completion status error. If a wildcard character is present in the second or subsequent file specifications in a search list, RMS does not set the wildcard bit in the file name status bits field.
If the Parse and Search services precede an Open service, an open-by-name-block operation should be performed by specifying the address of the name block in the name block address (FAB$L_NAM or FAB$L_NAML) field and setting the file-processing options (FAB$L_FOP) open-by-name-block (FAB$V_NAM) bit option.
When the create-if option bit (FAB$V_CIF) or the supersede option bit (FAB$V_SUP) is set in the file-processing options (FAB$L_FOP) field, the program may invoke the Parse service to check for wildcard characters or search lists in the file specification. If a search list or wildcard characters are found, the program must invoke the Search service before invoking the Create service.
The create-if option tries to open any file found in the search list. If the file is not found in the search list, RMS creates it using the first file specification in the search list. If these options are specified and a wildcard character is present when the Create service is invoked, the file specification is invalid; if a search list is present, the file is created using the first file specification from the search list.
You can either call these services directly from a VAX MACRO procedure, as part of a USEROPEN or USER_ACTION routine in a high-level language, or you may execute the calls from high-level language subroutines or functions that call RMS. The Parse and Search services require that a name block be present. Unless your language supports a means of setting values in a name block (and other control blocks) and invoking RMS, you should use a VAX MACRO procedure. FDL does not support the use of a name block.
In addition to a name block, you usually need a file access block (FAB) and a record access block (RAB). To perform file services, a FAB (and, if needed, extended attribute blocks [XABs]) must be present; to perform record services, a RAB must be present.
The following program shows how to use the LIB$FIND_FILE routine to locate the desired file, which the interactive user enters. Because LIB$FIND_FILE is used with the supplied arguments, the file specification may contain wildcard characters, a search list, and a search list that assumes the program will allow the use of "sticky" defaults, as in DCL command line parsing. The routine is called by the following VAX BASIC program USEROPEN option for the BASIC OPEN statement:
The BASIC program allocates the control blocks before control is given to the USEROPEN routine; it also passes the address of the FAB as the first argument and the address of the RAB as the second argument. These arguments enable the VAX MACRO routine to obtain the control block addresses because the argument pointer points to the longword count of arguments, followed by the longword-length arguments. Because the VAX MACRO macros $FAB and $NAM are not used, access to the symbolic offset values defined for these control blocks is not available; thus, the $FABDEF, $NAMDEF and $RABDEF macros define these symbols for the USEROPEN routine.
In addition to locating the file using any valid file specification, the called routine also connects to the file requesting 15 global buffers (or as many global buffers as system resources permit). This routine is linked with the BASIC program to form the executable image. Example 5-2 shows the routine.
Example 5-2 also shows the proper way to signal errors. The RAB$L_STS (completion status) field and the RAB$L_STV (additional status values) field of the FAB or RAB are used so that secondary completion information is displayed, if appropriate, by the LIB$SIGNAL or LIB$STOP routines.
The VAX MACRO program shown in Example 5-3 invokes the Parse service, determines whether a wildcard character or search list is present, and conditionally branches to a sequence of instructions that invoke the Search service followed by the Open service. The resultant string is displayed after the file is opened.
For more information about the LIB$ routines, see the OpenVMS RTL Library (LIB$) Manual.
The next example program uses the $PARSE and $SEARCH functions, demonstrates the use of C language's fopen function, and shows how you can mix RMS calls and C I/O calls.
Example 5-3 uses cc$rms_fab and cc$rms_nam to define the $FAB and $NAM control blocks and specify the arguments for the Parse, and Search services.
The program shows how to preprocess a file specification using the Parse and Search services. First, the program prompts the user for an input file specification that may contain wildcard characters. The program then searches each file that matches the file specification for the specified text string.