A KeyedAccessRecordFile object represents a file opened for keyed access. The file is opened implicitly when the object is generated (see section "Opening and closing a file").
The KeyedAccessRecordFile class offers methods for reading, writing and deleting records in this file. There are also methods for handling keys and for closing the file.
The file that is to be opened must already exist in the underlying file system. The createNewFile() method of the RecordFile class must be used to generate a file.
When a file is opened for keyed access, the specific access direction can be restricted and deletion of the contents of an existing file can be requested.
The following open modes are permitted with this class:
INPUT
After the file has been opened only read operations are permitted.OUTIN
After the file has been opened both write and read operations are permitted. The entire file contents are deleted when the file is opened.INOUT
After the file has been opened both read and write operations are permitted. The file contents remain unchanged when the file is opened.
After the file has been closed the KeyedAccessRecordFile object should no longer be used.
Opening and closing a file
When a KeyedAccessRecordFile object is constructed, the file specified as RecordFile object is opened in the specified mode with the specified access method or with the specified access parameters.
The file must already exist in the underlying file system and the access method must belong to this file system and must be permissible for this file. The user must possess the necessary access rights to the file for the specified open mode. gegebenen Open-Modus erforderlichen Zugriffsrechte auf die Datei besitzen. If a Security Manager is active and its restrictions for this file conflict with the specified open mode, an exception is triggered (see section "Security").
If access parameters are specified for opening the file, these are taken into account when the file is opened provided the file parameters do not have priority. After the file has been opened, the parameters are updated with the corresponding values of the opened file.
The close() method closes the indexed-sequential file. Subsequently no I/O operations can be performed via this KeyedAccessRecordFile object.
Special features of the DMS file system
Shared update processing (see section "Shared update processing" and section "AccessParameter") of a KeyedAccessRecordFile is possible for all open modes (INPUT, INOUT, OUTIN). However, OUTIN open mode is permitted only for the application that opened the file first. If the file was opened in INPUT open mode, all accesses are made without locks. As a result, no access conflicts can arise. However, it must be expected that another application changes the contents of the record in the meantime. With the other open modes, read and write accesses are made with implicit locks. In the event of access conflicts, this can trigger a RecordLockedException or cause the thread or the entire application to wait, depending on the option set using setWaitMode(). Locks are released after writing or deleting the locked record. They can also be released explicitly using unlock(). When a record is read, an existing lock for another record is also released. Details are provided in the appropriate interface description in the shipped JAVADOC documentation.
Methods for reading records
All read methods are offered in two variants, one in which the record read is provided as a result in a newly generated Record object, and a second in which a Record object transferred by the calling program as an argument is filled with the data of the record read.
When a record buffer is created, it has precisely the same size as the data read. If the calling program provides the Record object, it must ensure that the record buffer is large enough to contain the data of the record to be read. If the specified record buffer is too small to contain all the data, an exception is triggered and no data is transferred.
With the read methods in which a KeyValue or KeyDescriptor object can be specified, such arguments are only accepted if they are suitable for the file (see the
getPrimaryKeydescriptor() and getSecondaryKeydescriptor() methods).
The read() methods read the record which is selected by the specified key value. If there is more than one record with the same key value in the file, the first one is returned. Both a value of the primary key and a value of the secondary key can be specified as the key value.
The readNext() methods read the next record in the order determined by the given argument. There are three variants of these methods:
If no order argument is specified, the next record defined by the order of the primary key is read. If this method is called as the first operation after a file has been opened, the record with the lowest available primary key value is read. In all other cases this operation reads the record following the last record read, provided the last record read was also read via the primary key (in other cases the behavior is access-method-specific). This is a method to permit sequential reading of records which contain the same key value.
If a key definition is specified as an order argument, the next record defined by the order of the primary or secondary key of the given key definition is read. If this method is called immediately after a file has been opened, the record with the lowest available key value as defined in the given key definition is read. In all other cases this operation reads the record following the last record read, provided the last record read was read via the same key definition (in other cases the behavior is access-method-specific). This is a method to permit sequential reading of records which contain the same key value.
If a key value is specified as an order argument, the record is read with the next highest key in accordance with the order of the associated key definition.
The readPrevious() methods read like the readNext() methods, but they read the preceding record rather than the following record.
Methods for writing and deleting records
When records are written to an indexed-sequential file, the position of a written record is determined by the key fields contained in the record.
The write() method writes a record to a file. If a file with the same primary key value already exists and no duplicate keys are permitted for the primary key, the existing record is replaced. If duplicate keys are permitted and the record already exists, the record is added after the last record with the same primary key value.
The writeNew() method writes a record to the file, but only if no record with the same primary key exists in the file.
The writeBack() method overwrites a record in the file that was read directly beforehand. Between the read and write operations, no modification may be made to the record’s primary key field. In shared update processing an existing record is not overwritten unless the lock set in order to read the record still applies. Otherwise, a RecordNotLockedException is triggered.
The delete() method deletes the record selected by the specified key value. If there are several records with the same key value in the file, the first one is deleted. Either a value of the primary key or a value of a secondary key can be specified as the key value.
Methods for unconditional lock release
The unlock() method is used to explicitly release a lock set implicitly by a read operation in shared update processing.
Methods for determining key definitions
The getPrimaryKeyDescriptor() method returns the key definition for the primary key of this file.
The getSecondaryKeyDescriptor() method returns the key definition for the secondary key with the specified name.
The getKeyDescriptorNames() method returns a list of the names of all of this file’s secondary keys.
Methods for generating and deleting secondary keys
The createSecondaryKey() methods generate a new secondary key for this indexedsequential file with the specified parameters. There are two parameter variants. One variant is that all fields of the KeyDescriptor object (name, key position, key length and the specification as to whether identical key values are permitted in different records for this key) are specified individually, and the second is that a KeyDescriptor object is specified for a secondary key. The second variant enables, for example, the attributes of another file’s secondary key to be used in order to generate a corresponding secondary key in this file.
The deleteSecondaryKey() method deletes the specified secondary key of this indexedsequential file.
The createSecondaryKey() and deleteSecondaryKey() methods require exclusive access to the file and are therefore not permitted in shared update processing. They would trigger an IOException.