Apple II Q&A

Apple II DEVELOPER TECHNICAL SUPPORT

Q When I write an Apple II GS TextEdit keyFilter procedure and put its address in my
TextEdit control template, I get funny little pieces of garbage drawn on the screen in
my TextEdit record, and sometimes TextEdit crashes. Doesn't the keyFilter mechanism
work?

A The keyFilter mechanism in TextEdit works, but there's no space for a keyFilter
address in a TextEdit control template. The only filter procedure in the control
template is the generic  filter procedure, which does not take the same parameters as
the keyFilter procedure. If you include a filterProc address in a TextEdit control
template, it must be to a generic filter procedure. Generic filter procedures are
defined on pages 49-16 through 49-18 of Apple IIGS Toolbox Reference  Volume 3.

 If you want to use TextEdit's keystroke filter, word wrap hook, or word break hook,
you must modify the TERecord directly to put your procedure's address in the
appropriate place.

Q While linking my Apple IIGS® application, LinkIIGS does a system death:
"ExpressLoad error 1301." What am I doing wrong?

A Believe it or not, LinkII GS has dynamic segments. ExpressLoad has the annoying
habit of taking error codes it's not expecting, adding $1100 to them, and calling
SysFailMgr. Why is this habit annoying? Well, it works just fine for what the author
had in mind, which was GS/OS errors (all of the form $00xx), but it causes problems
with Toolbox errors.

 You've probably figured out the rest by now: $1301 - $1100 = $0201 = Memory
Manager "unable to allocate handle" error. ExpressLoad ran out of memory trying to
load a dynamic segment in LinkIIGS.

 The best solution is to get more memory. If you can't make enough memory to link it,
you might consider having some of your code in code resources instead of in dynamic
segments in the data fork, to create separate links for those segments and make the big
link even smaller.

Q What is the correct procedure for installing system software on an Apple II GS?

A Always use the Installer application. The Installer scripts provided by Apple on the
Apple II GS system disks will put everything you need on the startup disk. If you
attempt to install system software without using the Installer, there's a good chance
you'll forget to copy a needed file or delete an obsolete file. Because SCSI hard disk
drivers are not included on System.Disk, you'll need to do the following to install
System 5.0.4 on a hard disk:

1. Make backup copies of System.Disk and System.Tools, making sure they
   keep the same names.
2. Launch the Installer from System.Tools (backup) and install SCSI Driver
   on the backup of System.Disk. The Installer script will delete a couple of fonts
   as well as the tutorial folder to make room for the SCSI information on a
   3.5-inch disk.
3. Boot the backup of System.Disk and install System 5.0.4 onto your hard
   drive. If you want Shaston 16 and Times 12 fonts, install "Additional Fonts"
   last.

 The Installer knows how to make the software fit on a floppy disk. It can also update
your system without requiring you to trash your existing System Folder.

 Apple IIGS Technical Note #64, Apple IIGS Installer and Installer Scripts, describes
how the Apple IIGS Installer executes Installer script files and how to write Installer
script files.

Q In some of my recent work, I've found it necessary to patch the Apple II GS GS/OS
vectors in order to monitor OS calls. My patch works without interfering, but it
disappears when the user switches to ProDOS 8 and back to GS/OS. I tried
unsuccessfully to fix this by using the notification queue, asking GS/OS to notify me
when the user was coming back from ProDOS 8. How can I safely and reliably patch
GS/OS on a permanent basis?

A You should be able to patch GS/OS ®  with System 5.0.4. Two observations may help:

• If you ask for all notification events, you'll get at least one disk-insert
  event before you get any restart events, since the device driver for the startup
  disk will "fake" a disk insert to get the appropriate disk-switched statuses set
  before doing any real work.
• Your procedure may not be the first notification procedure called at
  restart time. For example, the Resource Manager inserts a procedure so that
  it can reopen the system resource file on return from ProDOS®
• If this mechanism was broken as you say, the Resource Manager's
  notification procedure wouldn't work either.

