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

DEFINITION MODULE JumpTab;

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

    Module  JumpTab     (Version 1.0)

      Copyright (c) 1992-2006 by Juerg Thoeny and ETH Zurich.

    Purpose   Manage jump tables of file positions in text files.

    Remarks   Allows you to store large amounts of data into
              text files, yet efficiently retrieve individual
              data sets via a jump table.


    Programming

      o Design
        Juerg Thoeny              07/12/1992

      o Implementation
        Juerg Thoeny              07/12/1992


    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:  07/12/1992  JT

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


  TYPE
    JumpTabErrorCodes = (NoError,
                         FileError,
                         WrongVersion,
                         WrongMachine,
                         NoMemory,
                         TabNotFound,
                         TabAlredyExists,
                         ItemNotFound,
                         WrongMode);   (* if you try to access an item of an table which
                                          is on disk and not in memory *)

    TabLocation   = (onFile, inMemory);

    TabHandle;

    TabItem = RECORD
      posInfo   : LONGINT;
      ident     : INTEGER;
      attribute : LONGINT;
    END;(*RECORD*)


  PROCEDURE NewTab(VAR tab : TabHandle; location : TabLocation) : JumpTabErrorCodes;
  (* Creates a new table                                                             *)
  (* IN  : location  determines whether the items should be stored in memory or in a *)
  (*                 temporary file                                                  *)
  (* OUT : tab       A handle to the created table.                                  *)
  (* RETURNS : TabAlredyExists                                                       *)
  (*           NoMemory  if there is not enough memory                               *)
  (*           FileError if the temporary file could not be created                  *)
  (* REMARKS : Disposes the table if an error occurs                                 *)

  PROCEDURE AddItem (tab : TabHandle; item : TabItem)  : JumpTabErrorCodes;
  (* Adds an Item to the table by either allocation it in memory or writes it to the *)
  (* temporary file                                                                  *)
  (* IN  : item                                                                      *)
  (*       tab    table to which the item should be added                            *)
  (* RETURNS : TabNotFound if tab could not be found                                 *)
  (*           NoMemory    if there is not enough memory                             *)

  PROCEDURE TabSize (tab : TabHandle; VAR size : CARDINAL ) : JumpTabErrorCodes;
  (* Gives the number of items collected in the table                                *)
  (* RETURNS : TabNotFound                                                           *)

  PROCEDURE WriteTab (tab : TabHandle; fileName, tabHeader : ARRAY OF CHAR ) : JumpTabErrorCodes;
  (* Appends the table tab to the file fileName                                      *)
  (* IN  : tabHeader String which will be written in the header of the table         *)
  (* RETURNS : TabNotFound                                                           *)
  (*           FileError if either the file fileName or the temporary item file      *)
  (*                     could not be written rsp. read                              *)

  PROCEDURE ReadTab (fileName : ARRAY OF CHAR; VAR tab :TabHandle ) : JumpTabErrorCodes;
  (* Reads the table tab from the end of the file fileName and builds the table in   *)
  (* memory                                                                          *)
  (* RETURNS : TabAlredyExists                                                       *)
  (*           NoMemory     if there is not enough memory                            *)
  (*           FileError    if the file fileName could not be read                   *)
  (*           WrongVersion if the JumpTable implementation has the wrong version    *)
  (*           WrongMachine if the machine on which the table was generated was not  *)
  (*                        the same.                                                *)

  PROCEDURE GetItem (tab : TabHandle; ident : INTEGER; VAR item : TabItem) : JumpTabErrorCodes;
  (* Searchs the table tab for the first item with identification ident              *)
  (* RETURNS : TabNotFound                                                           *)
  (*           WrongMode    if the table was genereted with NewTab(..,onFile)        *)
  (*           ItemNotFound                                                          *)

  PROCEDURE DisposeTab (tab : TabHandle ) : JumpTabErrorCodes;
  (* Disposes the table tab                                                          *)
  (* RETURNS : TabNotFound                                                           *)

END JumpTab.