Volume Number: 13 (1997)
Issue Number: 8
Column Tag: develop

Macintosh Q & A

by Apple Developer Support Center

Q: I'm debugging my PCI native driver and notice that the dCtlFlags field of my Device Control Entry (DCE) has some undocumented bits set. What do these flags mean?

A: The current bits in the dCtlFlags field of the DCE are:

• bit 0 - VMImmune - This bit indicates that your device driver is VM safe. See Technote NW 13 http://devworld.apple.com/dev/technotes/nw/nw_13.html for details.
• bit 1 - reserved.
• bit 2 - kmDriverGestaltEnableMask (in "DriverGestalt.h") is set if the driver supports the Driver Gestalt mechanism. See Designing PCI Cards and Drivers for Power Macintosh Computers for a description of Driver Gestalt.
• bit 3 - Native Driver - Set if the driver is a native driver (ndrv). The system will set this bit when it loads your native driver.
• bit 4 - Concurrent - Set if the native driver supports concurrent operation. When loading a native driver, the system sets this bit based on the kDriverIsConcurrent field of the driverOSRuntimeInfo.driverRuntime field of your DriverDescription. See Designing PCI Cards and Drivers for Power Macintosh Computers for a description of concurrent drivers.
• bit 5 - dOpenedMask (in "Devices.h") is set if the driver is open.
• bit 6 - dRAMBasedMask (in "Devices.h") is set if the dCtlDriver field is a DRVRHeaderHandle rather than aDRVRHeaderPtr.
• bit 7 - drvrActiveMask (in "Devices.h") is set if the driver is currently processing a request.
• bit 8 - dReadEnableMask (in "Devices.h") is set if the driver handles _Read requests.
• bit 9 - dWritEnableMask (in "Devices.h") is set if the driver handles _Write requests.
• bit 10 - dCtlEnableMask (in "Devices.h") is set if the driver handles _Control requests.
• bit 11 - dStatEnableMask (in "Devices.h") is set if the driver handles _Status requests.
• bit 12 - dNeedGoodByeMask (in "Devices.h") is set if the driver needs a "goodbye" _Control call before the application heap is reinitialized.
• bit 13 - dNeedTimeMask (in "Devices.h") is set if the driver wants periodic SystemTask time through the "accRun" _Control call.
• bit 14 - dNeedLockMask (in "Devices.h") is set if the driver requires that its DCE and code be locked at all times when the driver is open.
• bit 15 - reserved.

See Inside Macintosh: Devices for more information about bits 5 through to 14.

Q: I'm calling the serial driver to clear XON/XOFF flow control but flow control is not being lifted. What's going on?

A: You have stumbled across a bug in Apple system software (ID 1635221). The File System Manager patches _Control in such a way that the serdClrXOff (csCode = 22) is mistaken for a block device "Return Media Icon" (csCode = 22) call. This causes the serdClrXOff to never make it to the serial driver.

The simplest workaround is to clear ioVRefNum before making the serdClrXOff call. The following code snippet demonstrates this technique:

OSErr DoClearXOff(short serialOutDrvrRefNum)
{
CntrlParam pb;

pb.ioCRefNum = serialOutDrvrRefNum;
pb.csCode = serdClrXOff;
pb.ioVRefNum = 0;
// This above line is required because of a bug
// in system software. The workaround, clearing
// ioVRefNum, should be benign when the bug is fixed
// in future systems.

return ( PBControlSync( (ParmBlkPtr) &pb ) );
}

Q: Sometimes, MacsBug generates a PowerPC unmapped memory exception with an address that starts with the symbol BowelsOfTheMemoryMgr. What does this mean?

A: When you are displaying addresses in Macsbug, MacsBug shows offsets from the last symbol it can find. In the Modern Memory Manager on Power Macintosh computers up to MacOS version 7.6, the last symbol was __HSetStateQ. The code after __HSetStateQ consists of various internal Memory Manager subroutines. So, if there's a hang or crash in an internal Memory Manager subroutine, it shows up in MacsBug as __HSetStateQ+xxxxxxxx.

