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.
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.
In general, you should let the system specify values for the DATE
secondary attributes. The only secondary attribute you can routinely
specify is EXPIRATION.
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.
