OpenVMS Record Management Utilities Reference Manual

Document revision date: 30 March 2001

OpenVMS Record Management Utilities Reference Manual

Contents

Index

The ALLOCATION attribute corresponds to the FAB$L_ALQ field.

ASYNCHRONOUS

This switch specifies asynchronous I/O operations. When you select this attribute, RMS returns control to your program as soon as an I/O operation begins. The switch is ignored for process-permanent files.

The ASYNCHRONOUS attribute corresponds to the ASY option in the RAB$L_ROP field.

BEST_TRY_CONTIGUOUS

This switch controls whether the file is to be allocated contiguously, assuming there is sufficient contiguous space for it. If you set the switch and there is not enough space, the system allocates the file noncontiguous space. If you take the default, no space is allocated.

The BEST_TRY_CONTIGUOUS attribute corresponds to the CBT option in the FAB$L_FOP field.

BUCKET_SIZE

This numeric attribute establishes the number of blocks per bucket. Its value must be an integer in the range 0 to 63. If you take the default (0), RMS computes the smallest bucket size capable of holding the largest record. Files processed by RMS--11 are limited to 32 blocks.

If you specify separate areas for the data level and the index levels, you must define separate bucket sizes for each file area; thus, the corresponding attribute in each AREA section overrides this related attribute in the FILE section.

The BUCKET_SIZE attribute corresponds to the FAB$B_BKS field.

CLUSTER_SIZE

This numeric attribute specifies the number of blocks allocated to a disk cluster. The disk cluster size can be established only when a disk volume is initialized.

The CLUSTER_SIZE attribute is output from the Analyze/RMS_File utility (ANALYZE/RMS_FILE), which returns the actual value of the disk cluster size to EDIT/FDL for use during an Optimize script.

CONTEXT

This numeric attribute contains a user-specified value 4 bytes long. RMS never uses the attribute for record management activities. It is intended solely for you to convey user information to a completion routine in your program.

The CONTEXT attribute corresponds to the FAB$L_CTX field.

CONTIGUOUS

This switch specifies that a file is allocated contiguous space.

If there is not enough contiguous space for the file's initial allocation, RMS returns an error.

If you take the default, the system allocates no space for the file.

This attribute corresponds to the CTG option in the FAB$L_FOP field.

CREATE_IF

This switch creates a file if the specified file does not already exist and, where applicable, RMS returns the alternate success status RMS$_CREATED to indicate that the file was created, not just opened. If the file exists, RMS opens it.

The CREATE_IF attribute is valid as input to the Create service only. It overrides the SUPERSEDE (supersede existing file) attribute and corresponds to the CIF option in the FAB$L_FOP field.

DEFAULT_NAME

This attribute takes a string value that defines portions of the file specification for the data file being created.

When a utility creates a data file from an FDL file, it first attempts to get the file specification from the calling process. If the call includes a full file specification, the utility ignores the DEFAULT_NAME and NAME attributes.

When a process supplies a partial file specification, the invoked utility tries to complete the file specification from the DEFAULT_NAME string. If the calling process does not specify a value for DEFAULT_NAME, the utility uses the RMS defaults.

If the calling process supplies a file specification by using the NAME attribute, the utility uses it. If the NAME attribute includes only a partial file specification, the utility uses it and examines the DEFAULT_NAME attribute for the rest of the file specification.

If the NAME and DEFAULT_NAME attributes together provide only a partial file specification, the utility uses RMS default values to complete the file specification.

For example, if you assign the value WRKD$:.KSM to DEFAULT_NAME, unless you specify otherwise, the created data file specification takes the device name WRKD$ and the file type .KSM.

The NAME and DEFAULT_NAME attributes correspond to the FAB$L_DNA and the FAB$B_DNS fields, respectively.

DEFERRED_WRITE

This switch specifies that the writing of modified I/O buffers to the file is deferred until that buffer is needed for other purposes. This attribute applies only to relative files, indexed files, and sequential files opened for shared access.

The DEFERRED_WRITE attribute corresponds to the DFW option in the FAB$L_FOP field. This attribute is not supported for DECnet for OpenVMS operations.

DELETE_ON_CLOSE

