DEFINITION MODULE files;

 (* files is a structured file package that offers a high level of
    abstraction and a simple user interface.  Each file defined in
    files is limited to 65535 elements, where an element can be
    either a user defined data structure or one of the scalar types. *)


   FROM SYSTEM IMPORT
    (* type *) BYTE;


   EXPORT QUALIFIED
    (* type *) filetype,
    (* proc *) openf, closef, readf, writef, setposf, getposf,
               resetf, rewritef, atendf, resultf;


 TYPE
   filetype;



 PROCEDURE openf (VAR file : filetype;     (* out *)
                  elemsize : CARDINAL;     (* in *)
                  filename : ARRAY OF CHAR (* in  *));

  (* Will open the file on disk identified as 'filename' (may include
     a path).  If the file does not exist it will be created,
     otherwise the file pointer is set to the first element of the
     existing file.  The file must then be referenced by 'file' when
     attempting further operations and each access of the file must be
     compatible with the same element size ('elemsize' is the size in
     bytes of each element).  'filename' must be a literal string or
     end with a null (CHR(0)) or blank (CHR(32)) character.  *)



 PROCEDURE closef (VAR file : filetype (* in/out *));

  (* Will close the file on disk associated with 'file'.  No further
     operations on 'file' are allowed unless the file is reopened. *)



 PROCEDURE readf (VAR file : filetype;      (* in/out *)
                  VAR elem : ARRAY OF BYTE  (* out    *));

  (* Will read from 'file' the element at the current pointer position
     and place that element into the parameter 'elem'.  The file
     pointer will then be positioned at the next element in the file
     unless the end of file is encountered.  If the element size of
     the file ('elemsize') and the size (in bytes) of 'elem' do
     not match, no action is taken. *)



 PROCEDURE writef (VAR file : filetype;     (* in/out *)
                   elem     : ARRAY OF BYTE (* in     *));

  (* Will write to 'file' the contents of the parameter 'elem' to
     the current file pointer position. The file pointer will then be
     positioned at the next element in the file unless the end of file
     is encountered.  If the element size of the file ('elemsize')
     and the size (in bytes) of 'elem' do not match, no action is
     taken. *)



 PROCEDURE setposf (VAR file : filetype; (* out *)
                    elemnum  : CARDINAL  (* in  *));

  (* Will position the file pointer of 'file' at the element number
     specified in 'elemnum'.  The first element in the file is
     defined as element number one.  If an attempt is made to position
     the pointer past the last element, the pointer is set to the end
     of the file. *)



 PROCEDURE getposf (file : filetype (* in *)) : CARDINAL;

  (* Will return in 'getposf' the element number presently pointed to
     by 'file'.  The first element of the file is element number one.
     If the pointer is at the end of the file and the file contains
     the maximum 65535 elements then 'getposf' returns zero. *)



 PROCEDURE resetf (VAR file : filetype (* out *));

  (* Will position the pointer associated with 'file' to the first
     element of the file. *)



 PROCEDURE rewritef (VAR file : filetype (* out *));

  (* Will truncate the file to zero elements and position the pointer
     associated with 'file' to the beginning of the file. *)



 PROCEDURE atendf (file : filetype (* in *)) : BOOLEAN;

  (* Will return true if the file pointer associated with 'file' is
     positioned at the end of the file. *)



 PROCEDURE resultf () : CARDINAL;

  (* Will return the result code of the last file operation performed.
     The following is a list of the return codes and their meanings:

     0 -- no error
     1 -- error opening or creating file
     2 -- error closing: not created or invalid file
     3 -- error reading: not created, element mismatch, or at end of file
     4 -- error writing: not created, element mismatch, or at element limit
     5 -- attempt made to move pointer beyond present boundries of file  *)



END files.