HP OpenVMS Systems Documentation
Content starts here

Guide to OpenVMS File Applications
Previous Contents Index

4.6 Summary of File-Creation Options

This section summarizes the file-creation options that are available using RMS. File-creation options may be available as qualifiers or keywords to the OPEN statement and include various aspects of file creation, including file disposition, file characteristics, file allocation, and file positioning.

Note that the run-time options for opening files in conjunction with creating files are not included here, but they are described in Chapter 9.

4.6.1 File-Creation Options

The following table lists the creation-time options that apply to specifying how an application uses a file:

Name of Option Function
Create-if Creates the file only if the directory does not contain a file with the same name. If a file with the same name exists in the directory, RMS opens the existing file instead of creating a new file.
  • FDL: FILE CREATE_IF
  • RMS: FAB$L_FOP FAB$V_CIF
Maximize version Creates the file with the specified version number or a version number one greater than a file of the same name in that directory.
  • FDL: FILE MAXIMIZE_VERSION
  • RMS: FAB$L_FOP FAB$V_MXV
Supersede version Supersedes the file with the same name, type, and version number in the current directory.
  • FDL: FILE SUPERSEDE
  • RMS: FAB$L_FOP FAB$V_SUP
Temporary Creates a temporary file (which has no directory entry) that is retained when the file is closed. The file can be accessed only if its internal file identifier is known (requires the use of a name block). Name blocks provide additional fields for extended file specifications.
  • FDL: FILE DIRECTORY_ENTRY
  • RMS: FAB$L_FOP FAB$V_TMP
Temporary, delete Creates a temporary file (which has no directory entry) marked for deletion. The file is deleted automatically when the file is closed.
  • FDL: FILE TEMPORARY
  • RMS: FAB$L_FOP FAB$V_TMD

4.6.2 File Characteristics

The creation-time options that define file characteristics are described in the following chart:

Name of Option Function
Block size Defines the number of bytes to be used in each block (unit of I/O) throughout the life of this file. This file characteristic applies only to magnetic tape files.
  • FDL: FILE MT_BLOCK_SIZE
  • RMS: FAB$W_BLS
Bucket size Defines the number of blocks to be used in each bucket (unit of I/O) throughout the life of this file. This file characteristic applies only to relative and indexed files.
  • FDL: FILE BUCKET_SIZE
  • RMS: FAB$B_BKS or XAB$B_BKZ
Date information Specifies the date and time values for file backup, file creation, file expiration, and file revision. Can also set the number of file revisions.
  • FDL: DATE attributes and
    FILE REVISION
  • RMS: Date and Time XAB fields
File organization Defines the file organization: sequential, relative, or indexed.
  • FDL: FILE ORGANIZATION
  • RMS: FAB$B_ORG
File protection Defines the file protection for the file being created.
  • FDL: FILE OWNER,
    FILE PROTECTION,
    FILE MT_PROTECTION
  • RMS: Protection XAB fields
Fixed-length control field size Defines the number of bytes in the fixed-length control field of a VFC record.
  • FDL: FILE CONTROL_FIELD_SIZE
  • RMS: FAB$B_FSZ
Key characteristics Defines the characteristics of a key in an indexed file, including key size, starting position, key type, bucket fill size, and key options.
  • FDL: KEY attributes
  • RMS: Key Definition XAB fields
Maximum record number Defines the maximum number of records for the file. Applies only to relative files.
  • FDL: FILE MAX_RECORD_NUMBER
  • RMS: FAB$L_MRN
Maximum record size Defines the maximum record size for all records in the file. Maximum record size refers to the size of all records in a file with fixed-length records, the size of the largest record with variable-length records, or the size of the variable-length portion of VFC records. A value of 0 with variable-length records means that there is no limit on the record size, except for magnetic tape files, for which a value of 0 sets an effective maximum record size equal to the block size minus 4. Variable-length records and VFC records must conform to certain physical limitations (see the OpenVMS Record Management Services Reference Manual).
  • FDL: RECORD SIZE
  • RMS: FAB$L_MRS
Record attributes Defines the following control information for each record:
  • Records can use one of the following carriage control conventions:
    • Each record is preceded by a line feed and terminated by a carriage return (FDL attribute RECORD CARRIAGE_RETURN). This is the default.
    • Each record contains a Fortran carriage return (FDL attribute RECORD FORTRAN).
    • Each record is in print format where the two-byte fixed-length control field (VFC record format) of each record contains the carriage return information (FDL attribute RECORD PRINT).
    • No carriage control provided (FDL attribute RECORD NONE).
  • Records can be prevented from crossing block boundaries (FDL attribute RECORD BLOCK_SPAN).
  • For variable-length records, the byte count field may be formatted in LSB (least-significant-byte) format (default) or in MSB (most-significant-byte) format (FDL attribute RECORD MSB_RECORD_LENGTH).
  • FDL: RECORD BLOCK_SPAN, RECORD MSB_RECORD_LENGTH
  • RMS: FAB$B_RAT