Q Why does a dialog box without a Cancel button come up from an Apple II GS Loader
call when the volume is not on-line?

A The loaders always set the preferences to "dialog, no Cancel button" when trying to
load a dynamic segment indirectly (because you passed control to it). The loaders must
do this because they have no way to report errors. For example, if your code does a
JMP DynSegLabel, the Loader must load the dynamic segment. Should it get an error, it
has no way to report an error and no place to pass control back to if your program does
a JMP and the Loader has no place to return to. In earlier systems, inability to load a
dynamic segment was a fatal system error. Today, the Loader will not give up until you
insert the disk because it has no other choice. However, if you call LoadSegName
yourself, the Loader should not change the preferences; because that's a call, the
Loader can return from it gracefully. Indirect dynamic segment loading doesn't have
that luxury. The current Loader documentation is in the Addison-Wesley version of
GS/OS Reference .

Q What are longStatText2 items, mentioned in the "Dialog Manager" chapter of the
Apple II GS Toolbox Reference?

A A longStatText2 item is similar to a longStatText item except that the text is drawn
with LETextBox2. A longStatText2 item allows you to embed formatting codes so that
you can change fonts, font styles, sizes, colors, and justification. The longStatText2
capability is built into the Dialog Manager to support formatting flexibility in
standard dialogs. To use longStatText2 items, the Apple IIGS QuickDraw Auxiliary and
Font Manager tools must be started.

Q Where do I find a current list of the MessageCenter message types that have been
registered with DTS?

A Message types that are assigned to individual developers are treated confidentially.
We have very few of these, as most developers now use MessageByName to get an
assignment dynamically.

Q Where do I find technical documentation on the messages written by the Finder to tell
an Apple II GS application which files to open as it starts up?

A The only truly public message types are #1 (the files message from the Finder or
other program launchers) and #2 (the desktop pattern message).

 Message type #1 is documented in Apple IIGS Toolbox Reference  Volume 2, with the
description of the MessageCenter tool call. The documentation implies that there are
both filenames and full pathnames (such as Standard File returns) in the message,
but, in fact, each Pascal string indicates a totally separate file. Message type #2 is
documented in Apple IIGS Toolbox Reference  Volume 3, in the "Window Manager
Update" chapter (page 52-4).

Q How does an Apple II GS New Desk Accessory (NDA) obtain its ID?

A Each Apple IIGS NDA has two IDs: a Memory Manager ID and a Menu ID. If you want
the Memory Manager ID, simply call MMStartup from your DA. The NDA ID for the
OpenNDA call can easily be obtained from your menu string. The Desk Manager
replaces the ** of your \H** at the end of your menu string with your Menu ID, which
is also your NDA number. A note of caution: Please be sure you're running in the
16-bit environment before using the NDA ID to call OpenNDA. If you try this while
ProDOS 8 is running, nothing good comes of it!

Q I'm creating an Apple IIGS list control from a resource. How can I update my listRef
resource dynamically, if my list grows dynamically?

A To modify the content of a resource and to grow it, load the resource, make any
changes you want to the handle (such as change the data inside or call SetHandleSize to
make it bigger), and then use the MarkResourceChange call to tell the Resource
Manager your resource's content has been changed. The Resource Manager then updates
the contents of your file when you call UpdateResourceFile. The Resource Manager even
recognizes handle size and content changes (actually, it just assumes the contents have
changed).

Q Why is there no GS-only version of HyperMover?

A HyperMoverTM is actually implemented as a pair of HyperCard ® stacks:
HyperMover.mac, which runs under Macintosh HyperCard and disassembles Macintosh
stacks; and HyperMover.GS, which runs under HyperCard II GS and reassembles the
stacks into HyperCard IIGS stacks. Although there are a few XCMDs to handle tricky
stuff like sounds and paint files, the majority of the work is done by simple HyperTalk
scripts. It may seem like a disadvantage to require two computers to do the translation,
but in fact there are a number of tremendous advantages:

• HyperMover doesn't need to know anything about the internal binary
  format of stacks. This makes it somewhat immune to stack format changes. For
  example, you can convert a Macintosh HyperCard 1.2.5 stack to HyperCard
  2.0 format, but HyperMover will still translate it because the HyperCard
  program takes care of reading data from the stack.
• The interchange format is simple--a file containing a complete textual
  description of the stack. After disassembly, you can open and even edit this file
  using any text editor (such as MPW or APW), before reassembling the file on
  the GS side. This provides an easy way to browse scripts, looking for potential
  machine dependencies, and you can actually perform global modifications on
  your stack using the find-and-replace capabilities of your text editor.
• When small-font painted text is used to label objects, it often shrinks to
  unreadability when converted to the Apple IIGS screen resolution. You'll need a
  Macintosh to view all the graphics and decide what they're supposed to look
  like, before you can redraw them in 16- color Apple IIGS graphics.
• You'll also need a Macintosh to perform side-by-side comparisons and
  testing of your new stack.

 Having a Macintosh available is important at all  phases of the stack translation
process. You'll find it makes the entire process much smoother.

Q Which versions of Macintosh HyperCard are compatible with HyperMover?

A The HyperMover stack will execute in the 1.2.5 and 2.0 Macintosh HyperCard
environments. However, stacks that are translated should be either 1.2.5 stacks, or
1.2.5 stacks converted  to 2.0 but not modified . There are two reasons for this:

• The graphics converters are designed to start from a Macintosh
  HyperCard 1.2.5-sized card only, because stacks with other card sizes may
  have objects and graphics improperly aligned.
• HyperCard IIGS uses a version of the HyperTalk ® scripting language
  derived from Macintosh HyperCard 1.2.5, so if a stack uses language elements
  that were not present in Macintosh HyperCard 1.2.5, it may translate
  correctly but report script errors when the script is executed.

Q How can I perform error trapping in a script?

A Normally, most errors interrupt script execution and immediately present a dialog
to the user. Advanced scripters may want to intercept these errors and deal with them
more "aggressively." Two new HyperCard properties, lockErrors and lastError, have
been provided to control error handling:

• lockErrors is a Boolean property that has a simple effect: it prevents the
  display of errors. The errors, however, are still there, and stop execution of
  the current handler.
• lastError is a string property that always contains the text of the most
  recent error dialog, whether displayed or not. Because errors cause handlers
  to terminate, you'll probably wind up checking lastError from an idle
  handler.

 How do you use lockErrors and lastError? To activate an "error catcher" you can use
the following scripts:

on CatchErrors errorSource    -- Begin handling errors.
  global gErrorSource
  set the lastError to empty
  set lockErrors to true
  put errorSource into gErrorSource
end CatchErrors
on ClearErrors        -- Handle errors normally.
  global gErrorSource
  set the lastError to empty
  set lockErrors to false
  put empty into gErrorSource
end ClearErrors
on idle               -- Check for error occurrence.
  global gErrorSource
  if gErrorSource is not empty
  then
    -- Error-handling code goes here.
    -- gErrorSource = where in your code the error happened.
    -- The lastError = what the error was.
  end if
  pass idle
end idle

 If you have a button that does something dangerous, you can surround the dangerous
portions of the handler with

on mouseUp
  -- normal error handling out here
  CatchErrors “dangerous operation #1”
  -- Do things that might not work.
  ClearErrors
  -- Now we’re back to normal error handling.
end mouseUp

 For more information, be sure to see the HyperCard IIGS Script Language Guide ,
published by Addison-Wesley.

Kudos to our readers who care enough to ask us terrific and well thought-out
questions. The answers are supplied by our teams of technical gurus; our thanks to all.
Special thanks to Matt Deatherage, C. K. Haun, Jim Luther, and Jim Mensch for the
material in this Q & A column.

 *Have more questions? Need more answers? Take a look at the developer
technical library on AppleLink (updated weekly) or the Q & A stack on the Developer
Essentials   disc. *