Resource Mover Modula-2
Volume Number: | | 2
|
Issue Number: | | 3
|
Column Tag: | | Modula-2 Mods
|
A Resource Mover in Modula-2 
By Tom Taylor, Hewlett Packard, Santa Clara, MacTutor Contributing Editor
Moving Resources in Modula-2
The Macintosh's built-in ability to deal with resources can both complicate and simplify life for the Mac programmer. Resources allow many items that would normally be hardcoded into a program to be separated from the code and made independent of program compilation. Typical resources include windows, dialogs, controls, and icons. Many utility-type programs need to move resources from one file to another. This article will present the steps necessary to move resources and provide the sources to a library module and a demonstration program.
Clearing a resource file
The first routine I needed while designing a module to copy resources was a procedure to clear a resource file of all resources. In dealing with the Mac, it seems like there's always a ToolBox routine at hand to do exactly what you want. In this case, I could find no routine to clear a resource file. My first cut at writing a resource clearing routine worked by finding all the resources that belonged to the desired resource file and then individually removing the resources by calling RmveResource. For some unexplainable reason, this method did not work. Sometimes it would take more than one pass over the file to delete all the resources. Out of frustration, I resorted to a more brute-force, direct technique. This method involved opening the resource file using the File Manager and directly manipulating its contents to mimick that of an empty, newly created resource file. Figure one shows the contents of a resource file after it has been "cleared" by my ClearRsrcFile routine (see the commented routine in the MoveResources.MOD file).
PROCEDURE ClearRsrcFile
(file : ARRAY OF CHAR) : INTEGER;
There are two ways to open a resource file. Normally, the Resource Manager's OpenResFile routine is called. This routine looks only on the default volume for the specified file (unless one passes the volume name as part of the filename; a no-no according to Apple and might not work with the HFS). Therefore, always do a SetVol to the volume containing the resource file before calling OpenResFile. It is interesting to note that the Resource Manager in the new ROMs includes a call called OpenRFPerm that allows you to specify the volume reference number along with the resource file (and permission too!). The other way to open a resource file is with the File Manager's FSOpenRF call. FSOpenRF treats the resource file as a traditional data file and OpenResFile treats the file as a collection of resources. Since the ClearRsrcFile routine needs to go in and fool with the resource file directly, I used the FSOpenRF call to open the file.

