|
|
|
|
||
|
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.
|
||
|
|
|