This switch specifies that the file is to be deleted after it is closed. If you select this attribute, you cannot create the file with either the Create/FDL utility or the FDL$CREATE routine because both open and then close the file. Therefore, the file will not exist long enough to be used. To create a file with the DELETE_ON_CLOSE attribute, you must use the FDL$PARSE routine.

The DELETE_ON_CLOSE attribute corresponds to the DLT option in the FAB$L_FOP field. The default is to ignore this attribute.

DIRECTORY_ENTRY

This switch specifies a temporary file created and retained with a directory entry. When you set this switch to NO, RMS retains the file but does not include it as a directory entry. To access the file, you must use its file identification number (FID).

The DIRECTORY_ENTRY attribute corresponds to the TMP option in the FAB$L_FOP field.

EXTENSION

This numeric attribute establishes the size, in blocks, of the file's default extension value. Each time the file is automatically extended, the specified number of blocks is added. The value for this attribute must be an integer in the range 0 to 65,535. When you take the default (0), the system determines the extension size.

The EXTENSION attribute corresponds to the FAB$W_DEQ field.

FILE_MONITORING

This switch enables RMS performance monitoring. It corresponds to the XABITM field XAB$_STAT_ENABLE and its default value is NO.

GLOBAL_BUFFER_COUNT

This numeric attribute specifies the number of global buffers allocated to the file. The value must be a number in the range 0 to 32,767; the default value is 0.

The GLOBAL_BUFFER_COUNT attribute corresponds to the FAB$W_GBC field. This attribute is not supported for DECnet for OpenVMS operations.

MAX_RECORD_NUMBER

This numeric attribute specifies the maximum number of records that can be placed in a relative file. The value must be an integer in the range 0 to 2,147,483,647. When you take the default value (0), you can place as many records as you want in the relative file, up to the maximum 2,147,483,647.

The MAX_RECORD_NUMBER attribute corresponds to the FAB$L_MRN field.

MAXIMIZE_VERSION

This switch specifies the file's version number. If you take the default, YES, the File Definition Language facility assigns the greater of two possible version numbers: either the number that was part of the file specification or a version number that is 1 higher than the highest existing version number.

When you set the switch to NO, assigning an explicit version number lower than an existing version results in creating a new data file with the lower version number. If you assign an explicit version number that matches an existing version, RMS returns an error.

The MAXIMUM_VERSION attribute corresponds to the MXV option in the FAB$L_FOP field.

MT_BLOCK_SIZE

This numeric attribute establishes the number of bytes in a magnetic tape file block. The value can be 0, an integer in the range 20 to 65,535 for ANSI-formatted tapes, or an integer in the range 14 to 65,532 for foreign tapes (tapes that are not in the standard ANSI format used by OpenVMS operating systems and that must be mounted by means of the DCL command MOUNT/FOREIGN). If you take the default value (0), RMS assigns the block size specified when the tape was mounted.

The MT_BLOCK_SIZE attribute corresponds to the FAB$W_BLS field.

MT_CLOSE_REWIND

This switch controls whether a magnetic tape volume is rewound when the file is closed. The magnetic tape volume does not rewind if you take the default (NO).

The MT_CLOSE_REWIND attribute corresponds to the RWC option in the FAB$L_FOP field.

MT_CURRENT_POSITION

This switch directs RMS to position the magnetic tape volume set immediately after the most recently closed file when it creates the next file. If you use this option when you invoke the $CREATE service, RMS overwrites all files located beyond the current tape position.

If you do not specify either of the position specifiers (MT_CURRENT_POSITION or MT_OPEN_REWIND), RMS creates the new file at the logical end of the tape. If you specify both position specifiers, the MT_OPEN_REWIND attribute overrides the MT_CURRENT_POSITION attribute.

The MT_CURRENT_POSITION attribute corresponds to the POS option in the FAB$B_FOP field.

MT_NOT_EOF

This switch prevents positioning the tape to the end of a file being opened with the PUT attribute specified.

This attribute corresponds to the NEF option in the FAB$L_FOP field.

MT_OPEN_REWIND

This switch specifies that the magnetic tape volume is to be rewound before the file is opened or created. If you use this option to create a tape file, RMS assumes that write operations are to take place at the beginning of the tape, rewinds the tape to the beginning, and proceeds to overwrite the tape data beginning with the first tape file.

Conversely, if you specify this attribute when you open an existing tape file, RMS rewinds to the beginning of the tape but then proceeds to find the specified file before doing any file operations.

