HP OpenVMS Systems Documentation

Guide to OpenVMS File Applications

On Alpha systems, RMS identifies the file name, file type, and file version components from the portion of a file specification that follows any node, device, root and directory components as follows:

The right-most semicolon or period followed by legal version characters begins the version component. A semicolon (unescaped) followed by characters that are not legal for a version component is illegal. The right-most period to the left of the version (if any) begins the type component. The characters to the left of the type are the file name.

Legal forms of a version component are:

 ;<decimal digit(s)>
 ;-<decimal digit(s)>
 ;*                     (multiple-character wildcard)

On ODS-2 and ODS-5 disks, the numerals in a version component, interpreted as a decimal number, may not exceed 32767.

Note that, although RMS accepts a period as a version delimiter, in output specifications, RMS always uses the semicolon as the delimiter.

The following are some examples of name, type, and version:

      Name+Type+Version            Name      Type      Version
        A.B;1                      A          .B        ;1
        A.B.C                      A.B        .C        (none)
        A.B;C                              (illegal)
        A.B.1                      A          .B        .1
        A.B.-1                     A          .B        .-1
        A.B.-32767                 A          .B        .-32767
        A^.B                       A^.B      (none)     (none)
        A.B^.C                             (illegal)
        A.B;1234567                        (illegal)

Note that, although RMS on Alpha systems allows periods in a file name, files with such names can be created only on ODS-5 disks.

On VAX systems and on Alpha systems with versions previous to OpenVMS V7.2, RMS identifies the file name, file type, and file version components from the portion of a file specification that follows any node, device, root, and directory components as follows:

• A semicolon or the right-most period followed by legal version characters begins the version component.
• A semicolon followed by characters that are not legal for a version is illegal.
• A period to the left of the version (if any) begins the type component.
• No periods, other than the type and version delimiters, are allowed.

On Alpha systems, OpenVMS Version 7.2 supports the use of file names and subdirectory names that begin with hyphens. This is supported on ODS-5 and ODS-2 disks.

No special action is required for specifying a name that begins with a hyphen, with the following exception. A reference to a subdirectory whose name consists only of hyphens must include at least one escaped hyphen (so that RMS can distinguish the reference from a relative directory specification). On output, RMS always displays such a subdirectory name with the first hyphen escaped.

For example:

$CREATE/DIRECTORY DISK$:[^---]
$CREATE/DIRECTORY DISK$:[FLARKY.LEVEL1.LEVEL2.LEVEL3]
$SET DEFAULT DISK$:[FLARKY.LEVEL1.LEVEL2.LEVEL3]
$WRITE SYS$OUTPUT F$PARSE("[---]")            ! (relative spec.)
DISK$:[FLARKY].;
$WRITE SYS$OUTPUT F$PARSE("[^---]")           ! (directory ---)
DISK$:[^---].;
$$ WRITE SYS$OUTPUT F$PARSE("[-^--]")           ! (directory ---)
DISK$:[^---].;
$DIRECTORY/NOHEADING/NOTRAILING DISK$:[000000]---.DIR
DISK$:[000000]---.DIR;1                        ! (file ---.DIR)

The following sections describe a restriction when using extended file names and a DCL parsing anomaly.

5.2.9.1 Restriction with Extended File Names

Using the tilde (~) as the first character in a file name in the Compaq C Run-Time Library (CRTL) allows a programmer to specify both UNIX style and OpenVMS style file specifications to routines such as creat() and fopen().

In UNIX file specifications, a tilde (~) in the first character of a pathname represents the user's home directory. However, in an OpenVMS extended file name, a tilde is legal anywhere in a file name or directory name.

To preserve backward compatibility, the CRTL will continue to interpret a leading tilde (~) to mean the user's home directory. To pass an OpenVMS file name that begins with a tilde (~) to a CRTL routine that accepts UNIX style file specifications, specify the tilde preceded by the escape character (^). For example, ^~.

The following Compaq CRTL functions accept OpenVMS extended file names and require this syntax for a leading tilde (~) in the file specification:

.create
.fopen
.freopen
.open
.stat

Prior to OpenVMS Version 7.2, DCL parses some file specifications incompletely, and does not detect all illegal ODS-2 file specifications. Specifically, if a file specification has three comoponents separated by two delimiters, DCL does not verify that the second delimiter is a semicolon and the third component is a version number. However, RMS verifies the file specification completely and detects errors that DCL may miss. For example, on an ODS-2 volume:

$CREATE A.B.C
%CREATE-E-OPENOUT, error opening A.B. C as output
-RMS-F-SYN, file specification syntax error.

For compatibility, this behavior has been preserved. However, this can produce unexpected results when accessing an ODS-5 volume under the following conditions:

• The parsing style is traditional (the default).
• The file specification is illegal on ODS-2.
• DCL does not detect the error.
• The file specification is legal on ODS-5.

Under these conditions, the command CREATE A.B.C succeeds on an ODS-5 volume. However, you cannot access the file with a DCL command that requires a version number (such as the DELETE command). For example:

