TweetFollow Us on Twitter

System File
Volume Number:3
Issue Number:8
Column Tag:Resource Roundup

Sleuthing the New System File

By Joel West, Contributing Editor

This month, I’m going to talk about the new traps available in System 4.1 under the Macintosh Plus -- and, to a lesser extent, the 512, SE and Macintosh II. (When I sat down to write this article, I wanted to call it “Trapping System Compatibility”, or “Seeking the Compatibility Trap,” but finally decide to give up on the puns.)

This all started when I was working on my book, Programming with Macintosh Programmer’s Workshop (due to be published by Bantam this month.) I wanted to include an up-to-date list of traps; in particular, I wanted to pull together all the traps and indicate exactly when it was safe to use them. (If you have the book already, I’m referring to Appendix E.)

At the time I was writing the appendix, all I had was the APDA draft for Inside Macintosh, Volume V, which described new features developed for the Macintosh II. After the draft was published, many of the features described for Mac II were retrofitted for the Plus. For the Macintosh SE, some of the new stuff made it before the SE ROM was frozen (several months before the II), while other stuff also had to be retrofitted.

I have a fastidious pre-occupation for detail, and sometimes I get carried away. In this case, what started out as a simple exercise ended up being a rather elaborate endeavor. I probably spent 10-15 working days over three months trying to get the exact answer to exactly which trap is available when. I ended up testing five different System files on the Mac 512, Mac Plus, Prodigy 4, Macintosh SE and Macintosh II. I didn’t test all possible combinations, but all the valid ones for the Mac Plus, SE and II, and all but one (System 3.3, very similar to System 4.0) for the Macintosh 512.

My work was assisted by the generous help of Silicon Beach Software, who supplied an SE and a prototype Mac II. Neil Rhodes also lent his production Mac II, while my former employer coughed up the prehistoric 512. I’ve ignored the Macintosh XL, aka Lisa 2, since most developers traded theirs in when the opportunity presented itself and it never sold that well, anyway.

Educated Guessing

First let me note (standard disclaimer follows) that I am not privy to any confidential Apple information regarding the ROM or trap patches. If I were, I probably couldn’t share my thoughts on the subject.

However, I like to consider myself clever and resourceful, and I felt that a studied application of documented techniques would produce valuable results. Those of you who are regular readers of MacTutor will recognize this as “sleuthing.”

In this case, I know the availability of each by trap word ($A000-AFFF) with certainty, both the traps that have names, and those that do not. However, some of the OS traps share the same trap number and use high-order bits to distinguish between the traps, but my analysis of the trap dispatch table can’t distinguish this. Also, for the dispatched traps, I can’t tell which new traps are added that share the same dispatch word.

There are also some problems with occasional ROM traps looking like RAM traps, since some other interloper (like a development system or application) may have patched a perfectly good ROM trap. From a compatibility standpoint, it’s not as important to know which ROM-based traps are patched, so although there might be a glitch or two here, it’s not worth losing sleep over.

After pouring over all the information and asking a few sources for help, I know the trap names with a strong degree of certainty. I’ve left off a few traps for which I have discerned names because Apple has not told anyone (including me) how to call them, nor guaranteed that they will work in the future. There are quite a few traps that are defined but not named at all (at least, outside Apple), but presumably those are called from within the ROM only and subject to change at any time.

Finally, when we get down to why a particular trap was added or modified, all I can do is make an educated guess. But since I’ve spent so much time studying trap compatibility, I thought people might be interested in the results of my education.

The Format of a Trap

A trap is an unimplemented Motorola 68000 instruction that generates a standard 68000 exception vector interrupt, which is used by the Macintosh to transfer control to the appropriate code.

The 68000 uses instructions that are a multiple of 16 bits, with many instructions contained in a single 16-bit word. In the case of Macintosh traps, the instructions are 16-bit words (trap words) in which the first hex digit is A, so these are sometimes referred to as “A-line” traps. All 4096 A-line traps are considered illegal instructions.

(I heard a story that Motorola wanted to use A-line traps someday for a future processor, but with Apple machines now holding the majority of the chips out there, that possibility is gone. However, Motorola has reserved the 4096 F-line traps for coprocessor calls, such as for the MC68881 and MC68851 of the Macintosh II.)

When it sees an illegal instruction in the range $A000 to $AFFF, the MC68000 (or MC68020) transfers control to the exception handling routine pointed to by location $028. For a Macintosh, this transfers control to the trap dispatcher.

As shown by Figure 1, the range of possible traps is split into two groups, with $A000 to $A7FF allocated to OS traps, and $A800 to $AFFF for Toolbox traps. The lowest bits of the trap word are the trap number.

All traps from $A000-$A7FF are OS traps that accept any parameters in low-numbered registers, such as A0 and D0, returning any results similarly in registers.

Most of the traps from $A800 on are Toolbox traps, which have parameters passed on the stack along the lines of the standard Lisa (now MPW) Pascal calling sequence. There are also a number of stack-based traps for OS managers above $A800, and a handful of register-based OS traps as well, but for our purposes, these are numbered and treated as Toolbox traps.

The basic OS traps are numbered $A000 to $A0FF, with the upper 3 bits are used for other indicator flags. The figure summarizes what these flags are used for, and their hex mask equivalents are:

$100 trap returns a value in A0

$200 HFS traps

$400 asynchronous I/O call; or

allocate in system heap

