Document revision date: 30 March 2001

## OpenVMS Record Management Utilities Reference Manual

Previous | Contents | Index

## 4.5 CONNECT Section

The CONNECT section specifies application-dependent run-time attributes related to record access and performance. The CONNECT keyword takes no values; it serves only to define this section. The following table lists the CONNECT secondary attributes. Note that all CONNECT secondary attributes are run-time attributes.

Secondary Attribute | Default Value
--- | ---
ASYNCHRONOUS | None
BLOCK_IO | None
BUCKET_IO | None
CONTEXT | None
END_OF_FILE | None
FAST_DELETE | None
FILL_BUCKETS | None
KEY_GREATER_EQUAL | None
KEY_GREATER_THAN | None
KEY_LIMIT | None
KEY_OF_REFERENCE | None
LOCATE_MODE | None
LOCK_ON_READ | None
LOCK_ON_WRITE | None
MANUAL_UNLOCKING | None
MULTIBLOCK_COUNT | None
MULTIBUFFER_COUNT | None
NOLOCK | None
NONEXISTENT_RECORD | None
READ_AHEAD | None
READ_REGARDLESS | None
TIMEOUT_ENABLE | None
TIMEOUT_PERIOD | None
TRUNCATE_ON_PUT | None
TT_CANCEL_CONTROL_O | None
TT_PROMPT | None
TT_PURGE_TYPE_AHEAD | None
TT_READ_NOECHO | None
TT_READ_NOFILTER | None
TT_UPCASE_INPUT | None
UPDATE_IF | None
WAIT_FOR_RECORD | None
WRITE_BEHIND | None

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

> #### BLOCK_IO

> This switch determines whether block or record I/O operations are performed. If you set the switch to YES, only block operations are permitted. If you set the switch to NO, only record operations are allowed for relative and indexed files. However, if you specify the ACCESS section RECORD_IO attribute, mixed block and record operations may be performed on sequential files only.

> The BLOCK_IO attribute corresponds to the BIO option in the RAB$L_ROP field.

> #### BUCKET_IO

> This numeric attribute specifies a relative record number or a numeric value representing the virtual block number to be accessed. You use this attribute with records in a relative file or when you want block I/O to be performed.

> The BUCKET_IO attribute corresponds to the RAB$L_BKT field.

> #### CONTEXT

> You can use this attribute to specify any numeric value, up to 4 bytes in length. RMS does not use the CONTEXT attribute; it is provided exclusively for your use. For example, you could use it to communicate with a completion routine in your program.

> The CONTEXT attribute corresponds to the RAB$L_CTX field.

> #### END_OF_FILE

> This switch directs RMS to connect to the end of the file.

> The END_OF_FILE attribute corresponds to the EOF option in the RAB$L_ROP field.

> #### FAST_DELETE

> This switch directs RMS not to delete the alternate index pointers used for duplicate records when you delete a record. Instead, RMS deletes the pointers and generates an appropriate error message only when you subsequently attempt to access the deleted record. The FAST_DELETE attribute avoids the overhead usually involved with RMS record deletions---updating the data level, the primary index, and then the alternate indexes.

> The FAST_DELETE attribute corresponds to the FDL option in the RAB$L_ROP field.

> #### FILL_BUCKETS

> This switch directs RMS to load buckets according to the fill size established at file-creation time. If you do not set the switch, RMS ignores the established bucket fill size and fills buckets completely.

> The FILL_BUCKET attribute corresponds to the LOA option in the RAB$L_ROP field.

> #### KEY_GREATER_EQUAL

> When using an ascending data type, this switch directs RMS to access the first record in an indexed file containing a key of reference value greater than or equal to the value described by the RAB$L_KBF and RAB$B_KSZ fields. For a descending data type, RMS accesses the first record that contains a key of reference value less than or equal to the value described by the RAB$L_KBF and RAB$B_KSZ fields.

