Macintosh Q & A

Q Can I assume that the value of the ColorSync CMWorldRef parameter returned by the NCWNewColorWorld routine isn't NULL if the routine was successful? I'd like to determine whether a color world exists before trying to use it.

A Yes, you can assume that if no error is returned, the CMWorldRef parameter will be valid.

Q Can ColorSync 2.0 profiles be embedded in EPS images?

A Yes, you can embed ColorSync profiles into EPS, as well as into PICT and TIFF formats. For more information on how to do this, see the Macintosh Technical Q&A "Embedding ICC Profiles" (CS 06). There are also details on how to embed profiles in PICTs, along with sample code, in Advanced Color Imaging on the Mac OS, page 4-34.

Q How can I determine whether SCSI Manager 4.3 has been loaded by an extension at startup time?

A Drivers or applications that intend to call the asynchronous SCSI Manager must check that it's present by checking for the presence of the _SCSIAtomic trap (0xA089).

While this is sufficient by itself for applications, driver writers must keep in mind that if the asynchronous SCSI Manager is loaded as a system extension, the driver may be running before the _SCSIAtomic trap is installed (this is true for the startup device driver), so simply checking for the existence of the trap when your driver starts up isn't sufficient. The extension loading process needs to be completed before you make the check.

One way to do this is to use the accRun mechanism. If you set the dNeedTime flag in your driver, it will get an accRun call at SystemTask time. You can test for _SCSIAtomic then, set a flag indicating that you've discovered it, and then optionally reset the dNeedTime flag so that your driver doesn't get called after you've completed your discovery process. (Note that this technique is only suitable for old-style drivers, type 'DRVR'. New PCI-compatible drivers, type 'ndrv', can't use the accRun mechanism.)

This method isn't foolproof, however. It's possible for your driver to get an accRun call before all the extensions are loaded, such as when a dialog is presented from an extension that calls, for instance, ModalDialog (which will eventually dispatch SystemTask). This results in the driver receiving an accRun call even though there may be more extensions to follow.

So, in addition to simple determination of the presence of _SCSIAtomic, you need a way to test that the Finder (or some other application process) has been launched. You can do this by checking the length of CurApName. CurApName has a -1 length at startup and becomes positive when a process (such as the Finder) gets launched.

An alternative is to queue up a Notification Manager task without specifying an icon or sound, but only a response procedure. The procedure will get called after the extensions finish loading. You can then check for the _SCSIAtomic trap.

Q I'm writing a QuickDraw GX printer driver that supports SCSI and PrinterShare (server) connection types. I can connect multiple printers to one Macintosh on the SCSI bus, and I've seen that I can have active print jobs printing on all of them simultaneously. My question is: Do I have to be concerned about reentrancy when coding my message overrides?

A There are a few issues you'll need to keep in mind. One is that each copy of your driver must store any data it needs in its own data space. You can do this by using the GetMessageHandlerInstanceContext and SetMessageHandlerInstanceContext functions. If there is common global data that all copies of your driver will need to access, you can use the functions SetMessageHandlerClassContext and GetMessageHandlerClassContext. These are documented in Chapter 6 of Inside Macintosh: QuickDraw GX Environment and Utilities.

For each instance of your driver, you'll also need to watch out for insufficient memory. You shouldn't need to add much code if you're already checking for error conditions when attempting to allocate memory within your driver, but if there are places where you're not checking to make sure that the allocation was actually successful, you'll need to add code (it's a good idea to always check anyway).

You'll also need to confirm that you don't have multiple instances of your driver trying to write to the same printer at the same time. There are any number of ways you can confirm this, including using a shared (ClassContext) data block with a semaphore to mark whether an instance of your driver was in the middle of a GXWriteDTPData call. Each instance could then first check that semaphore before attempting to read or write data from the desktop printer. Be sure to include file locking while your driver is reading or writing other files.

Finally, if you're writing a PostScript driver, be aware that the PostScript font downloading code is not reentrant.