The $200 and $400 bits are also used by some other traps, including _GetTrapAddress.

There can be two (usually related) OS traps with the same OS trap number, differing only in their indicator bits. For example, _PostEvent is $A02F and _PPostEvent is $A12F. More significantly, _Open is $A000, while its HFS counterpart is _HOpen at $A200, and their are many similar HFS pairs.

Trap Tables

The trap dispatcher transfers control to the correct routine using a trap table, which contains the address (possibly encoded) of the corresponding routine. The trap table is always in RAM, because it is possible for a program to modify the entry for any trap, as we’ll see.

The trap table on the original Macintosh was compressed, with only 16 bits for the trap address. Using the 68000 restriction that instructions begin on even addresses, this allowed 64K of ROM addressability, plus patches in the first 64K of low memory, presumably in the System Heap.

The Macintosh 512, of course, is just a Macintosh (128) with more RAM; same connectors, maybe (as noted in earlier MacTutor articles) a better power supply -- but the same ROM, traps and trap table. I’ll talk about the 512 from now on, since presumably everyone has at least 512K.

The 64K ROM also cheated by overlapping the OS and Toolbox trap tables into a single table. As shown in Table 1, this limits a Mac 512 to 512 of both kinds of traps. More significantly, certain trap words are not available on the Macintosh 512 -- since that spot in the trap table is taken for the opposite (Toolbox or OS) purpose.

Generally, the first 80 slots (A000 to A04F) in the 64K ROM are allocated to OS traps, and the last 432 slots (A850 to A9FF) are allocated for the Toolbox. But a few stragglers from the OS take slots allowed for the Toolbox, although the ROM doesn’t seem to care which type of trap is in the slot .

The Plus and SE split the two trap tables. A full 256 OS traps are defined, and 512 Toolbox traps -- $A800 to $A9FF -- are allowed for the Plus and SE. When you get to the Macintosh II, the maximum 1024 Toolbox traps are provided, with the extended traps -- $AA00 to $ABFF -- used for Color QuickDraw.

Inherent Limits

Some people have told me that they have a certain machine and wish they could have a certain new capability, typically offered with the next machine up.

For example, many folks want Color QuickDraw on their SE or Plus. While I can’t say it won’t happen, it would require some changes to the trap dispatcher, because the necessary traps are not possible using the built-in SE or Plus trap tables. (There’s also the question of how to get the code itself, but if there are BIOS clones in the IBM world, certainly the Mac world will inspire color clone conversions of the SE if there’s enough demand.)

More significantly, many people will find that there are certain things they cannot do and never will do with their old-ROM machine. The gap between the 64K ROM and the rest of the world is now huge and largely unbridgable; if you’re not aware of the differences, then read on.

First, bridging this gap would require throwing out the trap dispatch mechanism on the 512 to allow for more traps, with separate OS & Toolbox traps. However, 512K is at the low end nowadays for dynamic memory in the Macintosh world, and that’s the largest configuration Apple ever offered in the 64K ROM world. Apple could have gone to a lot of trouble to try to improve marginally adequate machines (or third-party upgraded machines), but they didn’t, perhaps wisely so. The clincher is that these old-ROM machines now form 20% (my estimate) of the installed base, and that number is getting smaller every day.

The Good Ol’ Days

Once upon a time, things were much simpler. There were only traps and glue. There was one list of available traps. Occasionally, the glue got more elaborate in a new release of Lisa Pascal, but this was strictly a compile-time decision. When your program ran, you knew it would face only one set of traps.

Along came the 128K ROM of the Macintosh Plus, and the world was never the same again. The 128K ROM had a whole list of new traps not available on the 64K ROM. All of a sudden, the Macintosh software architecture was not a fixed target, but an evolving one.

(Its smaller sibling, the Mac 512K enhanced, has the exact same ROM as the Plus, with less memory and different peripheral interfaces, but these differences are uninteresting for our purposes and the 512Ke will be treated as a Plus for the remainder of this article.)

To make matters worse, a certain subset of the 128K ROM traps -- those involving the File Manager -- were also available on 64K ROM machines using trap patches. All you have to do is place the file “Hard Disk 20” on your boot disk and you’re all set, with full access to the Hierarchical File System of the 128K ROM.

The traps patched by “Hard Disk 20” to 64K ROM machines are shown in Table 2. A total of 13 traps are analogous to existing traps, most of which add an “H” to their corresponding 64K trap, such as _HOpen vs. _Open.

As their Pascal names suggests, the higher-level PBH routines are HFS-oriented ParamBlockRec calls. In addition, the _HFSDispatch trap provides 11 separate routines, not shown.

However, even with this range of options, things were easy by comparison to today. At least there were only three configurations:

• Mac 512 (or a 128 for masochists)

• Mac 512 + HFS (using Hard Disk 20)

• Mac Plus (including Mac 512Ke)

Come 1987, with new machines and System files, the configuration possibilities became much, much more complex, as we’ll see in a minute.

Dispatched Traps

In some cases, several routines share the same trap word. A trap selector is a value that distinguishes between calls to the different routines; a trap word that requires a selector is called a dispatched trap.

In the original ROM, the only dispatched traps were the packages, which were disk-based resources of type ‘PACK’, loaded into RAM (like any other resource) in an as-needed basis. Six of the eight possible packages were defined, and their dedicated traps were:

_Pack2 Disk Initialization

_Pack3 Standard File

_Pack4 SANE floating-point

_Pack5 SANE trancendentals