> If you set neither this switch nor the KEY_GREATER_THAN switch, RMS accesses the first record that contains a key of reference value equal to the value described by the RAB$L_KBF and RAB$B_KSZ fields.

> This attribute corresponds to the KGE option in the RAB$L_ROP field. For more information about the RAB$L_KBF and RAB$B_KSZ fields, refer to the OpenVMS Record Management Services Reference Manual.

> #### KEY_GREATER_THAN

> When using an ascending data type, this switch directs RMS to access the first record in an indexed file containing a key of reference value greater than the value described by the RAB$L_KBF and RAB$B_KSZ fields. When using a descending data type, the switch directs RMS to access the first record that contains a key of reference value less than that specified in the RAB$L_KBF and RAB$B_KSZ fields.

> If you set neither this switch nor the KEY_GREATER_EQUAL switch, RMS accesses the first record that contains a key of reference value equal to the value described by the RAB$L_KBF and RAB$B_KSZ fields.

> The KEY_GREATER_THAN attribute corresponds to the KGT option in the RAB$L_ROP field. For more information about the RAB$L_KBF and RAB$B_KSZ fields, refer to the OpenVMS Record Management Services Reference Manual.

> #### KEY_LIMIT

> This switch directs RMS to compare the key value described by the RAB$L_KBF and RAB$B_KSZ fields to the value in the record accessed in sequential mode. If you set this switch and the record's key value is greater than the limit key value, RMS returns the RMS$_OK_LIM status code.

> This attribute corresponds to the LIM option in the RAB$L_ROP field.

> #### KEY_OF_REFERENCE

> This numeric attribute specifies the key or index (such as primary, or first alternate) by which you want to process records in a file. The default value, 0, indicates the primary key. Values 1 to 254 indicate alternate keys.

> The KEY_OF_REFERENCE attribute applies only to indexed files and it corresponds to the RAB$B_KRF field.

> #### LOCATE_MODE

> This switch directs RMS to return records by supplying a pointer to the data rather than by copying the data to the user buffer.

> The LOCATE_MODE attribute corresponds to the LOC option in the RAB$L_ROP field.

> #### LOCK_ON_READ

> This switch permits a process reading a record to prohibit other processes from modifying the record.

> The LOCK_ON_WRITE attribute takes precedence over the LOCK_ON_READ attribute, and the NOLOCK attribute takes precedence over both.

> The LOCK_ON_READ attribute corresponds to the REA option in the RAB$L_ROP field.

> #### LOCK_ON_WRITE

> This switch permits a process to allow other processes to read a record that it is modifying.

> The LOCK_ON_WRITE attribute takes precedence over the LOCK_ON_READ attribute, and the NOLOCK attribute takes precedence over both.

> The LOCK_ON_WRITE attribute corresponds to the RLK option in the RAB$L_ROP field.

> #### MANUAL_UNLOCKING

> This switch prohibits RMS from unlocking records automatically. Instead, after a record is locked by a Get, Find, or Put operation, RMS must use a Free or Release operation to explicitly unlock the record.

> The NOLOCK attribute takes precedence over the MANUAL_UNLOCKING attribute and corresponds to the ULK option in the RAB$L_ROP field.

> #### MULTIBLOCK_COUNT

> This numeric attribute permits a process that is accessing a sequential disk file to specify the number of blocks, in the range 0 to 127, allocated to each I/O buffer.

> The MULTIBLOCK_COUNT attribute optimizes data throughput for sequential operations, and it does not affect the structure of the file. It reduces the number of times you have to access the disk for record operations, thereby reducing execution time. However, the extra buffering increases memory requirements.

> If you do not specify this attribute or if you specify the value 0, RMS uses the process default for the multiblock count. If the process default is 0, RMS uses the system default. If the system default is 0, the default size for each I/O buffer is one block. Use the DCL command SET RMS_DEFAULT to establish process or system defaults.

> The MULTIBLOCK_COUNT attribute corresponds to the RAB$B_MBC field and is not supported for DECnet for OpenVMS operations.

