biagioni@unc.UUCP (Edoardo Biagioni) (11/06/86)
(***************************************************************************) (*** ***) (*** ***) (*** O S S I ***) (*** ========== ***) (*** ***) (**) DEFINITION MODULE SIRandomIO; (**) (*** ============================ ***) (*** ***) (*** This module defines an interface for record oriented file I/O ***) (*** ***) (***---------------------------------------------------------------------***) (*** ***) (*** Hardware: independent ***) (*** Operating System: UNIX BSD 4.2 ***) (*** Compiler: independent ***) (*** ***) (*** Version: 3.0 ***) (*** Implemented: see copyright ***) (*** Date: 1986-09-08 ***) (*** ***) (***---------------------------------------------------------------------***) (*** ***) (*** Copyright 1984, 1985, 1986 by ***) (*** E. S. Biagioni ***) (*** G. Heiser ***) (*** K. Hinrichs ***) (*** C. Muller ***) (*** ***) (*** Institut fuer Informatik ***) (*** ETH Zuerich ***) (*** CH 8092 Zuerich ***) (*** Switzerland ***) (*** ***) (*** Department of Computer Science ***) (*** University of North Carolina ***) (*** Chapel Hill, North Carolina 27514 ***) (*** U.S.A. ***) (*** ***) (*** Permission to copy without fee all of this material is granted ***) (*** provided that the copies are not made or distributed for direct ***) (*** commercial advantage, that this OSSI copyright notice is ***) (*** included in the copy, that the module is not modified in any way ***) (*** except where necessary for compilation on a particular system, ***) (*** and that the module is always distributed in its original form. ***) (*** Distribution of this module in a modified form without including ***) (*** the original version is a violation of this copyright notice. ***) (*** ***) (***---------------------------------------------------------------------***) (*** ***) (*** Updates: ***) (*** ***) (*** ***) (***************************************************************************) (* This module allows for record oriented random access I/O to files. In order to access the data of a file, a channel must be connected to it. This is done using the procedure ConnectChannel. After processing of the file's data is finished, the channel should be disconnected using DisconnectChannel. A channel left connected at program termination time is in an undefined state. Some data may be lost or corrupted. For handling of files as units, see the module SIFiles. DeleteFile may not be called for a file which is currently connected to a channel. If this is done, the result is undefined. Success or failure of an operation is indicated by a variable 'result'. After a successful operation, 'result' will be equal to 'SIDone', after an unsuccessful operation its value will be different from 'SIDone'. The possible result values are system dependent; the error message corresponding to a particular value can be obtained by a call to 'SMessage'. *) (* Remarks on the UNIX implementation: The following conventions hold for file names (as parameter to ConnectChannel): - a leading tilde character is replaced by the path name of the user's home directory - after making this substitution the name must be a valid UNIX path name. *) FROM SISystem IMPORT SIResult, BYTE; EXPORT QUALIFIED ChannelMode, Channel, ConnectChannel, DisconnectChannel, RReadRecord, RWriteRecord, Truncate, NumberOfLastEntry, RecordLength; TYPE ChannelMode = (channelRead, channelWrite, channelReadWrite); Channel; PROCEDURE ConnectChannel (VAR c: Channel; fileName: ARRAY OF CHAR; mode: ChannelMode; recordLength: CARDINAL; VAR result: SIResult); (* connects the channel c to the file named fileName. A new file is created if a file with fileName does not exist. The new file will store arbitrary records of fixed size recordLength bytes. This parameter is ignored if the channel connects to a file which has been created previously by a call to this procedure. The operation fails if the file exists, but has not been created by ConnectChannel. ConnectChannel may not be called if a channel is already connected to the specified file. If this is done, the result is undefined. After a succesful call of this procedure, the parameter 'c' can be used in the procedures that follow. *) PROCEDURE DisconnectChannel (VAR c: Channel; VAR result: SIResult); (* disconnects the channel from the file and closes the file. This procedure must be called for every opened file to avoid possible system errors. *) PROCEDURE RReadRecord (c: Channel; recordNumber: CARDINAL; VAR record: ARRAY OF BYTE; VAR result: SIResult); (* reads the record at position recordNumber in the file, and returns it in the parameter record. The record number of the first record in the file is 1. If the record has not previously been written the returned result may or may not reflect the fact, but in any case the value returned is undefined. If the size of record is less than recordLength declared for the file the record is truncated to fit. If the size of record is greater than recordLength declared for the file the value of the superfluous bytes is undefined. *) PROCEDURE RWriteRecord (c: Channel; recordNumber: CARDINAL; VAR record: ARRAY OF BYTE; VAR result: SIResult); (* writes the record to the given position in the file. The record number of the first record in the file is 1. The file is lengthened if necessary to accomodate the record. If the size of record is less than recordLength declared for the file the value of the missing bytes stored in the file is undefined. If the size of record is greater than recordLength declared for the file the record is truncated to fit. *) PROCEDURE Truncate (c: Channel; lastEntryNumber: CARDINAL; VAR result: SIResult); (* A call to this procedure ensures that the file contains no records with number greater than lastEntryNumber. After this call, NumberOfLastEntry will return lastEntryNumber. If lastEntryNumber is 0, the number of entries in the file becomes 0. *) PROCEDURE NumberOfLastEntry (c: Channel; VAR lastEntry: CARDINAL; VAR result: SIResult); (* lastEntry returns the number of the last entry in the file, or 0 if the file is empty. *) PROCEDURE RecordLength (c: Channel; VAR recordLength: CARDINAL; VAR result: SIResult); (* recordLength is the length in bytes of the records stored in the file. *) END SIRandomIO.