Record format Defines the record format:
  • Fixed-length record format
  • Variable-length record format
  • VFC record format
  • Stream record format
  • Undefined record format (sequential files only)
  • FDL: RECORD FORMAT
  • RMS: FAB$B_RFM

4.6.3 File Allocation and Positioning

You can specify file-allocation and positioning options with either the FAB control block or an allocation XAB (XABALL) control block. Note that any value specified in the XABALL control block overrides the corresponding value in the FAB. The creation-time options described in the following table apply to file allocation and positioning:

Name of Option Function
Allocation quantity Allocates the file or area using the number of blocks specified by this value, rounded up to the nearest even multiple of the volume's cluster size.
  • FDL: FILE ALLOCATION or
    AREA ALLOCATION
  • RMS: FAB$L_ALQ or
    XAB$L_ALQ
Areas Allocates the file using single or multiple areas. Applies only to indexed files; sequential and relative files are always contained in a single area. Indexed files can be placed in specific areas, for example, to separate the data area from the index area.
  • FDL: AREA number
  • RMS: XAB$B_AID
Contiguous Allocates the file or area using a single extent. If the disk's unallocated space does not permit the file to be allocated contiguously, an error is returned.
  • FDL: FILE CONTIGUOUS or
    AREA CONTIGUOUS
  • RMS: FAB$L_FOP FAB$V_CTG or
    XAB$L_AOP XAB$V_CTG
Contiguous best try Attempts to allocate the file or area using a minimum number of extents. If the file cannot be allocated contiguously, an error is not returned.
  • FDL: FILE BEST_TRY_CONTIGUOUS or
    AREA BEST_TRY_CONTIGUOUS
  • RMS: FAB$L_FOP FAB$V_CBT or
    XAB$L_AOP XAB$V_CBT
Cylinder boundary Allocates the file or area at the beginning of a cylinder boundary.
  • FDL: AREA POSITION
    ANY_CYLINDER
  • RMS: XAB$B_AOP XAB$V_ONC
Cylinder position Positions the file or area at the beginning of the specified cylinder number.
  • FDL: AREA POSITION CYLINDER
  • RMS: XAB$B_ALN XAB$V_CYL and
    XAB$L_LOC
Default extension Defines the minimum number of blocks for a file extension (extent) when additional disk space is needed. For the Edit/FDL utility file extension sizes, see Appendix A.
  • FDL: FILE EXTENSION
  • RMS: FAB$W_DEQ or
    XAB$W_DEQ
Hard positioning Directs OpenVMS RMS to return an error if the requested file or area positioning or alignment cannot be performed.
  • FDL: AREA EXACT_POSITIONING
  • RMS: XAB$B_AOP XAB$V_HRD
Logical block
position 		Positions the file or area at the beginning of the specified logical block.
  • FDL: AREA POSITION LOGICAL
  • RMS: XAB$B_ALN XAB$V_LBN and
    XAB$L_LOC
Related file
position 		Positions the file or area as close as possible to a related file, at the specified virtual block.
  • FDL: AREA POSITION FILE_ID or
    AREA POSITON FILE_NAME
  • RMS: XAB$B_ALN XAB$V_RFI and
    XAB$L_LOC
Virtual block
position 		Positions the file or area at the beginning of the specified virtual block.
  • FDL: AREA POSITION VIRTUAL
  • RMS: XAB$B_ALN XAB$V_VBN and
    XAB$L_LOC
Truncate end of file Truncates a nonshared sequential file at its logical end to release the space between the logical end of the file (end of file data) and the physical end of the file (allocated file space) for other use.
  • FDL: FILE_TRUNCATE_ON_CLOSE
  • RMS: FAB$V_TEF
Volume number Indicates the volume set where the file or area is placed when it is created.
  • FDL: AREA VOLUME
  • RMS: XAB$W_VOL

For the list of the run-time options that are common to creating and opening a file, see Chapter 9.

For more information about the options listed above, see Chapter 2. For more detailed information about the programming aspects of these options, refer to the OpenVMS Record Management Services Reference Manual.

Chapter 5
Locating and Naming Files on Disks

When creating or opening a file, your program must identify it with an appropriate file specification. Typically, high-level languages require a file specification argument for an OPEN statement that names a file being created or locates a file being opened.

The most direct way for an application to provide a file specification is to accept a complete specification from the user and to pass it to the OPEN statement.

