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 DMResources;

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

    Module  DMResources     ('Dialog Machine' DM_V3.0)

      Copyright (c) 1990-2006 by Andreas Fischlin and ETH Zurich.

    Purpose   Store variable values of elementary data types
              permanently on disk in a so-called resource
              for later reusage.

    Remarks   Typically this module is used to save
              current settings, so that when the same
              application is started again at a later time
              the settings will be exactly the same as
              they were when the application was quit.

              The data structure of a resource is defined
              by the sequence in which elements are added
              respectively retrieved (here called fetched). Some
              restrictions apply to the maximum size of a resource
              (<=32000 bytes) and to the values elements of type
              CHAR and String (ARRAY OF CHAR) may contain
              for certain resource types.

              Uses DMConversions, DMStrings.

              This module belongs to the 'Dialog Machine'.


    Programming

      o Design
        Andreas Fischlin          14/10/1990

      o Implementation
        Andreas Fischlin          14/10/1990


    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:  26/07/1991  AF

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


  FROM SYSTEM IMPORT BYTE;

  (*
    Implementation restrictions:

     o  At a particular time you may only compose one single resource.
        Call repeatedly StartResourceConstruction and after the add
        routines StoreResource before composing another one.

     o  If the resource type is 'STR ' neither AddString nor
        AddString255 must pass a nul length string nor a string
        argument containing the character 0C (except at its end)
        since it is used to signal the end of the total resource.
        Moreover, there is also the danger that a number stored
        with AddBinXYZ or AddBinLongXYZ will not be stored properly
        if the type 'STR ' is used.  Again this is because the byte
        0C may be contained in any binary data. The only exception
        to this rule is the procedure AddChar; it allows to store
        0C.  However, the price to pay is that the character nulCh
        can no longer be used as an argument of AddChar.

     o  Resource type 'TEXT' will result in using the data fork of
        a text file instead of the resource fork. (Note, this type
        is in the current implementation only supported by allowing
        to read or write a single resource, i.e. resIDs are
        ignored).

     o  Only resID > 127 must be used, otherwise no storing will
        take place and the ResourcesDone = FALSE (This serves to
        avoid conflicts with resIDs used internally by the system
        software).  Note that storing a resource with a resID which
        is the same as one of an existing resources of the same
        type results in the overwriting of the already existing
        resource.

     o  Type CARDINAL is no longer supported, use INTEGER or
        LONGINT instead.

     o  Type ADDRESS is not supported, since procedure pointers
        and other memory locations vary usually too little that
        a need to store them may arise.  If it should really be
        necessary, use LONGINT instead.

     o  If no resource data of the requested type and resID can't
        be found, ResourcesDone will be set FALSE.

     o  If no proper resource data is available, e.g. after
        an attempt to access a non-existing resource or if an
        integer is fetched where actually a string is present, the
        subsequent calls to the fetching routines will return the
        following values standing for undefined:

            type        returned default if data not available
            ----        ---------------------------------------
            BOOLEAN     FALSE
            INTEGER     0
            LONGINT     0D
            REAL        0.0
            LONGREAL    0.0D0
            CHAR        0C
            String      ''
  *)


  CONST
    nulCh  = 21C; (* ASCII dc1 or Command key on Mac *)
    defaultResType = 'STR ';

  TYPE
    ResourcePointer = POINTER TO Resource;
    Resource = ARRAY [0..32000] OF CHAR;
    Padding = (noPadding, padToEven, padToOdd);

  VAR
    theResource: ResourcePointer;
    (* always allocated as long this module exists and used internally
    for temporarily resource composition or fetching *)
    ResourcesDone: BOOLEAN; (* read only variable set by StoreResource,
                              RetrieveResource, DeleteResource, and the
                              number fetch routines FetchInt, FetchLongInt,
                              FetchReal, FetchLongReal as well as all
                              hex versions of the fetch routines. *)

  (*

    There are 3 versions used for internal storage of numbers in resources:
    ----------------------------------------------------------------------

    o The standard versions of the add or fetch routines use a text or
      string format.

        The advantages are:
          - human readable
          - storable when using resource type 'STR '
          - transferrable to other machines (e.g. via Kermit)

        The disadvantages are:
          - maximum storage space needed
          - precision loss due to conversion errors when converting
            from binary to decimal format might occur (important
            when using reals).
          - access slowed down by conversion


    o The hex versions of the add or fetch routines use hex codes
      instead of strings.

        The advantages are:
          - storable when using resource type 'STR '
          - medium storage space needed
          - no precision loss due to conversion errors
          - transferrable to other machines (e.g. via Kermit)

        The disadvantages are:
          - not human readable
          - access slowed down by conversion


    o Binary versions of the add or fetch routines are similar to the
      hex code versions but use internally an exact binary image.

        The advantages are:
          - minimum storage space needed
          - no precision loss due to conversion errors
          - access with maximum speed because no conversions done

        The disadvantages are:
          - not human readable
          - not storable when using resource type 'STR '
          - fully machine dependent, i.e. not transferrable to
            other machines

  *)

  PROCEDURE StartResourceComposition;

  PROCEDURE AddBoolean       (b: BOOLEAN);

  PROCEDURE AddInt         (int: INTEGER);
  PROCEDURE AddHexInt      (int: INTEGER);
  PROCEDURE AddBinInt      (int: INTEGER);

  PROCEDURE AddLongInt     (lint: LONGINT);
  PROCEDURE AddHexLongInt  (lint: LONGINT);
  PROCEDURE AddBinLongInt  (lint: LONGINT);

  PROCEDURE AddReal        (r: REAL);
  PROCEDURE AddHexReal     (r: REAL);
  PROCEDURE AddBinReal     (r: REAL);

  PROCEDURE AddLongReal    (lr: LONGREAL);
  PROCEDURE AddHexLongReal (lr: LONGREAL);
  PROCEDURE AddBinLongReal (lr: LONGREAL);

  PROCEDURE AddChar          (ch: CHAR);
  PROCEDURE AddString        (s: ARRAY OF CHAR);
  PROCEDURE AddString255     (s: ARRAY OF CHAR; pad: Padding);
  (*
    If the string x has a maximum length of 255 characters and has
    to be stored such that the first character (index 0) is used to
    hold the actual length, use this routine instead of AddString.
    Don't convert the string to this format before calling
    AddString255. Pass an ordinary Modula-2 string, the conversion
    will be done internally. Should the string possibly be padded
    to an even or odd length, set padToEven to accordingly.
    Implementation restriction:  Note that this procedure allows
    also to produce resources in exactly the same format as
    required by the Macintosh system software. Note however, that
    you may not store this resource with the default type 'STR ',
    unless your resource holds the empty string as the very last
    item.
  *)


  PROCEDURE StoreResource (filename: ARRAY OF CHAR; resID: INTEGER);
  (*
    Terminates previous composition by calls to any of the AddXYZ
    routines and stores resource permanently with resource
    identifier resID. If filename is empty the resources are
    searched in the current application, otherwise a resource file
    with the name 'filename' is searched according to the search
    strategy defined by the current path settings.  NOTE: Unless
    you work only with the resource type 'TEXT' and 'STR ' this
    routine may fail if called on a machine which does not
    support resources.
  *)




  PROCEDURE RetrieveResource(filename: ARRAY OF CHAR; resID: INTEGER);
  (*
    Makes the resource with resource identifier resID available for
    subsequent fetching of data from it by calls to any of the
    FetchXYZ routines . If filename is empty the resources are
    searched in the current application, otherwise a resource file
    with the name 'filename' is searched according to the search
    strategy defined by the current path settings.  NOTE: Unless
    you work only with the resource type 'TEXT' and 'STR ' this
    routine may fail if called on a machine which does not
    support resources.
  *)

  PROCEDURE FetchBoolean     (VAR b: BOOLEAN);

  PROCEDURE FetchInt         (VAR int: INTEGER);
  PROCEDURE FetchHexInt      (VAR int: INTEGER);
  PROCEDURE FetchBinInt      (VAR int: INTEGER);

  PROCEDURE FetchLongInt     (VAR lint: LONGINT);
  PROCEDURE FetchHexLongInt  (VAR lint: LONGINT);
  PROCEDURE FetchBinLongInt  (VAR lint: LONGINT);

  PROCEDURE FetchReal        (VAR r: REAL);
  PROCEDURE FetchHexReal     (VAR r: REAL);
  PROCEDURE FetchBinReal     (VAR r: REAL);

  PROCEDURE FetchLongReal    (VAR lr: LONGREAL);
  PROCEDURE FetchHexLongReal (VAR lr: LONGREAL);
  PROCEDURE FetchBinLongReal (VAR lr: LONGREAL);

  PROCEDURE FetchChar        (VAR ch: CHAR);
  PROCEDURE FetchString      (VAR s: ARRAY OF CHAR);
  PROCEDURE FetchString255   (VAR s: ARRAY OF CHAR; pad: Padding);
  (*
    If the string s has been stored by means of AddString255,
    retrieve it by means of this routine.  Note that it returns an
    ordinary Modula-2 string starting at index 0 and terminated with
    0C. In case the string was possibly padded during storage, make
    sure that you read with exactly the same padding mode.
  *)

  PROCEDURE CurPosition(): INTEGER;
  (*
    Returns current writing or fetching position within the resource
    after a successful StartResourceComposition, RetrieveResource,
    add, or fetch procedure call.  Note that the position is the index
    into the array of type Resource, where the denoted element is the
    one where either the next writing or next reading process will start
    from.
  *)

  PROCEDURE OverWriteAtPos (VAR x: ARRAY OF BYTE; VAR theResource: ARRAY OF CHAR;
                            VAR curPos: INTEGER);
  (*
    Does overwrite in the current resource theResource (actually of
    type Resource) starting from curPos the whole content of array
    x.  Note that in contrast to above AddXYZ procedures, such an
    overwriting process will not affect any following data
    contained in the resource, in particular no 0C character will
    be added to the written data.  Hence, overwriting should not be
    done at the end of a writing sequence, use the above AddXYZ
    procedures instead, only they will guarantee a proper
    termination of a default 'STR ' type resource.  Typically
    OverWriteAtPos is used to overwrite some data in the middle of
    the resource later on, i.e. after having added several items,
    and having calculated the length of the added data by means of
    CurPosition.
  *)



  PROCEDURE DeleteResource(filename: ARRAY OF CHAR; resID: INTEGER);
  (*
    Deletes the resource with resource identifier resID in the file
    filename of the type currently in use. If filename is empty the
    resources are searched in the current application, otherwise a
    resource file with the name 'filename' is searched according to
    the search strategy defined by the current path settings.
    NOTE: Unless you work only with the resource type 'TEXT' and
    'STR ' this routine may fail if called on a machine which
    does not support resources.
  *)

  PROCEDURE SetResourceName (fileName: ARRAY OF CHAR; resID: INTEGER;
                                 name: ARRAY OF CHAR);
  PROCEDURE GetResourceName (fileName: ARRAY OF CHAR; resID: INTEGER;
                             VAR name: ARRAY OF CHAR);

  PROCEDURE SetResourceType  (    type: ARRAY OF CHAR);
  PROCEDURE GetResourceType  (VAR type: ARRAY OF CHAR);
  (*
    Resources have a type of exactly 4 characters.  Using type
    'TEXT' will result in the use of the data fork of a text file.
    All other types will result in the storage of the data in the
    resource fork of a file or if no file is specified in the
    resource fork of the currently running application.  Avoid
    using the resource types already reserved for system use by
    Apple or other software vendors such as 'WIND', 'MENU', 'DLOG',
    'DITL', 'CODE', 'ICON', 'PICT', 'PIC2', 'SIZE', 'FREF', 'BNDL',
    'ICN#' etc.  The default type initially used by this module is
    'STR '.  NOTE: These routines work on all machines, regardless
    whether resources are actually supported.
  *)


END DMResources.

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