> #### MULTIBUFFER_COUNT

> This numeric attribute specifies the number of buffers, in the range 0 to 127, to be allocated at connect time.

> If you do not select this attribute or if you use the value 0, RMS uses the process default for the particular file organization and device type. If the process default is 0, the system default for the particular file organization and device type applies.

> If the system default is likewise 0, one buffer is allocated. However, if you specify either the READ_AHEAD attribute or the WRITE_BEHIND attribute, RMS allocates at least two buffers. Similarly, RMS allocates a minimum of two buffers for an indexed sequential file or for a process-permanent file.

> The MULTIBUFFER_COUNT attribute corresponds to the RAB$B_MBF field and is not supported for DECnet for OpenVMS operations.

> #### NOLOCK

> This switch specifies that the record accessed through a Get or Find operation is not to be locked. The NOLOCK attribute takes precedence over all other attributes that control record locking, such as MANUAL_UNLOCKING, LOCK_ON_READ, and LOCK_ON_WRITE.

> The NOLOCK attribute corresponds to the NLK option in the RAB$L_ROP field.

> #### NONEXISTENT_RECORD

> This switch specifies that if a record randomly accessed with a Get or Find RMS operation does not exist (was never inserted into the file or was deleted), it is to be processed anyway, locking the record cell if necessary.

> The NONEXISTENT_RECORD attribute does not apply to indexed files, and it corresponds to the NXR option in the RAB$L_ROP field.

> #### READ_AHEAD

> This switch is used with multiple buffers (see MULTIBUFFER_COUNT) to indicate read-ahead operations. It directs the system not to wait for I/O completion because input and computing can overlap. That is, when one buffer is filled, the next record is read into a second buffer while I/O operations take place in the first buffer.

> If you specify READ_AHEAD when the multibuffer count is 0, two buffers are allocated to allow multibuffering. If you specify two or more buffers, multibuffering is allowed regardless. However, if you specify a buffer count of 1, multibuffering is disabled.

> The READ_AHEAD attribute applies only to sequential file processing and is ignored for unit record device I/O. This attribute corresponds to the RAH option in the RAB$L_ROP field and is not supported for DECnet for OpenVMS operations.

> #### READ_REGARDLESS

> This switch permits you to read a record even if it is locked, allowing some control over access. If a record is locked against all access and you request a Find or Get RMS operation, RMS returns the record anyway.

> The READ_REGARDLESS attribute corresponds to the RRL option in the RAB$L_ROP field.

> #### TIMEOUT_ENABLE

> This numeric attribute specifies the maximum time value, in seconds, allowed for a record input wait caused by a locked record when you specify the WAIT_FOR_RECORD attribute. This attribute also applies to the time allowed for a character to be received during terminal input. If the timeout period expires, RMS returns an error status.

> The TIMEOUT_ENABLE attribute also serves a special purpose for mailbox devices. If you specify this attribute with a TIMEOUT_PERIOD of 0, Get and Put RMS operations to mailbox devices use the IO$M_NOW modifier. The operation then completes immediately instead of synchronizing with another cooperating writer or reader of the mailbox. See the OpenVMS I/O User's Reference Manual for a further discussion of mailboxes.

> The TIMEOUT_ENABLE attribute corresponds to the TMO option in the RAB$L_ROP field and is not supported for DECnet for OpenVMS operations.

> #### TIMEOUT_PERIOD

> This numeric attribute specifies the maximum duration, in seconds (0 to 255), of a Get operation. If the user specifies a Get operation from the terminal and the attribute value is 0, RMS does not return the current contents of the type-ahead buffer.

> You can use this attribute only with the TIMEOUT_ENABLE attribute. It corresponds to the RAB$B_TMO field and is not supported for DECnet for OpenVMS operations.

> #### TRUNCATE_ON_PUT

> This switch permits a Put or Write operation at any point in a file, truncating the file at that point. A Write operation causes the end-of-file (EOF) mark to immediately follow the last byte written.

