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:
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:
stdloginto 'Send to the programmer'
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:
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:
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.)