TweetFollow Us on Twitter




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.

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.

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.

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.

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.

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.

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)

/* 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;

    if (PrError() == noErr) {
        ignored = PrStlDialog(thePrintRecord);
/* 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.                        */
    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.     */
            theError = ResError();
            if (theError == noErr) {
            /* If the resource was successfully removed, dispose */
            /* of its memory and update the resource file.  */
        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,
                theError = ResError();
                if (theError == noErr) 
                theError = ResError();
    if (theError != noErr)
    /* Be polite and restore the original resource file to the top */
    /* of the chain.    */

/* 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();
    theError = ResError();
    if (theError == noErr) {
        theResource = GetResource(gPRResType, gPRResID);
        theError = ResError();

        if (theError == noErr) {
            theError = PrError();
            if (theError == noErr) {
                if (PrValidate((THPrint)theResource)) ;
    if (theError != noErr)
/* 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;
    if (PrError() == noErr) {
        if (PrJobDialog(thePrintRecord)) {
            thePMPort = PrOpenDoc(thePrintRecord, NULL, NULL);
            if (PrError() == noErr) {
                PrOpenPage(thePMPort, NULL);
                if (PrError() == noErr) {
                    MoveTo(100, 100);
                    DrawString("\pThis is a test...");
            if (((*thePrintRecord)->prJob.bJDocLoop == bSpoolLoop)
                    && (PrError() == noErr))
                PrPicFile(thePrintRecord, NULL, NULL, NULL,
    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); /* the error to the user. */

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

        /* 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.                  */
        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...                   */
        } else
    } else
    /* Kill the print record (if it was created) and go home...    */
    if (gPrintRecordHdl != NULL)

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.

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

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.

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,

     *  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 */

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.

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


Community Search:
MacTech Search:

Software Updates via MacUpdate

SketchUp 19.1.174 - Create 3D design con...
SketchUp is an easy-to-learn 3D modeling program that enables you to explore the world in 3D. With just a few simple tools, you can create 3D models of houses, sheds, decks, home additions,... Read more
ClamXav 3.0.12 - Virus checker based on...
ClamXav is a popular virus checker for OS X. Time to take control ClamXAV keeps threats at bay and puts you firmly in charge of your Mac’s security. Scan a specific file or your entire hard drive.... Read more
BetterTouchTool 3.151 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom)... Read more
FontExplorer X Pro 6.0.9 - Font manageme...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
Dropbox 77.4.131 - Cloud backup and sync...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keeps them up-to-date between systems... Read more
DiskCatalogMaker 7.5.3 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Notion 1.0.7 - A unified workspace for m...
Notion is the unified workspace for modern teams. Notion Features: Integration with Slack Documents Wikis Tasks Note: This application contains in-app and/or external module purchases. Version 1.0... Read more
Microsoft Office 2016 16.16.12 - Popular...
Microsoft Office 2016 - Unmistakably Office, designed for Mac. The new versions of Word, Excel, PowerPoint, Outlook, and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more
Little Snitch 4.4.2 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
MainStage 3 3.4.3 - Live performance too...
Apple MainStage makes it easy to bring to the stage all the same instruments and effects that you love in your recording. Everything from the Sound Library and Smart Controls you're familiar with... Read more

Latest Forum Discussions

See All

Upcoming visual novel Arranged shines a...
If you’re in the market for a new type of visual novel designed to inform and make you think deeply about its subject matter, then Arranged by Kabuk Games could be exactly what you’re looking for. It’s a wholly unique take on marital traditions in... | Read more »
TEPPEN guide - The three best decks in T...
TEPPEN’s unique take on the collectible card game genre is exciting. It’s just over a week old, but that isn’t stopping lots of folks from speculating about the long-term viability of the game, as well as changes and additions that will happen over... | Read more »
Intergalactic puzzler Silly Memory serve...
Recently released matching puzzler Silly Memory is helping its fans with their intergalactic journeys this month with some very special offers on in-app purchases. In case you missed it, Silly Memory is the debut title of French based indie... | Read more »
TEPPEN guide - Tips and tricks for new p...
TEPPEN is a wild game that nobody asked for, but I’m sure glad it exists. Who would’ve thought that a CCG featuring Capcom characters could be so cool and weird? In case you’re not completely sure what TEPPEN is, make sure to check out our review... | Read more »
Dr. Mario World guide - Other games that...
We now live in a post-Dr. Mario World world, and I gotta say, things don’t feel too different. Nintendo continues to squirt out bad games on phones, causing all but the most stalwart fans of mobile games to question why they even bother... | Read more »
Strategy RPG Brown Dust introduces its b...
Epic turn-based RPG Brown Dust is set to turn 500 days old next week, and to celebrate, Neowiz has just unveiled its biggest and most exciting update yet, offering a host of new rewards, increased gacha rates, and a brand new feature that will... | Read more »
Dr. Mario World is yet another disappoin...
As soon as I booted up Dr. Mario World, I knew I wasn’t going to have fun with it. Nintendo’s record on phones thus far has been pretty spotty, with things trending downward as of late. [Read more] | Read more »
Retro Space Shooter P.3 is now available...
Shoot-em-ups tend to be a dime a dozen on the App Store, but every so often you come across one gem that aims to shake up the genre in a unique way. Developer Devjgame’s P.3 is the latest game seeking to do so this, working as a love letter to the... | Read more »
Void Tyrant guide - Guildins guide
I’ve still been putting a lot of time into Void Tyrant since it officially released last week, and it’s surprising how much stuff there is to uncover in such a simple-looking game. Just toray, I finished spending my Guildins on all available... | Read more »
Tactical RPG Brown Dust celebrates the s...
Neowiz is set to celebrate the summer by launching a 2-month long festival in its smash-hit RPG Brown Dust. The event kicks off today, and it’s divided into 4 parts, each of which will last two weeks. Brown Dust is all about collecting, upgrading,... | Read more »

