(* $VER: FSystem 1.2 (24-Nov-93) Copyright © by Lars Düning *)

DEFINITION FSystem;

---------------------------------------------------------------------------
 File handling library module for Amiga-Oberon.

 Copyright © 1991-1993  Lars Düning  -  All rights reserved.
 Permission granted for non-commercial use.
---------------------------------------------------------------------------

BUGS:
  Doesn't use the OS-2.0 buffered files.
  Doesn't know multi-assigns.

TYPE

  FilePtr * = POINTER TO File;


CONST

  StdBufSize *= 1024;  Default buffer size
  cEof        = 1CX;   End-Of-File character


CONST: Open() access modes

  newFile * = Dos.newFile;    excl. access, erases existing file
  oldFile * = Dos.oldFile;    shared access, file has to exist
  update  * = Dos.readWrite;  excl. access, file may exist


CONST: Open() operation modes

  writeOnly * = 0;
  readOnly  * = 1;
  readWrite * = 2;


CONST: File.status, error codes in fact

  ok        * = 0;  no error occured
  eof       * = 1;  end of file reached
  readerr   * = 2;  unspecified read error, ask Dos
  writeerr  * = 3;  unspecified write error, ask Dos
  onlyread  * = 4;  tried to write a read-only file
  onlywrite * = 5;  tried to read a write-only file
  toofar    * = 6;  seeked beyond the file's limits
  outofmem  * = 7;  ran out of memory
  cantopen  * = 8;  couldn't open file
  cantlock  * = 9;  couldn't lock file

TYPE: The File structure, source level compatible to FileSystem

  File * = RECORD
    handle * : d.FileHandlePtr;
    status * : INTEGER;
    write  * : BOOLEAN;
    read   * : BOOLEAN;
    name   * : POINTER TO ARRAY OF CHAR;
    string * : bt.DynString;
  END;

  The file structure makes no statements about the 'true' current
  fileposition as managed by DosS (except .read is TRUE and .buflen 0).
  That means that prior to every file operation using Dos at least
  one Dos.Seek(file.pos) should happen, better a call to EmptyBuf() to
  flush the internal buffers.


PROCEDURE Use * (VAR    file: File
                ;       name: ARRAY OF CHAR
                ;    accMode: INTEGER
                ;    opMode : INTEGER
                ;    bufsize: LONGINT
                ): BOOLEAN;


  Open a file according to access and operation mode.

  Arguments:
    file: the empty(!) File structure to fill in.
    name: the name of the file to open (will be copied into file).
    accMode: the access mode to use.
    opMode : the operation mode to use.
    bufSize: size of the buffer to allocate, must be at least 1.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  A bufsize of 1 will result in unbuffered io.


PROCEDURE open * (VAR    file: File
                 ;       name: ARRAY OF CHAR
                 ;    accMode: INTEGER
                 ): BOOLEAN;


  Open a file for read/write with a default sized buffer.

  Arguments:
    file: the empty(!) File structure to fill in.
    name: the name of the file to open (will be copied into file).
    accMode: the access mode to use.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The allocated buffer will be of StdBufSize.
  The file will be opened for reading and writing.


PROCEDURE Open * (VAR  file: File
                 ;     name: ARRAY OF CHAR
                 ;    write: BOOLEAN
                 ): BOOLEAN;

  Open a file for read or write with a default sized buffer.

  Arguments:
    file: the empty(!) File structure to fill in.
    name: the name of the file to open (will be copied into file).
    write: TRUE if the file shall be written, FALSE if it shall be read.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The allocated buffer will be of StdBufSize. The file will be opened
  for either reading or writing.

  This is a compatibility function to FileSystem.


PROCEDURE OpenReadWrite * (VAR file: File; name: ARRAY OF CHAR) : BOOLEAN;

  Open a file for read and write with a default sized buffer.

  Arguments:
    file: the empty(!) File structure to fill in.
    name: the name of the file to open (will be copied into file).

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The allocated buffer will be of StdBufSize. The file will be opened
  for reading and writing.

  This is a compatibility function to FileSystem.


PROCEDURE Flush    * (VAR file: File): BOOLEAN;
PROCEDURE FlushBuf * (VAR file: File): BOOLEAN;

  Flush the buffers of a file.

  Arguments:
    file: the file to flush.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.
    file will be update appropriately.

  If the file has been changed, this call will flush the internal buffer
  out to the disk file. To do this, the file.buflen bytes starting
  from file.buffer[0] are written, then the old file.pos will be seeked.


PROCEDURE close * (VAR file: File);
PROCEDURE Close * (VAR file: File): BOOLEAN;

  Close the file.

  Arguments:
    file: the file to close.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  Before closing, all changed data is written out using FlushBuf().


PROCEDURE read * (VAR file: File; VAR to: ARRAY OF s.BYTE);
PROCEDURE Read * (VAR file: File; VAR to: ARRAY OF s.BYTE): BOOLEAN;

  Read data from a file.

  Arguments:
    file: the file to read.
    to  : the buffer to read into.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The function optimizes large reads by circumventing file's buffer then.


PROCEDURE readBlock * ( VAR    file : File
                      ;          to : s.ADDRESS
                      ;         size: LONGINT
                      ; VAR actSize : LONGINT
                      );