_Pack6 International Utilities

_Pack7 Binary/Decimal Conversion

The Hierarchical File System added _HFSDispatch as a non-package dispatched trap. System 3.0 added a new package (_Pack0) for the List Manager, while the 128K ROM included _SCSIDispatch.

Now there are six more. TextEdit, Script Manager, Shutdown Manager and Printing Manager have four, available on all systems. Specific to the Mac II is the Slot Manager, while Color Picker Package is primarily designed for the Mac II, but available on any 128K ROM machine. For five of the managers listed (all but TextEdit), the dispatched trap is used to support all routines of the manager.

Most of the dispatched traps take stack-based parameters, and these use a selector on the stack. Packages use 32-bit selectors, while others may use either 16- or 32-bit selectors.

The two register-based dispatched traps, _HFSDispatch and _SlotManager, use a 16-bit selector in register D0, and usually a parameter record pointer in A0.

System Versions

The Macintosh system software has changed tremendously since 1984. Table 3 gives a chronology of the System and Finder versions publicly released as of this writing. I’ve omitted beta versions and others that Apple never encouraged people to use, such as System 3.1 or 3.11. I couldn’t find the 1.0 disk that came with my original Macintosh in February 1984, but since no one should be using that version today, I figured it wasn’t important enough to go digging through storage to find its exact date.

Until System 4.1, the System and Finder had textual version dates in the resource fork, in the ‘STR ‘ and ‘FNDR’ resources, respectively. These generally coincide with the modification date for the file, but where there was a conflict, I took the modification date (which seemed to correspond to a release date). Why the new System and Finder don’t have dates is beyond me, but I hope they put them back in. Without them, it is hard to write utilities that indicate which version each system is running; an important consideration for network management.

One interesting curiosity is the similarity of System 3.3 and System 4.0. They are only three days apart and share the same finder, and, as noted later, are very similar in the traps they implement. System 4.0 was obviously designed for the Macintosh SE.

I’m sure most of you have seen Apple’s smiley-face compatibility table for System/Finder versions and different Macintosh models, either in the developer mailing or in the APDA newsletter. But for further reference later on, the recommendations are summarized in Table 4.

RAM patches

Trap patches have always been with us. But somewhere around System 3.0 (Finder 5.1) Apple developed a formal scheme for implementing trap patches using ‘PTCH’ resources in the System file. Since this is Resource Roundup, no column would be complete without at least a prefunctonary discussion of an interesting resource.

One or more ‘PTCH’ resources are loaded at startup time. They contain routines that will be available to all applications until the machine is powered off, and these routines are loaded into the system heap. The address of the patch replaces the ROM address that was previously stored in the trap dispatch table.

Patches were originally intended to fix bugs in the ROM. Not suprisingly, no piece of software is done until after it’s tested, and some complex software only gets properly tested by end-users. It’s an unfortunate reality of this business that the most embarassing crashes only show up after you’ve shipped out 100,000 disks.

Since the original system software releases, however, trap patches have taken on new importance. They now have three uses:

• Fix a bug;

• Extend existing capabilities; or

• Add a new trap

Between System 2.0 and 3.2, no new traps are defined by RAM patches. However, after that, the number of traps increases significantly, particularly for the Macintosh Plus. Table 5 summarizes the number of documented traps for each machine for System 3.2 and System 4.1. System 3.2 is not recommended for the SE, so I listed the minimum configuraton of 4.0. Some people used beta releases of 4.1 on the II, but again it’s not kosher, so the Mac II list starts with 4.1.

If you have your own count of traps, it might be slightly different. There are some gray areas when it comes to defining exactly what is a “documented” trap.

System 4.1

Looking at the trap count, it’s pretty obvious that System 4.1 makes a Macintosh Plus almost identical to an SE from a software standpoint. It has the same Toolbox calls available, and in the OS, is missing only the ADB-related stuff and a couple of slot-oriented calls.

Table 6 summarizes the programming-level features of System 4.1, primarily in the area of new and enhanced traps. The list is short for the 512; the other machines share most of the same functionality.

For those traps not provided in ROM, there are corresponding ‘PTCH’ resources in System 4.1, as shown in Table 7. Resource #0 is used for all systems; if the other numbers seem strange, they’re nothing more than the concatenation of the two bytes of machine and ROM version returned by the _Environs trap. Notice how huge the trap patches are for the Mac Plus -- this must be one important reason why System 4.1 provides a resizable system heap.

Traps can also be patched by any other code loaded at system startup time, notably ‘INIT’ resources. In case you missed the scoop, startup looks for files of type ‘INIT’ or ‘RDEV’ in the system (“blessed”) folder and then runs any ‘INIT’ resources found there.

Incidentally, if you’re having trouble fitting System 4.1 onto a floppy-based boot disk, you can strip out the unused ‘PTCH’ resources. If you don’t have a Macintosh II, you can also delete all the ‘snd ’,’snth’, and ‘cicn’ resources; this saves nearly 40K for a Macintosh Plus. However, you should edit the ‘STR ’ #0 (version) resource and the Get Info box to indicate your hack, and DO NOT DISTRIBUTE THIS VERSION TO SOMEONE ELSE. If the modification is performed only by people smart enough to know how to do it, it’s much less likely to cause naïve users to come to grief.

New Traps

With System 4.1, a few new traps are available on all machines, including the 512.

