DEFINITION MODULE RandomIO;
(*
     Written by Dexter (Chip) Orange, July, 1987.

3227 Rain Valley Ct.
Tallahassee, FL.  32308

home: (904) 877-0061
Work: (904) 487-2680
Compuserve: 71450,1162





          Copyright (C) 1987, 1989, Dexter (Chip) Orange
All rights reserved.  The modules of the TurboFile system may not be
distributed, nor a discussion of the algorithms used there-in, in any way
without the express written permission of the copyright holder (Dexter
Orange).

     This module of the TurboFile system implements routines for doing very
 fast, sophisticated,
I/O to random access files with fixed-length records and optional file headers.
All I/O is buffered, and the larger the buffer, the faster things will go.

          Features Include:
     1.  Record size upto 64K
     2.  File size limitted only by available disk space
     3. The buffering of output records in such a way that groups of contiguous
records are identified, and written out together, to allow a more efficient
write access speed.
     4.  Optional file header record to store information relevant to the file



          Version 1.0,  September 1989.
Converted from TDI to M2Sprint.

*)


FROM SYSTEM IMPORT
  BYTE;

TYPE

  RandomFile;

  RandomFileMode = (ReadOnly, ReadWrite, NewFile, NewFileWriteOnly);
(* defines type of file to be opened.  ReadOnly is self-explanatory,
ReadWrite is for an existing file which will be opened for both reads and
 writes,
NewFile is for a new file to be created for both reads and writes,
and NewFileWriteOnly is for a new file to be created which will only be written
 to *)


  FileWriteAccessMode = (Random, Ascending, Sequential);
(* when  a file is opened with a RandomFileMode of other than ReadOnly,
this defines in what way writes will occur to that file.  The default is
Random, and can be changed through a call to SetWriteAccessMode (see its
description for an explanation of the various write modes *)



VAR
  RIOErrorMessage: ARRAY [0..80] OF CHAR;
(* contains the text of an error message when an error occurs *)





PROCEDURE OpenRandomFile (VAR File     : RandomFile; FileName : ARRAY OF CHAR;
mode         : RandomFileMode; RecSize      : CARDINAL; HeaderSize: CARDINAL;
BufferedBytes: LONGCARD) : BOOLEAN;
(* open (or create) a file for random access. *)
(* returns true if the open is successful *)
(* Note: If the mode is ReadWrite or NewFile, then the BufferedBytes are
divided into a read and a write buffer. *)


PROCEDURE CloseRandomFile (VAR File : RandomFile);
(* Flushes the write buffer (if any) and concludes access to a random file *)



PROCEDURE ReadRandomFile (File     : RandomFile; VAR data : ARRAY OF BYTE;
                                        (* Any type here *)
RecNum: LONGCARD) : BOOLEAN;
(* read a specific record from a random file *)
(* returns TRUE if successful. Number of bytes read is "RecSize", as specified
in the call to OpenRandomFile *)
(* Note that record numbers begin with 1, and do not include the header record
 *)


PROCEDURE ReadHeader (File     : RandomFile; VAR data : ARRAY OF BYTE)
                                        (* Any type here *)
: BOOLEAN;
(* read the file header from the beginning of the random file *)
(* returns TRUE if read successful.  Number of bytes read is "HeaderSize"
as specified in the call to OpenRandomFile *)


PROCEDURE WriteRandomFile (File    : RandomFile; VAR data : ARRAY OF BYTE;
                                        (* Any type here *)
RecNum: LONGCARD) : BOOLEAN;
(* write a specific record to the random file *)
(* returns TRUE if write successful.  Number of bytes written is "RecSize"
as specified in the call to OpenRandomFile *)
(* Note that the file can only be extended by writing a record with a record
number one greater than the current number of records in the file. *)


PROCEDURE WriteHeader ( File    : RandomFile; VAR data : ARRAY OF BYTE)
                                        (* Any type here *)
: BOOLEAN;
(* write the header record at the beginning of the file. *)
(* Note: if "HeaderSize" is not zero, a header record must be written before
any data records can be. *)
(* returns true if the write is successful.  Number of bytes written is
"headerSize" as specified in the call to OpenRandomFile *)


PROCEDURE NumRecs(File: RandomFile) : LONGCARD;
(* Determine number of records in file (excluding any header block) by using
the size of the file contained in the file info block *)



PROCEDURE Reset(File: RandomFile; RecSize: CARDINAL; HeaderSize: CARDINAL;
BufferedBytes: LONGCARD);
(* reset the "RecSize", "HeaderSize", and "BufferedBytes" parameters for
the given random file.  Causes read and write buffers to be flushed first.
Using this procedure you can read/write headers which are themselves composed
of more than a single record , or which
contain information (such as the record length) about the file itself.
*)


PROCEDURE SetWriteAccessMode(File: RandomFile; WriteAccessMode:
FileWriteAccessMode);
(* set the access mode that will be used for future writes to this file *)
(* Random gives the most flexibility, Ascending is faster if you can always
guarantee that the writes will go to records in asscending order, and Sequential
is the fastest, but writes must go in ascending consecutive order .
Note: This causes the write buffer to be flushed.
Note: Sequential or Ascending write access does not restrict in any way
you from reading the file randomly, and the writes do not need to begin with
record 1. *)
(* Sequential is particularly affective when you have a large number of records
to be appended to the end of a file. *)


END RandomIO.