Price Scanner via

Clearance 12″ 1.2GHz MacBook on sale for $899...
Focus Camera has clearance 12″ 1.2GHz Space Gray MacBooks available for $899.99 shipped. That’s $400 off Apple’s original MSRP. Focus charges sales tax for NY & NJ residents only. Read more
Get a new 2019 13″ 2.4GHz 4-Core MacBook Pro...
B&H Photo has new 2019 13″ 2.4GHz MacBook Pros on sale for up to $150 off Apple’s MSRP. Overnight shipping is free to many addresses in the US: – 2019 13″ 2.4GHz/256GB 6-Core MacBook Pro Silver... Read more
AirPods with Wireless Charging Case now on sa...
Amazon has extended their Prime Day savings on Apple AirPods by offering AirPods with the Wireless Charging case for $169.99. That’s $30 off Apple’s MSRP, and it’s the cheapest price available for... Read more
New 2019 15″ MacBook Pros on sale for $200 of...
B&H Photo has the new 2019 15″ 6-Core and 8-Core MacBook Pros on sale for $200 off Apple’s MSRP. Overnight shipping is free to many addresses in the US: – 2019 15″ 2.6GHz 6-Core MacBook Pro Space... Read more
Amazon drops prices, now offers clearance 13″...
Amazon has new dropped prices on clearance 13″ 2.3GHz Dual-Core non-Touch Bar MacBook Pros by $200 off Apple’s original MSRP, with prices now available starting at $1099. Shipping is free. Be sure to... Read more
2018 15″ MacBook Pros now on sale for $500 of...
Amazon has dropped prices on select clearance 2018 15″ 6-Core MacBook Pros to $500 off Apple’s original MSRP. Prices now start at $1899 shipped: – 2018 15″ 2.2GHz Touch Bar MacBook Pro Silver: $1899.... Read more
Price drop! Clearance 12″ 1.2GHz Silver MacBo...
Amazon has dropped their price on the recently-discontinued 12″ 1.2GHz Silver MacBook to $849.99 shipped. That’s $450 off Apple’s original MSRP for this model, and it’s the cheapest price available... Read more
Apple’s 21″ 3.0GHz 4K iMac drops to only $936...
Abt Electronics has dropped their price on clearance, previous-generation 21″ 3.0GHz 4K iMacs to only $936 shipped. That’s $363 off Apple’s original MSRP, and it’s the cheapest price we’ve seen so... Read more
Amazon’s Prime Day savings on Apple 11″ iPad...
Amazon has new 2018 Apple 11″ iPad Pros in stock today and on sale for up to $250 off Apple’s MSRP as part of their Prime Day sale (but Prime membership is NOT required for these savings). These are... Read more
Prime Day Apple iPhone deal: $100 off all iPh...
Boost Mobile is offering Apple’s new 2018 iPhone Xr, iPhone Xs, and Xs Max for $100 off MSRP. Their discount reduces the cost of an Xs to $899 for the 64GB models and $999 for the 64GB Xs Max. Price... Read more

Jobs Board

*Apple* IOS Systems Engineer - Randstad (Uni...
Apple IOS Systems Engineer **job details:** + location:Irvine, CA + salary:$45 - $55 per hour + date posted:Tuesday, July 16, 2019 + job type:Temp to Perm + Read more
Business Development Manager, *Apple* Globa...
Business Development Manager, Apple Global Tampa, FL, US Requisition Number:73805 As a Global Apple Business Development Manager at Insight, you proactively Read more
*Apple* Systems Architect/Engineer, Vice Pre...
…its vision to be the world's most trusted financial group. **Summary:** Apple Systems Architect/Engineer with strong knowledge of products and services related to Read more
*Apple* Graders/Inspectors (Seasonal/Hourly/...
…requirements. #COVAentryleveljobs ## Minimum Qualifications Some knowledge of agricultural and/or the apple industry is helpful as well as the ability to comprehend, Read more
Best Buy *Apple* Computing Master - Best Bu...
**710003BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Location Number:** 000171-Winchester Road-Store **Job Description:** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.