Document revision date: 19 July 1999

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.

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.

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

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