Two, in fact, came in with earlier System versions 3.3 and 4.0, both released in January. Other than adding the Shutdown Manager, in fact, System 4.0 is almost identical to 3.3. Both contain the trap-based Printing Manager.

Owners of the Macintosh 512 can also take advantage of the Script Manager under System 4.1, via a dispatched trap. The _KeyTrans trap provides a new scheme for keycode translation, unlike the original (low-memory global) approach described in an earlier column (“Be A Keyboard Sleuth”, August 1986.)

The other new traps are provided to Macintosh Plus (and SE) owners to keep up with their II-owning brethren. The use of these traps is described in the Macintosh II documentation, such as Inside Macintosh Volume V.

The Toolbox functionality of Plus and SE is essentially the same as the II, except for color. The OS is different, reflecting three hardware-dependent differences of the Macintosh II:

• 32-bit memory addressing

• NuBus slots

• Sound Manager

The new traps available in System 4.1 are listed in Table 8, along with where the trap can be found -- since several made it into ROM on the SE and Mac II. A few traps were already defined in the SE’s ROM, but were patched in System 4.1 to get it right.

Enhanced Capabilities

A number of traps are not new, but are previously ROM-based traps redefined by RAM patches in System 4.1. Those redefined for the Mac 512 are shown in Table 9, while Table 10 lists those for the three other machines. I don’t have any way of knowing which patches have changed from the previously RAM-based traps, so these lists exclude traps that were RAM-based previously.

Some of these patches are to fix bugs, but System 4.1 also contains enhanced capabilities for two important managers.

Table 10: Traps changed from System 3.2 to System 4.1

(Macintosh Plus, SE, II)
NameWordPlusSEIIRemarks
_ReadA002patchedROMROM
_FreeMemA01CROMpatchedROM
_SetHandleSizeA024unpatchedROMROM
_HLockA029unpatchedROMROM
_HUnlockA02AROMpatchedpatched
_GetOSEventA031patchedrampatchedAlso Mac 512
_CompactMemA04Cpatchedpatchedpatched
_RelStringA050unpatchedROMROM
_RmvTimeA059patchedROMROM
_PrimeTimeA05ApatchedramROMPatched/ Sys 4.0
_HFSDispatchA060rampatchedROM
_StackSpaceA065ROMpatchedROM
_HGetStateA069rampatchedROM
_TESelViewA811patchedROMROM
_TEPinScrollA812patchedpatchedpatched
_TEAutoViewA813patchedpatchedROM
_InsMenuItemA826patchedpatchedROM
_SetFScaleDisableA834patchedROMROM
_FontMetricsA835patchedROMROM
_MeasureTextA837patchedRAMROM
_Fix2LongA840patchedROMROM
_Frac2FixA842patchedROMROM
_FracDivA84BpatchedROMROM
_FixDivA84DpatchedROMROM
_FixMulA868ROMpatchedpatched
_FixRatioA869unpatchedROMROM
_FixRoundA86CpatchedpatchedROM
_GetClipA87AunpatchedROMROM
_DrawTextA885ROMpatchedROM
_TextFaceA888ROMunpatchedROM
_FillRectA8A5ROMpatchedROM
_PtInRectA8ADROMunpatchedROM
_FillRgnA8D6ROMpatchedROM
_StdGetPicA8EEpatchedpatchedROMcolor PICT
_DrawPictureA8F6patchedpatchedROMcolor PICT
_InitFontsA8FEpatchedpatchedram
_RealFontA902patchedROMROM
_SetFontLockA903patchedROMROM
_InitWindowsA912patchedpatchedpatched
_ValidRectA92Apatchedpatchedpatched
_FindWindowA92CpatchedpatchedROM
_InitMenusA930patchedpatchedramAlso Mac 512
_NewMenuA931patchedpatchedROMMenu Manager
_DisposMenuA932patchedpatchedROMMenu Manager
_AppendMenuA933patchedpatchedROMMenu Manager
_ClearMenuBarA934patchedpatchedROMMenu Manager
_InsertMenuA935patchedpatchedROMMenu Manager
_DeleteMenuA936patchedpatchedpatchedMenu Manager
_DrawMenuBarA937patchedpatchedramMenu Manager
_HiliteMenuA938patchedrampatchedMenu Manager
_EnableItemA939patchedramROMMenu Manager
_DisableItemA93ApatchedramROMMenu Manager
_GetMenuBarA93BpatchedpatchedROMMenu Manager
_SetMenuBarA93CpatchedpatchedROMMenu Manager
_MenuSelectA93DpatchedpatchedROMMenu Manager
_MenuKeyA93EpatchedpatchedROMMenu Manager
_GetItmIconA93FpatchedpatchedROMMenu Manager
_SetItmIconA940patchedpatchedROMMenu Manager
_GetItmStyleA941patchedpatchedROMMenu Manager
_SetItmStyleA942patchedpatchedROMMenu Manager
_GetItmMarkA943patchedpatchedROMMenu Manager
_SetItmMarkA944patchedpatchedROMMenu Manager
_CheckItemA945patchedpatchedROMMenu Manager
_GetItemA946patchedpatchedROMMenu Manager
_SetItemA947patchedpatchedROMMenu Manager
_CalcMenuSizeA948patchedpatchedROMMenu Manager
_GetMHandleA949patchedpatchedpatchedMenu Manager
_SetMFlashA94ApatchedpatchedROMMenu Manager
_PlotIconA94BpatchedpatchedROMMenu Manager
_FlashMenuBarA94CpatchedpatchedROMMenu Manager
_AddResMenuA94DpatchedpatchedROMMenu Manager
_CountMItemsA950patchedpatchedROMMenu Manager
_InsertResMenuA951patchedpatchedROMMenu Manager
_DelMenuItemA952patchedpatchedROMMenu Manager
_GetResourceA9A0ROMpatchedpatched
_LoadResourceA9A2ROMpatchedpatched
_TEGetTextA9CBpatchedROMROMTextEdit
_TEInitA9CCpatchedpatchedramAlso Mac 512
_TEDisposeA9CDpatchedROMROMTextEdit
_TextBoxA9CEpatchedpatchedpatchedTextEdit
_TESetTextA9CFpatchedROMROMTextEdit
_TECalTextA9D0patchedROMROMTextEdit
_TESetSelectA9D1patchedROMROMTextEdit
_TENewA9D2patchedROMROMTextEdit
_TEUpdateA9D3patchedROMROMTextEdit
_TEClickA9D4patchedROMROMTextEdit
_TECopyA9D5patchedROMROMTextEdit
_TECutA9D6patchedROMROMTextEdit
_TEDeleteA9D7patchedROMROMTextEdit
_TEActivateA9D8patchedROMROMTextEdit
_TEDeactivateA9D9patchedROMROMTextEdit
_TEIdleA9DApatchedROMROMTextEdit
_TEPasteA9DBpatchedROMROMTextEdit
_TEScrollA9DDpatchedROMROM_TEKey unchanged
_TEInsertA9DEpatchedROMROMTextEdit
_TESetJustA9DFpatchedROMROMTextEdit
_MungerA9E0rampatchedROM

Most noticeably, the new TextEdit supports what we’ve all been asking for -- mixed fonts and styles in an editing record managed by TextEdit. Three new traps -- _TEGetOffset, _TEStyleNew and the dispatched _TEDispatch are provided, while the existing TextEdit traps have been modified to use the new style data structure. As Table 10 shows, this is provided in ROM by the Macintosh SE and II, but in RAM by the Macintosh Plus.

And if you haven’t heard by now, the Mac II (and System 4.1) provides hierarchical menus. Selecting an item from a normal menu causes another menu to pop up. The revised Menu Manager also includes the _PopUpMenuSelect trap and a menu bar definition procedure (type ‘mbdf’) to complement the menu definition procedure (‘MDEF’).

As an aside, new File Manager traps for external and shared file systems have been provided since the original HFS release. These traps are allocated as new selectors off of _HFSDispatch. At least some are installed for those having the AppleShare client driver (an ‘RDEV’ file) in their blessed folder; the SE that I tested with, for example, was using AppleShare at the time.

Other Changes

There are a number of bug fix changes in System 4.1, including many I don’t know about. However, there are a few that either Apple has talked about or that I can guess to explain the remaining traps on Table 10. There are also changes that correspond more to a change in specification than a bug correction.

The draft IM Volume V included notes about how many of the fixed-point arithmetic traps had problems that are now fixed. To summarize, _FixRound had trouble with negative numbers, _FracDiv and _FixDiv had problems with large quotients, and _FracToFix and _FixToLong acted up when rounding up to the next number. It’s nice to know that Apple’s programmers are human, just like the rest of us. For the Macintosh II, _ClosePort was patched to be able to close a CGrafPort (color drawing port). Earlier in the Color QuickDraw specification, there was a separate trap to close these ports, but they were later combined into one and _CloseCPort went away.

Also, many of the Mac II traps didn’t make it into the ROM-burning party, and had to be added to ‘PTCH’ #376. This includes the entire Palette Manager, not shown.

There are many other changes I have no explanation for. Such changes include all of the unnamed OS traps in the range $A0BF to $A0FF, of which many are patched by System 4.1. I’m sure the folks at Apple know what these are -- and probably Duane Maxwell at Levco, since the Levco ROM supplied with the Prodigy 4 patches some of these traps, according to my sleuthing.

SysEnvirons

As you may have gathered by now, System 4.1 and the 128K (or later) ROM offer a lot of attractive capabilities for the Macintosh developer. But with all the possible configurations, how do you tell what is available when your program is running?

I suspect Apple’s Tech Support department anticipated a flurry of questions on this subject, because they proposed and developed a new routine just to provide such information. The routine SysEnvirons is now the official way to check for compatibility testing The details of calling it are well-described in Macintosh Technical Note #129, so I won’t reiterate them here. If you don’t have the tech note in front of you, the information returned by SysEnvirons is summarized in Table 11.

The rules on how SysEnvirons works and when it is available are interesting, and certainly relevant for a discussion of trap patches, so let me touch on a few points.

Beginning with System 4.1, there’s a _SysEnvirons trap provided as a RAM patch for the Macintosh Plus, SE and II. It is not available on the Macintosh 512, nor is it in ROM for any machine yet released. Apple provides a standard “glue” routine for calling the trap, which will be part of MPW 2.0 and presumably other development systems.

The glue can be used on any machine, whether it includes the _SysEnvirons trap or not. Figure 2 shows a flow chart for how the glue works.

Note that the glue is more than just stuffing a few registers for the _SysEnvirons trap. For a 64K ROM machine, _SysEnvirons uses the same trap number as _StdLine, so it’s not practical to include a trap patch for it. Instead, the glue fills in as many values as possible for a 64K ROM machine, as it also does for the Plus (and SE) when used on a System version before 4.1.