Figure 1. A cleared resource file.
Copying a resource file
The next step in designing a resource copying module was to design a resource copying routine. I wanted the routine to be very simple from a user's point of view. The routine takes two resource file reference numbers, one the source and the other the destination, and simply copies all resources from one file to the other. Other parameters of the routine specify whether information about each resource should be printed as the resource is copied and whether duplicate resources should be replaced or flagged as an error. Finally, a fairly involved error record is passed to the resource copying routine so that if an error occurs, the caller has a chance at doing some sort of sophisticated error recovery.
PROCEDURE MoveRsrcs
(src, dest : INTEGER;
noisy : BOOLEAN;
allowDuplicate: BOOLEAN;
VAR error : RsrcErr);
The resource copying routine (called MoveRsrcs in the the MoveResources.MOD file), basically follows these steps:
1- Turn off resource loading by calling SetResLoad(FALSE). This tells the Resource Manager not to load the resource data associated with each resource into memory (of course, those resources marked as "preloadable" will have already been loaded by the OpenResFile call). After every Resource Manager call, the procedure CheckError is called to check for a Resource Manager error. If an error did indeed occur, resource loading is turned back on by calling SetResLoad(TRUE). Leaving a program without setting resource loading back on causes serious problems!
2- Find all the resources associated with the source resource file. We loop through all the resource types and the various resources of each type (by calling CountTypes and CountResources) and get a handle to each resource. Unfortunately, we must look at every resource from every open resource file just to find the resources that belong to a specific file. When you ask the Resource Manager for a resource, it checks all of the open resource files and there is no way to limit its search to one file (although the order of the search can be changed). The new ROMs, however, now implement a number of new Resource Manager calls that only search a single resource file (routines such as: Count1Resources, Get1IndType, etc). Of course, by using any of the new ROM calls, the program wouldn't work on a Mac with the old ROMs. The HomeResFile routine tells us which resource file a resource belongs to. If the resource belongs to the source file we are interested in, then the handle to the resource is saved by our module in a linked list.
3- Loop through the selected resources. Each selected resource handle is removed from the linked list.
a- Load the resource into memory by specifically calling LoadResource. LoadResource will load the resource even though SetResLoad is FALSE.
b- Call GetResInfo to find out the resource's name, type, and id.
c- "Detach" the resource with DetachResource. In other words, tell the Resource manager to "forget" about it.
d- Check to see if the destination resource file already contains the same resource and handle a possible collision.
e- Add the resource to the destination resource file.
4- Turn resource loading back on (SetResLoad(TRUE)) and return.
Step 2 mentioned that the resource manager searches all the open resource files when performing various operations. In the case of MacModula-2, these files could include: the System file, the Modula-2 interpreter, the .LOD file that uses the resource copier module, the source resource file (the one we're copying), and the destination resource file (the one we're copying to). Actually, the Resource Manager keeps a linked list of all the open files and it sequentially searches the files in the list. By calling UseResFile, one can change the order of this linked list. In fact, UseResFile is called in a number of places where it is desireable that either the source or destination file be searched first.
Figure 2. MoveResource program.
An applications program
The sample application program provides a front-end to the MoveResource module (see figure 2). The program (called MoveResources.MOD) displays the SFGetFile dialog box and prompts the user to select a source resource file. If the file has a resource fork, the user is asked to select a destination resource file and decide whether the destination resources should be cleared. Finally, the resources are copied from the source to the destination file.
Since the Mac is so tied to resources, it's important that we understand how to manipulate these resources. I hope that you will be able to make use of the code or concepts discussed in this article in your own projects.
----------- MoveResources.DEF -----------
(* Tom Taylor
3707 Poinciana Dr. #137
Santa Clara, CA 95051
*)
DEFINITION MODULE MoveResources;
(* This module is used for copying
resources from one file to another. *)
FROM ResourceManager IMPORT
ResType;
EXPORT QUALIFIED
RsrcErrType, RsrcErr,
MoveRsrcs, ClearRsrcFile;
TYPE
(* Possible errors during a resource copy *)
RsrcErrType = (noRsrcError,
duplicateRsrc,
otherRsrcError);
RsrcErr = RECORD
errType : RsrcErrType;
CASE RsrcErrType OF
duplicateRsrc: dupInfo :
RECORD
(* The ID and type of
the offending duplicate
resource. *)
dupID : INTEGER;
dupType : ResType;
END;
| otherRsrcError: errNum :
(* Mac error number *)
INTEGER;
ELSE
END;
END;
PROCEDURE MoveRsrcs (src, dest : INTEGER;
noisy : BOOLEAN;
allowDuplicate : BOOLEAN;
VAR error : RsrcErr);
(* Moves all resources from the src resource
file number to the dest resource file number.
If noisy is true, then information is printed
about each resource as it is copied. If
allowDuplicate is true, then a destination
resource of the same type and ID as a source
resource is replaced by the source resource.
If allowDuplicate is false, then an error is
returned when a duplicate is found. *)
PROCEDURE ClearRsrcFile
(file:ARRAY OF CHAR) : INTEGER;
(* Clears all resources in the resource file
specified by 'file'. ClearRsrcFile returns
0 if no error occured or the error number. *)
END MoveResources.
----------- MoveResources.MOD -----------
(* Tom Taylor
3707 Poinciana Dr. #137
Santa Clara, CA 95051
*)
IMPLEMENTATION MODULE MoveResources;
(* This module contains the code for
copying resources from one file
to another. *)
IMPORT Storage;
FROM InOut IMPORT
Write, WriteString,
WriteInt, WriteLn;
FROM MacSystemTypes IMPORT
Handle, Str255, LongCard;
FROM ResourceManager IMPORT
CloseResFile, ResError,
CountTypes, ResType,
OpenResFile, GetIndType,
CountResources, HomeResFile,
GetIndResource, ReleaseResource,
SetResLoad, CreateResFile,
LoadResource, UseResFile,
GetResInfo, AddResource,
DetachResource, GetResource,
RmveResource;
FROM FileManager IMPORT
FSOpenRF, GetVol,
FSClose, FSWrite,
SetEOF;
FROM Strings IMPORT
StrModToMac;
FROM SYSTEM IMPORT
ADR;
CONST
ResNotFound = -192;
NoErr = 0;
FileNotFoundErr = -43;
MODULE LinkedList;
(* This internal module is used
for maintaining a linked list
of resource handles. *)
IMPORT Handle;
FROM Storage IMPORT
ALLOCATE, DEALLOCATE;
EXPORT
AddRsrcNode,
RmveRsrcNode;
TYPE
RsrcPtr = POINTER TO RsrcNode;
RsrcNode = RECORD
rsrcHandle : Handle;
next : RsrcPtr;
END;
VAR
rsrcHead : RsrcPtr; (* Pointer to the
first node. *)
PROCEDURE AddRsrcNode(data : Handle);
(* This procedure adds a new node
to the front of the linked list. *)
VAR
newNode : RsrcPtr;
BEGIN
NEW(newNode);
WITH newNode^ DO
rsrcHandle := data;
next := rsrcHead;
END;
rsrcHead := newNode;
END AddRsrcNode;
PROCEDURE RmveRsrcNode() : Handle;
(* This procedure removes a node from
the front of the linked list. It
returns the resource handle found in
the node or NIL if there are no more
nodes. *)
VAR
data : Handle;
oldNode : RsrcPtr;
BEGIN
IF rsrcHead # NIL THEN
data := rsrcHead^.rsrcHandle;
oldNode := rsrcHead;
rsrcHead := oldNode^.next;
DISPOSE(oldNode);
ELSE
data := NIL;
END;
RETURN data;
END RmveRsrcNode;
BEGIN
rsrcHead := NIL; (* Init the list header *)
END LinkedList;
PROCEDURE MoveRsrcs (src, dest : INTEGER;
noisy : BOOLEAN;
allowDuplicate : BOOLEAN;
VAR error : RsrcErr);
(* Moves all resources from the src resource
file number to the dest resource file number.
If noisy is true, then information is printed
about each resource as it is copied. If
allowDuplicate is true, then a destination
resource of the same type and ID as a source
resource is replaced by the source resource.
If allowDuplicate is false, then an error is
returned when a duplicate is found. *)
VAR
theType : ResType;
rsrcHdl, destHdl : Handle;
types, rsrcs, theID : INTEGER;
rsrcName : Str255;
PROCEDURE CheckError
(VAR errRec : RsrcErr) : BOOLEAN;
(* This procedure checks to see if the last
resource procedure generated an error. If
so, then the procedure fills in the error
record. *)
VAR
resError : INTEGER;
BEGIN
resError := ResError(); (* An error? *)
IF resError # 0 THEN (* Yep... *)
WITH errRec DO
errType := otherRsrcError;
errNum := resError;
END;
(* Since we got an error,
be sure to turn resource
loading back on so the Mac
will work as expected. *)
SetResLoad(TRUE);
END;
RETURN resError # 0;
END CheckError;
BEGIN
error.errType := noRsrcError; (* Init no error *)
(* Since we are only interested in figuring
out which resources exist in the source file,
we turn off resource loading. This prevents
the heap from becoming polluted with billions
of resources. *)
SetResLoad(FALSE);
IF CheckError(error) THEN RETURN END;
(* Check out all the resource types found in
all the open resource files (which are
probably:
1- System
2- Modula-2 interpreter
3- The .LOD file that imports this
module
4- The source resource file
5- The destination resource file)
*)
FOR types := 1 TO CountTypes() DO
GetIndType(theType,types); (* get the type *)
(* Go through all the resources of a given
type. *)
FOR rsrcs := 1 TO CountResources(theType) DO
(* Get a handle to the resource. Note
that the resource isn't loaded because
we turned resource loading off. *)
rsrcHdl := GetIndResource(theType,rsrcs);
IF CheckError(error) THEN RETURN END;
(* If the resource belongs to the
source file, then we are interested
in it. *)
IF HomeResFile(rsrcHdl) = src THEN
(* Save the resource in the linked list *)
AddRsrcNode(rsrcHdl);
END;
END;
END;
(* Get a handle to a source resource
from the linked list. *)
rsrcHdl := RmveRsrcNode();
(* Process until there are no more
handles in the list... *)
WHILE rsrcHdl # NIL DO
IF noisy THEN
WriteString(' ');
Write(theType[0]); Write(theType[1]);
Write(theType[2]); Write(theType[3]);
WriteString(' ');
WriteInt(theID,0); WriteLn;
END;
(* Force the source resource to be loaded *)
LoadResource(rsrcHdl);
IF CheckError(error) THEN RETURN END;
(* Get the resource's vital stats *)
GetResInfo(rsrcHdl,theID,theType,rsrcName);
IF CheckError(error) THEN RETURN END;
(* Make the resource manager forget about
this resource. *)
DetachResource(rsrcHdl);
IF CheckError(error) THEN RETURN END;
(* Tell the resource manager to search
the dest resource file before all others *)
UseResFile(dest);
IF CheckError(error) THEN RETURN END;
(* We've already pulled a resource from the
source resource file. Try to grab the same
one from the destination file. If the grab
is successful, then we have a duplicate. *)
destHdl := GetResource(theType,theID);
IF (ResError() = NoErr) AND (HomeResFile(destHdl) = dest) THEN
IF NOT allowDuplicate THEN
(* The user requested no duplicates
so set the error and exit. *)
WITH error DO
errType := duplicateRsrc;
WITH dupInfo DO
dupID := theID;
dupType := theType;
END;
END;
(* Before getting out of here, turn
resource loading back on so the
Mac will work properly. *)
SetResLoad(TRUE);
RETURN;
ELSE
(* If we got a duplicate and its ok
with the user, zap the resource
from the destination resource file
so it can be replaced with the resource
from the source file. *)
RmveResource(destHdl);
IF CheckError(error) THEN RETURN END;
END;
END;
(* Finally, add the resource from the source
file to the destination file. The files
will be updated when they are closed. *)
AddResource(rsrcHdl,theType,theID,rsrcName);
IF CheckError(error) THEN RETURN END;
(* Set things back so the resource manager
will look at the source resource file
first. *)
UseResFile(src);
IF CheckError(error) THEN RETURN END;
(* Get another resource handle from the
linked list and process it. *)
rsrcHdl := RmveRsrcNode();
END;
UseResFile(dest);
IF CheckError(error) THEN RETURN END;
(* Turn resource loading back on so
the Mac won't get mad. *)
SetResLoad(TRUE);
IF CheckError(error) THEN RETURN END;
END MoveRsrcs;
PROCEDURE ClearRsrcFile
(file:ARRAY OF CHAR) : INTEGER;
(* Clears all resources in the resource file
specified by 'file'. ClearRsrcFile returns
0 if no error occured or the error number. *)
CONST
BufSize = 143; (* Number of words that are
to be written to the resource
file. *)
VAR
err, vRefNum, refNum : INTEGER;
filename : Str255;
rsrcBuffer : ARRAY [1..143] OF INTEGER;
i : CARDINAL;
count : LongCard;
BEGIN
(* We expect that the file that
we are attempting to clear is
found on the default volume. *)
StrModToMac(filename,file);
err := GetVol(NIL,vRefNum);
IF err # NoErr THEN RETURN err END;
(* Open the resource fork. *)
err := FSOpenRF(filename,vRefNum,refNum);
IF err = FileNotFoundErr THEN
(* If there was no resource file,
then create one. *)
CreateResFile(filename);
err := ResError();
ELSE
IF err # NoErr THEN RETURN err END;
(* The resource file already exists.
Write over the info that's there
with a resource map that makes the
resource file look empty. *)
FOR i := 1 TO BufSize DO
rsrcBuffer[i] := 0;
END;
rsrcBuffer[2] := 00100h;
rsrcBuffer[4] := 00100h;
rsrcBuffer[8] := 0001eh;
rsrcBuffer[130] := 00100h;
rsrcBuffer[133] := 00100h;
rsrcBuffer[136] := 0001eh;
rsrcBuffer[141] := 0001ch;
rsrcBuffer[142] := 0001eh;
rsrcBuffer[143] := -1;
count.h := 0;
count.l := BufSize*2;
err := FSWrite(refNum,count,ADR(rsrcBuffer));
(* Truncate the resource file to the size
of an empty resource file. *)
vRefNum := SetEOF(refNum,count);
vRefNum := FSClose(refNum);
END;
RETURN err;
END ClearRsrcFile;
END MoveResources.
----------- RsrcMover.MOD -----------
(* Tom Taylor
3707 Poinciana Dr. #137
Santa Clara, CA 95051
*)
MODULE RsrcMover;
(* This example program demonstrates
a possible use of the MoveResources
module. It allows the user to move
resources from one file to another. *)
IMPORT DialogManager;
FROM MacInterface IMPORT
InitViewPort;
FROM MoveResources IMPORT
RsrcErrType, RsrcErr,
MoveRsrcs, ClearRsrcFile;
FROM DialogManager IMPORT
GetNewDialog, DialogPtr,
ModalDialog, DisposDialog;
FROM MacSystemTypes IMPORT
LongCard, Str255;
FROM WindowManager IMPORT
WindowPtr, ShowWindow,
GetNewWindow;
FROM Strings IMPORT
StrModToMac, StrCat,
StrMacToMod, StrCpy;
FROM PackageManager IMPORT
SFReply, SFTypeList, SFGetFile;
FROM QuickDraw1 IMPORT
Point, SetPort,
TextFont;
FROM FileManager IMPORT
SetVol;
FROM ResourceManager IMPORT
OpenResFile, ResError,
CloseResFile;
FROM SYSTEM IMPORT
ADR;
FROM NumConversions IMPORT
IntToStr;
VAR
behind : LongCard;
MODULE DialogHandler;
(* This internal module exports
procedures that display
messages in dialog boxes on
the screen. *)
IMPORT
WindowPtr, behind,
Str255, StrModToMac,
ShowWindow, IntToStr,
StrCat, StrCpy;
FROM DialogManager IMPORT
GetNewDialog, DialogPtr,
ParamText, DrawDialog;
EXPORT
ShowMessage,
ShowErrorMessage;
CONST
dialogID = 978; (* Resource ID of dialog *)
VAR
dPtr : DialogPtr; (* Pointer to the dialog
box *)
PROCEDURE ShowMessage(msg : ARRAY OF CHAR);
(* ShowMessage displays a message in a static
dialog box *)
VAR
s : Str255;
BEGIN
StrModToMac(s,msg); (* Convert to Str255 *)
ParamText(s,'','',''); (* Stick the msg in the
dialog box *)
ShowWindow(dPtr); (* Display the window
if it's not up *)
DrawDialog(dPtr); (* Force the dialog
info to be drawn *)
END ShowMessage;
PROCEDURE ShowErrorMessage(msg : ARRAY OF CHAR;
error : INTEGER);
(* ShowErrorMessage is the same as ShowMessage
except that an integer error message number
is also displayed *)
VAR
errMsg : ARRAY [0..100] OF CHAR;
errNum : ARRAY [0..7] OF CHAR;
BEGIN
StrCpy(errMsg,msg); (* Make a local copy
of the string *)
StrCat(errMsg,' Error = ');(* Append a msg *)
IntToStr(error,errNum,8); (* Convert the num *)
StrCat(errMsg,errNum); (* Concat to end of
the main msg *)
ShowMessage(errMsg); (* Display the msg *)
END ShowErrorMessage;
BEGIN
(* Get the basic dialog box from the rsrc file *)
dPtr :=
GetNewDialog(dialogID,NIL,WindowPtr(behind));
END DialogHandler;
PROCEDURE SelectRsrcFile(msg : ARRAY OF CHAR;
VAR filename : ARRAY OF CHAR;
ClearTheFile : BOOLEAN):INTEGER;
(* Put up the mini-finder and let the user
select a file. Returns the resource file
ID or zero if the user wants to cancel. *)
VAR
where : Point;
reply : SFReply;
typeList : SFTypeList;
err : INTEGER;
sPtr : POINTER TO Str255;
newMsg : ARRAY [0..200] OF CHAR;
BEGIN
where.h := 90;
where.v := 120;
ShowMessage(msg);
newMsg := "That file doesn't have a resource fork! ";
StrCat(newMsg,msg);
LOOP
(* Put up mini-finder *)
SFGetFile(where,'',NIL,-1,typeList,NIL,reply);
WITH reply DO
IF NOT good THEN RETURN 0 END; (* Hit cancel? *)
(* OpenResFile doesn't know how to
deal with volumes very well... *)
err := SetVol(NIL,vRefNum);
sPtr := ADR(fName);
err := OpenResFile(sPtr^);
(* Save the filename *)
StrMacToMod(filename,sPtr^);
(* Ask clear question? *)
IF (err # -1) AND ClearTheFile AND
EraseQuestion() THEN
(* The resource file must be closed
before we can open and clear it. *)
CloseResFile(err);
err := ClearRsrcFile(filename);
IF err # 0 THEN
ShowErrorMessage(
'An error occured while clearing the resource file.',err);
END;
err := OpenResFile(sPtr^); (* Re-open the file *)
END;
IF err # -1 THEN RETURN err END;
END;
(* If we make it to here, some error occured.
Put up a message and bring up the mini-
finder again *)
ShowMessage(newMsg);
END;
END SelectRsrcFile;
PROCEDURE EraseQuestion():BOOLEAN;
CONST
eraseID = 979;
BEGIN
RETURN ShowModal(eraseID) = 1;
END EraseQuestion;
PROCEDURE ShowModal(id : INTEGER) : INTEGER;
(* ShowModal brings up the dialog with id
= 'id' and returns the number of the
button pressed. *)
VAR
dPtr : DialogPtr;
item : INTEGER;
BEGIN
dPtr := GetNewDialog(id,NIL,WindowPtr(behind));
ModalDialog(NIL,item);
DisposDialog(dPtr);
RETURN item;
END ShowModal;
CONST
windID = 913;
Chicago = 0;
GoodID = 1023;
BadID = 1024;
VAR
src, dest, err : INTEGER;
errRec : RsrcErr;
wind : WindowPtr;
destFile : ARRAY [0..100] OF CHAR;
BEGIN
behind.h := 65535; (* Setup a -1 LongInt *)
behind.l := 65535;
err := 0; (* Clear the error rememberer *)
src := SelectRsrcFile('Select a source file...',
destFile,FALSE);
IF src # 0 THEN
dest :=
SelectRsrcFile('Select a destination file...',
destFile,TRUE);
IF dest # 0 THEN
TextFont(Chicago); (* ...to make the window title
come up with the right font *)
(* Bring up a window to show the resource copy
information *)
wind := GetNewWindow(windID,NIL,
WindowPtr(behind));
SetPort(wind);
InitViewPort; (* Make Modula-2 aware of the window *)
(* Now do the work... *)
MoveRsrcs(src,dest,TRUE,FALSE,errRec);
err := INTEGER(errRec.errType); (* error occur? *)
CASE errRec.errType OF
noRsrcError:
| duplicateRsrc:
ShowMessage('Duplicate resources error!');
| otherRsrcError:
ShowErrorMessage('An error occured while copying resources',errRec.errNum);
END;
CloseResFile(src); (* Close up *)
CloseResFile(dest);
IF err = 0 THEN
err := ShowModal(GoodID);
ELSE
err := ShowModal(BadID);
END;
END;
END;
END RsrcMover.
--------------
* Tom Taylor
* 3707 Poinciana Dr. #137
* Santa Clara, CA 95051
*
* Resource file for RsrcMover
* demo program.
*
MacModula-2:RsrcMover.REL.rsrc
LODRM2MC
type DLOG
,978
Null
31 104 96 409
Invisible NoGoAway
1
0
978
,979
Null
134 102 225 401
Visible NoGoAway
1
0
979
,1023
Null
100 148 168 364
Visible NoGoAway
1
0
1023
,1024
Null
171 92 229 421
Visible NoGoAway
1
0
1024
type DITL
,978
1
staticText
5 5 55 295
^0
,979
3
BtnItem Enabled
49 33 81 113
Yes
BtnItem Enabled
49 120 81 200
No
StatText Disabled
6 20 42 277
Clear destination resource file before copying resources?
,1023
2
BtnItem Enabled
33 54 59 162
Hoaky Doaky
StatText Disabled
10 17 30 200
Resource copy successful!
,1024
2
BtnItem Enabled
24 123 48 206
Bummer!
StatText Disabled
3 5 25 333
Sorry, errors occured during the resource copy!
type WIND
,913
Copied Resources
166 106 316 406
Visible NoGoAway
4
0