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.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib