System Sleuthing II: The Sequel

By Joel West, Palomar Software, Inc., MacTutor Contributing Editor

About this time last year, I wrote an installment of Resource Roundup on the various changes in trap patches from System 3.2 to 4.1, and the compatibility issues related to the use of those systems (“Sleuthing the New System File,” August 1987.)

That article seemed to have struck a chord, with many programmers (including some generous folks from Apple) telling me it was extremely valuable to have the information all pulled together all in one place.

Since that time, the original story has continued where we left off last time, with two new system software releases introduced to date.

So, like many Hollywood writers and producers lacking creativity, I’ve decided to go for the easy buck, the cheap knock-off; in short, a sequel:

Sleuthing the System File,Part II: MultiFinder. Starring System 4.2 (née 5.0) and 6.0.

Written by yours truly.

Incidentally, we’ll pick up the story where we left off last time, so if you have the earlier article handy, you may wish to grab it to refresh your memory.

A Number of Numbers

First, let me clear up a little appelative confusion in these most recent systems.

I have two sets of disks sitting next to my desk. One is marked 5.0, dated October 1987; another is marked 6.0, dated April 1988. However, 5.0 is not called 5.0 by most of its components, although 6.0 is much better in this regards.

If you’ll recall our last episode, the naming scheme is somewhat arcane for the System and Finder (and now MultiFinder). Table 1 shows an updated list of software versions, and the systems with which they are compatible.

Release 5.0 actually consists of System 4.2, Finder 6.0 and MultiFinder 1.0 (figure that one out!). However, Release 6.0 offers an important step towards sanity, with version numbers 6.0, 6.1, and 6.0, respectively. It seems apparent that all the numbers will eventually be the same.

Let’s hope they stop changing the leading digit every 6 months, or we’ll be up to version 19.0 (instead of 9.3) in no time at all. I also like a two-part rule-of-thumb I’ve heard for software versions that is not specific to Apple’s software: 1. When they change the first digit, the programmers were ambitiously adding new features, so watch out! 2. When they change the digit after the decimal point, you have a good, reliable piece of software, because they were mostly fixing bugs, not adding them.

Fig. 1 Patch Size Trend in Bytes is going up, up, up!

Note that the table offers the most optimistic viewpoint of compatibility; if the version was ever considered compatible, I list it as compatible, although usually the latest version has the most up-to-date bug fixes. Also, a 512Ke with a 1 Mb or more (third party or otherwise) can be treated just like a Plus; otherwise, taking a 512K memory configuration beyond System 3.3 is not such a great idea.

Not shown in the table is the great improvement in user-identifiable version information now included in all system software. The ‘vers’ resource, when properly used by any programmer, provides the user with a way to unambiguously identify the version of software or a document. More on that another time.

Passels of PC’s

A year ago, I was writing the earlier article on my Macintosh Plus; thus, my testing emphasized the Plus, because it was easier much more accessible.

A full year later, I’m back to a Macintosh Plus again. However, this year I was able to test on Macintosh II and SE’s owned by Palomar Software.

Of the Mac II’s at the office, we have both the original ROM and the second revision (which provides 32-bit Slot Manager support). However, it should be noted that the ‘PTCH’ resources don’t distinguish between the two, patching the same traps for each. Also, the location of all ROM-based traps were the same, lending credence to the speculation that the changes were limited in nature.

Any Similarity to Real Traps

As I’ve said before, Apple doesn’t show me ROM listings, which, under trade secret law, allows me to write what little I know and publish it in MacTutor!

I used the same algorithm as in Part I, which compares the address of each trap to the standard unimplemented trap, $A89F. The sample program shown there is unchanged.

This gives me the availability of each trap by trap word ($A000-AFFF) with certainty, both for the traps that have names, and those that do not. But for the dispatched traps, I can’t tell when (or which) new traps are added that share the same dispatch word.

As before, I’ve left off those traps for which I have discerned names but are not supported by Apple. Even more traps are defined but not named outside Apple--although it’s interesting to note that System 6.0 seems to remove many of these traps from the trap table, marking them as unimplemented.

Apple does provide some clues as to why the changes were made, which were of great help.

