Apple's System Software Version 7.0 provides the most important test of
compatibility since the introduction of the Macintosh II. This article should help you
prepare for the release of System 7.0. For an overview of the most critical
compatibility issues and how to address them, read on.
If you've already read too many stuffy articles full of dire warnings about
compatibility, you've probably decided this one will be best suited for lining the
bottom of your filing cabinet. But before doing that, consider the case of Johnny
Appledweeb.
Ace Macintosh programmer for Cliff Grazer Enterprises, Johnny is currently putting
in the long hours to get a spread-processor-terminal-graphics-emulator out the door.
He doesn't have time to read an article like this because Cliff Grazer, his boss and
President of CGE, is all over his case. Four months ago, the company began accepting
prepayment from customers who can't wait for Johnny's program to reach their local
stores. Those customers are now beating down the doors.
Although Cliff is desperate to get the product out, he has required certain levels of
performance. The application must be kept under the 1megabyte limit, for example,
and must keep up at 19.2 kbaud through the modem port. Finally, at the last minute,
legal decides to require copy protection. Once the application ships, reviews are
excellent, customers are happy, and sales are good. Cliff is ecstatic and gives Johnny a
big raise. Johnny has time to relax a bit and maybe even catch up on some reading.
But this article doesn't interest him because he's a crack programmer, and his
application works fine. Bottom of the filing cabinet time.
Six months later, Johnny comes back from his well-earned vacation to find that Apple
has introduced new machines and released a new version of the system software.
Cliff's hopping mad because of reports of compatibility problems and complaints from
angry customers. As Johnny begins to look into the problems, he has a vague
recollection of some article he saw on compatibility. He rummages around, finds the
article, and quickly discovers it addresses his problems. But it's too late for the
customers. They don't understand compatibility, but they do understand that the
application they have been using every day no longer works. Cliff doesn't really
understand compatibility either. What he understands is he now has the expense of
shipping updated versions to keep his customers happy.
Johnny might have saved himself and others a lot of trouble if he'd spent a few minutes
with this article right away. Sure, it probably would have meant a delay in the first
release of the application, but it might also have made a second release unnecessary.
Johnny's a good programmer, and he's aware of almost everything in this article, but
if a single sentence had helped avoid problems, the article would have been worth
Johnny's time.
It may be worth your time as well to check out the compatibility of your current
application's features with System 7.0. The road gets a little dry and dusty from here
on, so grab a cold one and we'll get down to business. This article focuses on specific
areas of Macintosh programming where compatibility might trip you up today or in
the future. It isn't meant to be a guide to Macintosh programming, so if you need
additional information on a topic, such as implementation details, refer to Inside
Macintosh, volumes I-V, and the Macintosh Technical Notes.
Murphy was clearly a computer engineer. If anything can go wrong with your
application, it will, as most of us learn the hard way. Once you recognize that users
always stress your program in ways you never thought possible, you acquire defensive
programming habits.
TESTING
Always test return values for possible errors because you never know when some
unusual situation will arise. Assume that data structures will change. The Memory
Manager is an example of a manager whose data structures are changing, as described
later in this article. Avoid any portion of a data structure marked "Unused"--its use
is reserved for Apple.
MEMORY ALLOCATION
If you treat the Memory Manager with a little courtesy and respect, your application
will live a long and happy life. Keep in mind the strengths as well as the limitations of
the Memory Manager and listen to what it tells you. Believe it when it returns a nil
handle to tell you of memory allocation failure. Every application's memory needs are
different, and as you design your application, think about how memory you allocate
will be used. A little planning can ease the Memory Manager's task by reducing the
number of Memory Manager calls and minimizing fragmentation and thrashing.
You should ask yourself a few simple questions about the memory you allocate in the
heap. Is this memory you will need frequently? Rather than frequently allocating and
releasing the memory, wouldn't it be better to allocate it once at the start of your
application if it is a handle, move it high in the heap with MoveHHi and simply reuse it
when necessary?
Is it memory that shouldn't move? If so, consider the use of NewPtr instead.
Is this a large block of memory used for a very short period of time? Judicious use of
MultiFinder temporary memory can satisfy such needs and reduce overall heap usage,
allowing you to shrink your MultiFinder size partition.
Is this memory you are willing to let the Memory Manager dispose of at its discretion,
such as for a resource? Then you should consider making it purgeable. But if you've
made it purgeable, be sure to check for empty handles.
Once you have your application working, be sure to stress test your use of the Memory
Manager. You can do this by using your debugger to force heap scrambling and
purging. You can also simulate low memory conditions by running your application in
a small MultiFinder partition.
Another way to treat the Memory Manager with kindness and respect is to practice
32-bit cleanliness. Being 32-bit clean may be the single most important
compatibility issue facing developers. To understand what 32-bit cleanliness means,
let's take a closer look at Macintosh memory management. The Memory Manager
maintains free-form memory structures called heap zones. It allocates memory
blocks of various sizes within these zones to satisfy memory allocation requests by the
system and applications. Occasionally, heaps will become full or fragmented and the
Memory Manager will need to rearrange or purge blocks in a zone to create enough
contiguous space to satisfy a memory allocation request. To minimize confusion that
could occur when blocks are rearranged, the Memory Manager uses indirect
references called handles to refer to relocatable blocks in the heap.
The Memory Manager maintains a series of master pointers referring to blocks in
memory. A handle is a pointer to a master pointer, as shown in the following
illustrations.
In the example in the first illustration, two independent handles refer to the same heap
block at address $20000 via the master pointer at address $1000. Only the master
pointer should be referring to the heap block. Now, suppose the system needs to
relocate the heap block to address $30000. The second illustration shows the state of
the system after relocating the block.
The master pointer is now correctly set to point to the new block. The master pointer
is the only thing the Memory Manager had to update. The original handles 1 and 2 still
correctly refer to the heap block because they refer to the master pointer, which has
the correct location of the heap block.
The classic Macintosh has what is referred to as a 24-bit memory management
system. To the hardware, only the lower 24 bits of a 32-bit address are significant.
The upper 8 bits are always ignored in a hardware address reference. The Memory
Manager maintains certain information about heap blocks, such as whether they are
locked in memory and cannot be moved or whether they can be purged from memory to
free up space in the heap. The original Macintosh Memory Manager took advantage of
the unused upper 8 bits of the address in a master pointer to maintain flags about heap
blocks. The illustration shows the master pointer structure of the 24-bit Memory
Manager.
The most common violation of 32-bit cleanliness involves direct manipulation of
Memory Manager flags. In a 32-bit system, all 32 bits of an address are valid, and in
the case of a master pointer, the flags bits are stored elsewhere. The system provides
traps for setting and cleaning these flags: HLock/HUnlock, HPurge/HNoPurge and
HSetRBit/HClrRBit. There are also traps for getting and setting all the flags at once:
HGetState and HSetState. Some applications have taken advantage of knowledge of the
master pointer structure to set and clear the flag bits directly. Setting flag bits
directly on a 32-bit system means you are not changing the flags, but changing the
address itself, and suddenly your master pointer is pointing to a completely different
location in memory.
The issue of 32-bit cleanliness is not limited to proper use of master pointer flags.
Every address reference must assume all 32-bits are valid. If you have used any of
the upper 8 bits of pointers or handles for anything other than part of an address, you
must find an alternate representation for that information.
Two other places you can be bitten by 32-bit violations are in window definition
functions (WDEFs) and control definition functions (CDEFs). The original Macintosh
Window Manager stored the window variation code in the upper 8 bits of the handle to
the window definition procedure. If you are using custom WDEFs and need to access the
window variation code, use the GetWVariant trap. Similarly, use GetCVariant to
retrieve the variant control value for a control that was formerly stored in the high
bits of the control defproc handle.
Using pre-System 7.0 software, including A/UX 1.1, it is impossible to write a
strictly clean CDEF. The problem with custom CDEFs is that the calcCRgns message
uses the high bit of the region handle as a flag. Inside Macintosh, volume I, page 331
incorrectly advises you to "clear the high byte (not just the high bit) of the region
handle before attempting to update the region." Rather, you should clear only the high
bit (not the high byte). This makes the reasonable assumption, given the current
system software, that the handle represents only a 31-bit address and clearing the
high bit is not harmful.
With System 7.0, the Control Manager has a new way of telling your CDEF to calculate
control regions. Two new messages have been defined, calcCntlRgn and calcThumbRgn,
with values of 10 and 11 respectively. With a 32-bit Memory Manager in operation,
the Control Manager, which previously would have used calcCRgns, will now use one of
the new messages. With a 24-bit Memory Manager operating, calcCRgns will still be
used, so you must continue to support that method.
CREATING VALID HANDLES
Just as the master pointer structure will change in System 7.0, other Memory
Manager structures will be subject to change. As a precaution, you should not access
Memory Manager data structures directly or attempt to "walk the heap" yourself.
Since a handle is a pointer to a pointer, it is possible for an application to create a
handle itself, a so-called fake handle. If you pass a fake handle to any Memory Manager
routine, the Memory Manager will assume it is a valid handle under its control and
may try to relocate or dispose of it. You should never pass a fake handle to any
Macintosh trap, because you never know when that trap may itself call the Memory
Manager.
Prior to System 7.0, handles allocated with MFTempNewHandle trap were not true
handles and could not be passed, directly or indirectly, to Memory Manager traps.
They were to be treated as fake handles. Under System 7.0, this is no longer true the
Memory Manager knows how to manage such memory.
Remember that MultiFinder temporary memory is just that, temporary. It should be
allocated, used, and released as quickly as possible, preferably within one event loop
cycle. With System 7.0, you can use the HPurge Memory Manager trap to mark
handles as purgeable. You can continue to use the memory as long as MultiFinder does
not need it for another application. But be sure to check for empty handles to ascertain
if your memory has been purged.
USING STRIPADDRESS
One of the keys to 32-bit cleanliness is proper use of the StripAddress trap.
StripAddress is necessary because handle flags in master pointers can create dirty
address references. When a 24-bit Memory Manager is operating, StripAddress
clears the high byte of the address, and returns a clean address. The operation of
StripAddress is simple enough. What is not always so clear is when use of
StripAddress is necessary or even appropriate.
To understand the operation of StripAddress, consider, again, the second illustration.
Imagine that a 24-bit Memory Manager is in operation and you've called HLock to lock
the handle. The value of the master pointer will now be $80030000 because HLock
has set the lock bit in the master pointer as indicated in the third illustration. In
normal operation, you never need to concern yourself with that high byte because the
hardware ignores it. In other words, the hardware quietly strips the address for you.
But suppose you are writing a driver that needs to access a NuBus board. To do that,
you need to switch the hardware to 32-bit addressing mode using SwapMMUMode.
Now, suddenly, the hardware is no longer ignoring that high byte, so to access the
address properly you first need to call StripAddress to clean up the address.
Another situation in which StripAddress is necessary is comparing master pointers.
In the previous example, comparing the value of the master pointer before and after
calling HLock would lead you to conclude the master pointer is now pointing to a
different block because the comparison looks at all 32 bits. To be sure you are
comparing the relevant portions, namely the addresses, call StripAddress before
comparing master pointers.
If a 32-bit Memory Manager is in operation, StripAddress will return the address
unchanged, because all 32 bits of the address are valid. If you have used StripAddress
correctly, you need never worry whether a 24-bit or 32-bit Memory Manager is
operating, because StripAddress does the right thing.
Finally, do you need to call StripAddress on other addresses, such as handles? No,
because there should be no extraneous bits set in the high byte of handles. If you are
using the high byte of handles for your own purposes, go directly to the beginning of
this section on 32-bit cleanliness. Do not pass Go do not collect $200.
FILE ACCESS
Use the File Manager for all your file access. Avoid assumptions about the underlying
file and directory structure. Not only has the Macintosh file system changed in the
past, but you might not even be accessing a Macintosh volume. Foreign file systems
such as DOS, ProDOS®, High Sierra ISO 9660, and Unix are all supported. If your
application is running under A/UX, there may be no Macintosh volumes. These file
system differences create many subtle problems. For example, Unix filenames are
case-sensitive, whereas Macintosh names are not. Unix uses '/' as a pathname
delimiter, while Macintosh uses ':'. Different file systems may have different
restrictions on the length of filenames. Always use SFGetFile and SFPutFile. Not only
will this ensure maximum compatibility across file systems, but it will be comforting
to your users that your application looks and behaves like other Macintosh
applications.
Apple is working to make printing easier for Macintosh programmers in the near
future. Meanwhile, we can offer some help in two areas that often cause problems
when printing: handling print records and using PostScript.
HANDLING PRINT RECORDS
Some applications set fields in the print record to change the default settings of items
in the print dialogs. Rather than modify these fields, applications should just save the
print record after the user has configured it. The best method for saving the record is
to save it as a resource in your document's resource fork. Since a valid handle already
points to the print record, creating a resource is easy:
/* This is an example of saving a print record into a resource */
/* file. Saving the print record in document resource files */
/* provides a method of retaining the user setting from the last */
/* print job. For example, if a user elects to print a document */
/* using landscape orientation, that information is stored in the */
/* print record. If the record is saved with the document, the */
/* orientation information will be available for the next time the */
/* document is printed. When the 'Page Setup' dialog is */
/* presented, the user’s choices from the last time the document */
/* was printed will be displayed as defaults. This provides a */
/* convenient, device independent method for saving print job */
/* information. */
/* */
/* NOTE: Information from the Page Setup dialog is saved into */
/* the print record. Information from the Print dialog (i.e. # of */
/* copies, page range...) is considered to be per job */
/* information, and is not saved. This method will not allow you */
/* to provide new defaults for the PrJobDialog. */
/* */
/* Version When Who What */
/* 1.0 7/18/89 Zz First release. */
/* */
#include <Values.h>
#include <Types.h>
#include <Resources.h>
#include <QuickDraw.h>
#include <Fonts.h>
#include <Events.h>
#include <Windows.h>
#include <Menus.h>
#include <TextEdit.h>
#include <Dialogs.h>
#include <Desk.h>
#include <ToolUtils.h>
#include <Memory.h>
#include <SegLoad.h>
#include <Files.h>
#include <OSUtils.h>
#include <OSEvents.h>
#include <DiskInit.h>
#include <Packages.h>
#include <Printing.h>
#include <Traps.h>
/* POPT = Print OPTions. This type can be anything */
/* but to avoid confusion with Printing Manager */
/* resources, the following types should NOT be */
/* used: PREC, PDEF, & POST... */
#define gPRResType 'POPT'
/* This can also be any value. Since there should */
/* only be one print record per document, the ID is */
/* a constant. */
#define gPRResID 128
/* Resource name. */
#define gPRResName "\pPrint Record"
/* Define the globals for this program... */
THPrint gPrintRecordHdl;
short gTargetResFile;
/* ReportError */
/* */
/* This procedure is responsible for reporting an error to the */
/* user. This is done by first converting the error code passed */
/* in theError into a message that can be displayed for the user. */
/* See Technical Note #161, "When to call PrOpen and PrClose" */
*/
void ReportError(theError)
OSErr theError;
{
/* Real programs handle errors by displayed comprehensible */
/* error messages. */
/* This is NOT a real program... */
if (theError != noErr)
SysBeep(10);
}
/* InitializePrintRecord */
/* */
/* This procedure is responsible for initializing a newly created */
/* print record. It begins by calling PrintDefault to fill in */
/* default values, and then presents the standard 'Page Setup' */
/* dialog allowing the user to specify page setup options. The */
/* modified print record is then returned. */
void InitializePrintRecord(thePrintRecord)
THPrint thePrintRecord;
{
Boolean ignored;
PrOpen();
if (PrError() == noErr) {
PrintDefault(thePrintRecord);
ignored = PrStlDialog(thePrintRecord);
}
PrClose();
}
/* SavePrintRecord */
/* */
/* This procedure is responsible for saving a print record into a */
/* resource file. On entry, the print record should be */
/* initialized, and the resource file should be open with */
/* permission to write. */
void SavePrintRecord(thePrintRecord, theResFile)
THPrint thePrintRecord;
short theResFile;
{
short currentResFile;
Handle existingResHdl;
Handle newResHdl;
OSErr theError;
/* First save the currently selected resource file (before */
/* calling UseResFile). */
currentResFile = CurResFile();
/* Now select the target resource file. */
UseResFile(theResFile);
theError = ResError();
if (theError == noErr) {
existingResHdl = GetResource(gPRResType, gPRResID);
if (existingResHdl != NULL) {
/* There is already a print record resource in this file, so */
/* we need to delete it before adding the new one. */
RmveResource(existingResHdl);
theError = ResError();
if (theError == noErr) {
/* If the resource was successfully removed, dispose */
/* of its memory and update the resource file. */
DisposHandle(existingResHdl);
UpdateResFile(theResFile);
}
}
if (theError == noErr) {
/* Okay, now we have successfully opened the file, and */
/* deleted any previously saved print record resources. */
/* Finally we can add the new one... */
/* Since the Resource Manager is going to keep the handle */
/* we pass it, we need to make a copy before calling */
/* AddResource. We’ll let the system do it for us by */
/* calling HandToHand. */
newResHdl = (Handle)thePrintRecord;
theError = HandToHand(&newResHdl);
if (theError == noErr) {
AddResource(newResHdl, gPRResType, gPRResID,
gPRResName);
theError = ResError();
if (theError == noErr)
UpdateResFile(theResFile);
theError = ResError();
}
}
}
if (theError != noErr)
ReportError(theError);
/* Be polite and restore the original resource file to the top */
/* of the chain. */
UseResFile(currentResFile);
}
/* GetPrintRecord */
/* */
/* This function is responsible for loading a resource containing */
/* a valid print record. On entry theResFile should be open with */
/* permission to read. */
THPrint GetPrintRecord(theResFile)
short theResFile;
{
short currentResFile;
Handle theResource;
OSErr theError;
currentResFile = CurResFile();
UseResFile(theResFile);
theError = ResError();
if (theError == noErr) {
theResource = GetResource(gPRResType, gPRResID);
theError = ResError();
if (theError == noErr) {
PrOpen();
theError = PrError();
if (theError == noErr) {
if (PrValidate((THPrint)theResource)) ;
}
PrClose();
}
}
if (theError != noErr)
ReportError(theError);
UseResFile(currentResFile);
return((THPrint)theResource);
}
/* TestPrintRecord */
/* */
/* This procedure is used to test a print record. It will print */
/* a line of text using the options specified in thePrintRecord */
/* passed. On exit, a line of text will have been printed. */
void TestPrintRecord(thePrintRecord)
THPrint thePrintRecord;
{
GrafPtr currentPort;
TPPrPort thePMPort;
OSErr theError;
TPrStatus thePMStatus;
GetPort(¤tPort);
PrOpen();
if (PrError() == noErr) {
if (PrJobDialog(thePrintRecord)) {
thePMPort = PrOpenDoc(thePrintRecord, NULL, NULL);
if (PrError() == noErr) {
PrOpenPage(thePMPort, NULL);
if (PrError() == noErr) {
SetPort(&thePMPort->gPort);
MoveTo(100, 100);
DrawString("\pThis is a test...");
}
PrClosePage(thePMPort);
}
PrCloseDoc(thePMPort);
if (((*thePrintRecord)->prJob.bJDocLoop == bSpoolLoop)
&& (PrError() == noErr))
PrPicFile(thePrintRecord, NULL, NULL, NULL,
&thePMStatus);
}
}
theError = PrError(); /* Any errors? */
PrClose(); /* Close the Printing Manager before */
/* attempting to report the error. */
if (theError != noErr) /* If there was an error during */
/* printing...*/
ReportError(theError); /* ...report the error to the user. */
SetPort(currentPort);
}
main()
{
InitGraf(&qd.thePort);
InitFonts();
InitWindows();
InitMenus();
TEInit();
InitDialogs(NULL);
InitCursor();
/* Get the ID of our resource file. Since we were just */
/* opened, the CurResFile() will be ours. In a real */
/* application, the resource file ID would be the ID */
/* of your application’s document file. */
gTargetResFile = CurResFile();
/* Create a valid print record */
gPrintRecordHdl = (THPrint)NewHandle(sizeof(TPrint));
if (gPrintRecordHdl != NULL) {
/* Okay, we got a print record, now initialize it. */
InitializePrintRecord(gPrintRecordHdl);
/* Now save the print record into the resource file. */
SavePrintRecord(gPrintRecordHdl, gTargetResFile);
/* Now that it’s saved, kill it off. We’ll restore it by */
/* calling GetPrintRecord. */
DisposHandle((Handle)gPrintRecordHdl);
gPrintRecordHdl = NULL;
/* Now get the print record from the file. Since the */
/* record will be loaded as a resource handle anyway, */
/* let GetPrintRecord allocate the handle. */
gPrintRecordHdl = GetPrintRecord(gTargetResFile);
if (gPrintRecordHdl != NULL) {
/* Now use the print record to see if the information */
/* we saved was preserved... */
TestPrintRecord(gPrintRecordHdl);
} else
ReportError(MemError());
} else
ReportError(MemError());
/* Kill the print record (if it was created) and go home... */
if (gPrintRecordHdl != NULL)
DisposHandle((Handle)gPrintRecordHdl);
}
There are several points to remember when using this technique. Use a resource type
not used by the Printing Manager so it doesn't become confused. Types to avoid include
'PREC', 'PDEF' and 'POST'. Remember that lowercase resource types are reserved for
use by Apple. You also should not make assumptions about the size of the record. Use
GetHandleSize if you really need to know. This allows for the record to grow in size in
the future. Finally, when rereading the record from your document, be sure to pass it
to PrValidate before using it in case the user has changed printers or print drivers
since last printing the document.
USING POSTSCRIPT
Some applications prefer to bypass QuickDraw and print using PostScript instead.
This often results in poor or nonexistent support for printers such as the
ImageWriter and LaserWriter II SC. It also means relying on a method for
determining which printer is in use, such as checking the wDev field in the TPrStl
record.
One method for printing PostScript without relying on the type of printer being used
is using the TextIsPostScript PicComment:
PicComment (PostScriptBegin, 0, NIL); PicComment (TextIsPostScript, 0, NIL); DrawString (ThePostScript); PicComment (PostScriptEnd, 0, NIL);
The problem with this technique is that because non-PostScript printers ignore the
TextIsPostScript PicComment, DrawString, which is a QuickDraw procedure, literally
sends ThePostScript to the printer, resulting in garbage being printed. A better
technique is using the PostScriptHandle PicComment. Because this comment is only
understood by PostScript drivers, it avoids the QuickDraw/ PostScript interaction
just described:
PicComment (PostScriptBegin, 0, NIL); PicComment (PostScriptHandle, GetHandleSize (ThePostScript), ThePostScript); PicComment (PostScriptEnd, 0, NIL);
Further problems occur with applications that never print using QuickDraw but only
use PostScript. Some versions of the LaserWriter® driver assume that if they see no
QuickDraw, nothing was printed on the page and no output occurs. This can be avoided
by embedding some nonprinting QuickDraw in your code. Immediately after calling
PrOpenPage, issue the following calls:
PenSize (0,0); MoveTo (10, 10); Line (0,0); PenSize (1,1);
This technique also solves a problem with background printing. In this case, the
Printing Manager starts off each page with an empty default clipping region. Without
seeing any valid QuickDraw calls, this region is never altered and your nice PostScript
output is clipped entirely off the page. For more details on printing, see the article on
"The Perils of PostScript" in this issue.
System 7.0 will introduce an alternate way of dealing with fonts. While this new
technology won't cause problems for most applications, you should be aware of a few
issues. Any application that allows user font selection will be affected by the new
outline font technology. The most obvious feature is that any size font is now available.
That means a list of point sizes in a menu is no longer sufficient. If you currently
combine font selection and font size selection in a dialog box, be sure to include an
editable field that allows the user to type in any point size. If you now have a list of
common sizes in a menu, include an "Other..." menu item that displays a similar dialog
box with an editable field.
Since Apple introduced the LaserWriter, there has been a problem about where to get
font metrics. The most compatible method is simply to call FontMetrics and read the
metrics from the width table. For one reason or another, however, applications have
seen fit to read metrics directly from the 'FOND' resource. The addition of outline fonts
adds another layer of complexity. Outline fonts will store metric information in the
'sfnt'. Accessing metrics in the 'FOND' could give invalid data. If you are currently
accessing the 'FOND' directly, you will have to revise to take advantage of 'sfnt's.
You can greatly expand the market for your product if you do not make assumptions
about your user's language. Following a few simple rules can make your application
much easier to localize. Don't simply assume, like many C programmers, that a
character is one byte. Using the C routine strcmp, for example, to sort strings can
give completely wrong results in languages other than English. Use IUCompStr
instead. Determine the local conventions for decimal point, thousands separator, list
separator, and time cycle from the appropriate international resource when
performing input and output. Script Manager 2.0 routines, if available, can make this
even easier by doing the right thing for you automatically. For example, the
Str2Format routine can take input in one language and convert it to a canonical form
that can be used by Format2Str to output the string for a user in a completely
different country.
Higher-level issues, such as the ones just discussed, are likely to affect all
applications. But a lot of code that gets written needs to work at a lower level-- either
accessing memory in strange ways or depending on tricks in assembly language, for
example. The remainder of this article will take a look at some of those issues.
LOW MEMORY GLOBALS
Applications should avoid reliance on low-memory globals. In particular,
undocumented low-memory globals must be avoided since they are most likely to
change. But even dependence on well-known globals can be avoided. For example, the
TickCount trap returns the same value as the low memory global Ticks. TickCount is
supported under A/UX, while Ticks is not, so use of the trap guarantees compatibility.
In general, if a trap is available, always use it. And if a glue routine is available, you
should use it as well. Then if a change is necessary, you need only update your
development system and recompile to implement the change. For the same reason, use
of glue routines is also good advice for assembly-language programming.
There is an exception to this rule. The Journaling Driver (see IM I-261) patches key
Event Manager traps : GetMouse, Button, GetKeys, and TickCount. The Journaling
Driver is now used exclusively by MacroMakerTM, and unfortunately the driver's
patches are not reentrant. This means you cannot safely use these traps in interrupt
or VBL code. If you experience strange system hangs only when MacroMaker is
installed, this is probably the cause and your code should instead reference the
appropriate low-memory globals for the information you need.
SELF-MODIFYING CODE
Applications that use self-modifying code can present serious compatibility issues.
There are two kinds of self-modifying code. The first kind involves actually changing
machine instructions on the fly. Such code, popular in copy protection schemes,
crashes and burns on Macintoshes that use an instruction cache. For example, after a
sequence of instructions has been executed and cached by the Macintosh II, some code
comes along, modifies the original instructions, and tries to execute them again. But
the CPU says, "Ah ha! I already know what these instructions are" and tries to execute
the cached instructions, which is not what the programmer originally intended.
Fortunately, the Macintosh II and natural selection have made such self-modifying code
virtually extinct.
A second, subtler form of self-modifying code keeps variables in the code segment
itself. A typical example is the use of DC.W or DC.L directives to allocate variables in
the same segment as the actual code. Such code avoids the earlier problem because it is
not actually modifying instructions. The catch is that future operating systems may
make 'CODE' segments read-only, and when that code tries to write to its variables, it
will fail. Of course, read-only use of such data, such as storing string constants
within code segments, is valid. It's fine to do this when no alternative is available. You
won't crash in the foreseeable future.
A variety of small tasks, such as VBL tasks and completion routines, run
asynchronously on the Macintosh. Because they are executed asynchronously, they
cannot be assured that register A5, which by convention points to the application's
global variables, is valid when they are called. A common technique used in this case
was to store a copy of A5 in with the code so these routines could use the saved value to
access global variables.
It's possible to avoid such self-modifying code, as the following MPW sample code
illustrates. The trick here is that in creating a VBL task you must pass a record
describing the task to the system. When the VBL task is invoked, the system sets up
register A0 to point to the start of this record. While the record itself does not contain
storage for A5, it's simple to embed the VBL task record into a larger record, or in
this case a C struct, that does have room for A5, or anything else you deem important,
such as a handle. An inline function called at the start of the VBL task converts A0 into
a pointer to the record. Then the task can access anything it needs.
#include <Events.h>
#include <OSEvents.h>
#include <OSUtils.h>
#include <Dialogs.h>
#include <Packages.h>
#include <Retrace.h>
#include <Traps.h>
#define INTERVAL 6
#define rInfoDialog 140
#define rStatTextItem 1
/*
* These are globals which will be referenced from our VBL Task
*/
long gCounter; /* Counter incremented each time our VBL gets */
/* called */
/*
* Define a struct to keep track of what we need. Put theVBLTask
* into the struct first because its address will be passed to our
* VBL task in A0
*/
struct VBLRec {
VBLTask theVBLTask; /* the VBL task itself */
long VBLA5; /* saved CurrentA5 where we can find it */
};
typedef struct VBLRec VBLRec, *VBLRecPtr;
/*
* GetVBLRec returns the address of the VBLRec associated with
* our VBL task. This works because on entry into the VBL task,
* A0 points to the theVBLTask field in the VBLRec record, which
* is the first field in the record and is the address we return.
* Note that this method works whether the VBLRec is allocated
* globally, in the heap (as long as the record is locked in memory)
* or if it is allocated on the stack as is the case in this
* example. In the latter case this is OK as long as the procedure
* which installed the task does not exit while the task is running.
* This trick allows us to get to the saved A5, but it could also
* be used to get to anything we wanted to store in the record.
*/
VBLRecPtr GetVBLRec ()
= 0x2008; /* MOVE.L A0,D0 */
/*
* DoVBL is called only by StartVBL ()
*/
void DoVBL (VRP)
VBLRecPtr VRP;
{
gCounter++; /* Show we can set a global */
VRP->theVBLTask.vblCount = INTERVAL;
/* Set ourselves to run again */
}
/*
* This is the actual VBL task code. It uses GetVBLRec to get
* our VBL record and properly set up A5. Having done that, it
* calls DoVBL to increment a global counter and sets itself to
* run again. Because of the vagaries of MPW C 3.0 optimization,
* it calls a separate routine to actually access global variables.
* See Tech Note #208 - "Setting and Restoring A5" for the
* reasons for this, as well as for a description of SetA5.
*/
void StartVBL ()
{
long curA5;
VBLRecPtr recPtr;
recPtr = GetVBLRec (); /* First get our record */
curA5 = SetA5 (recPtr->VBLA5); /* Get the saved A5 */
/* Now we can access globals */
DoVBL (recPtr); /* Call another routine to do actual work */
(void) SetA5 (curA5); /* Restore old A5 */
}
/*
* InstallVBL creates a dialog just to demonstrate that the global
* variable is being updated by the VBL Task. Before installing
* the VBL, we store our A5 in the actual VBL Task record, using
* SetCurrentA5 described in Tech Note #208. We’ll run the VBL,
* showing the counter being incremented, until the mouse button
* is clicked. Then we remove the VBL Task, close the dialog, and
* remove the mouse down events to prevent the application from
* being inadvertently switched by MultiFinder.
*/
void InstallCVBL ()
{
VBLRec theVBLRec;
DialogPtr infoDPtr;
DialogRecord infoDStorage;
Str255 numStr;
OSErr theErr;
Handle theItemHandle;
short theItemType;
Rect theRect;
gCounter = 0; /* Initialize our global counter */
infoDPtr = GetNewDialog (rInfoDialog, (Ptr) &infoDStorage,
(WindowPtr) -1);
DrawDialog (infoDPtr);
GetDItem (infoDPtr, rStatTextItem, &theItemType, &theItemHandle,
&theRect);
/*
* Store the current value of A5 in the MyA5 field. For more
* information on SetCurrentA5, see Tech Note #208 - "Setting
* and Restoring A5".
*/
theVBLRec.VBLA5 = SetCurrentA5 ();
/* Set the address of our routine */
theVBLRec.theVBLTask.vblAddr = (VBLProcPtr) StartVBL;
theVBLRec.theVBLTask.vblCount = INTERVAL; /* Frequency of task,
in ticks */
theVBLRec.theVBLTask.qType = vType; /* qElement is a VBL task */
theVBLRec.theVBLTask.vblPhase = 0;
/* Now install the VBL task */
theErr = VInstall ((QElemPtr)&theVBLRec.theVBLTask);
if (!theErr) {
do {
NumToString (gCounter, numStr);
SetIText (theItemHandle, numStr);
} while (!Button ());
theErr = VRemove ((QElemPtr)&theVBLRec.theVBLTask);
/* Remove it when done */
}
/* Finish up */
CloseDialog (infoDPtr); /* Get rid of our dialog */
FlushEvents (mDownMask, 0); /* Flush all mouse down events */
}
PRIVILEGED INSTRUCTIONS
Under the current Macintosh operating system, the CPU operates in the supervisor
state and applications are allowed to use any and all 680x0 instructions, with the lone
exception of the Test And Set (TAS) instruction, which is not supported by the
hardware. The .A/UX operating system forces applications to run in the user state, and
applications that use privileged instructions reserved for the supervisor state will
fail. Examples of such instructions are MOVE, ANDI, and EORI instructions with the
status register (SR) as either the source or the destination. Typically, these
instructions are used to alter the condition code register (CCR), which is the low byte
of the SR. Using these instructions with the CCR as the source or destination instead of
the SR will accomplish the same thing without causing your application grief. Certain
floating point instructions such as FSAVE and FRESTORE are also privileged and should
be avoided. As we mentioned, A/UX does not allow the use of privileged instructions
and is a good test of compatibility in this case.
DIRECT HARDWARE ACCESS
If you think you need direct access to hardware, let Apple know. It may be acceptable
on other personal computers to access hardware directly, but it is decidedly
anti-social on the Macintosh and absolutely verboten under operating systems with
multi-user protection like A/UX. Beware of schemes for copy protection or
performance enhancement that rely on direct hardware access. Macintosh hardware
has changed in the past, and it will change in the future. Each new machine may mean
yet another revision of your application.
TRAP PATCHING
Trap patching is very useful for overriding or enhancing system trap handling. It is
used by the system, for example, to correct errors in the Macintosh ROM. Many
applications also use it to provide additional functionality. Because it is very difficult
to anticipate all the possible side effects of your patch, maintaining compatibility is
difficult, too. Before writing a patch, you should decide if it's absolutely essential.
Often the results you need can be achieved without the patch.
Suppose, for example, you decide to patch ExitToShell. This may sound like an
excellent way for your program to get one last chance at closing files or doing
whatever other cleanup is necessary before exiting. Whether ExitToShell is called in
response to a user's Quit command or because of some fatal error condition, your patch
would always have a chance to clean up. But rather than having ExitToShells all over
your code, you could achieve the same result by calling a single, common exit routine
that performed the cleanup and then called ExitToShell.
If you absolutely must trap patch, here are some general guidelines. Don't make
assumptions about the format of the trap dispatch table. In particular, don't try to
read or write entries in the trap dispatch table directly--use GetTrapAddress and
SetTrapAddress instead. If your patch only applies to your application, install it in
your application heap. Otherwise, install it in the system heap. Application heap
patches will be swapped out by MultiFinder when your application is switched out.
Because system heap patches will apply to all applications that use the trap, use them
only when absolutely necessary.
You cannot assume that a valid A5 world exists when your patch is invoked. Register
A5 points to the base of an application's global variables, and A5 world refers to an
application's global address space. MultiFinder maintains different A5 worlds for each
running application. Your patch cannot assume when it is called that A5 points to your
application's global variables. If it needs access to global variables, you must save a
copy of A5 before installing your patch. Then the patch needs to preserve the current
value of A5, set the saved value, and restore the original A5 on exit. (See Technical
Note #208.) Your patch should avoid use of the Memory Manager if the trap could be
invoked at interrupt time or if memory could move during your patch.
Finally, you must not tail patch. In a normal patch, your code completes its task and
then invokes the standard trap code to complete the patch. In a tail patch, your code
regains control after the standard trap code completes. The problem with this
technique is that many of the ROM patches are themselves tail patches, and they rely
on knowledge of the caller to accomplish their task. If the ROM patch expects to be
called from a ROM address, but is instead called by your patch code, it can become
confused. If you JSR to invoke the standard trap code, then you are tail patching. The
correct way is to JMP to the starting address of the code.
It may be useful to know that Apple's implementation of Unix, A/UX, offers a major
test for compatibility with System 7.0. A/UX provides a very different environment
for Macintosh applications, but applications that follow the compatibility guidelines
work without alteration under A/UX. If your application works correctly under A/UX,
it stands a very good chance of working correctly under System 7.0.
If you've gotten this far, you are likely to avoid Johnny Appledweeb's fate. You
obviously are seriously concerned for your customers and willing to go that extra step
to minimize future compatibility problems. It may seem at times that Apple goes out
of its way to stretch its own rules, but that is not the case. It is simply impossible to
foresee all future hardware and software changes. Incompatibility is unfortunately an
ongoing battle. Your part of that battle goes beyond this article and requires you to
keep abreast of changes as Apple announces them.
Dave Radcliffe, "Technical Sherpa," has been with Apple about a year and a half,
putting his chemistry degree from Washington University to work in A/UX® and MPW
technical support. Actually, he discovered his true calling while working with the
computers in the UCLA chemistry research labs. When asked how he's changing the
world one person at a time, Dave replied, "home-brewed beer." In addition to home
concoctions, he's into hiking, backpacking, and photography. *