$DELETE A.B.C
%DELETE-E-DELVER, explicit version number or wild card required
$DELETE A.B.C;1
%DCL-W-PARMDEL, invalid parameter delimiter - check use of
special characters \;1\

The only way to delete this file when the parsing style is TRADITIONAL is to use wildcards, and for safety, you should use the /CONFIRM qualifier with the DELETE command. However, it is safer to change the parsing style to EXTENDED. For example:

$SET PROCESS/PARSE_STYLE=EXTENDED
$DELETE A.B.C;1
$SET PROCESS/PARSE_STYLE=TRADITIONAL

RMS translates a logical name present in a file specification at run time. The use of logical names can be desirable for several reasons, including program simplification, device independence, file independence, and ease of use.

You can specify the file specification at compile (or assembly) time, or the program can prompt for it at run time. By specifying a logical name when you compile a program, you eliminate having to program a terminal input request, and you preserve the flexibility of being able to specify the input file at run time.

Device independence is more readily attainable if a logical name is used for the device name component. By using a logical name rather than explicitly specifying a physical device, an alternate device (usually containing a recent backup copy of the device) can be substituted by changing the definition of the logical name. Typically, device independence can reduce or eliminate the downtime caused by media failure or scheduled preventive maintenance.

Similarly, when you use a logical name, and the current copy of a file is not available, an alternate file can be used. To locate several files in a defined search order, you can use a search list, which is a form of logical name. Alternatively, you can use wildcard characters to locate several files using one file specification; however, wildcard characters do not allow you to specify a search order.

Using a logical name to represent a complex file specification or a file specification component reduces keystrokes to save time and reduces the chance of error. For example, you could define a logical node name that translates to an actual node name and access control string for use when locating remote files. To keep the password a secret when you use this technique, the logical name should be defined interactively rather than in a command procedure.

RMS attempts to treat the file name component as a logical name if the file name is the only component in the file specification. Refer to the OpenVMS User's Manual for additional information on defining logical names. No logical name translation is done on any logical name that contains a compound character (containing the RMS escape character: "^").

5.4 File Specification and Component Length Limits

The following section describes a file specification on ODS-2 and ODS-5 disks.

5.4.1 VAX Systems and ODS-2 Disks on Alpha Systems

The maximum length of a file specification string is 255 characters, including all separator characters. The following table lists the length limits for each of the component parts of a file specification. Note that although the collective limit exceeds 255 characters, the overriding limitation is on the length of the file specification.

The maximum length of a file specification string is 4095 characters, including all delimiters. The following table lists the length limits for each of the component parts of a file specification.

RMS supports file names for which the sum of the lengths of the file name, the file type, and the file version does not exceed 255 (simple) characters. ODS-5 disks support file names for which the sum of the lengths of the file name and the file type does not exceed 236 bytes.

Be careful when naming files that will be copied or accessed by remote systems. File name restrictions are generally determined by the file naming capabilities of the networked systems that require access to them. These restrictions must be considered part of the overall application design when network access is required.

5.4.3 Maximum Subdirectory Depths

RMS supports creating and accessing up to 255 subdirectory levels (in any combination in the root and directory components) on ODS-2 and ODS-5 volumes accessed from Alpha systems. For ODS-2 and ODS-5 volumes accessed from VAX systems, RMS supports up to 8 subdirectory levels each for the root and directory components.

5.4.4 Accessing Files on ODS-5 Disks from VAX Systems

On VAX systems, RMS allows access to ODS-5 volumes. But, file specifications are allowed on those volumes that RMS on VAX does not support. Some of the limitations are described here.

When a search is done of a directory that contains files whose names are legal for ODS-5, but not for ODS-2, one of two pseudonames, "\PISO_LATIN\.???" or "\PUNICODE\.???" will be displayed. Such files can be accessed via RMS only from an Alpha system.

It is possible to create directory trees on both ODS-5 and ODS-2 volumes that are deeper than RMS can display. In those cases, RMS will not display any subdirectories that lie beyond its limits.

5.4.5 Determining the Structure Level of a Disk Device

From DCL, you can determine a disk device's structure level (for example, ODS-2 or ODS-5) via a SHOW DEVICE/FULL command.

A DCL command procedure can determine the structure level with code such as the following:

$!
$DeviceName = "SYS$SYSDEVICE"
$DeviceType = F$GETDVI(DeviceName,"ACPTYPE")
$IF DeviceType .EQS. "F11V5"
$THEN
$    DeviceType = "ODS-5"
$ELSE IF DeviceType .EQS. "F11V2"
$         THEN
$             DeviceType = "ODS-2"
$         ELSE
$             DeviceType is "unknown"
$ENDIF
$ENDIF
$WRITE SYS$OUTPUT -
$    "Disk ''DeviceName' on-disk structure is ''DeviceType'"
$!
$EXIT

The structure level can be determined in a program (executable image) via a call to the SYS$GETDVI system service using an item list with the DVI$_ACPTYPE request code. The following example, in the C programming language, displays a disk device's structure level of determining ODS-2 against ODS-5.