Bigger and Better

Extensible software is one of my fetishes; my main complaints against the Mac OS and Toolbox design are in those areas where it is not extensible.

Thus, in hindsight, I can say that the RAM-based trap patches introduced by Apple about two years ago were a brillant move. One look at the size of today’s patches and the functionality changes they provide will show how successful the concept has been.

As we saw in the last episode, trap patches have three purposes:

• Fix a bug;

• Extend existing capabilities

• Add a new trap.

In System 4.2 and 6.0, very few new traps were defined. Instead, the most radical difference since 4.1 comes with MultiFinder, which defines a few new traps and, more significantly, redefined many more.

As before, the ‘PTCH’ resources are used to apply machine-specific trap patches. New are the ‘ptch’ resources, which define patches common to two or more machine types. This reduces the size of the System file by removing duplicate patches, although the actual memory used may be higher.

In fact, the trend has been towards more and more memory allocated for patches. Table 2 lists the sizes of each patch resource, and the total size of the resources (approximately the total RAM required for the patches).

As shown in Figure 1, the Macintosh II has increased the most. It once had the most up-to-date ROM, but with most of the patches in the other machines, plus those required for Color QuickDraw, it now leads the way.

Unlike our last episode, Apple now approves allowing the user to install a stripped System disk with only those patches needed for their particular machine. (I guess the problem of building a MultiFinder master disk gave this an added urgency.)

If the user tries the stripped System on another model, an error alert is given at boot time and (s)he’s told to go back to the drawing board.

MultiFinder

MultiFinder has a major effect on the run-time environment of an application, including the available traps.

As shown in Table 3, MultiFinder defines two new traps. _WaitNextEvent is a _GetNextEvent designed for non-preemptive multitasking, while _OSDispatch is currently used only to get at MultiFinder temporary memory management routines.

Even without MultiFinder, _WaitNextEvent is implemented in System 6.0. If you wondered why Apple advised you to check the availability of the two traps separately, wonder no more.

MultiFinder also patches a large number of traps to augment windowing, event, file control and memory-related functions. Changes also affect the Standard File Package and several Resource Manager calls, as shown in Table 4.

Other New Traps since 4.1

The new traps have been defined since the earlier episode are listed in Table 5. All but one of the traps are new with System 6.0.

One new trap, _LwrString, is a complement to the long-standing _UprString in the OS Utilities. It should be used only as a quick&dirty way to lower-case Roman text; a more portable call is to use the Script Manager transliteration routines.

All machines get a new manager in System 6.0, the Notification Manager. This provides a structured way for a background application to get a user’s attention, as PrintMonitor does under MultiFinder.

The Notification Manager requires two new traps, _NMInstall and _NMRemove, which add and delete notification requests from a system-maintained queue. Everything you ever wanted to know about the Notification Manager is in Macintosh Technical Note #184.

The Notification Manager traps are stored ‘ptch’ #2.

Two traps that are not new to most programmers are _Debugger and _DebugStr. However, they are now provided by default by System 6.0, even if no debugger is installed.

I think this is great. Suppose you accidentally leave debugging code in your program and give it to an unsophisticated user. Your debugging calls become no-ops instead of ID=12 bombs: which do you think the user would prefer?

Finally, System 4.2 introduced one new trap for the Macintosh II only. The Pallette Manager was extended by _CopyPalette, for making a copy of a palette.

RAM-based traps

Although the Macintosh II included a new Sound Manager, this was not available across all machines. System 6.0 remedies this situation by providing the same RAM-based Sound Manager for all three machines. This provides bug fixes to the earlier version in the Mac II ROM.

The Sound Manager patches for all three machines are stored in ‘ptch’ #3.

Extended TextEdit, originally in RAM for the Mac Plus only, has been corrected and improved since System 4.2. Again, for all three machines, the manager is RAM-based, even though the Mac II has earlier versions in ROM.

These TextEdit patches are stored in ‘ptch’ #0.

Mac II Teething Pains

New babies have teething pains; the Macintosh II was no exceptions.