PROCEDURE ReadBlock * ( VAR    file : File
                      ;          to : s.ADDRESS
                      ;         size: LONGINT
                      ; VAR actSize : LONGINT
                      ): BOOLEAN;

  Read a block of data from a file.

  Arguments:
    file   : the file to read.
    to     : the address of the buffer to read into.
    size   : the length of the buffer = number of bytes to read.
    actSize: variable taking the actual number of bytes read.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The function optimizes large reads by circumventing file's buffer then.


PROCEDURE readChar * (VAR file: File; VAR ch: CHAR);
PROCEDURE ReadChar * (VAR file: File; VAR ch: CHAR): BOOLEAN;

  Read a character from a file.

  Arguments:
    file: the file to read.
    ch  : the variable taking the character read.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  On eof, ch is set to EOF.


PROCEDURE readString * (VAR file: File; VAR to: ARRAY OF CHAR);
PROCEDURE ReadString * (VAR file: File; VAR to: ARRAY OF CHAR): BOOLEAN;

  Read a string from a file.

  Arguments:
    file: the file to read.
    to  : the buffer to read the string into.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The string is read until a \0 or a \n shows up (which is not stored)
  or the buffer is exhausted. If possible, the read string is terminated
  with \0.


PROCEDURE ReadLongString * (VAR file: File): BOOLEAN;
PROCEDURE readLString    * (VAR file: File);
PROCEDURE ReadLString    * (VAR file: File): BOOLEAN;

  Read a long string from a file.

  Arguments:
    file: the file to read.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.
    The read string is store in file.string.

  The string is read until a \0 or a \n shows up (which is not stored).
  If possible, the read string is terminated with \0.

  ReadLongString() is a compatibility function to FileSystem.


PROCEDURE write * (VAR file: File; VAR from: ARRAY OF s.BYTE);
PROCEDURE Write * (VAR file: File; VAR from: ARRAY OF s.BYTE): BOOLEAN;

  Write data to a file.

  Arguments:
    file: the file to write.
    from: the buffer to write from.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The function optimizes large writes by circumventing file's buffer then.


PROCEDURE writeBlock * ( VAR    file : File
                       ;        from : s.ADDRESS
                       ;        size : LONGINT
                       ; VAR actSize : LONGINT
                       );
PROCEDURE WriteBlock * ( VAR    file : File
                       ;        from : s.ADDRESS
                       ;        size : LONGINT
                       ; VAR actSize : LONGINT
                       ): BOOLEAN;

  Write a block of data to a file.

  Arguments:
    file    : the file to write.
    from    : the address of the buffer to write from.
    size    : the length of the buffer = the number of bytes to write.
    actSize : variable taking the actual number of bytes written.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.
    actsize: the number of bytes written.

  The function optimizes large writes by circumventing file's buffer then.


PROCEDURE writeChar * (VAR file: File; ch: CHAR);
PROCEDURE WriteChar * (VAR file: File; ch: CHAR): BOOLEAN;

  Write a character to a file.

  Arguments:
    file: the file to write.
    ch  : the character to write.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.


PROCEDURE writeString * (VAR file: File; from: ARRAY OF CHAR);
PROCEDURE WriteString * (VAR file: File; from: ARRAY OF CHAR): BOOLEAN;

  Write a string to a file.

  Arguments:
    file: the file to write.
    from: the string to write.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The function writes the string plus one \n character.


PROCEDURE Size * (VAR file: File): LONGINT;

  Determine the size of a file.

  Arguments:
    file: the file to query.

  Result:
    The file's size in bytes.


PROCEDURE Position * (VAR file: File): LONGINT;

  Determine the current position in a file.

  Arguments:
    file: the file to query.

  Result:
    The position within the file in bytes.


PROCEDURE move * (VAR file: File; to: LONGINT);
PROCEDURE Move * (VAR file: File; to: LONGINT): BOOLEAN;

  Seek within a file.

  Arguments:
    file: the file to seek in.
    to  : the new position to seek, counted in bytes from the files start.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.


PROCEDURE forward * (VAR file: File; to: LONGINT);
PROCEDURE Forward * (VAR file: File; to: LONGINT): BOOLEAN;

  Seek forward within a file.

  Arguments:
    file: the file to seek in.
    to  : the number of bytes to skip forward.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.


PROCEDURE backward * (VAR file: File; to: LONGINT);
PROCEDURE Backward * (VAR file: File; to: LONGINT): BOOLEAN;

  Seek backward within a file.

  Arguments:
    file: the file to seek in.
    to  : the number of bytes to skip backward.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.


PROCEDURE delete * (VAR file: File);
PROCEDURE Delete * (VAR file: File): BOOLEAN;

  Delete a file.

  Arguments:
    file: the file to delete.

  Result:
    TRUE on success, else FALSE with file.status denoting the error.

  The file is closed, then deleted.


PROCEDURE Exists * (name: ARRAY OF CHAR): BOOLEAN;

  Check if a named file exists.

  Arguments:
    name: the filename to check.

  Result:
    TRUE if the file exists, else FALSE.

  BUGS:
    Doesn't handle multi-assigns.

END FSystem.