September 96 - Macintosh Q & A

Q What books and articles would you recommend that provide strategies for debugging?

A Here's a list of resources that can help you with debugging on the Macintosh:

• How to Write Macintosh Software by Scott Knaster and Keith Rollin (Addison-Wesley, 1992). This book describes how to find all the bugs you wrote when you used memory manipulation in C.

• Debugging Macintosh Software With MacsBug, by Konstantin Othmer and Jim Straus (Addison-Wesley, 1991), and MacsBug Reference and Debugging Guide by Apple Computer, Inc. (Addison-Wesley, 1990). These books don't describe the latest version of MacsBug; check the MacsBug 6.5.2 release notes for additional details.

• "Macintosh Debugging: A Weird Journey Into the Belly of the Beast" by Bo3b Johnson and Fred Huxham, develop Issue 8, and "Macintosh Debugging: The Belly of the Beast Revisited" by Fred Huxham and Greg Marriott, develop Issue 13.

• "Debugging on PowerPC" by Dave Falkenburg and Brian Topping, develop Issue 17.

• "Balance of Power: MacsBug for PowerPC" by Dave Evans and Jim Murphy, develop Issue 22.

• "KON & BAL's Puzzle Page," in every issue of develop since Issue 9.

Q I have a customer who's encountering a problem using my product. Can you suggest a way to use MacsBug to diagnose problems at a customer site?

A Yes. Here, in a few easy steps, is a technique for using MacsBug to diagnose problems in the field:

• Install a clean copy of the latest MacsBug.

• Create a file using ResEdit (or Resorcerer, or whatever) containing an 'mxbm' resource (which contains MacsBug macro definitions) and install it into the MacsBug Preferences folder.

• In this 'mxbm' resource, define the macro everytime to call the stdloginto macro as follows:

stdloginto 'Send to the programmer'

• This way, if MacsBug is ever invoked due to a program error, a log of what occurred will be automatically generated. The log, named "Send to the programmer," will appear on the desktop.

• Have your customer send you the log file created by the above steps.

See page 219 of the MacsBug Reference and Debugging Guide by Apple Computer, Inc. (Addison-Wesley, 1990) for details of the everytime macro. For details of what the stdloginto macro does, look at the 'mxbm' resource named "log stuff" in MacsBug's resource fork.

Q We're developing an application that uses Apple Guide. It's working well on 680x0 Macintosh computers but is presenting a problem on the Power Macintosh, because of AppleGuideGlue. If we import this library as "weak," the program runs but crashes when we call any Apple Guide routines. If we import "strong," the program simply refuses to run. What can we do?

A Linking with the .xcoff file produces a reference to a shared library named AppleGuideGlue. Unfortunately, the Apple Guide extension provides a library named AppleGuideGlueLib instead, so the reference isn't resolved and the application fails to launch.

The AppleGuideGlue.xcoff file has been changed to AppleGuideGlueLib.xcoff on the latest Mac OS SDK CD. You can use that one, or just rename the one you have before including it in your project.

In MPW, you can rename the library in the link process. If you're using Symantec C or C++ or CodeWarrior, however, the name of the file has to be correct for the matching library to be found at run time. Note that CodeWarrior ignores the ".xcoff" suffix if it's present in the filename, while Symantec must have the ".xcoff" suffix to properly include the file in the project.

Q My QuickDraw GX printer driver has a 'ptyp' of "A4 portrait" as the default paper type (via the isDefaultPaperType flag). But when a user chooses my driver from the Page Setup dialog, A4 is selected as the default paper type in the desktop printer, though my driver has no 'ptyp' named A4. How can I set my own paper type (A4 portrait) as the default?

A The paper-matching code is working incorrectly. QuickDraw GX internally adds the standard paper types (such as A4 and US Letter) to the options for your driver. The bug is that QuickDraw GX thinks it's finding a better fit for the current page dimensions than the assigned A4 portrait paper type. It then defaults to the internal A4 paper type.

