HP OpenVMS Systems Documentation

OpenVMS Guide to Extended File Specifications

Order Number: AA--REZRB--TE

April 2001

This document provides an overview of Extended File Specifications and describes the impact of Extended File Specifications on system managers, application developers, and users of the traditional OpenVMS environment.

Revision/Update Information: This manual supercedes the OpenVMS Guide to Extended File Specifications, Version 7.2.

Software Version: OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3

Compaq Computer Corporation Houston, Texas

Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

OpenVMS is a trademark of Compaq Information Technologies Group, L.P. in the United States and other countries.

Microsoft and MS-DOS are trademarks of Microsoft Corporation in the United States and other countries.

Motif, OSF/1, and UNIX are trademarks of The Open Group in the United States and other countries.

All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein.

The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6536

The Compaq OpenVMS documentation set is available on CD-ROM.

Contents

Index

Preface

Intended Audience

This document is intended for system managers, application developers, and users who implement Extended File Specifications on one or more systems in an OpenVMS environment.

Document Structure

This manual consists of the following chapters and appendixes:

Chapter 1 provides an overview of Extended File Specifications and its features.
Chapter 2 describes the changes visible to OpenVMS system managers, provides instructions on how to enable and control user access to ODS-5 volumes, and describes the impact on functions such as backing up and restoring media.
Chapter 3 describes the changes visible to OpenVMS users when using ODS-5 volumes.
Chapter 4 describes how to evaluate the support for Extended File Specifications of OpenVMS applications.
Appendix A contains guidelines for setting users' expectations about using the features of Extended File Specifications.
Appendix B contains detailed technical information about the changes to the OpenVMS programming interface to support Extended File Specifications. Much of this material appears in other documents in the OpenVMS documentation.
Appendix C describes the DEC Multinational character set and the ISO Latin-1 character set.

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@compaq.com
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How to Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Conventions

The following conventions are used in this manual:

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
\|	In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold text	This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
`Monospace text`	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Overview of Extended File Specifications for OpenVMS

OpenVMS Version 7.2 on Alpha implements Extended File Specifications, which consists of two major components:

A new, optional, volume structure, ODS-5, which provides support for file names that are longer and have a greater range of legal characters than in previous versions of OpenVMS
Support for deep directories

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.

1.1 Benefits of Extended File Specifications

The deep directories and extended file names supported by Extended File Specifications provide the following benefits:

Users of Advanced Server for OpenVMS 7.2 (formerly known as PATHWORKS for OpenVMS) have the ability to store longer file names, preserve the case of file names, and use deeper directory structures. These new capabilities make the use of an OpenVMS file server more transparent to Windows 95/98 and Windows NT users.
OpenVMS system managers can see files on OpenVMS systems with the names as specified by Windows 95/98 and Windows NT users.
Applications developers who are porting applications from other environments that have support for deep directories can use a parallel structure on OpenVMS.
Longer file naming capabilities and Unicode support enables OpenVMS Version 7.2 to act as a DCOM server for Windows NT clients, and ODS-5 provides capabilites that make the OpenVMS and Windows NT environment more homogeneous for DCOM developers.
JAVA applications on OpenVMS will comply with JAVA object naming standards.
General OpenVMS users can make use of long file names, new character support, and the ability to have lowercase and mixed-case file names.

These benefits result from the features described in Section 1.2.

1.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.

1.2.1 ODS-5 Volume Structure

OpenVMS Version 7.2 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:

Long file names
More characters legal within file names
Preservation of case within file names

These features are described in the sections that follow.

1.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.

For more information on extended file names, see Section 3.1.2.

1.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 (^).

For more information on how these character sets are used in file names, see Section 3.1.2.

1.2.1.3 Preservation of Case

In prior versions of OpenVMS, 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.

For more information on case sensitivity, see Section 3.1.2.6.

1.2.2 Deep Directory Structures

Both ODS-2 and ODS-5 volume structures support deep nesting of directories, subject to the following limits:

There can be up to 255 levels of directories.
The name of each directory can be up to 236 8-bit or 118 16-bit characters long.

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.

1.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.

Section 3.2 contains more information about deep directories. Section 3.6.1 contains information about displaying long directory names.

1.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.

1.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 systems. Compaq recommends that ODS-5 volumes be enabled only on a homogeneous OpenVMS Alpha V7.2 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:

Users must access ODS-5 files and deep directories from OpenVMS Alpha V7.2 systems only, because these capabilities are not supported on earlier versions.
Users who have created deep directories can view those directories only from OpenVMS Alpha V7.2 systems.
Pre-Version 7.2 systems cannot mount an ODS-5 volume nor read ODS-2 or ODS-5 file names on that volume.

Section 1.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 1.3.3 describes in greater detail the impact of ODS-5 on OpenVMS applications.

Chapter 2 contains more information for determining the levels of support for Extended File Specifications, and guidelines for managing a system with ODS-5 volumes enabled.

1.3.2 Considerations for Users

A user on an OpenVMS Alpha Version 7.2 system can take advantage of all Extended File Specifications capabilities on ODS-5 volumes mounted on an OpenVMS Alpha Version 7.2 system.

A user on a mixed-version or mixed-architecture OpenVMS Cluster is subject to some limitations in ODS-5 functionality. Section 1.3.2.1 lists those restrictions that exist on a mixed-version OpenVMS Cluster. Section 1.3.2.2 lists those restrictions that exist on a mixed-architecture OpenVMS Cluster.

1.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 on prior versions of OpenVMS in a mixed-version cluster.

Users on OpenVMS Alpha Version 7.2 Systems

A user on an OpenVMS Alpha Version 7.2 system can continue to access pre-Version 7.2 files and directories; for example, a user can do all of the following:

Create and access deep directory structures on ODS-2 volumes.
Read a BACKUP saveset created on an earlier version of OpenVMS.
Use DECnet to copy a file with an ODS-5 name to a file with an ODS-2 name on a system running an earlier version of OpenVMS.

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:

Cannot access any files on an ODS-5 volume. This is true regardless of whether the volume is connected physically on a CI or SCSI bus, or by an MSCP or QIO server.
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.

1.3.2.2 Mixed-Architecture Support

Current ODS-2 volume and file management functions remain the same on both VAX and Alpha Version 7.2 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 clusters, OpenVMS Version 7.2 VAX systems are limited to the following Extended File Specifications functionality:

Ability to mount an ODS-5 volume
Ability to write and manage ODS-2-compliant files on an ODS-5 volume
See pseudonames ( \pISO_LATIN\.??? or \pUNICODE\.??? ) when accessing an ODS-5 file specification

BACKUP Limitations

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.

1.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:

OpenVMS file handling and command line parsing have been modified to enable them to work with extended file names on ODS-5 volumes while still being compatible with existing applications. The majority of existing, 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 may require modifications and should be analyzed. Applications that have a specific need to access ODS-5 file names or volumes should be analyzed to determine if they require modification.

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:

Internal knowledge of the file system, including knowledge of:
The data layout on disk
The contents of file headers
The contents of directory files
File parsing tailored to a particular on-disk structure.
Assumptions about the syntax of file specifications, such as the placement of delimiters and legal characters.
Assumptions about the case of file specifications. Mixed and lowercase file specifications will not be converted to uppercase, which can affect string matching operations.
Assumptions that file specifications are identical between RMS and the file system.

Note

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.

See Chapter 4 for further discussion of the support status of OpenVMS applications.