HP OpenVMS Systems Documentation

To support Extended File Specifications, RMS's user interface was extended to include capacities for the larger specifications that are sometimes necessary to access ODS-5-named files. (See the OpenVMS Record Management Services Reference Manual.) To take full advantage of all of the new features, applications would have to be updated to use the interface extensions. To provide extended capabilities (such as access to deep directories) to applications that continue to use the older interface, RMS supports the generation and acceptance of file specifications with an abbreviated form of root or directory specification, known as a DID (for Directory ID) abbreviation.

The DID is an alternate form of subdirectory specification that is not relative to the MFD. It takes the form (for ODS-2 and ODS-5 disks) of three decimal numbers separated by commas and can be used in the MFD position in a root or directory component specification.

Examples of valid root and directory components with DIDs are as follow:

 DKA200:[24,42,0]
 DKA200:[1223,4,0.a]
 DKA200:[134,59,0...]
 DKA200:[1223,4,0.][134,59,0]

A DID can also be used in place of a subdirectory in a root or directory component, but subdirectories located to its left in the specification (above it in the directory tree) are elided by RMS, as shown in the following example:

$SET PROCESS/PARSE_STYLE=EXTENDED
$WRITE SYS$OUTPUT F$PARSE("DKA200:[system.test.134,59,0...]*.*;*")
DKA200:[134,59,0...]*.*;*
$WRITE SYS$OUTPUT F$PARSE("DKA200:[system.test.134,59,0.BTEST2]*.*;*")
DKA200:[134,59,0.BTEST2]*.*;*

If a specification contains both a root with a DID and a directory with a DID, the root will be ignored (though not elided) by RMS.

The directory ID numbers are those that are displayed for a directory with the DIRECTORY/FILE_ID DCL command, as shown in the following:

$DIRECTORY/FILE_ID/NOHEADER/NOTRAILING/WIDTH=(FILE=45) .DIR;1
 DKA200:[SYSTEM]1.DIR;1                    (24,42,0)
 DKA200:[SYSTEM]a.DIR;1                    (1223,4,0)
 DKA200:[SYSTEM]BTEST1.DIR;1               (134,59,0)
 DKA200:[SYSTEM]DIR^^_1.DIR;1              (609,22,0)
 DKA200:[SYSTEM]lowercase.DIR;1            (655,49,0)
 DKA200:[SYSTEM]te^[mp.DIR;1               (20,37,0)
 DKA200:[SYSTEM]tmp^.tmp.DIR;1             (355,20,0)
 DKA200:[SYSTEM]UNICODE.DIR;1              (1968,10,0)
 DKA200:[SYSTEM]UPPERCASE.DIR;1            (656,45,0)
 DKA200:[SYSTEM]with^.dot.DIR;1            (768,28,0)

When RMS attempts to generate a file specification that is too long for the application's output buffer, pointed to by the NAM block expanded or resultant string field, NAM$L_ESA or NAM$L_RSA; or by the NAML block short expanded or short resultant string file, NAML$L_ESA or NAML$L_RSA, it replaces the root and directory component with one that has the DID for the lowest level subdirectory of the replaced component(s). The specification that results can then be used as input to RMS.

It should be noted that not all RMS features are available with DIDs. For example, attempts to use sticky defaulting with a root or directory with a DID will result in an error. And you cannot create a directory using a DID.

6.5 FID-Abbreviated Names (Alpha Only)

On Alpha systems, when a file specification, even with DID abbreviation, is too long to fit into a resultant name buffer (NAM block NAM$L_RSA field or NAML block NAML$L_RSA field), RMS attempts to generate a short-enough file specification by identifying the file with its file ID (three decimal numbers separated by commas, surrounded by brackets) in the file name component.

In cases in which the file type component would otherwise be presented, a generated file specification will either include the entire type or will not include any type (including the "." delimiter), depending upon whether or not there is space.

In cases in which the version component would otherwise be presented, a generated file specification will include the version component.

As a human-readable aid in recognizing files, when a FID is generated, the name component also contains a DCL-legal initial subset of the actual file name. The subset consists of the first 38 simple characters (where "^U1234" is six simple characters) of the actual file name, followed by "~".

No attempt is made to resolve ambiguities for files that differ only after the first 38 simple characters of their names.

An example of a generated name with a FID is as follows:

 DKA200:[SYSTEM]leadingfilenamechars~[384,35200,0].txt;1

Such a file specification can be used as input to RMS, with some limitations.

6.5.1 Restrictions on FID-Abbreviated Names

A FID can be used for input to RMS, but only the FID is significant. The subset portion of the name component, the type component, and the version component are ignored by RMS.

As input, the FID-abbreviated file name component is not used as a default (as from a related file specification to replace a wildcard in an output specification). Instead, the output specification will get a null file name, as shown in the following:

$COPY/LOG ^U6666^U7777^U8888^U9999^U5555^U6666~[449,35295,0].txt;1 *.xxx
%COPY-S-COPIED, DKA200:[SYSTEM]^U6666^U7777^U8888^U9999^U5555^U6666~
[449,35295,0].txt;1 copied to DKA200:[SYSTEM].xxx;1

Note that generated names with FIDs are possible only for resultant specifications, which refer to specific files, and not for expanded specifications, which do not necessarily refer to one file.

6.6 Using Process-Permanent Files

Process-permanent files are files that remain open independent of image activation and rundown. Process-permanent files are created by setting the process-permanent file bit (FAB$V_PPF) in the file-processing options field (FAB$L_FOP). When the bit is set, RMS-maintained internal data structures are allocated in the process control region of memory for the life of the process. Thus, process-permanent files can remain open across image activations. SYS$COMMAND, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR are all opened in this manner by the LOGINOUT command image.

The DCL command OPEN also opens files in this manner. With user mode code, you can access process-permanent files only indirectly. RMS provides a subset of the total available operations to the indirect accessor.

Indirect accessors gain access to process-permanent files through the logical name mechanism, as follows:

1. The LOGINOUT command image, or at a later point the command interpreter, opens or creates a file corresponding to the process's command, input, output, and error message streams. Logical names are created in the process logical name table for SYS$COMMAND, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR, respectively. The equivalence string for the logical name has a special format that indicates the correspondence between the logical name and the related process-permanent file. For more detail concerning the equivalence-string format for logical names, see the discussion of logical name services in the OpenVMS System Services Reference Manual. For example, for an interactive user, these single process-permanent files are opened for the terminal.
2. When an indirect accessor opens or creates a file specifying a logical name that has one of these special equivalence strings, RMS recognizes this and therefore does not open or create a new file. Instead, the returned value for the internal file identifier (and later the value for the internal stream identifier from a Connect service) is set to indicate that access to the associated process-permanent file is with the indirect subset of allowable functions.

The implications for the indirect accessor are described in the following list:

• A Create service for a process-permanent file becomes an Open service; the fields of the FAB are output according to the description of the Open service, not the Create service.
• The Open and Create services require no I/O operations.
• Any number of indirect Open and Create operations are allowed.
• There is only one position context for the file; each sequence of the Open or Create service accesses the same record stream, not an independent stream.
• If the process-permanent file was initially opened with the sequential-processing-only (FAB$V_SQO) bit set in the FAB$L_FOP field, neither random access nor the Rewind service is permitted. This is the case for SYS$COMMAND, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR.
• Certain options to various services produce errors. For example, you cannot set the non-file-structured (FAB$V_NFS), process-permanent file (FAB$V_PPF), and user-file-open (FAB$V_UFO) bits of the FAB$L_FOP field for the Open and Create services. Other options are ignored, such as: the spool (FAB$V_SPL), submit-command-file (FAB$V_SCF), delete (FAB$V_DLT) bits of the FAB$L_FOP field for the Close service; the asynchronous (RAB$V_ASY) bit of the RAB$L_ROP field; the multiblock count field (RAB$B_MBC) and the multibuffer count field (RAB$B_MBF; or optionally, the XAB$_MULTIBUFFER_COUNT XABITM).
• If a name block is used and either an expanded or resultant file specification string is returned, the string consists solely of the process logical name followed by a colon (such as SYS$INPUT:).
• The file access (FAB$B_FAC) field is ignored by the Open service; instead, operations are checked against the FAB$B_FAC field specified for the original Open or Create service.
• Information from the record attributes field is saved on each Open service and subsequent Connect service in the values returned in the internal file identifier and internal stream identifier fields. If the output file is a print file (VFC record format and the FAB$V_PRN bit set in the record attributes field), mapping is performed for each Put service from the user-specified carriage control to the print file carriage control format. Thus, different carriage control types from different indirect Open services all work correctly.
• You cannot use the Erase service.
• Checking is performed for $DECK, $EOD, and other dollar-sign ($) records on the SYS$INPUT stream if the SYS$INPUT stream is from a file. Checking is not done if SYS$INPUT comes from a record-oriented device, such as a terminal or a mailbox. (See the OpenVMS DCL Dictionary.)
• At image exit time, the run-down control routine ensures that the indirect I/O on process-permanent files terminates; however, these files are not closed.
• All file organizations may be opened directly as process-permanent files (for example, through the DCL command OPEN), but only those files with a sequential organization may be indirectly accessed.

This chapter discusses the run-time options that are available when opening, connecting, and closing a shared file. These options are implicit in creating a shared file because the Create service includes an implied file open.

File sharing includes file accessing, record locking, and local and shared buffering. Figure 7-1 shows a typical shared file situation.

Figure 7-1 Shared File Access

See the OpenVMS Record Management Services Reference Manual for more information about accessing and sharing files.

7.1 File Accessing

OpenVMS RMS (hereafter referred to as RMS) file sharing allows multiple users to access a single file. Timely access to files sometimes requires that more than one active program be allowed to read, write, and modify records within the same file simultaneously.

Whether or not a file can be shared depends on the type of device it resides on and the explicit file-sharing information specified by the processes that access the file. Magnetic tape files cannot be shared because magnetic tape drives are sequentially operated devices. However, disk files can be shared by any combination of readers and writers without restriction. Your program provides the information that enables file sharing. You control the degree of sharing by providing an explicit file-sharing specification when your program opens or creates a file. This specification indicates the types of file operations that are permitted for application programs that share the file.

When a program creates or opens a disk file, it gives two pieces of information needed to determine if and how the file may be shared. First, it states the types of operations it intends to perform on the file, such as read, write, or update. RMS later checks this information to protect against unauthorized file access.

Second, the program specifies the types of operations other concurrently active programs can perform on the file. When the sharing specification of one program is compatible with the sharing specification of another, both programs can gain access to the file simultaneously. To ensure that multiple programs can access the file simultaneously, you may have to do some schedule planning.

7.1.1 Types of File Sharing and Record Streams

A single process can access the same file using multiple record streams. A record stream is the access environment in which file records may be read, written, deleted, or updated. Important elements of the access environment are the current record position (if any), the access mode established for the current record, the sequential next record position, and the state of locks on other records in the file.

The Connect service creates a record stream and associates it with a file opened or created by the appropriate service. The connection between a record stream and a file is explicitly terminated by the Disconnect service or is implicitly terminated by closing the file. Record streams are connected to a file in one of three ways:

• Within one process or across several processes, multiple FABs can be connected to a shared file. One or more record streams may then be connected to each FAB. This form of sharing is known as interlocked interprocess file sharing and is associated with reading or writing records, not blocks.
• Within one process, multiple record streams can be associated with one FAB to read and write records, not blocks. This form of sharing is known as multistreaming.
• Within one process or across several processes, multiple FABs can be connected to a file. One record stream (RAB) is connected to each FAB, and users provide their own synchronization. This form of file sharing is known as user-interlocked interprocess file sharing. (User-interlocked interprocess file sharing usually applies only to block I/O processing and to record processing for nonshared sequential files residing on disk devices.)

Two important options for shared files are the file-access and file-sharing options. These options specify the type of record access that the sharing processes can perform. They are specified by the FDL attributes ACCESS and SHARING and the FAB fields identified by the symbolic offsets FAB$B_FAC and FAB$B_SHR. When creating or opening a file, RMS compares the values of these fields to determine whether or not the requesting process may have access to the file.

In this manual, the term accessor refers either to a process that accesses a file or a record stream that accesses a record. The first process to access a file determines which operations other accessors can perform on the file, which in practice determines whether or not subsequent users are allowed to access the file. For example, if your process requests a certain type of access that the first accessor (since the file was last closed) has disallowed, your process cannot access the file.

When choosing the access other processes may have to the file, you can specify the type of file sharing to be used and indicate whether or not other processors can access the file simultaneously.

In an OpenVMS Cluster environment, processes can access shared files on the same or different nodes. (See Section 3.7).

A single file can be accessed by both interlocked interprocess file sharing and multistreaming. Compaq does not recommend the simultaneous use of interlocked interprocess file sharing and user-interlocked interprocess file sharing on the same file if the process that requests user-interlocked interprocess file sharing intends to modify the file. The reason is that record locking is not done or checked for the processes using user-interlocked interprocess file sharing.

You must define your process access based on planned record operations. The record operations with associated FDL and RMS options are summarized in Table 7-1.

The record-access functions you request are compared with the protection on the specified file. If your process is limited to reading and locating records, it should have read access to the file. If your process is deleting, adding, truncating, or updating records, it must have write access to the file. RMS permits any process that may delete, add, truncate, or modify records to also locate and read records because write access to a file also implies read access.

You can perform block I/O operations using the Read, Space, and Write services. Block I/O is usually only used by applications written in VAX MACRO or other low-level languages. Note that when ACCESS BLOCK_IO is specified, the application program must also specify either SHARING USER_INTERLOCK or SHARING PROHIBIT.

Different types of record operations can be specified to define the type of access to be allowed for other processes, as shown in Table 7-2.

If other processes are limited to reading and locating records, they are unable to modify or add records, and record-lock checking is not performed. If other processes are allowed to delete, add, or modify records, they can also read records; however, record-lock checking occurs. All record-access functions use interlocked interprocess file sharing.

No access denies access to all accessors except the accessor who specifies the option. This option might be used when a file is shared infrequently or when doing a major update. When you use this option, be sure to close the file promptly when other users are trying to access the file. Choose this option or the user-interlocking option when using block access. To use the Queue I/O Request system service, specify the FILE USER_FILE_OPEN attribute (FAB$L_FOP field FAB$V_UFO set). The no-access option does not allow file sharing and requires that your process have write file protection access.

User interlocking permits the user to maintain interlocking protection (including maintaining the end-of-file mark). For any other form of file sharing, RMS controls the reading and writing of I/O buffers to ensure the integrity of file and record structures. This option is useful for nonshared sequential files and for block I/O access using RMS or the Queue I/O Request system service.

Multistreaming allows your process to access the same file using more than one record stream and allows other users to access the file using interlocked interprocess file sharing (unless SHARING PROHIBIT is also specified). When you select this option, select the appropriate SHARING record operations, such as SHARING GET. When multiple streams are connected, the buffers allocated for each stream become part of a buffer cache for the entire process. (A buffer cache is a common shared buffer pool intended to minimize I/O.) A record operation on one stream may use cached buffers from a previous record operation on a different stream that referenced the same buckets.

When you open or create a file, you must specify the file access and file sharing you want for it. When using FDL or RMS, the default is to read records from the file (ACCESS GET) and to allow others accessors to read records from the file (SHARING GET). Typically, an application program may want to read records (ACCESS GET) while allowing other accessors to add records (SHARING PUT). You might want to modify records (ACCESS UPDATE) while allowing other accessors to add new records to the file (SHARING PUT).

When you create a file, the default is for FDL and RMS to add records to the file (ACCESS PUT) and to not allow others to access the file (SHARING NONE). When you create a file with the create-if option, it is especially important to specify the access and sharing values. In this instance, you have denied yourself access if the file already exists because you have specified SHARING NONE and you are not the initial accessor. One way to avoid this when you create a file is to allow most operations for other users (such as SHARING GET, SHARING PUT, SHARING UPDATE, and SHARING DELETE).

Combinations of file access and file sharing that specify a mixture of interlocked interprocess file access and user-interlocked interprocess file sharing allow the application program to access the file without record locking protection. Such combinations are not recommended for general use; they should be used only for application programs that require read-only access to a file. Other combinations may cause an error, such as requesting ACCESS BLOCK_IO without specifying SHARING NONE or SHARING USER_INTERLOCK.