Document revision date: 19 July 1999

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.

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.

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.

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.

	privacy and legal statement
4506PRO_013.HTML