Chooser with ATalk
|Column Tag:||C Workshop
How the Chooser Works with AppleTalk
By Bob Denny, Alisa Systems, Editorial Board
The 3.0 and later releases of the Macintosh system software (the System resource file) contain a new desk accessory called the Chooser. It replaces the old Choose Printer and provides a way to select devices in general, not just printers (note that the Chooser will not operate with earlier System versions). The Chooser is used to select remote devices of all sorts including printers and file servers, as well as ports for local devices such as the serial Imagewriter.
This article covers the operation of the Chooser (and its companion, the Namer), and describes how to add support for user-supplied devices to the Chooser. It also describes the zone concept, an important new addition to the AppleTalk architecture. The next release of the Chooser will support zone selection for remote (AppleTalk) device lists. Finally, the name string at the bottom of the Chooser window is described.
Figure 1 shows the window display of the Chooser that was released with System 3.0. Apple is currently finishing development of a new Chooser which will have a different appearance and will support AppleTalk zone selection, as discussed later.
The icons along the left edge correspond to the device files that the Chooser finds on the boot volume. When it is first brought up, the Chooser searches the blessed (System) folder HFS devices, or the entire disk on MFS devices, for these device files. For each one it finds, it opens the file, reads the icon and flags word, then closes it. When this process completes, the Chooser opens the device file for the current printer.
The list box shows the list of choices that are appropriate for the type of device that is selected. For the serial Imagewriter, the icons corresponding to the two possible connection ports (printer & modem) are displayed. For the LaserWriter and AppleTalk Imagewriter, the names of the available printers are listed. Note that you can name a LaserWriter anything you want (well, almost), and you must have a unique name for each LaserWriter on your net. If you have 5 LaserWriters, you'll see their 5 names in the list box.
The contents and action of the list box is handled by the List Manager, a new package supplied in Systems 3.0 and later. For more information on the List manager, see the updates to Inside Macintosh furnished with the December, 1985 (really March, 1986) Software Supplement. You should also refer to Schuster, Mike (1986), Palette Selection via List Manager, Mac Tutor, Vol.2, No. 5, May, 1986.
The cells of the list are filled in either by default procedures contained within the Chooser, or via an external fillList procedure provided with the device resources. For serial printers, the Chooser handles the display of the port icons in the list window. For AppleTalk devices, a default procedure is provided that issues periodic name lookups on the net for the specified device type and fills in the names found (more on this in the next section). If the device supports a fillList procedure, then it is called by the Chooser to fill in the list cells.
Finally, note that the Chooser is a modeless dialog. This means that the Chooser may be active while the user does other things.
AppleTalk Names and Zones
AppleTalk supports internetworking, the interconnection of networks. Depending on the application mix, a single AppleTalk net can comfortably support a cluster of from 4 to, say, 20 nodes. Large organizations can connect their work-group clusters by means of bridges to form an internet.
On AppleTalk, entities (such as LaserWriters) are located by using the Name Binding Protocol (NBP). Every entity on the net has a name which consists of three fields, the object, type and zone. The object is the actual name of the thing, the type puts the thing into a category, and the zone defines the set of networks in which the name is known. The first two fields are possessed by the object, the zone name is implicitly set by it's location in the internet, as we'll see.
NBP locates objects of a given type in the internet by broadcasting a request for the names and addresses of all objects of that type. The replies come streaming in from all over the internet, through the bridges, and into the requesting node. Normally a series of requests is issued to reduce the vulnerability to lost replies.
On a large internet, this process can become unwieldy. Suppose you had a world-class internet with nets located in cities on several continents. You bring up the Chooser to select one of your local LaserWriters, and after a minute or so, there are 600 LaserWriters in the list! Gad! Imagine the blast of traffic that such a lookup would generate. And who cares about the LaserWriters in Frankfurt, anyway?
The solution to this mess is to divide the internet into name zones. A zone is defined as a set of nets within which names are unique. Name lookups are restricted to the nets in a single zone. The intent is for organizations to partition the internet into zones corresponding to the geographic layout of their facilities, or by department, or something like that.
Note that zone partitioning relates only to name lookups. Every node on the internet is addressed by net/node/socket at all times. Zones partition the internet into areas in which names are known (and must be unique). There may be LaserWriters named Gutenberg in each zone, but not more than one in a given zone.
End nodes can find out what zone they are in and the names of all zones in the internet from a local bridge. When the new Chooser is started on a node which is connected to an internet (at least one bridge on its local net), it asks for its zone name, then displays it. It then asks the bridge for a list of zones in the internet. If there is more than one name in the list, the new Chooser will display a list of zones. From this list, the user can select the zone in which subsequent name searches will be made. If there are no bridges connected to the local net, the new Chooser will hide zone items from the user.
The Chooser has a companion application called the Namer. Its dialog is shown in Figure 2. This program is used to change the names of AppleTalk devices (such as LaserWriters). It operates in a manner similar to the Chooser, except that once a particular device is selected, a dialog appears requesting the new name for that device. The user types in the new name, then the Namer attempts to rename it. The device file discussed in the next section contains resources that are used by both the Chooser and the Namer.
Fig. 2 The Namer Utility
The Device File
Each device which uses the chooser is represented by a device file in the System Folder the current startup volume. The file's Finder type (fdType) serves as a rough classification for the device type, as shown in Table 1: (See top of next page.)
Table 1 - Device File Types
fdType Device Type
PRES Serial printer, such as Imagewriter
PRER Remote printer (any non-serial printer)
SDEV Serial non-printer device (not supported by current Chooser)
RDEV Remote non-printer device
The device file has a BNDL resource and associated ICN# & FREF resources which serve to give the device its icon as seen in the Chooser window (as well as in the Finder, as usual). It also contains resources that are used by the Chooser to manage the device properly. They include those shown in Table 2:
Table 2 - Device File Resources
Type ID Use
STR -4096 If AppleTalk device, its type name as known on the net via NBP.
STR -4095 Singular form of device name as used in alerts and dialogs.
STR -4094 Plural form of device name as used in alerts and dialogs.
STR -4091 The string for the Chooser to put at the top of its list window.
STR# -4093 If AppleTalk PAP device (Printer Acc-
-4092 ess Protocol, e.g., LaserWriter), the data to send in order to rename the device.
GNRL -4096 If AppleTalk device, NBP retry interval and count values for lookup.
PACK -4096 Code used by non-serial devices for handling messages from the Chooser and the Namer (see below).
If the device file contains a PACK -4096 resource, the Chooser and the Namer send messages to the code contained therein to handle the following operations:
(fillList) Fill in the list to be selected from
(select) An item in the list is selected
(deselect) An item in the list is de-selected
(getSel) Mark item(s) in the list as currently selected
(reName) The user has provided a new name
(terminate) Cleanup prior to Chooser or Namer exit
The format of the PACK resource is shown in Figure 3. It starts with a branch around the resource header. The device ID is an integer chosen to identify the particular device. Apple Developer Support is responsible for assigning these IDs. The version word identifies the particular version of the device code in the PACK. The code begins at an offset of 10(hex) from the physical start of the resource. Note that even though it is called a PACK, the Package Manager is never used to access the code.
The flags longword in the PACK header is used to control the operation of the Chooser and Namer with the device. These flags are defined in Table 3.
Table 3 - Flags Longword Bits
31 Set if device is AppleTalk device
30 Set if device uses PAP (Printer Access Protocol)
29 Set if device uses PostScript
28 Set if device can have multiple instances selected simultaneously
24-27 Set to 0!
23 Translate international characters to U.S equivalent in name
22 LaserWriter kludge flag (don't even ask ...)
21 Prefix new name with length byte on rename
16-20 Set to 0!
15 Set if device accepts fillList message
14 Set if device accepts getSel message
13 Set if device accepts select message
12 Set if device accepts deselect message
11 Set if device accepts terminate message
10 Set if device accepts reName message
0-9 Set to 0!
The Chooser and Namer call the PACK with the usual toolbox Pascal argument convention, and with the arguments shown below in C. If your C compiler does not support the Pascal function type, you'll need to write a glue routine to provide the toolbox call frame:
short pascal device( message, caller, objName, zoneName, p1, p2 );
short int message; /* Opcode*/
short int caller;/* Chooser/Namer or ? */
char *objName; /* Variable meaning */
char *zoneName; /* Zone name for msg*/
long p1, p2;/* Variable meaning */
The caller is 1 if being called by the Chooser, 2 if being called by the Namer. The routines should return noErr (0) if successful, else some kind of error. Now for the details of each of the calls that can be made to the PACK, and their values:
Caller needs a List Manager list filled in with the choices for this device.
zoneName the AppleTalk zone
p1handle to list to be filled in
Mark the choice(s) that is/are currently selected in the list.
zoneName the AppleTalk zone
p1handle to list
A choice has become selected in the Chooser.
objNameif device accepts fillList or is serial device, not used; if
not, name of object just selected
zoneName AppleTalk zone in which choice was made
p1handle to list
p2if device accepts fillList or is serial device, row number in list
which was selected; if not, contains internet address (AddrBlock)
of AppleTalk device which was selected.
A choice has become deselected in the Chooser.
objName if device accepts fillList or is serial device, not used; if
not, name of object just deselected
zoneNameAppleTalk zone in which choice was made
p1 handle to list
p2 if device accepts fillList or is serial device, row number in list
which was deselected; if not, contains internet address (AddrBlock)
of AppleTalk device which was deselected.
user has provided a new name in the Namer
objName if device accepts fillList, new name of device to be renamed;
if not, current name.
zoneNameAppleTalk zone in which choice was made
p1 if device accepts fillList, list handle; if not, pointer to new name
p2 if device accepts fillList, row of list to be renamed; if not, internet
address (AddrBlock) of device to be renamed.
a different device icon has been chosen or the Chooser window is being closed and the PACK should clean up if required.
objName not used
zoneNamethe AppleTalk zone (* = thisZone)
p1 handle to list
p2 not used
The Chooser has internal routines to handle the port selection for serial devices and the NBP lookup for vanilla AppleTalk devices such as the LaserWriter. For serial devices, the icons for the modem and printer ports are put into the list and displayed. For AppleTalk devices, the STR -4096 string is used (along with the currently selected zone name) to do an NBP lookup for "=:name @zone". The replies contain the names of the various devices of that type, and those names are inserted into the list. If the device accepts the fillList message, the Chooser calls the PACK to fill the list.
The Chooser calls the PACK with the getSel message to set the currently selected item in the list, passing the handle to the list. The PACK should, in turn, call the List manager (LSetSelect) to select the appropriate cell. The chooser will make this call whenever there is a change in the list. For example, the Chooser makes this call whenever a new name is added to the list during NBP lookup.
AppleTalk devices are grayed out if AppleTalk is disconnected. A warning is displayed if you try to change printers in any application except the Finder.
All printer icons except the currently selected one are grayed out unless the current application is the Finder. This default behavior is controlled by an application through flag bits in the low-memory byte location chooserBits ($946). The bit assignments are:
7Don't change printer type
6Don't change AppleTalk state
5-0 Reserved (all 1's)
WARNING -- the above should be touched only by system software such as server clients.
When the user chooses a different device by clicking on a different icon, the Chooser calls the old device with the terminate message (if accepted), then it does an UpdateResFile on the device file followed by a FlushVol on the boot volume. Finally, it opens the new device's file.
The Namer uses some of the device file resources when it changes the NBP name of a remote device. Currently, only PAP-speaking devices (the LaserWriter) support renaming. Future devices such as a file server will also support renaming (via their application protocols rather than PAP).
To rename a PAP device, the Namer first opens a PAP connection to the target remote printer. Then it sends the strings in the STR# -4093 to the printer until it reaches the last string in the list. It then takes the last STR# -4093 string, the new name string, and the first string from the STR# -4092 resource and concatenates them to form a new string. It sends this string to the printer, followed by the rest of the strings in the STR# -4092 resource. If the printer is a PostScript device, it waits for the EOF message from the printer. Finally, it takes down the PAP connection.
An Example: The LaserWriter Device
Now let's look at the LaserWriter device and see how it is handled by the Chooser. First, it is an AppleTalk device which does not accept the fillList message. Therefore, the Chooser will handle the NBP lookup and list fill process.
In order for the Chooser to recognize the device, the Finder type fdType on the LaserWriter file is set to 'PRER', for a remote printer. A quick look with Fedit or ResEdit confirms this. The type and creator are 'PRER' and 'LWRT', respectively.
Inside the LaserWriter file are the various resources needed for Chooser use. The GNRL -4096 resource contains the NBP lookup retry interval and count, 11 and 5, respectively. The interval is in units of 8 ticks, for a total of 88 ticks, or about 1.5 seconds. So it makes 5 tries at an interval of 1.5 seconds, for a total of 7.5 seconds or so. Keep in mind that the LaserWriter is blind for six seconds during printing.
The BNDL 128 resource references ICN#s and FREFs for 4 types of files owned by the creator type LWRT, shown below. The PRER icon is the one that shows in the Chooser.
STR -4096 contains the NBP type name, LaserWriter. STR -4095 and STR -4094 have the singular and plural names for alerts, LaserWriter and LaserWriters. The STR -4091 resource contains Select a LaserWriter:, the title shown above the Chooser selection box. Your strings should end in a colon.
The STR# -4093 and -4092 resources contain the PostScript needed to rename the printer as follows:
serverdict begin 0 exitserver(clear dict)
serverdict begin (new name) setprintername end
where the first line and the second line up through the ( are in the STR# -4093, and the last part of the second line, from the ) on, is in the STR# -4092.
There is a PACK -4096 resource for LaserWriter. The device ID is 3 and the version word (for the current release) is 2. The flags longword is $E0C07000, indicating that LaserWriter is an AppleTalk device that speaks PAP and PostScript, that international characters are to be translated in its name, that the name must be tested for a bug in the LaserWriter code (the kludge alluded-to earlier) and that it accepts only the getSel, select and deselect messages.
When the LaserWriter PACK receives the getSel message, it selects the printer whose name it recorded in the PAPA resource the last time around. When it gets the select message, it changes the selected printer in the PAPA resource to the new name. Finally, it ignores the deselect message, since the new select message overwrites the old PAPA string.
Some devices, such as a file server client driver, would support selection of several items at a time; this might be a set of remote volumes (possibly on different servers) to mount. For each selection, the PACK would be called with a select message. The PACK would mount the volume, and might record the selection in a resource (such as a STR#).
Remember that the Chooser does an UpdateResFile on the device file before deactivating that device (or deactivating the Chooser). The next time the system is booted, the device could load the STR# resource and automatically mount the volumes that were mounted when it was last shut down.
The Name Field
The Chooser has an edit text item labeled user name. The user is supposed to fill his name into this field. Currently, only the LaserWriter device uses this field. It uses it to inform the printer of the user name of the person who owns the current PAP connection to that printer. Other users then get a busy message with that user's name. The user name string is located in the System file as STR -16096, indicating that it is owned by the AppleTalk .MPP driver (ID=9). The chooser changes this resource whenever you change the text in its user name field.
I have taken the position that I will not publish benchmarks and reviews of the various C language systems available for the Macintosh. In the past, we have published articles using the Consulair Mac C system, the Megamax system and the Aztec (Manx) C system. It has been a while since there has been a new introduction in the C arena. We developers tend to get into a rut, so I feel this newcomer deserves a few paragraphs.
I recently received an evaluation copy of the LightSpeed C system (V1.02) from Think Technologies. There is a lot of folklore circulating about these days regarding LightSpeed C. Here are my subjective impressions.
The compiler and linker are surprisingly fast, reducing development turnaround time significantly. The generated code is reasonably good, comparable to the other systems I have used. I shouldn't even have to say it, but the linker does selectively load from libraries. Desk accessory and driver support is built-in, as is pascal calling convention. You can also make a code resource with arbitrary type such as PACK or INIT or whatever.
The built-in editor has a multi-file grep search and replace that I particularly appreciate. My company marketed an editor for the PDP-11 for years that had this feature, and our customers loved it. It (mostly) eliminates the need for editor macros. Also, the linker can put symbolic info into the application for use by Macsbug or TMON. The combination of LightSpeed C & TMON with the extended user area is about as powerful a development environment as you'll find on a micro.
On the minus side, Lightspeed has no assembler support (Think says it's coming). Their Pascal call and driver support does eliminate a lot of need for an assembler. You can use the MDS assembler then run the REL file through a LightSpeed utility to make it a library. It will not convert resource REL files, though, so you can't use their linker to make FKEYs or INITs from assembler.
Everything built by LightSpeed C has a 400+ byte preamble attached to the front. It consists of a collection of small routines that handle switch statement dispatches, longword multiplies and divides, and that sort of thing. They should have been library modules. It makes it impractical to write FKEYs, INITs or small drivers in C, my favorite pastime with Consulair.
One feature I particularly dislike is the choice of 16-bit INT's. While this follows the Lisa Pascal convention, it violates the C convention of choosing INT to be the natural word size of the machine. Last time I looked, the 68000 family was a 32-bit machine, capable of adding 32-bit numbers in a single leap. Think's reasoning was that the bus is only 16-bits wide, therefore 16-bit INTs are faster. A hardware quirk. Wait till 2 years from now. In any case, it makes it a pain to convert programs over to LightSpeed from other C languages.
If you plan to use the List Manager with LightSpeed, be aware that the List Manager is not supported in the MacTraps glue library. There is an undocumented hook that makes it possible to define calls as traps in a general way. It goes like this:
pascal void RomCall() = 0xA9ZZ;
where the void can be replaced with a function return type. The resulting defined function can take parameters like any other. It's highly non-portable, but so is Macintosh code.
It's nice to be back writing for Mac Tutor. I have been incredibly busy for the past 5 months, managing a growing business and working with Apple Computer to put AppleTalk on VAX/VMS. That project is mostly completed now, so the fun part is starting doing the network applications.
AppleTalk, and the Mac as a whole, is going to undergo an explosive expansion during the next year or so. There are a host of new computer systems techniques that may show up in the Macintosh architecture, such as hardware memory management, system-driven task scheduling, multi-tasking and supercharging for QuickDraw. If you want some hints, re-read that innocuous developer's questionnaire that appeared in one of the Software Supplements in the Fall of 1985. Remember that? It asked questions like Do you directly access the low memory globals?
Next month's C Workshop will cover AppleTalk inter-networking in more detail, including bridge operation, the new Zone Information Protocol, and will include a real C program. Until then.
As far as we know, this is the first published documentation on the Chooser Technology. Congratulations to Bob for his fine article, winner of our program of the month and an extra $50 from MacTutor!