It appears that a large amount of new code was written for the Mac II ROM. Even for existing traps, some may have been recoded in 68020 for speed; other code was required to support many of the Toolbox extensions, such as auxillary window records.

We all know there were severe time constraints in getting it out the door, so it’s not suprising there were problems, although I never noticed fatal problems associated with using my Mac II (except brain-damaged code incompatible with a 68020).

Both System 4.2 and 6.0 include a large number of traps patched only for the Macintosh II. These are listed in Table 8 and 9.

System 6.0 includes a much more robust and aggressive Palette Manager than was included in System 4.1, where it was a last-minute addition. However, the Palette Manager is not shown in the list of trap patches, because it has always been RAM-based, so the current testing methodology will not show any changes. However, changes to the two Color Manager calls _SaveEntries and _RestoreEntries are a tip-off to this color re-write.

I should also note that a few of these routines may also have been patched to fix problems in the Macintosh Plus and SE. As noted, these routines were already patched in System 4.1 to provide new functionality (notably hierarchical menus), so I couldn’t tell if they also had been changed by 4.2 or 6.0.

Other Bug Fixes

The remaining trap patches are shown in Table 10.

System 4.2 fixes the notorious early bug with _ADBReInit, while updating the _KeyTrans implementation.

System 6.0 improves the behavior of the standard polygon-drawing calls with large coordinates. Even if only a few points were defined, large enough coordinates would crash QuickDraw (without warning).

This was first pointed out to me by Jean-Paul Harmand at the Paris developer’s conference in April. His program is shown in Example 1; it works fine with 6.0, but crashes with ID=25 on System 4.2.

There were quite a few places were traps were unpatched by one of the new releases. Since I haven’t the foggiest idea of how to explain anything like that, I didn’t list them, except for those traps patched in System 4.2 but not in 6.0.

Hidden Changes

I can’t tell directly when a trap patch changes: if it was previously patched, all I know is that it remained patched, not whether the patch is the same.

In addition, for the dispatched traps, I can’t tell which new traps are added that share the same dispatch word.

There are two areas that surely changed but don’t show up on the list.

First, System 6.0 includes major changes to software related to internationalization. This includes the International Utilities and the Script Manager. A brief list of the new calls is given in Table 11. Except for the previously-mentioned _LwrString, all of these calls are part of a dispatched trap, either _Pack6 or _ScriptUtil, respectively; thus, there’s no way of knowing they’re there, except from the documentaton.

Secondly, _SysEnvirons has been updated for each machine and system version. Needless to say, this will always be a RAM-based call.

Printing Glue

In the earlier episode, I spent some time on the trap-based Printing Manager introduced in System 3.3.

Programmers who can verify (or count on) System 3.3 or later should use the traps, since this is the official, supported way from now on.

However, MPW programmers who still use glue may be in for a suprise. In MPW 2.0, the C and Pascal glue libraries first check for the trap to be implemented; if it is, they call it instead of performing the original Lisa Pascal glue functionality.

Acknowledgements

Since System 4.1, Apple has been including valuable release notes with each mailing of the new disks to developers.

The release notes only keep getting better; in the case of 6.0, it even includes a list of all the managers, any changes and their current known bugs.

I’m sure I speak for all developers when I say the more timely information like this, the better. This information was extremely valuable, both in tracking down our own compatibility problems, and in preparing this article.

If you haven’t figured it out already, you should grab all the release notes in your possession, shove them into a binder and file it next to Inside Macintosh and your tech notes in the programmer library.

Tech Support also provided me with an early draft of the Script Manager 2.0 documentation. I was about to sit down and write a two-part series on internationalizing software until I heard about 2.0, so I’ve held it up until I can fully grasp all the information. Look for it in a future issue.

Corrections

This all started when I was writing Programming with Macintosh Programmer’s Workshop . If you want a list of all the traps up to System 4.1, see Appendix E, but please excuse some of the formatting problems.

In the prior episode, I said the Levco Prodigy (for the Mac Plus) patched certain unnamed traps. Duane Maxwell of Levco promised that he hadn’t, but this information didn’t make it into the earlier article in time for publication.

Table 2: Trap patch sizes

Table 3: New traps in MultiFinder

