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.