Typically, a user specifies the MT_OPEN_REWIND option to improve efficiency in opening a tape file or to ensure access to the correct file when the tape contains files with duplicate names. ANSI tapes allow named files, but they have no directories and can contain repeated instances of files with the same name.

In the first case, assume the tape has 50 files, is positioned at the fortieth file, and the user wants to access the thirtieth file. If the user specifies MT_OPEN_REWIND to the Open service, RMS rewinds the tape to the first file and then winds the tape forward to the thirtieth file. If the user does not specify MT_OPEN_REWIND, RMS winds the tape forward to the end of the tape. Then, not having found the file, RMS rewinds the tape to the first file and proceeds to wind the tape forward to the thirtieth file.

In the second case, assume a tape has two files named X.DAT and is positioned between the two files. Assume further that the user wants to access the first file named X.DAT. If the user does not specify MT_OPEN_REWIND, RMS winds forward until it finds the second file and opens it, instead of opening the desired file. Conversely, if the user does specify MT_OPEN_REWIND, RMS rewinds the tape and then winds forward until it finds and opens the first file named X.DAT.

The MT_OPEN_REWIND option takes precedence over the MT_CURRENT_POSITION option and corresponds to the RWO option in the FAB$L_FOP field.

MT_PROTECTION

This single-character string attribute allows you to control access to a magnetic tape file. The default value is a space character that specifies access is not controlled. If the attribute is a non-space character, you can access the file only by specifying the /OVERRIDE=ACCESSIBILITY qualifier and option when you initialize or mount the volume.

This attribute corresponds to the XAB$B_MTACC field and is not supported for DECnet for OpenVMS operations.

NAME

This string attribute specifies the name of the data file to be created from this FDL file. If you supply a name for the data file, that name overrides the one specified here.

This attribute corresponds to the FAB$L_FNA and the FAB$B_FNS fields.

On Alpha systems, if you have implemented the on-disk-structure level 5 (ODS-5) volume structure of extended file specifications, you can name a file using the 8-bit ISO Latin-1 or 16-bit Unicode (UCS-2) character sets. You can also have a file name exceed the traditional 39.39 character limit to a maximum of 255 characters.

NON_FILE_STRUCTURED

This switch directs that the volume is to be processed in a manner that is not file structured. This attribute corresponds to the NFS option in the FAB$L_FOP field and is not supported for DECnet for OpenVMS operations.

ORGANIZATION

This keyword attribute specifies the file organization. Its value must be one of the following keywords:

SEQUENTIAL
RELATIVE
INDEXED

The default is SEQUENTIAL.

This attribute corresponds to the FAB$B_ORG field.

OUTPUT_FILE_PARSE

This switch specifies that the resultant file specification string, if used, is to provide directory, file name, and file type defaults only.

This attribute corresponds to the OFP option in the FAB$L_FOP field.

OWNER

This string attribute specifies the owner of the data file. The value must be the user identification code (UIC), in this form:

octal-group-number,octal-user-number

For example, OWNER [12,322] indicates that the person in group 12 with the user number 322 is the owner of the data file.

This attribute corresponds to the XAB$W_GRP and the XAB$W_MBM fields.

PRINT_ON_CLOSE

This switch controls whether the data file is to be spooled to the process default print queue when the file is closed, and applies to sequential files only. When you set the switch to YES, the data file is to be spooled to the process default print queue (SYS$PRINT) after the file is closed.

If you also set DELETE_ON_CLOSE to YES, the file is deleted after it is printed.

This attribute corresponds to the SPL option in the FAB$L_FOP field.

PROTECTION

This keyword attribute specifies file protection by defining the type of file access allowed for each of the four user classes:

System (S)
Owner (O)
Group (G)
World (W)

You define the access level for each user class by entering the appropriate access-level code as the argument for each user-class keyword. There are four access levels and you can assign one or more to each user class:

Read (R) access---lets the user read the file
Write (W) access---lets the user modify the file
Execute (E) access---lets the user run the file
Delete (D) access---lets the user delete the file

Each user class has a unique first letter (S, O, G, and W) and the same is true for each access level (R, W, E, and D). This lets you truncate the code for each user class if you prefer. Note that you must truncate the access level to the leading letter.

The syntax for encoding protection may take either of the following forms:

(SYSTEM=code,OWNER=code,GROUP=code,WORLD=code)

(SYSTEM:code,OWNER:code,GROUP:code,WORLD:code)

You must enclose the protection specification in parentheses and you have the option of using either the equal sign (=) or a colon (:) to separate each keyword from its associated code value.

By default, RMS assigns the file the default protection for the current process. To see the default protection for the current process, use the DCL command SHOW PROTECTION.

To deny a user class a specific access level, omit the access level from the code. To deny a user class all access levels, omit the user class keyword from the protection specification. For example, the following protection specification gives all access levels to user class System and user class Owner, read access to user class Group, and no access levels to user class World:

(System=RWED,Owner=RWED,Group=R)

This attribute corresponds to the XAB$W_PRO field.

READ_CHECK

This switch determines whether transfers from disk volumes are followed by read-compare operations.

When you activate the switch, transfers from disk volumes are followed by read-compare operations. This double check increases the likelihood that the system will catch data errors; however, it also increases disk overhead.

Activating this switch does not permanently mark the file for READ_CHECK; it merely selects a run-time option. To permanently mark the file for READ_CHECK, use the SET FILE/DATA_CHECK=READ command.

This attribute corresponds to the RCK option in the FAB$L_FOP field.

REVISION

This numeric attribute specifies the revision number of the data file as an integer in the range 0 to 65,535. Unless you want to change the revision number to some specific number, you should leave this value at its default of 0. When REVISION is set to 0, the file's revision number is incremented each time the file is opened for write access.

This attribute corresponds to the XAB$W_RVN field.

SEQUENTIAL_ONLY

This switch limits the file to sequential processing and related processing options. Any attempt at random access results in an error.

For DECnet for OpenVMS operations, this attribute enables file transfer mode, which is a data access protocol (DAP) feature that allows several records to be transferred in a single network operation. It maximizes throughput for single-direction, sequential-access file transfer.

This attribute corresponds to the SQO option in the FAB$L_FOP field.

STORED_SEMANTICS

Where applicable, this string attribute identifies the file semantics established when a file is created. The string is limited to 64 characters and the attribute corresponds to the XAB$_STORED_SEMANTICS field.

SUBMIT_ON_CLOSE

This switch submits the data file to the process default batch queue (SYS$BATCH) when the file is closed and is appropriate only for sequential command files.

If you also set DELETE_ON_CLOSE to YES, the file is deleted after the batch job completes.

This attribute corresponds to the SCF option in the FAB$L_FOP field and is not supported for DECnet for OpenVMS operations.

SUPERSEDE

This switch replaces the existing data file with a different file of the same name, type, and version.

If you successfully create a new file with the same name, type, and version as an existing file, the old file is deleted.

SUPERSEDE is overridden by the CREATE_IF attribute.

This attribute corresponds to the SCF option in the FAB$L_FOP field.

TEMPORARY

This creates a temporary file that is deleted when it is closed. No directory entry is created for a temporary file.

You cannot create a file that has this attribute by using the CREATE/FDL command or the FDL$CREATE routine, because these commands open and then close the data file before it can be used. You can only use the FDL$PARSE routine to create a file that has the TEMPORARY attribute.

This attribute corresponds to the TMD option in the FAB$L_FOP field.

TRUNCATE_ON_CLOSE

This switch deallocates unused space at the end of a sequential file when the file is closed.

This attribute corresponds to the TEF option in the FAB$L_FOP field.

USER_FILE_OPEN

This switch limits RMS operations to opening or creating a file. If you specify this option, you must also specify the SHARING USER_INTERLOCK attribute unless you have specified the SHARING PROHIBIT attribute.

This attribute corresponds to the UFO option in the FAB$L_FOP field and is not supported for DECnet for OpenVMS operations.

WINDOW_SIZE

This attribute specifies the number of retrieval windows (pointers) you want RMS to maintain in memory for your file. You can specify a numeric value in the range 0 to 127, or 255. A value of 0 indicates that RMS is to use the system default number of retrieval pointers. A value of 255 means to map the entire file, if possible. Values between 128 and 254, inclusive, are reserved for future use.

This attribute corresponds to the FAB$B_RTV field and is not supported for DECnet for OpenVMS operations.

WRITE_CHECK

This switch specifies that disk transfers are checked by a read-compare operation. Note, however, that this operation creates extra system overhead.