Name Word 5.0 6.0 MultiFinder

_WaitNextEvent A860 • •

_OSDispatch A88F •

Table 4: Traps patched by MultiFinder 6.0

Name Word

_Open A000

_Close A001

_GetVolInfo A007

_ReallocHandle A027

_SetTrapAddress A047

_HNoPurge A04A

_RDrvrInstall A04F

_NewHandle A122

_HFSDispatch A260

_SetCursor A851

_CalcVis A909

_CalcVBehind A90A

_ClipAbove A90B

_PaintOne A90C

_PaintBehind A90D

_NewWindow A913

_SelectWindow A91F

_BringToFront A920

_DragWindow A925

_CloseWindow A92D

_AddResMenu A94D

_GetNextEvent A970

_EventAvail A971

_WaitMouseUp A977

_ModalDialog A991

_UpdateResFile A999

_GetNamedResource A9A1

_SizeRsrc A9A5

_GetResAttrs A9A6

_GetResInfo A9A8

_SystemEvent A9B2

_SystemClick A9B3

_OpenDeskAcc A9B6

_SysEdit A9C2

_SysError A9C9

_Pack3 A9EA

Table 5: Other New Traps

Manager Trap Word Version Machine

Script _LwrString A056 6.0 Plus, SE, II

Notification _NMInstall A05E 6.0 Plus, SE, II

Notification _NMRemove A05F 6.0 Plus, SE, II

Debugger _Debugger A9FF 6.0 Plus, SE, II

Palette _CopyPalette AAA1 4.2 II

DebugStr _Debugger ABFF 6.0 Plus, SE, II

Table 6: RAM-based Sound Manager

Name Word

_SndDisposeChannel A801

_SndAddModifier A802

_SndDoCommand A803

_SndDoImmediate A804

_SndPlay A805

_SndControl A806

_SndNewChannel A807

_SysBeep A9C8

ROM-based Sound Manager traps are available in the Macintosh II only. With System 6.0, RAM-based traps are defined for the Macintosh Plus, SE, and II. System 6.0 also patches the OS Utility _SysBeep is patched for the Macintosh Plus and Macintosh SE only.

Table 7: RAM-based TextEdit

Name Word

_TESelView A811

_TEAutoView A813

_TEGetOffset A83C

_TEDispatch A83D

_TEStyleNew A83E

_TEGetText A9CB

_TEInit A9CC

_TEDispose A9CD

_TextBox A9CE

_TESetText A9CF

_TECalText A9D0

_TESetSelect A9D1

_TENew A9D2

_TEUpdate A9D3

_TEClick A9D4

_TECopy A9D5

_TECut A9D6

_TEDelete A9D7

_TEActivate A9D8

_TEDeactivate A9D9

_TEIdle A9DA

_TEPaste A9DB

_TEKey A9DC

_TEScroll A9DD

_TEInsert A9DE

_TESetJust A9DF

Table 8: Macintosh II System 4.2 patches

Name Word

_Open A000

_GetHandleSize A025

_SwapMMUMode A05D

_GetMaskTable A836

_FixDiv A84D

_NewRgn A8D8

_MapRect A8FA

_PaintOne A90C

_PaintBehind A90D

_NewWindow A913

_CouldDialog A979

_FreeDialog A97A

_DiposDialog A983

_CouldAlert A989

_FreeAlert A98A

_DetachResource A992

_HandToHand A9E1

_DisposPixPat AA08

_DisposCCursor AA26

_SetWinColor AA41

_GetAuxWin AA42

_NewCWindow AA45

_GetNewCWindow AA46

_DrawPictureÝ A8F6

_InsertMenuÝ A935

_CalcMenuSizeÝ A948

_CountMItemsÝ A950

_DelMenuItemÝ A952

Ý Patched in System 4.1 and later for the Macintosh Plus and SE.

Table 9: Macintosh II System 6.0 patches

Name Word

_DisposHandle A023

_HSetState A06A

_SetOSDefault A083

_InitGraf A86E

_InitWindows A912

_GetKeys A976

_NewPixPat AA07

_SetDeskCPat AA47

_SaveEntries AA49

_RestoreEntries AA4A