Some of this information was already available in low memory globals. Apple has recently been making nasty noises about not using low-memory globals in the future, so you should use SysEnvirons wherever possible. Since the main problem with low-memory globals is saving their context in a multi-application environment (Switcher and its sucessors), most of the compatibility globals should be the last ones to go. After all, they don’t changes values dynamically.

However, as Apple discovered on the Apple II, programs reading reserved memory locations (rather than using ROM calls) create permanent compatibility headaches, so if you use the ROM call, the OS can provide the requested information to you without being stuck with a particular memory representation into the 21st Century.

Sleuth Your Own Traps

David is never happy unless he gets a program with every article, so being a loyal columnist, I try to oblige him. In this case, I offer a way to do your own trap sleuthing.

Anyone who can say _GetTrapAddress can detect which traps are defined or patched. Detecting patches is the easiest, since the list of the trap patches is public record. To quote from Inside Macintosh, Volume II, page 383:

“You can tell whether a routine is patched by comparing its address to the global variable ROMBase; if the address is less than ROMBase, the routine is patched.”

You have to watch out, however, since this technique is not 100% accurate. RAM patches can come from other sources, such as AppleShare. Also, some applications patch traps. For example, MPW patches most of the File Manager traps so that it can provide shell I/O.

What about traps that aren’t implemented at all: how do you find them? One way would be to attempt to call the trap and see if the Macintosh crashes, but this would be a slow way to check out a list of 700 or so possible traps, not to mention extremely frustrating.

There is a better way. Apple has indirectly documented an approved technique to the outside world recently -- such as in the SysEnvirons tech note and MacApp 1.1 source code. I’m told it will probably be the subject of a future tech note.

Trap word $A89F is Apple’s standard unimplemented trap. If you get an address from the call:

GetTrapAddress($9F)

that is also the address of any unimplemented trap; just compare the address of any trap you check to this value.

The example (written in MPW C) shows an MPW tool to answer the question: does this trap exist? This allows you to inquire for one specific trap, which I find much more handy than my 160K Excel file containing all the traps for all configurations. The example also shows the algorithm for your own program to detect an unimplemented trap, such as whether to use the new TextEdit (check for _TEStyleNew) or the Script Manager (try _ScriptUtil).

The program distinguishes between system heap trap patches (presumably from the system) and application heap patches (presumably from the application). Neither rule is ironclad. Since there can be more than one application heap zone, it assumes that anything outside the system heap but below the ROM is in the application heap. Also, many programs place their actual patch in the application heap, but the trap table points to a single jump in the system heap -- so the address will fit into that first 64K of low memory on a Mac 512.

There are probably a few machines that violate this simple heuristic. Levco’s Prodigy has its own PROM that is neither RAM nor Apple ROM, as I suspect some of the coprocessor and display card companies do. If you were testing on such a machine, you might add tests to mark those references.

Coming Attractions

With my book behind me, I’m now doing some interesting things with Color QuickDraw. If you’re at the Macworld show in Boston (August 11-13), stop by MacTutor booth and ask for me if you want to see what I’m up to, or just have some suggestions for future topics to be covered in Resource Roundup.

It seems like every MacTutor reader I talk to asks me about my promised article on how to write your own printer driver. Since I wrote the last article (“Printer Sleuthing,” March 1987) I’ve been too busy with my book to do anything else, but I hope to get it to it in the coming months.

In the meantime, if you want to write your own printer driver, I would note that this has never been for the faint-hearted, and maybe only for the foolish. Even for an extremely skilled and knowledgeable Macintosh programmer, it’s probably several man-months to get even a hack driver working. I personally have not done it (yet), which is one reason I haven’t written the article.