In general, you should use these techniques to write any QuickDraw GX printer driver, whether or not you expect it to need reentrancy.

Q I want to program with Open Transport. What libraries should I link with?

A Here are descriptions of the libraries that come with Open Transport, and why you might need to link with them.

Let's look first at linking Open Transport with PowerPC code. The basic libraries to link with are OpenTransportLib and OpenTransportAppPPC.o. If you need AppleTalk services, also link with OpenTptAppleTalkLib and OpenTptATalkPPC.o. If you need Internet services, also link with OpenTptInternetLib and OpenTptInetPPC.o.

The OpenTransportUtilLib and OpenTptUtilsAppPPC.o libraries may provide a smaller footprint if your application deals only with ports. Once you've got it working, try replacing OpenTransportLib and OpenTransportAppPPC.o with these and see if your application still links.

The OpenTransportExtnPPC.o and OpenTptUtilsExtnPPC.o libraries replace OpenTransportAppPPC.o and OpenTptUtilsAppPPC.o if you're writing a standalone code resource, CFM fragment, or ASLM shared library.

Note that if your code is meant to run on machines with and without Open Transport (that is, you revert to Classic AppleTalk or MacTCP if Open Transport isn't available), you should make sure to weak-link with the libraries ending in "Lib." Otherwise the system will refuse to launch your application when Open Transport isn't installed.

Now let's take a look at linking Open Transport with 680x0 code. The basic libraries to link with are OpenTransport.o and OpenTransportApp.o. If you need AppleTalk services, also link with OpenTptATalk.o. If you need Internet services, also link with OpenTptInet.o.

The OpenTptUtils.o library may provide a smaller footprint if your application deals only with ports. Once you've got it working, try replacing OpenTransport.o with this and see if it still links.

The OpenTransportExtn.o library replaces the OpenTransportApp.o if you're writing a standalone code resource or ASLM shared library.

In addition, the following libraries are identical to their similarly named counterparts except that they're suitable for linking with MPW model-near clients: OpenTransport.n.o, OpenTransportApp.n.o, OpenTptATalk.n.o, OpenTptInet.n.o, OpenTptUtils.n.o, and OpenTransportExtn.n.o.

Q How do I use Open Transport with CFM-68K?

A The short answer is that you don't, at the moment.

To get a better answer to this you must first specify what you want to do: use CFM-68K to build Open Transport modules (plug-ins like device drivers and protocols), or call the Open Transport API from a CFM-68K application or library (an OpenDoc part, for example).

Building Open Transport modules with CFM-68K is not currently supported nor is it likely to be supported. The Apple Shared Library Manager is your only alternative for building 680x0 modules.

Support for calling Open Transport from a CFM-68K application or library is likely to be incorporated in the next major release of Open Transport. This is in line with Apple's shared library strategy, as outlined in the DLL Statement of Direction document (ftp://seeding.apple.com//ess/public/aslm/DLL_directions), which indicates a move away from ASLM in general.

Q I wanted an extension to load last in the initialization or startup sequence, so I put the backquote character (`) as the first character in its name. But when I did this, it actually loaded near the beginning. What happened?

A If you view the contents of any folder by name, you'll see that items whose names begin with a backquote appear last (or nearly last) in the list. To sort the list, the Finder calls PACK 6, which uses the international sorting routines; these sorting routines order words beginning with a backquote near the end of the list.

During extension loading, however, PBHGetFInfo is called, and it in turn calls RelString. RelString is called with case insensitivity and diacritical sensitivity turned on. Unfortunately, due to a bug that HFS relies on, backquote sorts between a and b. This means that extensions beginning with a backquote load after extensions beginning with a (or A) and before those beginning with b (or B).

There are no plans to fix this problem, because of the need to maintain compatibility with old HFS volumes (which were created before this bug was discovered and which use this sorting order).

Interestingly, UpperString converts a backquote to an a, but leaves all other nonletters unchanged.

If you want to make sure that your extension is loaded last in the initialization process, use the tilde (~) as the first character of its name.

Q When I'm printing and I call PrClosePage at the end of a page, I get a paramErr (-50) error. What does that mean?

A There are two ways to get this error. The most common is to pass a bad graphics port to PrClosePage. If you don't pass back the port you got from PrOpenPage, you will (rightfully) get an error.

The second way to get paramErr from PrClosePage is more esoteric. If you've hidden the menu bar before printing, and you leave it hidden, some drivers will report a paramErr error when PrClosePage is called. What's happening is that somewhere deep in the Printing Manager, one of the Printing Manager routines is calling a QuickDraw function with the menu bar's rectangle as the parameter. This QuickDraw function sees the empty rectangle (because you've hidden the menu bar) and sets QDError to paramErr. The driver checks QDError when it's done printing, sees the error, and sets PrError to the error. Note that this happens only on 680x0 machines, not on PowerPC machines, which is ironic since 680x0 QuickDraw does much less error checking, and seldom sets QDError.

Q Are there any tools to help me debug my QuickDraw 3D project?

A During your development process, you should use the debugging version of QuickDraw 3D. To install it, just place the three extension files in the Extensions folder (in the System Folder) and restart your computer. The debugging version has a larger footprint and lower performance, but it has more extensive error checking. Using the debugging version will help you find problems with your code; it posts notices in addition to the errors and warnings posted by the optimized version. You'll also want to check out the 3Debug application; it graphically displays QuickDraw 3D memory usage, which can be very helpful. 3Debug and the debugging version of QuickDraw 3D are provided with the QuickDraw 3D release.

Q I have a sample program compiled in MPW with Symantec's SC compiler. When I try to link the sample program, I get the following linker error:

### Link: Error: Undefined entry, name: (Error 28) "qd"
Referenced from: main in file: :Obj 68K:FIFDECO.c.o

qd is the QuickDraw global variable. If I declare the global, as in QDGlobals qd; the error goes away. This is confusing, because the global is supposed to be declared for PowerPC code, but should automatically be declared for 680x0 files. In fact, this same code compiles and links correctly with Symantec C++ v7.0 IDE, as well as Metrowerks CodeWarrior. Is there some new library I need to include to get the 680x0 global declared? Or has some subtle change been made to the header files?

A Recently there has in fact been a change: The MPW libraries for the classic Macintosh runtime architecture now require that the QuickDraw global qd be defined in the global space of your code, the same as in the MPW libraries for the other Macintosh runtime architectures (namely, the PowerPC and CFM-68K runtime architectures). If you're working in the MPW environment, a simple definition such as the following is all that will be necessary:

QDGlobals qd;

If you're working in multiple environments (say, MPW, Metrowerks, and Symantec) use a preprocessor conditional such as this:

#if GENERATINGCFM
	QDGlobals qd;	// Required for all CFM environments
#else
#if !defined(SYMANTEC_C) && !defined(SYMANTEC_CPLUS)
	#define __MPW_ONLY__
#endif
#if defined(__SC__) && defined(__MPW_ONLY__) 
	QDGlobals qd;	// Required for SC in MPW compilations
#endif
	#undef __MPW_ONLY__
#endif

For more details on the use of QDGlobals and qd, see Technote 1016, "Where Has my qd gone? And How Do I Use qd and QDGlobals Correctly?"

Q I'm confused about the implementation of the AutoStart feature that was announced with the QuickTime 2.1 release. Can you tell me how to create a CD with this feature that will work cross-platform?

A The AutoStart feature first documented in the release notes for QuickTime 2.1 has been available since the release of QuickTime 2.0. This means that any CD title you release today with an AutoStart application or document will work with most users' current installation of software, since QuickTime 2.0 has been available for well over a year. (Of course, there are other benefits to using QuickTime 2.1 over 2.0, but that's beside the point.)

The AutoStart feature is available only on HFS volumes, because it relies on information located in block 0 of an HFS disk or partition. The first two bytes in the sector of block 0 should be 0 or LK, although this realistically should be limited to 0 since LK designates an HFS boot volume. The name of the AutoStart file is stored in the area allocated for the Clipboard name. This area begins 106 bytes into the sector of block 0, with the first four bytes at that offset containing the hex value 0x006A7068. This value indicates that an AutoStart filename follows. After this 4-byte tag, 12 bytes remain, starting at offset 110. In these 12 bytes, the name of the AutoStart file is stored as a Pascal string, giving you up to 11 characters to identify the file. The file must reside in the root directory of the HFS volume or partition.

You may designate either an application or a document as the AutoStart file. If you choose an application, it may be visible or invisible in the root directory of the volume. However, document files must be visible. Additionally, you may select an alias file as the AutoStart file, but it too must be visible in the root directory of the volume or partition. If the AutoStart file is a document or an alias to a document, QuickTime will ask the Finder to launch the document as if it had been double-clicked from the Finder. If the creating application isn't available, the Finder will issue its normal warnings or use Macintosh Easy Open if available.

The real goal of the AutoStart feature in QuickTime is for users to be immediately engaged, upon insertion of a CD-ROM product, in an experience of the developer's choice, whether it's jumping right into a multimedia program or reading an important "ReadMe" document. Because there's no way for the user to bypass the launch of the AutoStart file (except for disabling QuickTime at startup), you, the developer, must determine what user experience you want to capture and decide whether or not the AutoStart feature makes sense for your project.

Creation of the AutoStart block 0 information is dependent on the CD-ROM mastering software that you use. Most of today's CD-ROM mastering software is capable of writing the AutoStart information. To be certain, however, it's best if you check with the developer of your CD-ROM mastering software if you aren't sure of its capabilities.

Note that the AutoStart feature wasn't implemented in QuickTime for Windows. This is primarily because new CD-ROM drivers are needed; the current drivers don't know when a new CD is inserted. When producing a cross-platform CD title, you'll need to create a hybrid disk that has an HFS partition if you want to use the AutoStart feature. You can create an HFS/ISO 9660 hybrid disk with your Macintosh project on the HFS partition and your cross-platform files on the ISO 9660 partition for use by both the Macintosh and PC main programs. Of course this means that you wouldn't have any AutoStart features on the PC platform unless you implemented a PC solution (like the Windows 95 auto-play feature) on the ISO 9660 partition.

Q The kATAOfflineEvent and kATARemovedEvent documentation in the various Developer Notes for IDE-compatible Macintosh computers seems incomplete. Is it?

A Yes, it is. Updated ATA Manager documentation is in progress. In the meantime, the documentation is supplemented here.

• kATAOnlineEvent (code 1) -- This event notifies clients when an ATA or ATAPI device becomes available for use. The event occurs either when a new device is connected to the bus or when a previously unavailable device becomes available again (as in system wakeup when power is restored to the device).

  If the device has a registered driver, only that driver will be notified of the event; otherwise, each registered default driver will be notified until a driver responds favorably (that is, with a noErr response to the event). Note that for newly connected devices a driver loaded from the device is given priority.

  Drivers should keep track of whether the device coming online is a newly connected device or one that's currently offline (that is, connected but not unavailable). A device should be considered connected until a kATARemovedEvent event for the device occurs.

• kATAOfflineEvent (code 2) -- This event notifies the registered driver of an ATA or ATAPI device that the device is now unavailable for use (offline). The device, however, is still connected to the bus and the offline state is assumed to be temporary. This event will occur at system sleep when power is removed.

  Currently, this event is generated only when the ATA Manager receives a PM_SUSPEND event (essentially the same as a Power Manager sleep demand event) from the PC Card Manager. Drivers receiving kATAOfflineEvent events most likely will want to maintain control of the device but deny access to the device from its clients. In addition, the driver should note that the device may need to be reconfigured when it comes online again (a kATAOnlineEvent event will be generated when this happens).

• kATARemovedEvent (code 3) -- This event notifies the registered driver of an ATA or ATAPI device that the device has been removed. The removal may be either controlled (for example, a software eject command to the ATA Manager) or uncontrolled (or example, a forced removal by the user). Note that the device may have been in either an online or an offline state before the removal. If the state was online before the removal, a kATAOfflineEvent event is not generated, since the removal implies that an offline condition had to occur.

• kATAResetEvent (code 4) -- This event notifies the registered driver of an ATA or ATAPI device that the device has been reset. The device may need to be reconfigured by the driver before it can be used again. This event was created for use with multiple devices per bus (ATA Master/Slave mode), since reset applies to all devices on the bus and not to a specific device. Apple currently doesn't implement multiple devices per bus with ATA, so this event isn't implemented. It's advised, however, that drivers support this event now to prevent problems later on when the event is implemented.

• kATAOfflineRequest (code 5) -- This event is obsolete. It was defined for the early stages of the PC Card Manager which would echo the Power Manager sleep events to its clients. The ATA Manager would in turn echo the request to its clients. This event was like the sleep request event. The current PC Card Manager allows only for an event akin to a sleep demand event, which does not permit rejection by the client.

• kATAEjectRequest (code 6) -- This event notifies the registered driver of an ATA or ATAPI device that a request has been made to eject the device. If the response to the request is 0, the device will be ejected and a subsequent kATARemovedEvent event will be generated when the ejection is successful. The kATAEjectRequest event serves as a protection mechanism to alert drivers of a pending ejection. Drivers will most likely want to reject the request unless they initiated the request, since ejection will remove the device from the bus.

Note also that the kATAResetEvent, kATAOfflineRequest, and kATAEjectRequest events are not currently implemented in the ATA Manager.

Q How do I convert Macintosh Simplified Chinese encoding to the relevant GB standard?

A The Macintosh encoding for Simplified Chinese is a shifted GB2312. To convert from GB2312 to Macintosh encoding, just add 0x8080 to each character. To convert from the Macintosh encoding to GB2312, subtract 0x8080 from each character. For example, an ideographic comma (Unicode code point 0x3001) is 0x2122 in GB, and 0xA1A2 on the Macintosh.

The only subranges of characters you need to worry about are the Roman characters. Below is some code that illustrates how to do the conversion.

// Returns true if the character needed conversion, or false if it
// was a one-byte character (meaning that only the first byte was
// processed).  (That is, a false return means the character was a
// Roman character.)
boolean MacToGB2312(unsigned char first, unsigned char second,
								unsigned short *output)
{
	if (first < 0x81) {
		*output = first;
		return false;
	} else {
		unsigned short temp;
		temp = (first - 0x80) << 8;
		temp += (second - 0x80);
		*output = temp;
		return true;
	}
}

// This will always convert, so we don't need to get the bytes
// separately nor do we need to return a Boolean saying whether
// we converted.
void GB2312ToMac(unsigned short input, unsigned short *output)
{
	*output = input + 0x8080;
}

As you can see from the code, you need to modify both bytes of a two-byte character. This is done so that it's obvious whether a character is part of a two-byte character or is a one-byte Roman character.

For more information, see Understanding Japanese Information Processing by Ken Lunde. See also Ken Lunde's Web page at http://jasper.ora.com/lunde/; while it contains mostly information about Japanese text processing and standards, there are pointers to more information about Chinese and Korean information processing as well.

Q I know that homonyms are words that are pronounced alike (and are often spelled the same) but have different meanings, and I know that synonyms are words that have the same or nearly the same meanings. But there are also words that are spelled alike but are pronounced differently and have different meanings. For instance, "row" (rhymes with "go") meaning things arranged in a line, and "row" (rhymes with "cow") meaning a fight. What do you call words like these?

A Heteronyms.

These answers are supplied by the technical gurus in Apple's Developer Support Center. For more answers, see the Macintosh Technical Q&As on this issue's CD or on the World Wide Web at http://dev.info.apple.com/techqa/Main.html. (Older Q&As can be found in the Macintosh Q&A Technical Notes on the CD.)*