The only workaround at this time is to remove the paper type that you're incorrectly defaulting to. If you're defaulting to a nonstandard paper type, such as Letterhead, Stationery, or Three-hole Punch, the best workaround is to remove that type from the Extensions folder. If you're defaulting to another paper type, the easiest thing you can do is to open your driver with a resource editor and remove or edit the 'ptyp' resource for the paper type that's incorrectly matching. (Open the resource and you'll see the paper type name embedded in the data.)

Q I'm creating a QuickDraw GX page that contains a line of single-layer text shapes, with each word a different color. The page displays correctly when it's opened in SimpleText but shows a bug when it's printed to a PostScript printer: each line prints with one color instead of each word being a different color. Any ideas?

A This is a bug that occurs only with single-layer text shapes that have a nil style in their face layer. There's a workaround that should be used anytime you do a one-layer text face, except for italics -- this workaround slows down italic drawing but speeds up all other cases.

Create a "generic" style object (with GXNewStyle) to replace the nil style. Set the text size to 1.0 (important) and the pen to 0 in the style. The other fields are irrelevant to this fix. Set your text face's style to this "generic" style and the problem will disappear.

Q I'm having a problem, apparent at very small font sizes (6 points and below), with the output quality of some fonts that emerge from a QuickDraw GX vector driver. My application uses gxLayouts for text display and editing. If I create my output using GXDrawShape to render the layout shapes, the small characters begin to look very crude: character height varies by about 30% between some letters, and curved letter forms degenerate to rough polygons. What can I do to improve the quality?

A Layouts (like all typographic shapes) have hints turned on by default. If the font you're using isn't hinted at small point sizes, using hints messes up the appearance of the text rather than helping it. Try using the layout shape and setting the gxNoMetricsGridText and gxNoContourGridText bits in the text attributes. The results at small sizes should be better.

Q I'm writing an Open Transport client program, and I'm confused about how to perform an orderly release when I receive the T_ORDREL message. When I get the T_ORDREL message I'm supposed to call OTRcvOrderlyDisconnect. The documentation for OTRcvOrderlyDisconnect says that I can then continue to send data but that I can't read data without getting an "out of state" error (kOTOutStateErr). Is this correct?

A Yes, it is. Your confusion is due more to the dynamics and subtleties of X/Open Transport Interface (XTI) programming than to Open Transport itself.

Let's examine an orderly disconnect situation. Assume that two nodes have an established TCP connection. Endpoint A has finished sending data and indicates closure by invoking an OTSndOrderlyDisconnect call (this translates into sending an end-of-file signal -- FIN -- over the wire). Endpoint B receives a T_ORDREL message. If, however, B hasn't finished receiving the data, B must continue until it gets back kOTNoDataErr. At this point, B initiates an OTRcvOrderlyDisconnect (which acknowledges A's FIN). This is known as a "half-close"; B can still send data to A (which will still receive T_DATA events), but if A attempts to send to B, A will receive an "out of state" error.

A, of course, should also continue accepting data until receiving kOTNoDataErr. A should then call OTRcvOrderlyDisconnect, thereby completing the other side of the link teardown. Both sides can then unbind.

If, however, either endpoint's network code is written such that T_ORDREL and T_DATA events are handled at different priorities (for instance, the T_ORDREL is handled at the notifier, but the T_DATA is deferred to SystemTask time), a race condition can occur. Your program must ensure that all data has been read before calling OTRcvOrderlyDisconnect.

There's also a subtlety of XTI programming that you should be aware of. It's possible that OTSndOrderlyDisconnect or OTRcvOrderlyDisconnect will return with a TLOOK error. This means that there's another event pending; your program must call OTLook to gather that event.

According to the XTI specification, the OTSndOrderlyDisconnect and OTRcvOrderlyDisconnect calls can fail because of a pending T_DISCONNECT event. XTI is trying to tell you that the connection to that endpoint broke. This can happen easily in our modern, wacky, asynchronous world of networks, and your program will have to call OTRcvDisconnect to acknowledge that your endpoint dropped.

Q I've implemented a server endpoint that hands off the connection to a hand-off endpoint. After the server processes a connect request with the OTAccept call, the asynchronous handler for the hand-off endpoint is passed a T_DATA event. When the handler makes the OTRcv call, however, it returns error -3168 (kOTStateChangeErr). Can you explain this?

A This problem occurs only when there's a hand-off (secondary) endpoint involved. The way Open Transport is implemented, it's possible for an asynchronous hand-off endpoint to receive a T_DATA event before the connect mechanism is completed. After accepting a connection, an asynchronous listener endpoint can expect to receive a T_ACCEPTCOMPLETE call. The "accepting" or hand-off endpoint can expect to receive the T_PASSCON event.

It's possible for the hand-off endpoint to receive the T_DATA event before receiving the T_PASSCON event, and this apparently is what's happening to you. When this happens, set a flag to defer receiving the data until later. After the T_PASSCON event is received, check the flag and issue the OTRcv call if the flag is set. (Note that after deferring the handling of the T_DATA event, your handler won't receive this event again until you process all of the data presently available.)

Q What's the relationship between the classic AppleTalk "self-send" variable and the one in Open Transport AppleTalk?

A In version 1.1, Open Transport AppleTalk shares the self-send variable with classic AppleTalk, so if you set the variable with the classic PSetSelfSend call, the effects are seen by both AppleTalk and Open Transport clients. If you're using Open Transport, you can change the variable with an OTIoctl call, as shown here:

enum {
   kATalkFullSelfSend      = MIOC_CMD(MIOC_ATALK, 47)
};

static OSStatus OTSetSelfSend(EndpointRef ep,
     Boolean enable_self_send)
{
   OSStatus result;
 
   result = OTIoctl(ep, kATalkFullSelfSend,
               (void *) enable_self_send);
   if (result > 0) 
      result = 0;
   return result;
}

Note that like the PSetSelfSend call, the OTIoctl call returns the previous value of the self-send variable as either 0 (it was previously disabled) or 1 (it was previously enabled). As in classic AppleTalk, it's rarely appropriate to restore the value of self-send when you're done, so the code above maps both results to 0 (noErr).

Here's why the value shouldn't be restored. The self-send value is a Boolean, not a counter. For example, imagine the following sequence:

• Self-send starts out false.

• Client A sets self-send to true and is returned false as the previous value.

• Client B sets self-send to true and is returned true as the previous value.

• Client A quits, "restoring" self-send to false.

In the end, client B is left with self-send set to false, which is incorrect.

For this reason, the standard practice is to set self-send if you need it and not attempt to restore it when finished. Because many clients follow this convention, it's important that your program work even if self-send is true.

Future versions of Open Transport will most likely have self-send always on for Open Transport native clients, and loop-back packets will be filtered out only for classic clients if PSetSelfSend wasn't called.

Q When I make a synchronous OTConnect call from a TCP client to a TCP server that's passively awaiting an incoming connection, I find that even before the server responds with the OTListen and OTAccept calls, the OTConnect call completes with no error. At this point, if I examine the client endpoint state, I find that it's in the T_DATAXFER state. Can you explain this?

A As mentioned in the XTI specification (available with the Open Transport release), "TCP does not allow the possibility of refusing a connection indication. Each connect indication causes the TCP transport provider to establish the connection. Therefore t_listen() and t_accept() have a semantic which is slightly different than that for ISO providers." Consequently, the server will accept the TCP connection request if the current number of connections allows it. The XTI specification states that "when the transport detects a T_LISTEN, TCP has already established the connection." The client, whether in synchronous or asynchronous mode, will receive notice that the connection was established. For synchronous endpoints, TCP completes the three-way connection handshake. For asynchronous endpoints, the OTRcvConnect call must be made to complete the handshake.

Q In my Open Transport TCP-based server application, I use a specific socket for receiving incoming connection requests. If I relaunch the server immediately after quitting, the initialization calls complete without error, but the server never receives any incoming connection requests. If I wait several minutes before relaunching the server, this problem doesn't occur. It appears that there's some internal timeout for disconnected connections. Is there a solution to this problem so that the server can be relaunched without waiting for the timeout?

A TCP has a two-minute timeout on a binding after a connection has closed before the same port can be bound to again. This prevents stale data from corrupting a new connection. For this reason, you see a delay before you can successfully bind to the port again.

There's a way around this, using the IP_REUSEADDR option and the OTOptionManagement call. Set this option on all of your listening endpoints before you bind, and the problem should disappear.

Note that even after you use the IP_REUSEADDR option, at most one endpoint that's in a state less than connected (listening; unbound doesn't count) may be bound to a given port. Any number of connected or closing endpoints may be so bound to other unique ports, however.

The following sample shows how to set this option. The function takes two input parameters, the EndpointRef that you want to set the option for, and the state of the option that you want, typically true. The function returns a result of OSStatus: if negative, it's the error returned from the OTOptionManagement call; if positive, it's the status field returned by OTOptionManagement (this means the call completed successfully but the status field had a value other than T_SUCCESS). If 0 (kOTNoError), then of course there was no error.

#include <OpenTransport.h>            // Open Transport files
#include <OpenTptInternet.h>
/* input:   reuseState (true: no delay, false: normal delay state)
   output: if result less than kOTNoError, it's the error returned by
   OTOptionManagement. Otherwise, the status value is returned as
   defined in OpenTransport.h:
      T_SUCCESS       = 0x020,      return kOTNoError if success
      T_FAILURE       = 0x040,
      T_PARTSUCCESS   = 0x100,
      T_READONLY      = 0x200,
      T_NOTSUPPORT    = 0x400
*/

OSStatus DoNegotiateIPReuseAddrOption(EndpointRef ep, Boolean reuseState)
{
  UInt8     buf[kOTFourByteOptionSize]; // Buffer for fourByte option
  TOption*  opt;                        // Option ptr to make items
                                        // easier to access
  TOptMgmt  req;
  OSStatus  err;
  Boolean   isAsync = false;
   
  opt = (TOption*)buf;                  // Set option ptr to buffer.
  req.opt.buf   = buf;
  req.opt.len   = sizeof(buf);
  req.opt.maxlen = sizeof(buf);         // We're using req for the
                                        // return result also.
  req.flags = T_NEGOTIATE;            // Negotiate for option dealing
  opt->level = INET_IP;              // with an IP-level function.
  opt->name = IP_REUSEADDR;
  opt->len = kOTFourByteOptionSize;
  *(UInt32*)opt->value = reuseState; // Set the desired option
                                        // level, true or false.
  if (OTIsSynchronous(ep) == false) {  // Check if ep is synchronous.
     isAsync = true;                    // Set flag if async.
     OTSetSynchronous(ep);              // Set endpoint to sync.
  }
  err = OTOptionManagement(ep, &req, &req);
  if (isAsync == true)              // Restore ep state if necessary.
     OTSetAsynchronous(ep);
      
  // If no error, check the option status value.
  if (err == kOTNoError) {
     if (opt->status != T_SUCCESS)   // If not T_SUCCESS, return
        err = opt->status;           // the status.
  }
  return err;
}

Q I'm implementing a passive TCP connection. Can I hand off the connection to a different port address?

A No, the hand-off connection endpoint must be bound to the same address as the endpoint that passed off the connection. This is an XTI requirement, as discussed in Appendix B of the XTI specification, Section B.3.

Q I'd like my network client software to be able to abort an asynchronous OTConnect in progress -- to allow a user, for example, to recover from an attempted connection to a nonexistent IP address. I've been calling OTSndDisconnect to abort it, but when I check the return code, I get a kOTOutStateErr error. What gives?

A Using an OTSndDisconnect is the proper way to abort an OTConnect in progress. After a successful call to OTConnect, the endpoint state will transition from T_IDLE to T_OUTCON. Calling OTSndDisconnect returns the endpoint state to T_IDLE.

You may be getting kOTOutStateErr for one of the following reasons:

• The original OTConnect failed. Determine this by checking the OTConnect result.

• The connection broke and was asynchronously handled by your notifier. In this case, your endpoint would no longer be in the T_OUTCON state before you do the disconnect.

A good rule of thumb is always to confirm the endpoint state before doing the OTSndDisconnect to ensure that the endpoint isn't already disconnected.

Q I have a question regarding T_DATA event handling for multiple active endpoints. Let's say I have two endpoints open, endpoint 1 and endpoint 2. Data arrives for endpoint 1, which then receives a T_DATA event. If data arrives for endpoint 2 before the data for endpoint 1 is read, it's my understanding that endpoint 2 won't get a T_DATA event until the data for endpoint 1 is read. Is that correct? In other words, does Open Transport queue multiple T_DATA events corresponding to multiple endpoints?

A XTI or Open Transport endpoints are handled independently of each other. Whatever events are pending on one endpoint have (for the most part) no effect on any other endpoints.

Assume that endpoint 1 gets notified of a T_DATA event. Following this, a separate T_DATA event is queued up for endpoint 2. As soon as the notifier for endpoint 1 completes and returns to Open Transport, the notifier for endpoint 2 will be invoked. This behavior isn't contingent upon whether endpoint 1 processed the event, although of course endpoint 1 won't receive any more T_DATA events until its current T_DATA event is cleared. Keep in mind that waiting too long to process endpoint 1's T_DATA event will result in the exhaustion of buffers in the lower protocol layers.

Q Given an AppleTalk network and the node address of a Macintosh, how can I remotely retrieve the Network Name specified in the Sharing Setup control panel?

A The only universal way to determine a Macintosh's "flagship" name is to target an NBP lookup of type "workstation" to that particular node. At first glance, it would seem that we could get the desired result by calling PConfirmName (since it allows us to direct the NBP LkUp to the specific node by using the confirmAddr field, whereas PLookupName would broadcast it to an entire zone). The PConfirmName call doesn't return the NBP Tuple information to the application, however: under classic AppleTalk, PConfirmName's sole purpose is to confirm or deny the existence of a registered NBP name. This leaves you with several alternatives.

Under classic AppleTalk, you have two options. The first option is to use the PLookupName call. This is a little complicated because PLookupName requires that you specify the "zone name" of the target node. You have to call GetZoneList and parse through the replies (illustrated in Inside Macintosh: Networking, page 4-7) to extract a list of zone names that correspond to your target's network number. (Note that if you're on an extended network, it's possible for an AppleTalk zone to have a range of network numbers.) Once you have a list of suspected network zones that the target is on, you can then direct a PLookupName to those zones and parse through the responses to find the one that matches your target's node address.

The second option under classic AppleTalk is to form the NBP LkUp packet yourself and send it via DDP. You can open and register your own DDP listener by using the POpenSkt call. You can then form your own NBP LkUp packet and transmit it to the target node's NBP listener socket (socket 2) with the PWriteDDP call. The target will respond to you with an NBP LkUp-Reply, which will cause your DDP socket listener to be called. You can parse the reply there.

Writing a DDP socket listener is tricky, but it's illustrated in the Network Watch (DMZ) sample provided on this issue's CD. Examine the doEcho function in the files dMZAT.c and SktListener.a. Writing a socket listener for the Power Macintosh can be challenging because of classic AppleTalk's 680x0 roots. If you're stuck with a classic AppleTalk system, however, this is the recommended approach.

If your code is written to run under Open Transport, you're in luck. You can specify the target address in the TLookupRequest data structure used by the OTLookupName function. Check out the DoSendLkUpReq function in DDPSample.cp, found on any Open Transport SDK CD. Since the programming model is so much simpler, you may want to investigate the Open Transport approach.

Q I need to get the full pathname to a document in a callback where the only relevant piece of information I have is the WindowPtr for the window that contains the document. I can get the filename from the window title, but I don't know the directory ID or volume reference number. Is there any way to obtain the dirID and vRefNum from the WindowRecord?

A No, there's no way to extract the file system information you need from a WindowRecord. A WindowRecord includes only structural human interface information (which might include the filename as the window's title) and has no intrinsic tie to any file on the disk. As you've implied, you must have the directory ID and volume reference number to extract a full pathname. Once you know the vRefNum and the parent dirID, you'll be able to use one of the full path routines in the sample code MoreFiles on this issue's CD to construct a full pathname.

If the file is open and you have the refNum for its access path, you can call PBGetFCBInfo to get the vRefNum and dirID (and then use them to get the pathname). For more information on PBGetFCBInfo, see Inside Macintosh: Files, pages 2-237 through 2-238.

Q We sell a game that incorporates our own proprietary 3D technology. We'd like to be able to take advantage of 3D acceleration hardware, if it's available on the user's system. What do you recommend we use?

A Use the Rendering Acceleration Virtual Engine (RAVE) application development interface, which defines an abstract standardized hardware interface for applications to communicate with and control 3D hardware. If you adapt your game to draw to RAVE, it'll be compatible with any hardware 3D accelerators with RAVE-compatible drivers. RAVE is also a cross-platform specification, so code you write for the Macintosh will be easier to port to Windows 95 or Windows NT (if at some point in the future RAVE is implemented for Windows).

Q We created a QuickDraw 3D application similar to the TextureEyes demo distributed by Apple: it maps a moving image texture onto a spinning cube. The display quality of TextureEyes, however, is much better than ours. We're using large high-quality textures (480 x 320), but the image mapped onto the cube is quite chunky even with a 3D accelerator card, and the animation seems to be slower and jerkier. What's TextureEyes' secret?

A No secrets: TextureEyes is a straightforward implementation of the texturing of QuickDraw 3D geometries. The problem is that the quality of your textures is actually too high!

QuickDraw 3D uses a trilinear MIP map algorithm to obtain the best possible quality texture mapping. To create an MIP map from an image requires creating subimages sized for every inverse power of 4 -- that is, 1/4, 1/16, 1/64, and so on. The process of creating an MIP map for every texture takes time, and larger textures take longer. TextureEyes uses a 128 x 128 source for its movie and video textures. For more information on MIP maps, see Computer Graphics: Principles and Practice, by Foley, VanDam, Feiner, and Hughes (Addison-Wesley, 1996).

Q My quartz watch is eerily accurate. Why?

A A quartz watch uses the vibrations of a quartz crystal as its time reference. The frequency of vibration in the crystal depends on three factors: voltage, pressure, and temperature. To keep the watch accurate, all three of these must be kept constant.

The electronics in the watch provide a nice constant voltage, and the atmosphere provides a nice constant pressure. But what really ensures that the watch is accurate is that it's worn on your wrist: the constant temperature of your body in contact with the watch ensures that the crystal operates at a constant temperature.

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