Also, Apple has never been very forthcoming with details on this subject, and recent indications (see Macintosh Technical Note #122: “Device-Independent Printing”) are that this will be even more true in the future, as they make private device-dependent fields for their new (and current) printers. The 2.0 version of the MPW interfaces also delete some previously-provided information about print records, including the bDevCItoh and bDevLaser constants indicating the printer type (does this mean a new printer is due soon?)

There’s some good news for application writers (the majority of us), however, since the new trap-based Printing Manager increases the amount of information provided in a device-independent way. More in a future column!


/* IsTrap.c: Detect trap availability

   Written by Joel West in MPW C, June 1987

   Compiled as an MPW tool (shell command); usage:
   IsTrap A010 A060print information 
 on traps $A010 and $A060
 IsTrap A800 -A830 information on all traps 
 from $A800 to $A830

   There is one option letter (which like UNIX 
 and unlike MPW, must come first):
   -p show detailed “progress” information

   Status values returned:
   0  ok
 1 syntax error
 2 trap not implemented
*/

#include <Memory.h>/* for THz heap zone ptr */
#include <OSUtils.h> /* for GetTrapAddress() */
#include <stdio.h>

#define UNDEFTRAP 0x9F
#define GETLONG(addr) *( (long *) addr)
 /* grab a low-memory global value */
#define ROMBase  GETLONG(0x2AEL)

typedef short Half;
typedef unsigned short UHalf; 
 /* traps are Axxx, normally negative numbers */
typedef unsigned long Addr; 
 /* for unsigned address comparisons */

int strspn(),strlen();
long MyGetTrapAddr();
void syntaxerr();

THz syshz;
#define INSYSHEAP(a) (a > (long) syshz && a < (long)     syshz->bkLim)

main(argc,argv)
int argc;
char **argv;
{int argno,len,status;
 Boolean range,verbose=0;
 Addr trapword, trapaddr, unimpaddr, rombegin;
 UHalf oldword=0,t;
 char *p;
 
 unimpaddr = GetTrapAddress(UNDEFTRAP);
 rombegin = ROMBase;
 syshz = SystemZone();

 argno = 1; /* parameter number */
 if (argno < argc && ! strcmp(argv[argno], “-p”))  /* -v for you UNIX 
types */
 {    verbose++;
      argno++;
 }

 if (argno >= argc)
     syntaxerr(argv);

 if (verbose)
 {   printf(“ROM @ %X\n”, rombegin);
     printf(“System heap from %X to %X\n”, syshz,              syshz->bkLim);
 }

 status = 0;
 for (; argno<argc; argno++)
 {   range = 0;
     p = argv[argno];
     if (*p == ‘-’)
     {   p++;
 range++;
     }
     len = strlen(p);
     if (len && len == strspn(p,   “0123456789ABCDEF”))
     {   sscanf(p,”%lx”,&trapword);
 if (range)
     t = oldword+1;
 else
     t = trapword;
 for (; t<=trapword; t++)
 {   trapaddr = MyGetTrapAddr(t);
     printf(“Trap %lX is “, t);
     if (verbose)
 printf(“%lX, “, trapaddr);
     if (trapaddr == unimpaddr)
     {   printf(“undefined\n”);
 status = 2;  /* indicate result to shell */
     }
     else 
 if (trapaddr >= rombegin)
     printf(“in ROM\n”);
 else if (INSYSHEAP(trapaddr))
     printf(“patched\n”);
 else /* in application heap? */
     printf(“overridden\n”);
 }
 oldword = trapword;
     }
     else
 syntaxerr(argv);
 }
 exit(status);
}

void syntaxerr(argv)
char **argv;
{
fprintf(stderr, “# %s - invalid syntax.\n”, argv[0]);
fprintf(stderr, “# %s - usage:  %s [-p] trap \n”,  argv[0], argv[0]);
exit(1);
}

/*
 Find the trap address for a given trap word.The 128K ROM provides NGetTrapAddress 
(a glue routine), which distinguishes between OS and Toolbox traps.  
This eventually uses the same trap number as GetTrapAddress, so it seems 
to work fine on the 64K ROM.
*/
long MyGetTrapAddr(trapword)
UHalf trapword;
{UHalf trapnum;
 TrapType typ;
 if ((long)trapword < 0x0000A800L)
 {   typ = OSTrap;
     trapnum = trapword & 0xFF;
 }
 else
 {   typ = ToolTrap;
     trapnum = trapword & 0x3FF;
 }
 return NGetTrapAddress(trapnum, typ);
}
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Typinator 9.1 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
ESET Cyber Security 6.11.414.0 - Basic i...
ESET Cyber Security provides powerful protection against phishing, viruses, worms, and spyware. Offering similar functionality to ESET NOD32 Antivirus for Windows, ESET Cyber Security for Mac allows... Read more
Opera 105.0.4970.29 - High-performance W...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
Slack 4.35.131 - Collaborative communica...
Slack brings team communication and collaboration into one place so you can get more work done, whether you belong to a large enterprise or a small business. Check off your to-do list and move your... Read more
Viber 21.5.0 - Send messages and make fr...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Hazel 5.3 - Create rules for organizing...
Hazel is your personal housekeeper, organizing and cleaning folders based on rules you define. Hazel can also manage your trash and uninstall your applications. Organize your files using a familiar... Read more
Duet 3.15.0.0 - Use your iPad as an exte...
Duet is the first app that allows you to use your iDevice as an extra display for your Mac using the Lightning or 30-pin cable. Note: This app requires a iOS companion app. Release notes were... Read more
DiskCatalogMaker 9.0.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
Maintenance 3.1.2 - System maintenance u...
Maintenance is a system maintenance and cleaning utility. It allows you to run miscellaneous tasks of system maintenance: Check the the structure of the disk Repair permissions Run periodic scripts... Read more
Final Cut Pro 10.7 - Professional video...
Redesigned from the ground up, Final Cut Pro combines revolutionary video editing with a powerful media organization and incredible performance to let you create at the speed of thought.... Read more

Latest Forum Discussions

See All

‘Sonic Dream Team’ Apple Arcade Review –...
What an unusual day we have arrived upon today. Now, Sonic the Hedgehog games aren’t a new thing for iOS gaming. The original Sonic the Hedgehog appeared on the classic iPod, so the Blue Blur got in the doors as fast as you would expect him to. The... | Read more »
PvP Basketball Game ‘NBA Infinite’ Annou...
Level Infinite and Lightspeed Studios just announced a new real-time PvP basketball game for mobile in the form of NBA Infinite (). NBA Infinite includes solo modes as well, collecting and upgrading current NBA players, managing teams, and more. It... | Read more »
New ‘Dysmantle’ iOS Update Adds Co-Op Mo...
We recently had a major update hit mobile for the open world survival and crafting adventure game Dysmantle ($4.99) from 10tons Ltd. Dysmantle was one of our favorite games of 2022, and with all of its paid DLC and updates, it is even better. | Read more »
PUBG Mobile pulls a marketing blinder wi...
Over the years, there have been a lot of different marketing gimmicks tried by companies and ambassadors, some of them land like Snoop Dog and his recent smoking misdirection, and some are just rather frustrating, let’s no lie. Tencent, however,... | Read more »
‘Goat Simulator 3’ Mobile Now Available...
Coffee Stain Publishing and Coffee Stain Malmo, the new mobile publishing studio have just released Goat Simulator 3 on iOS and Android as a premium release. Goat Simulator 3 debuted on PS5, Xbox Series X|S, and PC platforms. This is the second... | Read more »
‘Mini Motorways’ Huge Aurora Borealis Up...
Mini Motorways on Apple Arcade, Nintendo Switch, and Steam has gotten a huge update today with the Aurora Borealis patch bringing in Reykjavik, new achievements, challenges, iCloud improvements on Apple Arcade, and more. Mini Motorways remains one... | Read more »
Fan-Favorite Action RPG ‘Death’s Door’ i...
Last month Netflix revealed during their big Geeked Week event a number of new titles that would be heading to their Netflix Games service. Among them was Acid Nerve and Devolver Digital’s critically acclaimed action RPG Death’s Door, and without... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle reader, and welcome to the SwitchArcade Round-Up for December 4th, 2023. I’ve been catching up on my work as much as possible lately, and that translates to a whopping six reviews for you to read today. The list includes Astlibra... | Read more »
‘Hi-Fi Rush’ Anniversary Interview: Dire...
Back in January, Tango Gameworks and Bethesda released one of my favorite games of all time with Hi-Fi Rush. As someone who adores character action and rhythm games, blending both together seemed like a perfect fit for my taste, but Hi-Fi Rush did... | Read more »
Best iPhone Game Updates: ‘Pizza Hero’,...
Hello everyone, and welcome to the week! It’s time once again for our look back at the noteworthy updates of the last seven days. Things are starting to chill out for the year, but we still have plenty of holiday updates ahead of us I’m sure. Some... | Read more »

Price Scanner via MacPrices.net

Apple is clearing out last year’s M1-powered...
Apple has Certified Refurbished 11″ M1 iPad Pros available starting at $639 and ranging up to $310 off Apple’s original MSRP. Each iPad Pro comes with Apple’s standard one-year warranty, features a... Read more
Save $50 on these HomePods available today at...
Apple has Certified Refurbished White and Midnight HomePods available for $249, Certified Refurbished. That’s $50 off MSRP and the lowest price currently available for a full-size Apple HomePod this... Read more
New 16-inch M3 Pro MacBook Pros are on sale f...
Holiday MacBook deals are live at B&H Photo. Apple 16″ MacBook Pros with M3 Pro CPUs are in stock and on sale for $200-$250 off MSRP. Their prices are among the lowest currently available for... Read more
Christmas Deal Alert! Apple AirPods Pro with...
Walmart has Apple’s 2023 AirPods Pro with USB-C in stock and on sale for $189.99 on their online store as part of their Holiday sale. Their price is $60 off MSRP, and it’s currently the lowest price... Read more
Apple has Certified Refurbished iPhone 12 Pro...
Apple has unlocked Certified Refurbished iPhone 12 Pro models in stock starting at $589 and ranging up to $350 off original MSRP. Apple includes a standard one-year warranty and new outer shell with... Read more
Holiday Sale: Take $50 off every 10th-generat...
Amazon has Apple’s 10th-generation iPads on sale for $50 off MSRP, starting at $399, as part of their Holiday Sale. Their discount applies to all models and all colors. With the discount, Amazon’s... Read more
The latest Mac mini Holiday sales, get one to...
Apple retailers are offering Apple’s M2 Mac minis for $100 off MSRP as part of their Holiday sales. Prices start at only $499. Here are the lowest prices available: (1): Amazon has Apple’s M2-powered... Read more
Save $300 on a 24-inch iMac with these Certif...
With the recent introduction of new M3-powered 24″ iMacs, Apple dropped prices on clearance M1 iMacs in their Certified Refurbished store. Models are available starting at $1049 and range up to $300... Read more
Apple M1-powered iPad Airs are back on Holida...
Amazon has 10.9″ M1 WiFi iPad Airs back on Holiday sale for $100 off Apple’s MSRP, with prices starting at $499. Each includes free shipping. Their prices are the lowest available among the Apple... Read more
Sunday Sale: Apple 14-inch M3 MacBook Pro on...
B&H Photo has new 14″ M3 MacBook Pros, in Space Gray, on Holiday sale for $150 off MSRP, only $1449. B&H offers free 1-2 day delivery to most US addresses: – 14″ 8-Core M3 MacBook Pro (8GB... Read more

Jobs Board

Mobile Platform Engineer ( *Apple* /AirWatch)...
…systems, installing and maintaining certificates, navigating multiple network segments and Apple /IOS devices, Mobile Device Management systems such as AirWatch, and Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Senior Product Manager - *Apple* - DISH Net...
…Responsibilities** We are seeking an ambitious, data-driven thinker to assist the Apple Product Development team as our Wireless Product division continues to grow Read more
Senior Product Manager - *Apple* - DISH Net...
…Responsibilities** We are seeking an ambitious, data-driven thinker to assist the Apple Product Development team as our Wireless Product division continues to grow Read more
Senior Software Engineer - *Apple* Fundamen...
…center of Microsoft's efforts to empower our users to do more. The Apple Fundamentals team focused on defining and improving the end-to-end developer experience in Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.