This switch does not permanently mark the file for WRITE_CHECK; it sets an RMS run-time option. You must use the SET FILE/DATA_CHECK=WRITE command to mark the file permanently.

This attribute corresponds to the WCK option in the FAB$L_FOP field.

4.8 KEY Section

The KEY primary attribute acts as a header for a section of the FDL file that describes keys. You must specify a separate KEY section for each key of an indexed file. The number of the key being described follows the word KEY (for example, KEY 0, KEY 1,...KEY n). The KEY value for the primary key must be 0. The KEY value for secondary keys can be numbered from 1 to 254.

The KEY primary attribute corresponds to the XAB$B_REF field.

The following table lists the KEY secondary attributes and their default values. Note that all KEY secondary attributes are create-time attributes.

Secondary Attribute Default Value

CHANGES NO

COLLATING_SEQUENCE None (only present for files with collated keys)

DATA_AREA None

DATA_FILL Same as bucket size

DATA_KEY_COMPRESSION YES

DATA_RECORD_COMPRESSION YES

DUPLICATES NO for primary; YES for alternate

INDEX_AREA None

INDEX_COMPRESSION YES

INDEX_FILL Same as bucket size

LENGTH None

LEVEL1_INDEX_AREA None

NAME Null-string

NULL_KEY NO

NULL_VALUE ASCII null character

POSITION None

PROLOG System or process default

SEGn_LENGTH None

SEGn_POSITION None

TYPE STRING

Secondary Attribute	Default Value
CHANGES	NO
COLLATING_SEQUENCE	None (only present for files with collated keys)
DATA_AREA	None
DATA_FILL	Same as bucket size
DATA_KEY_COMPRESSION	YES
DATA_RECORD_COMPRESSION	YES
DUPLICATES	NO for primary; YES for alternate
INDEX_AREA	None
INDEX_COMPRESSION	YES
INDEX_FILL	Same as bucket size
LENGTH	None
LEVEL1_INDEX_AREA	None
NAME	Null-string
NULL_KEY	NO
NULL_VALUE	ASCII null character
POSITION	None
PROLOG	System or process default
SEGn_LENGTH	None
SEGn_POSITION	None
TYPE	STRING

CHANGES
This switch allows an RMS Update operation to change the value of the key. Such a change is not allowed for the primary key (regardless of this attribute), so the default setting for primary keys is NO. With alternate keys the default setting is also NO, but you can specify YES to allow changes to alternate key values.
This attribute corresponds to the CHG option in the XAB$B_FLG field.
COLLATING_SEQUENCE
The name of the NCS collating sequence that defines the sorting order of the characters for this key. The value is a string from 1 to 31 characters long. You must supply the value; there is no default.
This attribute corresponds to the XAB$L_COLNAM field.
DATA_AREA
This numeric attribute identifies the area where you place the data records in an indexed file with multiple areas. The value is an integer in the range 0 to 254, which must be the same number as that assigned to the area in an AREA section.
The DATA_AREA, LEVEL1_INDEX_AREA, and INDEX_AREA values are used when the data level and the index levels are placed in separate areas or when each key is placed in its own area.
This attribute corresponds to the XAB$B_DAN field.
DATA_FILL
This attribute establishes the percentage of bytes in each data bucket in the area you want populated initially. If you anticipate that many records will be inserted randomly into the file, this value should be less than 100 percent of the bytes. The default value is 100 percent, and the minimum value is 50 percent. The /FILL_BUCKETS qualifier to the CONVERT command overrides this attribute.
This attribute corresponds to the XAB$W_DFL field except that XAB$W_DFL contains a byte count, not a percentage.
DATA_KEY_COMPRESSION
This switch compresses leading and trailing repeating characters in the primary key and its default value is YES. For compression to occur, your indexed file must be defined as a Prolog 3 file with the FDL attribute KEY PROLOG. However, KEY PROLOG 3 is the default.
This attribute corresponds to the KEY_NCMPR option in the XAB$B_FLG field, and should be set for DECnet for OpenVMS operations.
DATA_RECORD_COMPRESSION
This switch controls whether repeating characters are compressed in the data records. The default is YES; however, for compression to occur, your indexed file must be defined as a Prolog 3 file.

Previous Next Contents Index

privacy and legal statement

6027PRO_007.HTML