HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
28.6 User-Open Routines
A user-open routine in Fortran, for example, gives you direct access to the file access block (FAB) and record access block (RAB) (the OpenVMS RMS structures that define file characteristics). Use a user-open routine to specify file characteristics that are otherwise unavailable from your programming language.
When you specify a user-open routine, you open the file rather than
allow the program to open the file for you. Before passing the FAB and
RAB to your user-open routine, any default file characteristics and
characteristics that can be specified by keywords in the programming
language are set. Your user-open routine should not set or modify such
file characteristics because the language might not be aware that you
have set the characteristics and might not perform as expected.
To open a file with a user-open routine, include the USEROPEN specifier in the Fortran OPEN statement. The value of the USEROPEN specifier is the name of the routine (not a character string containing the name). Declare the user-open routine as an INTEGER*4 function. Because the user-open routine name is specified as an argument, it must be declared in an EXTERNAL statement.
The following statement instructs Fortran to open SECTION.DAT using the routine UFO_OPEN:
18.104.22.168 Writing the User-Open Routine
Write a user-open routine as an INTEGER function that accepts three dummy arguments:
A user-open routine must perform at least the following operations. In addition, before opening the file, a user-open routine usually adjusts one or more fields in the FAB or the RAB or in both.
The following user-open routine opens an existing file. The file to be opened is specified in the OPEN statement of the invoking program unit.
22.214.171.124 Setting FAB and RAB Fields
Each field in the FAB and RAB is identified by a symbolic name, such as FAB$L_FOP. Where separate bits in a field represent different attributes, each bit offset is identified by a similar symbolic name, such as FAB$V_CTG. The first three letters identify the structure containing the field. The letter following the dollar sign indicates either the length of the field (B for byte, W for word, or L for longword) or that the name is a bit offset (V for bit) rather than a field. The letters following the underscore identify the attribute associated with the field or bit. The symbol FAB$L_FOP identifies the FAB options field, which is a longword in length; the symbol FAB$V_CTG identifies the contiguity bit within the options field.
The STRUCTURE definitions for the FAB and RAB are in the $FABDEF and $RABDEF modules of the library SYS$LIBRARY:FORSYSDEF.TLB. To use these definitions, do the following:
The following user-open routine specifies that the blocks allocated for the file must be contiguous. To specify contiguity, you clear the best-try-contiguous bit (FAB$V_CBT) of the FAB$L_FOP field and set the contiguous bit (FAB$V_CTG) of the same field.
$ CREATE x.Y [Ctrl/Z] $DIRECTORY Directory DISK1:[USER1] x.Y;1 $
As you can see, the mixed-case of the file name is preserved.
29.2.2 Deep Directory Structures
For example, a user can create the following deeply nested directory:
$ CREATE/DIRECTORY [.a.b.c.d.e.f.g.h.i.j.k.l.m]
A user can create the following directory with a long name on an ODS-5 volume:
$ CREATE/DIRECTORY [.AVeryLongDirectoryNameWhichHasNothingToDoWithAnythingInParticular]
Complete file specifications longer than 255 bytes are abbreviated by
RMS when presented to unmodified applications.
126.96.36.199 Directory Naming Syntax
On an ODS-5 volume, directory names conform to most of the same
conventions as file names when using the ISO Latin-1
character set. Periods and special characters can be present in the
directory name, but in some cases, they must be preceded by a
circumflex (^) in order to be recognized as literal characters.
29.3 Considerations Before Enabling ODS-5 Volumes
ODS-5 is being introduced primarily to provide enhanced file sharing capabilities for users of Advanced Server for OpenVMS 7.2 (formerly known as PATHWORKS for OpenVMS), as well as DCOM and JAVA applications.
Once ODS-5 volumes are enabled, some of the new capabilities can potentially impact certain applications or layered products, as well as some areas of system management. The new syntax for file names that is allowed on ODS-5 volumes cannot be fully utilized on ODS-2 volumes. Because pre-Version 7.2 Alpha systems cannot access ODS-5 volumes, and Open VMS Version 7.2 VAX systems have limited ODS-5 functionality, you must be careful where and how you enable ODS-5 volumes in mixed-version and mixed-architecture OpenVMS Clusters.
The following sections comprise a summary of how enabling ODS-5 volumes
can impact system management, users, and applications.
29.3.1 Considerations for System Management
RMS access to deep directories and extended file names is available only on ODS-5 volumes mounted on OpenVMS Alpha V7.2 and greater systems. Compaq recommends that ODS-5 volumes be enabled only on a homogeneous OpenVMS Alpha V7.2 and greater Cluster.
If ODS-5 is enabled in a mixed-version or mixed-architecture OpenVMS Cluster, the system manager must follow special procedures and be aware of specific restrictions on mixed-version and mixed-architecture OpenVMS Clusters with ODS-5 volumes enabled:
Section 29.3.2 describes in greater detail the limitations of ODS-5 support for users in a mixed-version or mixed-architecture OpenVMS Cluster.
Most unprivileged applications will work with most extended file names,
but some may need modifications to work with all extended file names.
Privileged applications that use physical or logical I/O to disk and
applications that have a specific need to access ODS-5 file names or
volumes may require modifications and should be analyzed. See the
website www.openvms.compaq.com for a list of fully supported OpenVMS
applications. Section 29.3.3 describes in greater detail the impact of
ODS-5 on OpenVMS applications.
29.3.2 Considerations for Users
A user on an OpenVMS Alpha Version 7.2 and greater system can take advantage of all Extended File Specifications capabilities on ODS-5 volumes mounted on an OpenVMS Alpha Version 7.2 and greater system.
A user on a mixed-version or mixed-architecture OpenVMS Cluster is
subject to some limitations in ODS-5 functionality. Section 188.8.131.52
lists those restrictions that exist on a mixed-version OpenVMS Cluster.
Section 184.108.40.206 lists those restrictions that exist on a
mixed-architecture OpenVMS Cluster.
220.127.116.11 Mixed-Version Support
Systems running prior versions of OpenVMS cannot mount ODS-5 volumes, correctly handle extended file names, or even see extended file names.
The following sections describe support on OpenVMS Version 7.2 and greater and on prior versions of OpenVMS in a mixed-version cluster.
A user on an OpenVMS Alpha Version 7.2 and greater system can continue to access pre-Version 7.2 files and directories; for example, a user can do all of the following:
On mixed-version clusters, some restrictions exist. Users on a version of OpenVMS prior to Version 7.2:
Current ODS-2 volume and file management functions remain the same on both VAX and Alpha Version 7.2 and greater systems; however, extended file naming and parsing are not available on VAX systems.
The following sections describe support on OpenVMS VAX and Alpha systems in a mixed-architecture cluster.
In mixed-architecture OpenVMS Version 7.2 and greater clusters, OpenVMS Version 7.2 and greater VAX systems are limited to the following Extended File Specifications functionality:
From a VAX system, users cannot successfully create or restore an ODS-5
image saveset. However, these users can successfully restore
ODS-2-compliant file names from an ODS-5 saveset.
29.3.3 Considerations for Applications
ODS-5 functionality can be selected on a volume-by-volume basis. If ODS-5 volumes have not been enabled on your system, all existing applications will continue to function as before. If ODS-5 volumes have been enabled, you need to be aware of the following changes:
On ODS-5 volumes, existing applications and layered products that are coded to documented interfaces, as well as most DCL command procedures, should continue to work without modification.
However, applications that are coded to undocumented interfaces, or include any of the following, may need to be modified in order to function as expected on an ODS-5 volume:
The data layout on disk
The contents of file headers
The contents of directory files
All unmodified XQP applications running on an OpenVMS VAX or Alpha system that access an ODS-5 volume will see pseudonames returned in place of Unicode or ISO Latin-1 names that are not ODS-2 compliant. This can cause applications to act in an unpredictable manner.
Applications that specify or retrieve filenames with the XQP interface using ODS-5 disks must be modified in order to access files with extended names.
This section describes considerations for applications and how to
evaluate an application's support for Extended File Specifications.
29.4.1 Evaluating Your Current Support Status
As part of testing OpenVMS Alpha Version 7.2 and greater, OpenVMS application developers should evaluate and test all existing applications to determine their current level of support for Section 29.5 and whether that level is appropriate.
Any applications that are coded to undocumented interfaces may not provide support for either deep directories or extended file names. Section 29.4.3 lists additional application attributes that may prevent an application from supporting extended file names. Section 29.4.4 lists additional application attributes that may prevent an application from supporting ODS-5 volumes.
You can choose either to modify these applications to support Extended
File Specifications or not to use them under Extended File
Specifications. For information on how to modify an application to
provide default support for Extended File Specifications, see
Section 29.5.1. For information on how to upgrade an application to
full support, see Section 29.5.2.
29.4.2 Default Support
Most unmodified OpenVMS applications fall into the default support
category. Specifically, these applications use the traditional API
rather than the new API when making RMS calls. Applications that use
high-level language calls to perform file operations will also fit into
this category unless the language run-time libraries have been modified
to full support.1 In most cases, you will not need to modify
these applications for them to function successfully under Extended
29.4.3 No Support for Extended File Names
An application that does any of the following may not support extended file names:
1 As of OpenVMS Version 7.2 and greater, no language RTLs have been upgraded to full support.