|Column Tag:||Resource Roundup
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, Ive 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.
Produced by Apple Computer, Inc.
Incidentally, well 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 youll 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.
Lets hope they stop changing the leading digit every 6 months, or well be up to version 19.0 (instead of 9.3) in no time at all. I also like a two-part rule-of-thumb Ive heard for software versions that is not specific to Apples 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 PCs
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, Im back to a Macintosh Plus again. However, this year I was able to test on Macintosh II and SEs owned by Palomar Software.
Of the Mac IIs 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 dont 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 Ive said before, Apple doesnt 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 cant tell when (or which) new traps are added that share the same dispatch word.
As before, Ive 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 its 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 todays 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)hes told to go back to the drawing board.
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 users 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.
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 its 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 couldnt 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 developers 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 havent the foggiest idea of how to explain anything like that, I didnt list them, except for those traps patched in System 4.2 but not in 6.0.
I cant 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 cant tell which new traps are added that share the same dispatch word.
There are two areas that surely changed but dont 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, theres no way of knowing theyre 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.
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.
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.
Im 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 havent 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 Ive held it up until I can fully grasp all the information. Look for it in a future issue.
This all started when I was writing Programming with Macintosh Programmers 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 hadnt, but this information didnt make it into the earlier article in time for publication.
Table 2: Trap patch sizes
|System 4.1||System 4.2||System 6.0
|ptch #1 (Plus,SE)||4,762
Table 3: New traps in MultiFinder
Name Word 5.0 6.0 MultiFinder
Table 4: Traps patched by MultiFinder 6.0
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
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
Table 8: Macintosh II System 4.2 patches
Ý Patched in System 4.1 and later for the Macintosh Plus and SE.
Table 9: Macintosh II System 6.0 patches
Ý 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
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
UprText Same as UprString
LwrText Simplified change to lowercase
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
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
QuickDraw RECORD ,DECREMENT
PolyLen EQU $001E
@1 MOVE.W (A1)+,(A0)+