Document revision date: 15 July 2002 | |
Previous | Contents | Index |
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.
28.6.1 Opening a File
Section 28.4.1.2 provides guidelines on opening a file with a user-open
routine. This section provides an example of a Fortran user-open
routine.
28.6.1.1 Specifying USEROPEN
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:
! Logical unit number INTEGER LUN ! Declare user-open routine INTEGER UFO_OPEN EXTERNAL UFO_OPEN . . . OPEN (UNIT = LUN, 2 FILE = 'SECTION.DAT', 2 STATUS = 'OLD', 2 USEROPEN = UFO_OPEN) . . . |
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.
INTEGER FUNCTION UFO_OPEN (FAB, 2 RAB, 2 LUN) ! Include Open VMS RMS definitions INCLUDE '($FABDEF)' INCLUDE '($RABDEF)' ! Declare dummy arguments RECORD /FABDEF/ FAB RECORD /RABDEF/ RAB INTEGER LUN ! Declare status variable INTEGER STATUS ! Declare system routines INTEGER SYS$CREATE, 2 SYS$OPEN, 2 SYS$CONNECT ! Optional FAB and/or RAB modifications . . . ! Open file STATUS = SYS$OPEN (FAB) IF (STATUS) 2 STATUS = SYS$CONNECT (RAB) ! Return status of $OPEN or $CONNECT UFO_OPEN = STATUS END |
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.
INTEGER FUNCTION UFO_CONTIG (FAB, 2 RAB, 2 LUN) ! Include Open VMS RMS definitions INCLUDE '($FABDEF)' INCLUDE '($RABDEF)' ! Declare dummy arguments RECORD /FABDEF/ FAB RECORD /RABDEF/ RAB INTEGER LUN ! Declare status variable INTEGER STATUS ! Declare system procedures INTEGER SYS$CREATE, 2 SYS$CONNECT ! Clear contiguous-best-try bit and ! set contiguous bit in FAB options FAB.FAB$L_FOP = IBCLR (FAB.FAB$L_FOP, FAB$V_CBT) FAB.FAB$L_FOP = IBSET (FAB.FAB$L_FOP, FAB$V_CTG) ! Open file STATUS = SYS$CREATE (FAB) IF (STATUS) STATUS = SYS$CONNECT (RAB) ! Return status of open or connect UFO_CONTIG = STATUS END |
Alpha OpenVMS Version 7.2 and greater implements Extended File Specifications, which consists of two major components:
Taken together, these components provide much greater flexibility for OpenVMS Alpha systems (using Advanced Server for OpenVMS 7.2, formerly known as PATHWORKS for OpenVMS), to store, manage, serve, and access files that have names similar to those in a Windows 95/98 or Windows NT environment.
This chapter provides a brief overview of the benefits, features, and support for Extended File Specifications, as well as changes in OpenVMS behavior that occur under Extended File Specifications.
For more information about extended file specifications, see the
Guide to OpenVMS File Applications, and the OpenVMS System Manager's Manual.
29.1 Benefits of Extended File Specifications
The deep directories and extended file names supported by Extended File Specifications provide the following benefits:
These benefits result from the features described in Section 29.2.
29.2 Features of Extended File Specifications
Extended File Specifications consists of two main features, the ODS-5
volume structure, and support for deep directories. These features are
described in the sections that follow.
29.2.1 ODS-5 Volume Structure
OpenVMS Version 7.2 and greater implements On-Disk Structure Level 5 (ODS-5). This structure provides the basis for creating and storing files with extended file names. You can choose whether or not to convert a volume to ODS-5 on your OpenVMS Alpha systems.
The ODS-5 volume structure allows the following features:
These features are described in the sections that follow.
29.2.1.1 Long File Names
On an ODS-5 volume, the name of a file (excluding the version number)
can be up to 236 8-bit or 118 16-bit characters long. Complete file
specifications longer than 255 bytes are abbreviated by RMS when
presented to unmodified applications.
29.2.1.2 More Characters Legal Within File Names
A broader set of characters is available for naming files on OpenVMS. ODS-5 offers support for file names that use the 8-bit ISO Latin-1 character and 16-bit Unicode (UCS-2) character sets.
ISO LATIN-1 and Unicode (UCS-2) Character Sets
The ISO Latin-1 Multinational character set is a superset of the traditional ASCII character set used by versions of OpenVMS previous to Version 7.2. In extended file specifications, all characters from the 8-bit ISO Latin-1 Multinational character set are valid in file specifications, except the following:
C0 control codes (0x00 to 0x1F inclusive)
Double quotation marks (")
Asterisk (*)
Backslash (\)
Colon (:)
Left and right angle brackets (< >)
Slash (/)
Question mark (?)
Vertical bar (|)
To unambiguously enter or display certain special characters in an
ODS-5 compliant file specification, such as a space, you must precede
the character with a
circumflex (^).
29.2.1.3 Preservation of Case
In prior versions of OpenVMS Version 7.2, DCL, RMS, and the file system converted all file specifications to uppercase. ODS-5 preserves the case of file specifications. For example:
$ 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
Both ODS-2 and ODS-5 volume structures support deep nesting of directories, subject to the following limits:
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.
29.2.2.1 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 29.3.2.1
lists those restrictions that exist on a mixed-version OpenVMS Cluster.
Section 29.3.2.2 lists those restrictions that exist on a
mixed-architecture OpenVMS Cluster.
29.3.2.1 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.
Users on OpenVMS Alpha Version 7.2 and greater Systems
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:
Users on Pre-Version 7.2 Systems
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.
Limited Extended File Specifications Capabilities on VAX Systems
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
File Specifications.
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. |
Previous | Next | Contents | Index |
privacy and legal statement | ||
5841PRO_076.HTML |