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

DEFINITION MODULE DataTables;

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

    Module  DataTables     (Version 1.0)

      Copyright (c) 1997-2006 by Dimitrios Gyalistras, Andreas Fischlin
      and ETH Zurich.

    Purpose   Handles data tables.

    Remarks   A data table consists of a header and a rectangular data field.
              The header is used to identify the individual columns of the data
              field.  All data within one column must contain data of one
              and the same type.  Any combinations of different types of
              columns are possible.


    Programming

      o Design
        Dimitrios Gyalistras      16/01/1997
        Andreas Fischlin          16/01/1997

      o Implementation
        Dimitrios Gyalistras      16/01/1997
        Andreas Fischlin          16/01/1997


    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:  09/08/1997  AF

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


  FROM SYSTEM     IMPORT ADDRESS;
  FROM DMStrings  IMPORT String;
  FROM DMFiles    IMPORT TextFile;
  FROM DMLanguage IMPORT onlyAnInsert;

  CONST
    notDone = onlyAnInsert;

  (*
    All procedures exported below return resCode = DMLanguage.allOk
    if the call to the procedure was succesfull, else resCode = notDone.
  *)


  TYPE
    DataTable;

    (*
       Data tables are matrix like objects consisting of rows and
       colums.  In contrast to the well known matrices consisting
       of numbers, data tables may consist of elements of different
       types (see DTElementType), however, within a single column
       types should be the same.  Missing values are tolerated
       (symbol NA - not available). Implementation restriction:
       Memory for data tables will be allocated efficiently, i.e.
       only to the size actually required.  Columns are numbered
       from 1 to 256 and rows from 1 to 3072.
     *)


  CONST
    unknownRowNr = 0; (* rows start at 1 *)
    unknownColNr = 0; (* columns start at 1 *)


  VAR
    notExistingDataTable: DataTable; (* read only *)


 (*****************************************************************************)


  TYPE
    String63       = ARRAY [0..63] OF CHAR;

    DTElementType  = ( unknownDTEle,
                       integer, longint, real, longreal,
                       boolean, ident, string );


    DTColDescr     =  RECORD
                        type : DTElementType;
                        id   : String63;
                      END;

    DTElementPtr   =  POINTER TO DTElement;
    SHORTENUM      =  CHAR; (* will hold [CHAR(MIN(DTElementType))..CHAR(MAX(DTElementType))] *)
    DTElement      =  RECORD
                          def: BOOLEAN; (* def holds whether DTElement is defined *)
                          type: SHORTENUM; (* type holds the type *)
                          CASE : DTElementType OF
                          | unknownDTEle : undefval : ARRAY [0..(SIZE(LONGREAL) DIV SIZE(CHAR))-1] OF CHAR;
                          | real         : real     : REAL;
                          | longreal     : lreal    : LONGREAL;
                          | integer      : int      : INTEGER;
                          | longint      : lint     : LONGINT;
                          | boolean      : boo      : BOOLEAN;
                          | ident        : id       : String;
                          | string       : str      : String;
                          END;(*CASE*)
                      END;

                      (* assumptions made:
                         (i)   SIZE(CHAR)     = 1
                         (ii)  SIZE(BOOLEAN) <= SIZE(INTEGER)
                         (iii) SIZE(INTEGER) <= SIZE(LONGINT)
                         (iv)  SIZE(REAL)    <= SIZE(LONGREAL)
                         (v)   SIZE(ORD(MAX(DTElementType))) <= SIZE(CHAR)
                         (vi)  SIZE(LONGREAL) = SIZE(undefval) (* implies assumption (i) *)
                         (vii) SIZE(undefval) >= SIZE(of all types)
                         Assumptions (v) to (vii) are tested during
                         module initialization. The latter are
                         assumed to be satisfied by all compilers.
                      *)


  PROCEDURE ShortDTEType(t: DTElementType): SHORTENUM;
  PROCEDURE DTEType(t: SHORTENUM): DTElementType;


 (*****************************************************************************)
 (*                             Object management                             *)
 (*****************************************************************************)


  PROCEDURE GetDTElementTypeDescr( dt: DTElementType; VAR descr: ARRAY OF CHAR );


 (*--------------------------------------------------------------------------*)


   PROCEDURE DeclDataTable( tableName    : ARRAY OF CHAR;
                            nRows        : INTEGER;
                            nCols        : INTEGER;
                            VAR colDescr : ARRAY OF DTColDescr;  (* VAR for speed-up only *)
                            VAR dt       : DataTable;
                            VAR resCode  : INTEGER;
                            VAR insert   : ARRAY OF CHAR );


   PROCEDURE RemoveDataTable( VAR dt : DataTable );


   PROCEDURE DataTableExists( dt : DataTable ): BOOLEAN;


 (*--------------------------------------------------------------------------*)


   PROCEDURE FirstDataTable():DataTable;


   PROCEDURE NextDataTable( dt: DataTable ):DataTable;


 (*--------------------------------------------------------------------------*)


   PROCEDURE GetDataTableAttr( dt          : DataTable;
                               VAR attr    : ADDRESS;
                               VAR resCode : INTEGER;
                               VAR insert  : ARRAY OF CHAR );

   PROCEDURE SetDataTableAttr( dt          : DataTable;
                               attr        : ADDRESS;
                               VAR resCode : INTEGER;
                               VAR insert  : ARRAY OF CHAR );


 (*--------------------------------------------------------------------------*)


    PROCEDURE LockDataTable( dt          : DataTable;
                             VAR resCode : INTEGER;
                             VAR insert  : ARRAY OF CHAR );
     (*
        content of data table dt can no longer be modified.  Data table dt can
        only be discarded as a whole.
      *)


    PROCEDURE UnlockDataTable( dt          : DataTable;
                               VAR resCode : INTEGER;
                               VAR insert  : ARRAY OF CHAR );


   PROCEDURE IsDataTableLocked( dt : DataTable ): BOOLEAN;


 (*--------------------------------------------------------------------------*)


   PROCEDURE GetDataTableName( dt            : DataTable;
                               VAR tableName : ARRAY OF CHAR;
                               VAR resCode   : INTEGER;
                               VAR insert    : ARRAY OF CHAR );


   PROCEDURE GetDataTableDescr( dt            : DataTable;
                                VAR tableName : ARRAY OF CHAR;
                                VAR nRows     : INTEGER;
                                VAR nCols     : INTEGER;
                                VAR colDescr  : ARRAY OF DTColDescr;
                                VAR resCode   : INTEGER;
                                VAR insert    : ARRAY OF CHAR );

   PROCEDURE GetDataTableColDescr( dt            : DataTable;
                                   colNo         : INTEGER;
                                   VAR colDescr  : DTColDescr;
                                   VAR resCode   : INTEGER;
                                   VAR insert    : ARRAY OF CHAR );

   PROCEDURE SetDataTableDescr( dt           : DataTable;
                                tableName    : ARRAY OF CHAR;
                                VAR colDescr : ARRAY OF DTColDescr;  (* VAR for speed-up only *)
                                VAR resCode  : INTEGER;
                                VAR insert   : ARRAY OF CHAR );


   PROCEDURE GetDataTableDim( dt          : DataTable;
                              VAR nRows   : INTEGER;
                              VAR nCols   : INTEGER;
                              VAR resCode : INTEGER;
                              VAR insert  : ARRAY OF CHAR );


 (*--------------------------------------------------------------------------*)


   VAR
     emptyDataEle: DTElement;  (* read only *)
     (*
        Inite your variables of type DTElement with emptyDataEle.
        Strongly recommended prior to any further use!
      *)


   PROCEDURE ClearDTEle( eleType: DTElementType; VAR ele: DTElement );
   (*
     Sets ele to emptyDataEle; NOTE: It deallocates also strings, if
     eleType requires this.  Thus, precondition for ele is either
     ele = emptyDataEle or a valid value of type eleType from previous
     use.
   *)


   PROCEDURE CopyDTEle( eleType: DTElementType;
                        VAR from : DTElement;  (* VAR for speed-up only *)
                        VAR to   : DTElement );
   (*
     to has to satisfy the same preconditions as required by ClearDTEle
   *)


   (*
      NOTE: for efficiency the following procedures do not
            check the validity of the input parameters!!
   *)

   PROCEDURE GetDTEle( dt       : DataTable;
                       row, col : INTEGER;
                       VAR ele  : DTElement );
   (*
     ele has to satisfy the same preconditions as required by ClearDTEle
   *)

   PROCEDURE SetDTEle( VAR  ele : DTElement; (* VAR for speed-up only *)
                       dt       : DataTable;
                       row, col : INTEGER );
   (*
     ele has to satisfy the same preconditions as required by ClearDTEle
     plus that dt contains already well defined types for all colums.
   *)

   PROCEDURE DTEleADR( dt       : DataTable;
                       row, col : INTEGER): DTElementPtr;
   (*
     NOTE: This routine is a loophole circumventing the locking mechanism
     entirely, so use it with caution and for reading ONLY, unless the dt is
     not locked!!!
   *)





 (*****************************************************************************)
 (*                     Reading of DataTables from file                       *)
 (*****************************************************************************)


  PROCEDURE SetMisValParams( misValStr,
                             misQuotStr  : ARRAY OF CHAR;
                             misReal     : REAL;
                             misInt      : INTEGER;
                             misLReal    : LONGREAL;
                             misLInt     : LONGINT;
                             misBool     : BOOLEAN;
                             VAR resCode : INTEGER;
                             VAR insert  : ARRAY OF CHAR );

  PROCEDURE GetMisValParams( VAR misValStr,
                                 misQuotStr: ARRAY OF CHAR;
                             VAR misReal   : REAL;
                             VAR misInt    : INTEGER;
                             VAR misLReal  : LONGREAL;
                             VAR misLInt   : LONGINT;
                             VAR misBool   : BOOLEAN);

  (*
    The values misReal and misInt are returned if the string "misValStr"
    is encountered at the place of a real (or longreal), or an integer
    (or longint), respectively.
    The default settings are:
       misValStr  = 'NA'
       misQuotStr = '???'
       misReal    = DMConversions.UndefREAL();
       misInt     = MIN(INTEGER)+1;
       misLReal   = DMConversions.UndefLONGREAL();
       misLInt    = MIN(LONGINT)+1;
       misBool    = BOOLEAN(ORD(MAX(BOOLEAN))+1);
  *)


  PROCEDURE ReadDataTable( inFName      : ARRAY OF CHAR;
                           tryOpenFile  : BOOLEAN;
                           keepFileOpen : BOOLEAN;
                           eolSeparated : BOOLEAN;
                           tableName    : ARRAY OF CHAR;
                           VAR dt       : DataTable;
                           VAR resCode  : INTEGER;
                           VAR insert   : ARRAY OF CHAR );
  (*
    Reads DataTable dt from file inFName.  If tryOpenFile=FALSE the
    file must have already been opened for scanning by means of
    procedure Scanner.InitFileScan.
    If the file is kept open, the Scanner procedures can be used to
    continue reading, e.g. to read a further table.

    The expected syntax is:

        DataTable     =  TableHeader TableLine {TableLine} "END".
        TableHeader   =  IDENTIFIER {IDENTIFIER} lineSeparator.
        TableLine     =  TableEle {TableEle} lineSeparator.
        TableEle      =  (INTEGER | LONGINT |  REAL | LONGREAL |
                          IDENTIFIER | STRING | BOOLEAN ).

    If eolSeparated=TRUE then

        lineSeparator =  "EOL".

    and all elements of TableHeader or a TableLine are expected on one line.
    Otherwise

        lineSeparator =  ";".

    In this case the elements of TableHeader or a TableLine can be distributed
    over any number of lines.

    The elementary data types are (given in regular expression notation):

        INTEGER     =  [+-]?[0-9]+
        LONGINT     =  [+-]?[0-9]+ "D"
        REAL        =  [+-]?[0-9]+ "." [0-9]+ (("E"|"e")[+-]?[0-9]+)?
        LONGREAL    =  [+-]?[0-9]+ "." [0-9]+ (("D"|"d")[+-]?[0-9]+)?
        IDENTIFIER  =  [a-zA-Z]+ [_a-zA-Z0-9]*
        STRING      =  ('.*')|(".*")
        BOOLEAN     =  "TRUE" | "FALSE"

    Comments start with "(*" and close with "*)".  Recursive comments
    are possible.

  *)


  PROCEDURE GetColDescriptors( VAR fName    : ARRAY OF CHAR; (* VAR for speed-up only *)
                               eolSeparated : BOOLEAN;
                               VAR nCols    : INTEGER;
                               VAR colDescr : ARRAY OF DTColDescr;
                               VAR resCode  : INTEGER;
                               VAR insert   : ARRAY OF CHAR );
  (*
    Retrieves header line (column descriptors) by reading from current position
    in a file previously opened by means of procedure Scanner.InitFileScan.
  *)


  PROCEDURE GetNextDataRow( VAR fName     : ARRAY OF CHAR;       (* VAR for speed-up only *)
                            eolSeparated  : BOOLEAN;
                            nCols         : INTEGER;
                            VAR colDescr  : ARRAY OF DTColDescr; (* is also set! *)
                            VAR rowData   : ARRAY OF DTElement;
                            VAR endOfData : BOOLEAN;
                            VAR resCode   : INTEGER;
                            VAR insert    : ARRAY OF CHAR );
  (*
    Retrieves a table row by reading from current position in a file
    previously opened by means of procedure Scanner.InitFileScan.
    If for the column descriptor of the i-th column holds colDescr[i].type=
    unknownDTEle then the type will be set according to the type of
    data found for column i (unless a missing value occurs).
    endOfData returns TRUE if the end of the data table has been
    reached (keyword "END"). rowData must be properly initialized
    all with emptyDataEle, when calling GetNextDataRow the first time.
  *)





 (*****************************************************************************)
 (*                      Writing of DataTables to file                        *)
 (*****************************************************************************)

  PROCEDURE SetNumOutputParams( nIntChars    : INTEGER;
                                nLIntChars   : INTEGER;
                                nRealChars   : INTEGER;
                                nDecDigits   : INTEGER;
                                nLRealChars  : INTEGER;
                                nLRDecDigits : INTEGER);


  PROCEDURE GetNumOutputParams( VAR nIntChars    : INTEGER;
                                VAR nLIntChars   : INTEGER;
                                VAR nRealChars   : INTEGER;
                                VAR nDecDigits   : INTEGER;
                                VAR nLRealChars  : INTEGER;
                                VAR nLRDecDigits : INTEGER );


  PROCEDURE WriteDataTable( outF          : TextFile;
                            eolSeparated  : BOOLEAN;
                            indentStr     : ARRAY OF CHAR;
                            lastIndentStr : ARRAY OF CHAR;
                            VAR dt        : DataTable;
                            VAR resCode   : INTEGER;
                            VAR insert    : ARRAY OF CHAR );
  (*
    Dumps DataTable dt to file outF.  The file must have already been
    opened for writing by means of a DMFiles procedure.
    If eolSeparated=FALSE data lines will be separated by ";".
    Each new line written starts with indentStr, the last line containing
    the keyword "END" with lastIndentStr.
  *)


END DataTables.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]