RAMSES	Systems Ecology
Start         Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE ReadData;

  (*******************************************************************

    Module  ReadData     (Version 1.0)

      Copyright (c) 1989-2006 by Andreas Fischlin, Thomas Nemecek, Olivier
      Roth, Frank Thommen and ETH Zurich.

    Purpose   Utilities to read and test data while reading
              from a file with data in columnar form.

    Remarks   --


    Programming

      o Design
        Andreas Fischlin          12/02/1989

      o Implementation
        Andreas Fischlin          12/02/1989
        Thomas Nemecek            09/09/1989
        Olivier Roth              23/11/1989
        Frank Thommen             03/03/1991


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  15/03/1991  FT

  *******************************************************************)


  (* List of all idents exported by this module:

  FROM ReadData IMPORT
    negLogDelta, SkipGapOrComment, ReadCharsUnlessAComment,
    SetMissingValCode, GetMissingValCode, SetMissingReal,
    GetMissingReal, SetMissingInt, GetMissingInt, dataF,
    OpenADataFile, OpenDataFile, ReReadDataFile, CloseDataFile,
    SkipHeaderLine, ReadHeaderLine, ReadLn, GetChars, GetStr,
    GetInt, GetReal, SetEOSCode, GetEOSCode, FindSegment,
    SkipToNextSegment, AtEOL, AtEOS, AtEOF, TestEOF, Relation,
    Compare2Strings, ErrorType, NumbType, ErrMsgProc, SetErrMsgP,
    GetErrMsgP, UseDefaultErrMsg;

  *)


  FROM DMStrings IMPORT String;
  FROM DMFiles   IMPORT TextFile;


  CONST
    negLogDelta = 0.01; (*offset to plot log scale if values <= 0*)



  (* File handling: *)
  VAR dataF: TextFile;

  PROCEDURE OpenADataFile( VAR fn: ARRAY OF CHAR;  VAR ok: BOOLEAN );
  (* opens a file using the standard open file dialog *)

  PROCEDURE OpenDataFile ( VAR fn: ARRAY OF CHAR;  VAR ok: BOOLEAN );
  (* opens a file specified by fn automatically, and calls OpenADataFile
   * if fn couldn't be found *)

  PROCEDURE ReReadDataFile;

  PROCEDURE CloseDataFile;


  (* Reading and number testing *)

  VAR readingAborted: BOOLEAN;
  (* Returns wether the file reading has been aborted by pressing the
   * pushButton "Stop reading".  It is highly recommended to use this
   * variable to test whether the reading of the data has been
   * successful.  If readingAborted = FALSE subsequently avoid any
   * program loop, for instance a simulation; instead make sure you
   * immediately return control to the'Dialog Machine'.  The latter
   * is very important if the user has pressed the button 'Abort
   * prgm', which has signaled to the 'Dialog Machine' to terminate
   * itself (i.e. it actually called QuitDialogMachine from
   * DMMaster).  After executing QuitDialogMachine, the 'Dialog
   * Machine' accepts no more user events and any loop under client
   * control can no longer be terminated via ordinary user events
   * such as a menu command 'Stop'. Thus any loop with a termination
   * condition depending on an user event will no longer function,
   * since the current (sub)program level accepts no more user
   * events. *)



  PROCEDURE SkipGapOrComment;
  (*  skips all characters <= " " and all text enclosed in comment
   *  brackets as used in Modula-2, i.e. "(* ..... *)"
   *  This procedure is used in this module. *)

  PROCEDURE ReadCharsUnlessAComment( VAR string: ARRAY OF CHAR );
  (* reads a string beginning from the current position until
   *  a character <= " " or a comment is encountered. *)


  (* Missing values: *)

  (* default missingValCode = "N" *)
  PROCEDURE SetMissingValCode( missingValCode    : CHAR );
  PROCEDURE GetMissingValCode( VAR missingValCode: CHAR );

  (* default missingReal = DMConversions.UndefREAL() *)
  PROCEDURE SetMissingReal( missingReal    : REAL );
  PROCEDURE GetMissingReal( VAR missingReal: REAL );

  (* default missingInt = MIN(INTEGER)+1 *)
  PROCEDURE SetMissingInt( missingInt    : INTEGER );
  PROCEDURE GetMissingInt( VAR missingInt: INTEGER );


  PROCEDURE SkipHeaderLine;

  PROCEDURE ReadHeaderLine( VAR labels: ARRAY OF String;
                            VAR nrVars: INTEGER );
  (* IMPORTANT NOTE: labels must be initialized to NIL before first use! *)

  PROCEDURE ReadLn  ( VAR txt: ARRAY OF CHAR );

  PROCEDURE GetChars( VAR str: ARRAY OF CHAR );

  PROCEDURE GetStr  ( VAR str: String );


  (*  In the following procedures the two first parameters desc and
   *  loc are only needed for the display of error messages and help
   *  the user to identify an erronous location within the data file:
   *   - desc a string describing the kind of data to be read, e.g.
   *              population density or number of individuals
   *   - loc      a location number indicating where the error has
   *              been found, e.g. a line number
   *)

  PROCEDURE GetInt ( desc : ARRAY OF CHAR;  loc: INTEGER;
                     VAR x: INTEGER;   min, max: INTEGER );

  PROCEDURE GetReal( desc : ARRAY OF CHAR; loc:  INTEGER;
                     VAR x: REAL;      min, max: REAL    );


  (* Working with data segments (EOS means End Of Segment): *)

  PROCEDURE SetEOSCode( eosCode    : CHAR );

  PROCEDURE GetEOSCode( VAR eosCode: CHAR );

  PROCEDURE FindSegment( segNr: CARDINAL; VAR found: BOOLEAN );

  PROCEDURE SkipToNextSegment( VAR done: BOOLEAN );


  (* Testing: *)

  PROCEDURE AtEOL(): BOOLEAN;

  PROCEDURE AtEOS(): BOOLEAN;

  PROCEDURE AtEOF(): BOOLEAN;

  PROCEDURE TestEOF; (* use only where you don't yet expect EOF (shows alert) *)


  TYPE Relation = ( smaller, equal, greater );

  PROCEDURE Compare2Strings( a, b: ARRAY OF CHAR ): Relation;


  (* Alerts: *)

  TYPE
    ErrorType = (NoInt, NoReal, TooBig, TooSmall,
                 NotEqual, EndOfFile, FileNotFound, DataFNotOpen);
    (* type of the error:
     *  -NoInt        : Integer expected but string or real encountered
     *  -NoReal       : Real expected but string or Integer encountered
     *  -TooBig       : Number higher than max
     *  -TooSmall     : Number smaller than min
     *  -NotEqual     : Special case if min=max and number #min resp. max
     *  -EndOfFile    : Attempt to read the file over it's end
     *  -FileNotFound : Data file not found
     *  -DataFNotOpen : Data file could not be opened *)

    NumbType  = (Real, Integer);
    (* tells weather a real or an integer had to be read *)

    Error =
         RECORD
           errorType : ErrorType;
           strFound  :ARRAY[0..63] OF CHAR;
           CASE numbType :NumbType OF
               Integer : minI, maxI: INTEGER
             | Real    : minR, maxR: REAL
           ELSE
           END;
           desc :ARRAY [0..255] OF CHAR;
           loc  :INTEGER
         END(*RECORD*);

    ErrMsgProc = PROCEDURE(Error);


  PROCEDURE SetErrMsgP(errP: ErrMsgProc);
  (* sets the current alert procedure to alert. Useful if working in batch
   * mode to avoid program halt *)

  PROCEDURE GetErrMsgP(VAR currErrP: ErrMsgProc);
  (* gets the current alert procedure *)

  PROCEDURE UseDefaultErrMsg;
  (* re-installs the default alert procedure *)

END ReadData.