//;
//;    Copyright 2001 Compaq Computer Corporation
//;
//;    Compaq and the Compaq logo Registered in U.S. Patent and Trademark Office.
//;
//;    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 vendors standard commercial license.
//;
//; Module:
//;     Determine_ODS_Level.C
//;
//; Abstract:
//;     Main (sole) module for a program to display the
//;     the on-disk structure level (e.g., ODS-2, ODS-5...)
//;     of a disk device, based on the ACP type identified
//;     by the SYS$GETDVI system service.
//;
//;     The device is identified by name, via the string
//;     deviceName, specified below.
//;
//;
//; To Build (OpenVMS/Alpha):
//;     CC   Determine_ODS_Level [/NODEBUG/OPTIMIZE]
//;     LINK Determine_ODS_Level [/NODEBUG]
//;     RUN  Determine_ODS_Level [/NODEBUG]
//;


//   Include (Header) Files
//
#include <descrip.h>                        // VMS descriptors...
#include <dvidef.h>                         // SYS$GETDVI() arguments
#include <lib$routines.h>                   // lib$signal()...
#define __NEW_STARLET 1                     // for built-in IOSB defn.
#include <starlet.h>                        // sys$getdvi()...
#include <iosbdef.h>                        // struct _iosb
#include <stdio.h>                          // printf()...
#include <string.h>                         // strlen()...


//   Structure Definitions
//
#pragma member_alignment save
#pragma nomember_alignment                   // structure members must be adjacent
typedef struct _item_list_3                  // sys$getdvi() item list (one entry)
    {
    unsigned short bufflen;
    unsigned short itemcode;
    unsigned long  *buffaddr;
    signed   long  *retlenaddr;
    unsigned int   terminator;
    } ITEM_LIST_3;
#pragma member_alignment restore


//   Main routine.
//
main()
    {
    static struct dsc$descriptor DevNameDesc; // descriptor for device name buffer references
    char deviceName[]="SYS$SYSDEVICE";  // device name string
    unsigned long ACP_typeBuffer;       // buffer for returned ACP type info. from sys$getdvi()
    long retLen;                        // buffer for returned info. length (4) from sys$getdvi()
    int status;                         // SYS$GETDVI() return status
    struct _iosb iosb;                  // I/O status block for SYS$GETDVI
    ITEM_LIST_3 DVI_itemList;           // item list for sys$getdvi()


    // Initialize the descriptor for the device name string.
    //
    DevNameDesc.dsc$w_length  = strlen(deviceName);
    DevNameDesc.dsc$a_pointer = &deviceName[0];


    // Initialize the item list to request ACP type information
    // from sys$getdvi().
    //
    DVI_itemList.bufflen    = sizeof(ACP_typeBuffer);
    DVI_itemList.itemcode   = DVI$_ACPTYPE;
    DVI_itemList.buffaddr   = &ACP_typeBuffer;
    DVI_itemList.retlenaddr = &retLen;
    DVI_itemList.terminator = 0;


    status = sys$getdviw(0,             // efn (not used)
                         0,             // channel (not used)
                         &DevNameDesc,  // device name (descriptor, by ref.)
                         &DVI_itemList, // item list (by ref.)
                         &iosb,         // I/O status block (by ref.)
                         0,             // astadr (not used)
                         0,             // astprm (not used)
                         0);            // nullarg (not used)


    if ((status & 1) == 1) status = iosb.iosb$w_status;// If the call succeeded, get the
                                                   //   status value from the queued request.
    if (status & 1)                                // If success...
        {
        switch(ACP_typeBuffer)
            {
            case DVI$C_ACP_F11V1:
                printf("On-disk structure level of disk device %s is 1\n",
                        deviceName);
                break;
            case DVI$C_ACP_F11V2:
                printf("On-disk structure level of disk device %s is 2\n",
                       deviceName);
                break;
            case DVI$C_ACP_F11V5:
                printf("On-disk structure level of disk device %s is 5\n",
                       deviceName);
                break;
            default:
                printf("Device %s is not of a recognized on-disk structure level\n",
                       deviceName);
                printf("...ACP type code is %8.8X\n",
                       ACP_typeBuffer);
                break;
            }                             // end of "switch(ACP_typeBuffer)"
        }                                 // end of "if (status & 1)"
    else                                  // Call or queued request failed;
        lib$signal(status);               //   signal exception.
    }                                     // end of "main()"

When you omit file specification components (except for the node name and root name), RMS supplies default values for the missing components. The file specification to which defaults are applied is called the primary file specification. Your program can supply default values for all file specification components using either the default file specification or the related file specification. In addition, the process executing the program supplies specific default values for device and directory components, via the process default specification.

Where applicable, RMS substitutes the translated logical name to the primary file specification before it applies default values. After translating the primary file specification, RMS applies the defaults from the default file specification, then it applies the defaults from the related file specification, if relevant. RMS then applies the process default values, where applicable, for the device and directory to obtain the full file specification it uses to locate the file.

For more information about the application of defaults, refer to Section 6.1.