_EnableItemÝ A939

_MenuSelectÝ A93D

_MenuKeyÝ A93E

Ý Patched in System 4.1 and later for the Macintosh Plus and SE.

Table 10: Other patches

Name Word Plus SE II

_UnmountVol A00E 6.0 4.2 4.2

_GetVol A014 ram 4.2 4.2

_DisposPtr A01F 4.2§ 4.2§

_HLock A029 4.2§ 4.2§

_HUnlock A02A 4.2§ 4.2

_InitApplZone A02C 4.2 6.0

_ADBReInit A07B - 4.2 4.2

_KeyTrans A9C3 ram 4.2 4.2

_StdPoly A8C5 6.0 6.0 ram

_PackBits A8CF 6.0 4.2

_StdBits A8EB 6.0 6.0

_StdTxMeas A8ED 6.0 6.0

_MoveWindow A91B 6.0 6.0 ram

_InitResources A995 6.0 6.0 6.0

_SystemTask A9B4 6.0 6.0 6.0

Legend:

Notation 4.1 4.2 6.0

ROM ROM ROM

ram RAM RAM RAM

4.2 ROM RAM RAM

4.2§ ROM RAM ROM

6.0 ROM ROM RAM

- (n.a.) (n.a.) (n.a.)

Table 11: New Script Manager calls

OS Utilities

UprText Same as UprString

LwrText Simplified change to lowercase

Script Manager

FindBlock Break Roman text from native run

Form2Str Display numeric format string

FormStr2X Parse string to number using format

FormX2Str Display number in string using format

GetFormatOrder Arrange text for bi-directional format runs

InitDateCache Initialize for String2Date and String2Time

LineBreak Break line on word boundary

LongDate2Secs Convert date with era to 64-bit integer

LongSecs2Date Convert 64-bit integer to date with era

PortionText Proportionate justification information

ReadLocation Read latitude, longitude, GMT difference

Str2Form Compile numeric format string

String2Date Convert string to date

String2Time Convert string to time

ToggleDate Increase/decrease date field

ValidDate Validate date

VisibleLength Length of text excluding trailing white space

WriteLocation Write latitude, longitude, GMT difference

International Utilities

IULDateString Convert long date to string

IULTimeString Convert long time to string

Source Code Listing: Quickdraw Crasher
; Sample program to crash QuickDraw with Polygon operation
; Original by Jean-Paul Harmand
; Transcribed to MPW by Joel West for MacTutor, 6/10/88
;
; Build using:
;CreateMake PolyTest PolyTest.a
;BuildProgram PolyTest
;
 Print  OFF
 Include‘Traps.a’
;Include‘ToolEqu.a’
 Include‘QuickEqu.a’
;Include‘SysEqu.a’
 Print  ON

QuickDraw RECORD ,DECREMENT
thePort DS.L1
white   DS.B8
black   DS.B8
gray    DS.B8
ltGray  DS.B8
dkGray  DS.B8
arrow   DS.BcursRec
screenBitsDS.B   bitmapRec
randSeedDS.L1
 ORG    -grafSize
 ENDR

 MAIN
PolyLen EQU $001E

 WITH QuickDraw
 PEA    thePort 
 _InitGraf
 _InitFonts
 _InitWindows
 _InitMenus
 CLR.L  -(SP)
 _InitDialogs
 _TEInit
 _InitCursor
 MOVE.L #PolyLen,D0
 _NewHandle

 MOVE.L A0,A2
 MOVE.L (A0),A0
 LEA    PolyValues,A1
 MOVE.W #PolyLen/2,D0
@1 MOVE.W (A1)+,(A0)+
 DBRA D0,@1
 
 MOVE.L A2,-(SP)
 PEA    WhitePattern
 _FillPoly
 _ExitToShell

WhitePattern
 DC.L 0,0
PolyValues
 DC.W PolyLen
 DC.W $FD20,$FDC3,$165C,$07EE
 DC.W $165C,$07EE
 DC.W $1170,$02B4
 DC.W $02FF,$0021
 DC.W $FD20,$FDC3
 DC.W $165C,$07EE
 ENDMAIN

 END