A FileOutputRecordStream object represents a file that has been opened for sequential write access. The file is opened implicitly when the object is created (see section “Opening and closing a file” below).
The FileOutputRecordStream class offers methods for writing records and for closing the file. In a file opened for sequential write access, records are always added at the end.
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.
Opening and closing a file
When a FileOutputRecordStream object is constructed, the file specified as RecordFile object is opened in write mode with the specified access method or with the specified access parameters. Users can decide whether or not any content the file may have should be deleted when the file is opened.
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 access rights which permit writing. If a Security Manager is active and its restrictions mean that writing is not permitted for the file, 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 file. Subsequently no I/O operations can be performed via this FileOutputRecordStream object.
Special features of the DMS file system
Shared update processing (see section "Shared update processing" and section "AccessParameter") for a FileOutputRecordStream is only possible with the ISAM access method if an existing file is opened in order to add to it. Other applications cannot then also open the file as FileOutputRecordStream. You are generally advised not to use shared update processing in conjunction with FileOutputRecordStream. In exceptional cases, simultaneous opening as FileInputRecordStream may be useful.
Methods for writing records
The write() method writes a record after the last record in the file. A lock is implicitly requested when shared update processing is used. This can trigger a RecordLockedException or, depending on the option set with setWaitMode(), can cause the thread or the entire application to wait in the event of access conflicts. The lock is released after completion of the write operation.
The flush() method ensures that all the records written with write() are actually output into the file, even if the basic access method envisages buffering the outputs. An existing lock for this file is released if shared update processing is used.