Another way is to have the application program supply specifications to RMS so that RMS can combine these, as defaults, with a partial user specification to compose a fully qualified file specification. Or, to have RMS resolve a partial specification by searching the disk for an existing file that matches the specification.

This chapter describes the components that make up a complete file specification and how RMS is used to name and locate files on disks. Chapter 6 describes in more detail the process that RMS uses to compose fully qualified file specifications from user input and from application input.

Note
This chapter documents file specifications as presented at the RMS interface such as RMS services SYS$OPEN and SYS$SEARCH. For details on specifications at the ACP-XQP interface, such as the system service SYS$QIO, refer to the OpenVMS I/O User's Reference Manual.

As of OpenVMS V7.2, RMS on Alpha systems has been extended to support disk file specifications of greater length and with a larger character set than was supported on prior versions and than is supported on VAX platforms. Some of the extended features can be used on existing ODS-2 structure-level disks. Many features are available only on ODS-5 structure-level disks. Throughout this chapter, behaviors that differ depending upon the architecture, Alpha or VAX, or upon the target device, ODS-5 disk or ODS-2 disk, are so marked in the text.

5.1 Understanding Disk File Specifications

A disk file specification on an OpenVMS system consists of up to seven components, several of which assume default values when they are not specified. To allow RMS to identify the boundaries of each component, certain characters separate the components in a file specification. These characters mark the beginning or the end of a file specification component and allow RMS to identify missing components for which defaults can be substituted. A complete file specification takes the following form:


node::device:[root.][directory-name]filename.type;version

The following table lists the characters that separate components of a file specification:

Component Separator Character(s)
Node Double colon (::) ends a node name.
Device Single colon (:) ends a device name.
Root Square brackets ([]) or angle brackets (<>) delimit the root name. Within the root component, a period (.) separates subdirectory names. A period (.) before the closing bracket distinguishes a root component from a directory.
Directory Square brackets ([]) or angle brackets (<>) delimit the directory name. Within the directory component, a period (.) separates subdirectory names.
File Name The rightmost period (.) that is not the version delimiter begins the type component and ends the file name.
File Type The rightmost period (.) that is not the version delimiter begins the type component. A version delimiter ends the type component.
File Version Period (.) or semicolon (;) followed by legal version characters begins the version. Section 5.2.7 describes a legal version component. The end of the file specification ends the file version.

Some examples of valid file specifications follow: 


DISK1:[MYROOT.][MYDIR]FILE.DAT
DISK1:[MYDIR]FILE.DAT
[MYDIR]FILE.DAT
FILE.DAT;10
NODE::DISK5:[REMOTE.ACCESS]FILE.DAT

5.2 File Specification Components

The following sections describe the particular file specification components.

5.2.1 The Node Component

Whether or not you should include the optional node component in a file specification depends on whether you confine file activity to the local node, or you conduct file activity on remote nodes. To locate a file on the local node, or in an OpenVMS Cluster environment, you do not have to include the node name in the file specification.

Note
In this chapter, discussions that refer to OpenVMS Cluster environments apply to both VAXcluster systems that include only VAX nodes and OpenVMS Cluster systems that include at least one Alpha node unless indicated otherwise.

Conversely, to locate a file on a remote node, you must present the name of the remote node either as the physical node name or as a logical name whose translation contains the physical node name. A logical node name can also contain access control information used to log in to the remote system.

5.2.1.1 Local Node

The following file specification format does not include a node name:


device:[root.][directory-name]filename.type;version

This is the general format of a file specification used to locate a file on the local node, or in an OpenVMS Cluster.

Note that a null node name of the form "::" specifies the local node; this form overrides any default node names.

5.2.1.2 Remote Node

The following file specification formats are used for accessing files on remote nodes:


node::filespec


node"access-control-string"::filespec

The second file specification format includes an access control string. If an access control string is specified or if the process seeking to gain access to a remote file has a proxy login account on the remote node, the specified remote process uses its access rights to locate the file. If an access control string is not specified and a proxy account does not exist on the remote system, the local process may use the default DECnet account, if there is one, to locate the file.

The following file specification format, known as a foreign file specification, is used to locate files on remote nodes that might have file specification formats that differ from those of the local node:


node::"foreign-filespec"

The only action RMS takes with the foreign file specification is to translate the logical node name, if applicable. This format is especially useful when the remote system is not an OpenVMS system and the file specification does not conform to OpenVMS file specification syntax conventions. Refer to the DECnet for OpenVMS Networking Manual for more information.

The following file specification format does not specify a file directly. Instead, it specifies a task on the remote system.


node::"task-spec-string"

For more information about specifying a logical node name or using any of the file specification formats and their associated syntax rules, refer to the OpenVMS User's Manual.

Previous Next Contents Index