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 myqd
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.

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.)*