Various system software engineers were tired of seeing bug reports that said __HSetStateQ was crashing, so beginning with MacOS 7.6, we decided to add a new last symbol to the Memory Manager. As a consequence, bug reports would be somewhat more informative. We thought of naming the new symbol YourHeapIsCorrupt (since that's usually the case when a program crashes the Memory Manager) but decided on BowelsOfTheMemoryMgr instead because that's where you are.

So if you're crashing or hanging at BowelsOfTheMemoryMgr+xxxxxxxx, type HC to see if your heap is corrupted (it probably will be) and then start debugging your code to find out how it got corrupted.

Q: What are the different Gestalt selectors for Macintosh networking?

A: Here is the breakdown:

MacTCP
The Gestalt selector for MacTCP is 'mtcp'.

• MacTCP versions 1.0 through 1.0.3 did not register this selector.
• MacTCP version 1.1 returns a value of 1.
• MacTCP version 1.1.1 returns a value of 2.
• MacTCP version 2.0 returns a value of 3.

A value of 0 is returned if the driver is not opened.

AppleTalk
The Gestalt selectors for AppleTalk are 'atkv' and 'atlk'. The 'atlk' Gestalt selector was introduced in AppleTalk version 54 to provide basic version information. Calling Gestalt with the 'atlk' selector provides the major revision version in the low-order byte of the function result. For example, passing the 'atlk' selector in a Gestalt call or through MacsBuG with a result of 0x0000003C means that AppleTalk version 60 is present. (Please note that the 'atlk' selector is not available when AppleTalk is turned off in the Chooser.)

The 'atkv' Gestalt selector was introduced as an alternative in AppleTalk version 56 to provide more complete version information via the 'vers' resource. For example, passing the 'atkv' selector to AppleTalk version 60 through a Gestalt call or MacsBuG yields the following LONGINT result: 0x3C108000.

Open Transport
The Gestalt selectors for Open Transport are 'otan' and 'otvr'. You can test whether Open Transport and its various parts are available by using the Gestalt function with the 'otan' selector. The bits currently used are defined by constants, defined in OpenTransport.h and shown below.

enum {
gestaltOpenTpt                  = 'otan',
gestaltOpenTptPresent           = 0x00000001,
gestaltOpenTptLoaded            = 0x00000002,
gestaltOpenTptAppleTalkPresent  = 0x00000004,
gestaltOpenTptAppleTalkLoaded   = 0x00000008,
gestaltOpenTptTCPPresent        = 0x00000010,
gestaltOpenTptTCPLoaded         = 0x00000020,
gestaltOpenTptNetwarePresent    = 0x00000040,
gestaltOpenTptNetwareLoaded     = 0x00000080
};

If Gestalt returns no error and responds with a non-zero value, Open Transport is available. To find out whether OT, AppleTalk, TCP, or NetWare are present, you can examine the response parameter bits as shown above. For example, passing the 'otan' selector in a Gestalt call or through MacsBuG with a result of 0x0000001F means that the Open Transport is present and loaded, AppleTalk driver is also present and loaded, and MacTCP is present but NOT loaded.

The 'otvr' selector is used to determine the Open Transport Version in NumVersion format. For example, passing the 'otvr' selector through a Gestalt call or MacsBuG to OT version 1.1.1b9 yields the following LONGINT result: 0x01116009. (Note that OT versions 1.0 through 1.0.8 did not register this selector.) For more information on Apple's Version Numbering Scheme and NumVersion format, please see Technote OV12: Version Territory.

Open Transport/PPP
The Gestalt selectors for Open Transport/PPP are 'otra' and 'otrv'. You can test whether Open Transport/PPP and its various parts are available by using the Gestalt function with the 'otra' selector. The bits currently used are defined by constants, defined in OpenTptPPP.h check OT/PPP SDK and shown below.

enum {
gestaltOpenTptRemoteAccess                = 'otra',
gestaltOpenTptRemoteAccessPresent         = 0x00000000,
gestaltOpenTptRemoteAccessLoaded          = 0x00000001,
gestaltOpenTptRemoteAccessClientOnly      = 0x00000002,
gestaltOpenTptRemoteAccessPServer         = 0x00000003,
gestaltOpenTptRemoteAccessMPServer        = 0x00000004,
gestaltOpenTptPPPPresent                  = 0x00000005,
gestaltOpenTptARAPPresent                 = 0x00000006
};

Note: If you are writting an control strip or startup item that uses OpenTransport/PPP, you should be aware that it takes a few event cycles for the remote access software to complete loading. Your software should check the gestaltOpenTptRemoteAccessPresent bit of the 'otra' gestalt to see if remote access software is present, then periodicaly check the gestaltOpen TptRemoteAccessLoaded to determine if loading is completed.

More information on acessing using the Open Transport/PPP API is available in the Open Transport/PPP Developer Note found at the OpenTransport web site's Reference and Technical Documentation section (found at http://17.126.23.20/dev/opentransport/reference.html).

Open Transport/Modem
The Gestalt selectors for Open Transport/Modem are 'otmo' and 'otmv'. You can test whether Open Transport/Modem and its various parts are available by using the Gestalt function with the 'otmo' selector.

enum {
gestaltOpenTptModem     = 'otmo',
gestaltOpenTptModemPresent   = 0x00000000
};

Q: I'm writing an Open Transport module that conforms to the Transport Provider Interface (TPI). I find that OT passes data to my TPI using M_DATA message blocks, rather than M_PROTO message blocks with PRIM_type being T_DATA_REQ. What's going on?

A: The answer can be found at the bottom of the description of T_DATA_REQ (7tpi) in Appendix A-2 of STREAMS Modules and Drivers (Unix Press, ISBN 0-13-066879-6):

The transport provider must also recognize a message of one or more M_DATA message blocks without the leading M_PROTO message block as a T_DATA_REQ primitive. This message type will be initiated from the write (BA_OS) operating system service routine.

Open Transport deliberately uses this variant behavior as an optimization. By using M_DATA, Open Transport avoids allocating a buffer for the M_PROTO header. As every memory allocation takes time, avoiding this one makes the system faster.

This behavior isn't seen on expedited data because the specification doesn't allow for this optimization on T_EXDATA_REQ.

Q: If my web server is running along happily under Open Transport (1.1 or 1.1.1), and the listener was bound to address 0.0.0.0, what happens when someone uses the control panel and changes the IP number? Right now it appears to just make the listener go deaf. I don't appear to receive connections on the new IP number, and if I use the control panel a second time to switch back to the original IP number, I don't get connections for that IP number either.

Is there some event that gets sent to the listener that I'm not looking for that tells me when this happens?

A: When an port changes its IP number, it is actually closing and re-opening. When Open Transport closes a port, any endpoint that is plumbed to it is also closed, hence you will get no further events on that endpoint.

The first thing you need to do is check for the provider events such as kOTProviderWillClose and kOTProviderIsClosed.

You should also use the OTRegisterAsClient call and register a notifier for client events, such as kOTPortDisabled, kOTPortEnabled, kOTPortOffline, kOTPortOnline, kOTClosePortRequest, kOTYieldPortRequest, kOTNewPortRegistered.

You need to close up your endpoints and rebind them when the interface changes.

Q: I'm trying to call the Control Strip routines SBIsControlStripVisible() and SBShowHideControlStrip() defined in the header file <ControlStrip.h>. When I try to link the PowerPC code, I get a link error on these routines. Which library are they implemented in?

A: There is no PowerPC library for Control Strip calls. As a consequence, you must create a routine descriptor and perform a Mixed Mode call to the 68K library.

The following is an example of how you can call the Control Strip routines from PowerPC code:

/* Defined in current Universal Header */
#ifndef _ControlStripDispatch
enum {
_ControlStripDispatch = 0xAAF2
};
#endif
#if GENERATINGCFM
/* */
/* If we're not generating CFM, then assume the */
/* 68K inlines in the headers apply instead. */
/* */
#include <MixedMode.h>
#include <OSUtils.h>
pascal Boolean SBIsControlStripVisible ( void );
pascal void SBShowHideControlStrip(Boolean showIt);
/* SBIsControlStripVisible is a Pascal routine, */
/* dispatched from the selector in D0, returning */
/* a Boolean result */
pascal Boolean SBIsControlStripVisible ( void )
{
enum
{
uppSBIsControlStripVisibleInfo = kD0DispatchedPascalStackBased
| RESULT_SIZE (SIZE_CODE (sizeof(Boolean)))
| DISPATCHED_STACK_ROUTINE_SELECTOR_SIZE (kFourByteCode)
};
return CallUniversalProc (
GetToolTrapAddress (_ControlStripDispatch),
uppSBIsControlStripVisibleInfo, 0x00);
}
pascal void SBShowHideControlStrip(Boolean showIt)
{
enum
{
uppSBShowHideControlStripInfo =
kD0DispatchedPascalStackBased
| DISPATCHED_STACK_ROUTINE_SELECTOR_SIZE (kFourByteCode)
| DISPATCHED_STACK_ROUTINE_PARAMETER
(1, SIZE_CODE (sizeof (showIt)))
};
CallUniversalProc (
GetToolTrapAddress (_ControlStripDispatch),
uppSBShowHideControlStripInfo, 0x01, showIt);
}
#else  /* not GENERATINGCFM */
#include <ControlStrip.h>
#endif /* GENERATINGCFM */

Q: I'm using the code from page 4-16 of Inside Macintosh: Processes to animate the cursor at VBL time, but it crashed (with the stack crawl indicating SetCursor as the culprit). What's up?

A: When hardware cursor support was added to the system (System 7.5.2 for PCI Power Macs), SetCursor started requiring A5 to refer to a valid QuickDraw globals world. Despite the fact that the code to which you refer accesses no global variables, your app still needs to make sure A5 is set up for SetCursor's benefit.

An explanation of setting up A5 in a VBL task can be found on page 4-13 of Inside Macintosh: Processes.

Q: I am trying to find a way for my application to determine if it is using a PostScript printer or not. For performance reasons, I'd like to send custom PostScript instead of a PICT to the printer if I can. Is there an API to find out if the currently selected printer uses PostScript?

A: There is no guaranteed way of doing this. For Apple's LaserWriters, you can determine this by looking at the wDev field in the print record of the currently selected printer. In order to determine whether the current printer is PostScript, here is a quote that is hidden in one of our older Technotes, Technote QD10 "Picture Comments - The Real Deal":

The high byte of the prStl.wDev field of the print record identifies a printer driver species; a value of $03 tells you that the printer driver belongs to the PostScript LaserWriter driver ancestry...

This Technote may be useful to you if you haven't already read it. You should also look at Inside Macintosh: Imaging With QuickDraw for more generic information on the print record.

However, although the Apple LaserWriter driver has a wDev of 3, third-party printer drivers for PostScript devices do not, so if your application determines whether or not to send PostScript based on wDev alone, your application may incorrectly print with QuickDraw on third-party PostScript devices.

Q: What's the logic behind the create/update preview behavior in the SFPGetFilePreview dialog? If I create previews for QuickTime movies, I sometimes get preview movies and sometimes preview pictures. With QuickTime movies that already have previews, I sometimes get an update button and sometimes I get a dimmed create button. What determines the behavior?

A: The expected behavior is this:

PICT files (or files that QuickTime can import as PICT a la the new graphic import components) don't have durations to them so they can only have a preview PICT in the StandardFilePreview dialog. Movies can have both a poster PICT and a movie preview.

In StandardFilePreview, via the preview components, when a movie or PICT file is selected, the preview component will first see if a preview already exists in the file, stored in the 'pnot' resource. The 'pnot' resource also identifies whether the preview is a PICT, a movie, etc. The preview component then compares a timestamp in the 'pnot' resource to the modification date of the selected file to see if the preview is current or not. If the 'pnot' date is older than the last modified date of the file, StandardFilePreview will show the Update button in its dialog (using the 'pmak' components to create the new preview if the user selects this option).

If no 'pnot' resource is found in the selected file and a 'pmak' component exists that can create a preview for the selected file type (QuickTime 2.5 supplies PICT, MOOV, and QTIF 'pmak' components), then the Create button will be active in the StandardFilePreview dialog.

It should be noted that sound files preview in a little different way. The 'pnot' components create an automatic 10-second (if there's that much sound) preview for supported sound file types without needing a 'pnot' resource in the file.

You can read more about Preview Components in Inside Mac: QuickTime Components.

Q: When I drag from my application into a Finder window, the system crashes. I noticed Finder uses a windowKind value of 20 for its windows, and so doesmy app. When my app avoids windowKind 20, everything's hunky-dory. What gives?

A: Through the Drag Manager, Finder has gotten access to the windows in your app's window list (specifically, by using undocumented calls to obtain the source window of a drag). If your window's windowKind field is 20, Finder assumes the window is one of its own (as opposed to a driver window, whose windowKind would be negative, or a dialog window, whose windowKind would be 2, etc.). Finder grabs the value in the window's refCon field and type-casts it to a pointer to a C++ object in Finder's heap. I think you can see where this is going: when Finder attempts to dereference the pointer, various crashing behaviors result. The upshot of this Finder bug is that your application should not use windowKind values of 20.

Q: I installed a sleep procedure. But the Power Manager will issue a sleepDemand if the user selects Sleep from the Special menu. The AutoSleepControl(false) call will stop sleepRequests but will it also stop SleepDemands?

A: Your Application can (should) not refuse a sleepDemand, as documented in Inside Macintosh: Devices pg 6-11: When your sleep procedure receives a sleep demand, however, your procedure has no way to determine whether it originated as a conditional sleep demand or an unconditional sleep demand. Your device driver or application must prepare for the sleep state and return control promptly to the Power Manager when it receives a sleep demand. As for AutoSleepControl, please refer to Inside Macintosh: Devices pg 6-44: When enableSleep is set to false, the computer will not go into the sleep mode unless it is forced to either by some user action - for example, by the user's selecting Sleep from the Special menu of the Finder - or in a low battery situation.

Q: We are writing an application that requires us to connect to a remote machine via TCP/IP and talk to a background application running on that machine. However, we cannot connect to that machine when it is in sleep mode. Is there a way to keep the network services alive when a machine is in sleep mode? I've seen how you can keep the serial port alive, but not the network services.

A: When a Macintosh (usually a PowerBook) goes into the "sleep" state, it is incapable of responding to network requests - the connections actually shut down. There are some Macintosh computers, however, that will attempt to go into an energy-efficient mode know as "doze".

The sleep state is easy to prevent and is pretty well documented in the Power Manager chapter of Inside Mac: Devices under "The Sleep Queue" and "Sleep Procedures", and there is more information in TN 1046: Inside Macintosh: Devices - Power Manager Addenda.

If you wanted to prevent the system from sleeping or dozing, you would:

1. Allocate a SleepQRec (preferably in the system heap).
2. Set it up to call into your sleepHandler.
3. When the Mac attempts to sleep or doze, it will call your sleepHandler with a sleepRequest or dozeRequest selector.
4. To prevent sleep from occurring, you simply return a nonzero value.

In the doze state, OpenTransport networking is still enabled and TCP connections that are set up should still function. But it might take several packets received within a short period (try 10 per second) to wake the machine from its doze state. You might also consider pinging the machine first to get it out of doze.

Either way, you should be aware that it will take some time for the networking to reactivate, especially if virtual memory is enabled and the disk drive must spin up.

There is more information on controlling the Energy Manager in TN 1086: Power Management & The Energy Saver API.

Q: I can't find documentation for the SetMovieDefaultDataRef function. What does it do, and how do I use it?

A: SetMovieDefaultDataRef is defined in Movies.h as: pascal OSErr SetMovieDefaultDataRef(Movie theMovie, Handle dataRef, OSType dataRefType);

It allows you to control where data will be written to when added to a movie. For example, if a movie was loaded from a file, the default data reference is initialized to be the file from which the movie was loaded. This example will set the default data reference to be a handle in memory:

OSErr ConvertGeneralMIDIToSoundTrack (void)
{
OSErr                  err = noErr;
StandardFileReply      reply;
   short                  refNum;
   long                  logicalEOF;
   Handle            dataHandle = nil,    tempHandle = nil;
      Movie            theMovie = nil, tempMovie = nil;
      // Specify the General MIDI file to import
      StandardGetFilePreview (nil, 0, nil, &reply);
         if (reply.sfGood)
         {
         // Open the data fork and suck everything into a handle
      err = FSpOpenDF (&reply.sfFile, fsRdPerm, &refNum);
         err = GetEOF (refNum, &logicalEOF);
            dataHandle = NewHandleClear (logicalEOF);
            HLock (dataHandle);
         err = FSRead (refNum, &logicalEOF, *dataHandle);
            HUnlock (dataHandle);
            FSClose (refNum);
         // Create a new movie in memory, set its default data reference
         // to be a handle
            tempMovie = NewMovie (newMovieActive);
            tempHandle = NewHandleClear (4);
            SetMovieDefaultDataRef (tempMovie, tempHandle,
                  HandleDataHandlerSubType);
                  DisposeHandle (tempHandle);
                              // Paste the handled data into our movie
                     err = PasteHandleIntoMovie (dataHandle,                   'Midi', tempMovie, 0, nil);
            // Save the movie out to a flattened file
            StandardPutFile ("\pSave MIDI to:", "\pMIDI                      movie", &reply);
               if (reply.sfGood)
            {
      theMovie = FlattenMovieData (tempMovie,
         flattenAddMovieToDataFork, &reply.sfFile, 'TVOD',
            smCurrentScript, createMovieFileDeleteCurFile);
         }
      }
   return err;
}

This method works fine as long as you have enough memory, and don't want to save the movie to disk. To put data into a file, call this function in order to pass in an alias to the file as the data reference and rAliasType as the data reference type:

SetMovieDefaultDataRef (tempMovie, fileAlias, rAliasType);

Q: When my application calls TrackDrag, it crashes in low memory at an illegal instruction. The MacsBug stack crawl doesn't produce any useful information. (I think the errant code did a JMP to the bad instruction, as opposed to a JSR.) I've stared and stared at all my app's calls to the Drag Manager and all the parameters appear to be valid. My drag tracking handler is never called, incidentally. If I take all calls to Drag Manager out of my application, it runs just fine. I've been investigating this crash for two months. Why is life so cruel?

A: You've unearthed a really ugly problem.

Early versions of Drag Manager did not enjoy the benefits of a drag-enabled Finder, so Drag Manager plays a little fast and loose with Finder's jump table. Yes, that means what it sounds like: Drag Manager calls Finder routines through its jump table. (It disgusted me at first, too.)

The even more interesting story concerns the method by which Drag Manager decides your application is Finder. When TrackDrag is called, Drag Manager determines whether the drag originates in any of the windows in the window list of the current process. If not, Drag Manager determines whether the drag originates in any Finder window. Since the desktop is a window for these purposes, there is a large area which qualifies.

Once Drag Manager has decided the drag originates in a Finder window, it assumes that Finder is the current process. (This is the fatal mistake.) Once this assumption is in place, the next thing for Drag Manager to do in order to coax Finder into exhibiting the correct drag behavior is call an entry in whatever jump table can be found by offsetting the current value of register A5. This is a valid assumption if Finder is the current process, which of course it is not. This is where things go terribly astray: Drag Manager calls a jump table entry in your application thinking your app is Finder, your app's routine doesn't do the same thing as the Finder routine, and any number of spectacular effects can result.

Now wait a minute, you're thinking, the drag originated in one of my application's windows; how is this stuff about Finder relevant? Consider the event record your app is passing to TrackDrag. An event record is supposed to contain a 'where' field expressed in global coordinates. However, the 'where' field your app is passing is expressed in local coordinates. How? Well, that depends on your application, but often this can result from application frameworks (like PowerPlant, MacApp, or THINK Class Library) modifying the event record before passing it to your code. There's no language-level way to specify the record has been modified, so the compiler doesn't warn you. (Honestly, this is Not Your Fault.)

Your code blithely calls TrackDrag with what it ought to be able to assume is a valid event record but is not. TrackDrag interprets the 'where' field, which is actually expressed in local coordinates, as global coordinates. This point is somewhere up and to the left of where your application expects, and quite often it's in the desktop, which as we said above is considered a Finder window for these purposes. Drag Manager reacts by going through its ritual for drags originating in Finder windows and eventually crashes after calling some odd routine in your application, as described above.

To solve this problem, simply call LocalToGlobal on the 'where' field of the event record before calling TrackDrag.