> TRUNCATE_ON_PUT can only be used with sequential files. It corresponds to the TPT option in the RAB$L_ROP field.

> #### TT_CANCEL_CONTROL_O

> This switch ensures that terminal output is not discarded if you press Ctrl/O. It corresponds to the CCO option in the RAB$L_ROP field and is not supported for DECnet for OpenVMS operations.

> #### TT_PROMPT

> This switch specifies that the contents of the prompt buffer be used as a prompt on a terminal-read operation.

> It corresponds to the PMT option in the RAB$L_ROP field and is not supported for DECnet for OpenVMS operations.

> #### TT_PURGE_TYPE_AHEAD

> This switch eliminates any information that might be in the type-ahead buffer on a terminal-read operation. The TT_PURGE_TYPE_AHEAD attribute corresponds to the PTA option in the RAB$L_ROP field and is not supported for DECnet for OpenVMS operations.

> #### TT_READ_NOECHO

> This switch specifies that input data is not to be echoed (displayed) on the terminal as it is entered on the keyboard. The TT_READ_NOECHO attribute corresponds to the RNE option in the RAB$L_ROP field and is not supported for DECnet for OpenVMS operations.

> #### TT_READ_NOFILTER

> This switch specifies that the Ctrl/U, Ctrl/R, and Delete keys are not to be considered control commands from the terminal but are to be passed to the user program.

> The TT_READ_NOFILTER attribute corresponds to the RNF option in the RAB$L_ROP field and is not supported for DECnet for OpenVMS operations.

> #### TT_UPCASE_INPUT

> This switch changes lowercase characters read from a terminal to uppercase. The TT_UPCASE_INPUT attribute corresponds to the CVT option in the RAB$L_ROP field and is not supported for DECnet for OpenVMS operations.

> #### UPDATE_IF

> This switch specifies that a Put operation for a record that already exists is converted to an Update operation. This attribute is necessary to overwrite (as opposed to update) an existing record in relative and indexed sequential files.

> Indexed files using UPDATE_IF must not allow duplicates on the primary key.

> The UPDATE_IF attribute corresponds to the UIF option in the RAB$L_ROP field.

> #### WAIT_FOR_RECORD

> This switch directs RMS to wait for a currently locked record until it becomes available. You can use this attribute with the TIMEOUT_ENABLE and TIMEOUT_PERIOD attributes to limit waiting periods to a specified time.

> The WAIT_FOR_RECORD attribute corresponds to the WAT option in the RAB$L_ROP field.

> #### WRITE_BEHIND

> This switch is used with multiple buffers (see MULTIBUFFER_COUNT) to specify write-behind operations. It directs the system not to wait for I/O completion because computing and output can overlap. When one buffer is filled, the next record is written into a second buffer while the I/O operation takes place for the first buffer.

> If you specify WRITE_BEHIND when the multibuffer count is 0, two buffers are allocated to allow multibuffering. If you specify two or more buffers, multibuffering is allowed regardless. However, if you specify a buffer count of 1, multibuffering is disabled.

> The WRITE_BEHIND attribute applies to sequential file processing only and is ignored for unit record device I/O. This attribute is not supported for DECnet for OpenVMS operations.

> This attribute corresponds to the WBH option in the RAB$L_ROP field.

## 4.6 DATE Section

The DATE section allows you to specify dates and times for various file characteristics. The DATE keyword takes no values; it serves only to define this section. The following table lists the DATE secondary attributes and their default values. Note that all DATE secondary attributes are create-time attributes.

Secondary Attribute | Default Value
--- | ---
BACKUP | Null-string
CREATION | Null-string
EXPIRATION | Null-string
REVISION | Null-string

In general, you should let the system specify values for the DATE secondary attributes. The only secondary attribute you can routinely specify is EXPIRATION.

> #### BACKUP

> This string indicates the date when the file was last backed up. It must use the following syntax:

> `dd-mmm-yyyy hh:mm:ss.cc.`

> The BACKUP attribute corresponds to the XAB$Q_BDT field.

> #### CREATION

> This string indicates the date and time when the file was created. It uses the following syntax:

> `dd-mmm-yyyy hh:mm:ss.cc.`

> The CREATION attribute corresponds to the XAB$Q_CDT field.

> #### EXPIRATION

> This string indicates the earliest date and time a disk file can be deleted. For magnetic tape files, the EXPIRATION attribute establishes the date and time when you can overwrite the file. It uses the following syntax:

> `dd-mmm-yyyy hh:mm:ss:cc.`

> The EXPIRATION attribute corresponds to the XAB$Q_EDT field.

> #### REVISION

> This string indicates the date of the last modification to the data file. It uses the following syntax:

> `dd-mmm-yyyy hh:mm:ss.cc.`

> The REVISION attribute corresponds to the XAB$Q_RDT field.

## 4.7 FILE Section

The FILE section allows you to specify file processing and file-related characteristics for your file. The FILE keyword takes no values; it serves only to define this section.

FILE section attributes (ALLOCATION, BEST_TRY_CONTIGUOUS, BUCKET_SIZE, CONTIGUOUS, and EXTENSION) have corresponding AREA section attributes. Values you specify for these attributes in the AREA section override associated values that you specify in the FILE section.

The following table lists the FILE secondary attributes and their default values. It also specifies whether each attribute is a create-time attribute or a run-time attribute.

Secondary Attribute | Default Value | Attribute Type
--- | --- | ---
ALLOCATION | 0 | Create-time
ASYNCHRONOUS | NO | Run-time
BEST_TRY_CONTIGUOUS | NO | Create-time
BUCKET_SIZE | 0 | Create-time
CLUSTER_SIZE 1 | See note | See note
CONTEXT | 0 | Run-time
CONTIGUOUS | NO | Create-time
CREATE_IF | NO | Run-time
DEFAULT_NAME | Null-string | Run-time
DEFERRED_WRITE | NO | Run-time
DELETE_ON_CLOSE | NO | Run-time
DIRECTORY_ENTRY | YES | Run-time
EXTENSION | 0 | Create-time
FILE_MONITORING | NO | Create-time
GLOBAL_BUFFER_COUNT | 0 | Create-time
MAX_RECORD_NUMBER | 0 | Create-time
MAXIMIZE_VERSION | YES | Run-time
MT_BLOCK_SIZE | 0 | Create-time
MT_CLOSE_REWIND | NO | Run-time
MT_CURRENT_POSITION | NO | Run-time
MT_NOT_EOF | NO | Run-time
MT_OPEN_REWIND | NO | Run-time
MT_PROTECTION | Space character | Create-time
NAME | Null-string | Create-time
NON_FILE_STRUCTURED | NO | Run-time
ORGANIZATION | SEQUENTIAL | Create-time
OUTPUT_FILE_PARSE | NO | Run-time
OWNER | System or process default | Create-time
PRINT_ON_CLOSE | NO | Run-time
PROTECTION | System or process default | Create-time
READ_CHECK | NO | Run-time
REVISION | 0 | Create-time
SEQUENTIAL_ONLY | NO | Run-time
STORED_SEMANTICS | None | Create-time
SUBMIT_ON_CLOSE | NO | Run-time
SUPERSEDE | NO | Run-time
TEMPORARY | NO | Run-time
TRUNCATE_ON_CLOSE | NO | Run-time
USER_FILE_OPEN | NO | Run-time
WINDOW_SIZE | Volume default | Run-time
WRITE_CHECK | NO | Run-time

1The bucket size attribute is available only following file analysis. The default value is the same as the disk cluster size of the analyzed file.

> #### ALLOCATION

> This numeric attribute establishes the number initially allocated to the file. The value must be an integer in the range 0 to 4,294,967,295. If you take the default (0), the system allocates no initial space for the file.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 6027PRO_006.HTML