Q When my application is running, it relies on the MultiFinder's "puppet strings"
(which choose Open from the application's File menu and suppress the SFGetFile
dialog) to open a document that was double- clicked in the Finder. Why doesn't this
work under System 7? The high-level event-aware bit in my 'SIZE' resource is clear.
A System 7 will not pull puppet strings for an application that makes use of the
System 7 Standard File routines, such as StandardGetFile and CustomGetFile, nor will
it pull them if the application's high-level event-aware bit is set.
If you update an older application to take advantage of any System 7 features, be sure
to also add support for the 'odoc' and other required Apple events. Sample code showing
how to support the required Apple events is available on the System 7 Golden Master
CD.
Q Why does Gestalt tell me I have Color QuickDraw features on a non-Color QuickDraw
machine?
A The gestaltQuickdrawFeatures ('qdrw') selector, used for determining your system's
Color QuickDraw features, has a bug that causes it to tell you incorrectly that noncolor
machines have color. The fix is quite simple: Gestalt has another selector,
gestaltQuickdrawVersion ('qd '), which simply returns the QuickDraw version
number. This version number is < gestalt8BitQD for classic QuickDraw and >=
gestalt8BitQD for Color QuickDraw (see Inside Macintosh Volume VI, page 3-39, for
more information). The trick is to ask Gestalt for the QuickDraw version first; once
you've determined that you have Color QuickDraw, the 'qdrw' selector is OK to use to
find out specifics.
Q What do we return to the Apple event handler if we get an application error while
processing a standard event, Edition Manager event, or custom Apple event for
commands and queries? Probably not errAENotHandled, since that means we didn't
handle the event, which is different from trying to handle it and failing. Would it be
errAEFail? What if we want to return more specific error information? Do we define
our own errors, or try to use Apple's errors such as memFullErr or parmErr?
A You pass back errAENotHandled, because it's true, and because some simple
applications will not be able to handle anything more than that. What you can also do,
and what most commercial applications will do (particularly applications that want to
be scripting savvy), is add errn and errs parameters to the reply record for that
event (as shown on page 6-49 of Inside Macintosh Volume VI). You can be as
descriptive as you like in the text--the more the better, in fact, since this text will be
seen at the user level usually. The errn value you pass back can be the system error
number; then the sending program may be able to recover and try again.
Q According to the QuickTime Movie Toolbox documentation, "The Movie Toolbox
maintains a set of global variables for every application using it." How much global
memory is required? Our application is shy on global data space.
A The information maintained is not kept with the application's global variables. The
handle created by the EnterMovies call is stored in the system heap, not in the
application heap. You don't have to worry about how much space to allocate in your
application. This initialization does not affect your A5 world either.
EnterMovies initializes everything, including setting up the necessary data space and
creating a handle to it. When you're done, be sure to make a call to ExitMovies to clean
up the QuickTime data. If an application makes multiple calls to EnterMovies, a
different set of "globals," or data area, is set up for each call. A call to ExitMovies
should be made before exiting the area that made the call to EnterMovies. For example,
an application that uses QuickTime will call EnterMovies and set up the QuickTime
world. Then an external may be called upon that wants to use QuickTime. This external
would have to make a call to EnterMovies to set up another QuickTime world for its
use. Before leaving, the external should call ExitMovies to clean up after itself. The
application can then continue to use QuickTime with the original world it set up.
Q Why does the longword at location $0 get changed to 0x40810000 at every trap?
A In System 7, the Process Manager slams a benign value into location $0 to help
protect against bus errors when an application inadvertently dereferences a NIL
pointer. (There's no bus-error checking on writes to ROM, so the "benign value" is
usually ROMBase+$10000.)
If you're debugging, you want the opposite effect: you want these inadvertent accesses
to "cause" bus errors. If you put a different value in location $0 before the Process
Manager starts up (that is, from MacsBug or TMON initialization, or from an INIT like
EvenBetterBusError), it will force that value instead. For more information, see the
"Macintosh Debugging" article in this issue.
Q I'm filling a large buffer with one SCSIRead call. What happens if the Macintosh runs
under System 7 with virtual memory (VM) and parts of my buffer are swapped out?
A Parts of your buffer must not be swapped out. Before calling SCSIGet, you must
ensure that all code and buffers accessed while the SCSI bus is busy are held in
physical memory. If there isn't enough real memory to allocate a full buffer, the
application must request smaller blocks (if possible) from the SCSI device, because
it's not possible to swap in and out any buffer space during a single I/O operation. Page
faults are not serviced while SCSI I/O is in progress. If SCSI I/O is performed at
device driver-level Read or Write calls, VM holds your buffer for you. Otherwise, you
are responsible for doing this yourself. If there is insufficient physical memory for
VM to hold your buffers for you, the Read or Write call fails with an error result.
In general, I/O buffer space used by drivers must be held in real memory for the
duration of the I/O operation. This is especially true for SCSI I/O because VM uses
SCSI to swap virtual memory in and out, and encountering another page fault would
cause a bus error. Device Manager-level I/O handles this automatically, by holding
down the appropriate memory when the driver is entered through a Read or Write call.
The Device Manager does not take care of this for you when the driver is entered
through a Control or Status call, however. If the SCSIRead call is made from within a
device driver as a result of a PBRead, no special action is necessary. Any other type of
code must be very careful not to cause page faults between SCSIGet and SCSIComplete.
This requires holding or placing in the system heap any code or data structures
referenced during this time.
Q Is there anything special that a Macintosh hard disk or a removable cartridge driver
must do to be fully compatible with System 7?
A One important thing you should be aware of regarding removable cartridges is that a
cartridge can't be removable if VM is to use it for a backing store. Some removables
allow you to fix this with a SCSI command to prohibit ejection and, just as important,
the drive must be marked nonejectable in the drive queue.
Here are a couple of suggestions: Read Macintosh Technical Note #285, "Coping with
VM and Memory Mappings." Also, take a look at the Memory Management chapter of
Inside Macintosh Volume VI and the Virtual Memory paper (Goodies:VM Goodies:VM
Paper) on the System 7 Golden Master CD.
Q What does the "!" mean when I use the MacsBug Heap Zone (HZ) command? It
appears in front of one of the zone names listed, or just after the address if the zone
doesn't have a name.
A MacsBug's HZ command does a quick-and-dirty heap check, and if it thinks
something is wrong with a heap, it puts the exclamation point after the address range
of the heap. If you select the heap flagged with a "!" with the Heap Exchange (HX)
command and then use the regular Heap Check (HC) command, MacsBug tells you what
it thinks is wrong with that heap.
Q I want to display only visible files and folders in a Standard File dialog, but I can't
find a way to filter out invisible folders--specifically the 000Move&Rename folder.
The FileFilter routine filters only files, not folders. If I put in a nonzero TypeList,
invisible folders seem to be removed, but I want to open all types of files, just not
invisible files or folders. Any suggestions?
A This is, in fact, impossible under System 6 using general methods. The problem is
that passing -1 as numTypes means not only to display all items, but to display
invisible items. A file filter can be used to remove the invisible files but cannot affect
invisible folders. The only current way to do this is to use CustomGetFile under System
7, as described in the Standard File Package chapter of Inside Macintosh Volume VI.
This provides a filter that allows you to filter both files and folders. This will give you
the right functionality, but will work only under System 7. We recommend that you
use this method under System 7, and a more standard SFGetFile when running under
earlier systems.
Q How can I obtain the volume reference information in my DlgHook function for a file
selected by the user before SFPPutFile or SFPGetFile has completed the reply record?
A On exit, SFPGetFile and SFPPutFile generate a working directory reference number
in the vRefNum field of the reply record. This is not available to you from within the
operation of a DlgHook function. WDRefNums are provided to allow compatibility with
older, pre-HFS functions that took vRefNum values of integer size with the older flat
file system.
We suggest that, unless you plan to support the flat file system of 64K ROM Macintosh
systems, you move your file system interfaces to the HFS interfaces documented in the
File Manager sections of Inside Macintosh Volumes IV and V (or to the equivalent
high-level calls as documented in Macintosh Technical Note #218, "New High-Level
File Manager Calls"). If you're using the HFS calls, low-memory globals SFSaveDisk
and CurDirStore contain, respectively, the negative of the "real" volume reference
number for the current volume and the HFS ID of the directory that Standard File is
displaying. You then have all the information you need to create, open, rename, or
delete files from within the SFPGetFile and SFPPutFile DlgHook functions. If a user is
accessing an MFS volume on an HFS system, these calls are designed tohandle file
access transparently.
Moving your file system interfaces to the HFS-level conventions has a side benefit of
being closer to the System 7 file system specifications. If you look at the new
high-level file system calls in Inside Macintosh Volume VI, you'll recognize much of
the HFS information embedded in the new data structures.
If your file system interfaces depend on MFS-style vRefNums, or WDRefNums in the
HFS nomenclature, you can use the HFS functions PBOpenWD, PBCloseWD, and
PBGetWDInfo to open, close, and obtain volume reference numbers and directory IDs.
This is particularly important if, for instance, you're using the THINK C ANSI file I/O
functions, which rely on SetVol to operate correctly.
Complete information on the HFS-level calls that will be most useful in Standard File
customization is contained in the File Manager chapters of Inside Macintosh Volumes
IV and V, and in Macintosh Technical Notes #66, 77, 102, 140, 179, 190, and 218.
For C users, Macintosh Technical Note #246 summarizes a list of the difficulties with
mixing C file I/O with Macintosh file I/O. Macintosh Technical Notes #47 and 80
discuss a few points of Standard File customization from the point of view of HFS.
Q Why does GetGWorldPixMap (when called on a Macintosh II, IIcx, or IIx running
system software version 6.0.5 or 6.0.7 with 32-Bit QuickDraw 1.2) return a
combination of the device field (two bytes) and the first two bytes of the portPixMap
field? Is this a bug?
A Your analysis of GetGWorldPixMap is exactly right: It doesn't work correctly in
system software version 6.0.5 and 6.0.7 with 32-Bit QuickDraw 1.2. It returns a
value that's two bytes before the value it's supposed to return.
The solution is to use GWorldPtr->portPixMap instead of GetGWorldPixMap. It's safe
to do this, but you should use GetGWorldPixMap under System 7. Not only is the bug
fixed there, but dereferencing the port is dangerous under System 7 because it may not
be CGrafPort. Use Gestalt with the gestaltQuickdrawVersion selector to determine
whether you can use GetGWorldPixMap. If Gestalt returns a value from gestalt8BitQD
($0100) through gestalt32BitQD12 ($0220), then GetGWorldPixMap either doesn't
exist or is the buggy version. If it returns gestalt32BitQD13 ($0230) or higher,
then GetGWorldPixMap does exist and works correctly. Interestingly,
GetGWorldPixMap can be called on a black-and-white QuickDraw machine under
System 7. It returns a handle to a structure which should be treated as a BitMap
structure, though there are some undocumented fields after the normal BitMap fields.
To tell whether GetGWorldPixMap is available on a black-and-white QuickDraw
machine, you must check the system software version by calling Gestalt with the
gestaltSystemVersion selector. If it returns $0700 or higher, GetGWorldPixMap is
available.
Q DrawText with srcCopy takes six times as long as with srcOr now that my Macintosh
is running System 7. Why is this so slow? Is this a bug in System 7?
A It's true that srcCopy is slower than srcOr when handling text, especially in color
mode. This loss in speed occurs because CopyBits is a lot smarter than it used to be. It
can handle foreground and background colors a lot better, but that improvement came
at the cost of speed. Our recommended method for drawing text is to erase before
drawing, and use srcOr to draw, not srcCopy. Alternatively, you could draw colorized
text in srcOr mode off screen and then use CopyBits to draw it on the screen in srcCopy
mode without colorization.
Q I'm creating PICTs that are comprised of many lines drawn in srcOr mode. When
using the LaserWriter 6.x or 7.x driver with the Color/Grayscale radio button
selected, some lines fail to print. Why is this happening?
A The problem is a bug in the LaserWriter driver. Sometimes, when using a
CGrafPort, the driver doesn't reproduce lines drawn in srcOr mode. (A CGrafPort is
used when the Color/Grayscale print option is selected; in Black & White print mode, a
regular grafPort is used.) A workaround is to use srcCopy instead of srcOr when
drawing QuickDraw objects within your PICTs.
Q Is there any way to determine whether I'm printing to either a color printer or a
printer simulating color, such as the LaserWriter set for Color/Grayscale?
A Check the grafPort returned by your call to PrOpenDoc. If the rowBytes of the
grafPort is less than 0, the Printing Manager has returned a color grafPort. You can
then make Color QuickDraw calls into this grafPort. LaserWriter driver version 6.0
and later returns a color grafPort from the PrOpenDoc call, if the Color/Grayscale
button has been set.
The following code fragment demonstrates this:
(* This function determines whether the port passed to it is a *)
(* color port. If so, it returns TRUE. *)
FUNCTION IsColorPort(portInQuestion: GrafPtr): BOOLEAN;
BEGIN
IF portInQuestion^.portBits.rowBytes < 0 THEN
IsColorPort := TRUE
ELSE
IsColorPort := FALSE;
END;
A third-party printer driver should return the type of grafPort that represents the
abilities of its printer. Therefore, if the printer supports color and/or grayscale, and
if Color QuickDraw is present, the application will receive a color grafPort after
calling PrOpenDoc. Otherwise, if the Macintosh you're running on does not support
Color QuickDraw, you should return a black-and-white grafPort.
Q If I use the PostScriptHandle PicComment to send PostScript code to the LaserWriter
driver, do I need to open a picture and then draw the picture to the driver, or can I
just use the PicComment with no picture open while drawing to the printer's
grafPort?
A You don't need to create a picture with your PicComment in it and draw the picture to
the driver. The best method for sending PostScript code to the LaserWriter is to use
the PostScriptHandle PicComment documented in Macintosh Technical Note #91,
"Optimizing for the LaserWriter--Picture Comments," as shown below.
PrOpenPage(...)
{ Send some QuickDraw so that the Printing Manager gets a }
{ chance to define the clipping region. }
PenSize(0,0);
MoveTo(0,0);
LineTo(0,0);
PenSize(1,1);
PicComment(PostScriptBegin, 0, NIL);
{ QuickDraw representation of graphic. }
MoveTo(100, 100);
LineTo(200, 200);
{ PostScript representation of graphic. }
thePSHandle^^ := '100 100 moveto 200 200 lineto stroke';
PicComment(PostScriptHandle, GetHandleSize(thePSHandle),
thePSHandl);
PicComment(PostScriptEnd, 0, NIL);
PrClosePage(...)
The above code prints a line on any type of printer, PostScript or not. The first
MoveTo/LineTo combination is required to give the LaserWriter driver a chance to
define a clipping region. The LaserWriter driver replaces the grafProcs record in the
grafPort returned from PrOpenDoc. In order for the LaserWriter driver to get
execution time, you must execute a QuickDraw drawing routine that calls one of the
grafProcs. In this case, the MoveTo/LineTo combination calls the StdLine grafProc.
When StdLine executes, it notices that the grafPort has been reinitialized, and
therefore initializes the clipping region for the port. Until the MoveTo/LineTo
combination is executed, the clipping region for the port is set to (0,0,0,0). If
PostScript code is sent via the PostScriptHandle PicComment before executing any
QuickDraw routines, all PostScript operations will be clipped to (0,0,0,0).
The next thing that's done is to send the PostScriptBegin PicComment. This comment is
recognized only by PostScript printer drivers. When the driver receives this
comment, it saves the current state of the PostScript device (by executing the
PostScript gsave operator), then disables all QuickDraw drawing operations. This
way, the QuickDraw representation of the graphic will be ignored by PostScript
devices. In the above example, the second MoveTo/LineTo combination is executed only
on non-PostScript devices. The next PicComment is PostScriptHandle, which tells the
driver that the data in thePSHandle is to be sent to the device as PostScript code. The
driver then passes this code unchanged to the PostScript device for execution. The
PostScriptHandle comment is recognized only by PostScript printer drivers.
The last PicComment, PostScriptEnd, tells the driver to restore the previous state of
the device (via a PostScript grestore call), and to enable QuickDraw drawing
operations.
Since most PicComments are ignored by QuickDraw devices, only the QuickDraw
representation is printed. Since PostScriptBegin tells PostScript drivers to ignore
QuickDraw operations, only the PostScript representation is printed on PostScript
devices. This is a truly device-independent method for providing both PostScript and
QuickDraw representations of a document.
Q How do users install the Macintosh Communications Toolbox (CTB)?
A The Communications Toolbox consists of two parts: the CTB managers and the CTB
tools. The installation procedure for CTB tools is different between System 6 and
System 7. Under System 6 the CTB tools are dragged from the Basic Connectivity Set
disk to the Communications Folder in the System Folder on the hard disk. Under System
7 the CTB tools are dragged from the Basic Connectivity Set disk to the Extensions
folder in the System Folder on the hard disk. Of course, because of the way System 7
works, CTB tools can simply be dragged to the System Folder and the Finder will
automatically move them to the Extensions folder where they belong.
No installation of the CTB managers is required under System 7, since System 7
includes the Communications Toolbox as part of the system. Users running System
6.0.5 should use the Installer and Install script on the Communications 1 disk to
install the CTB managers and other resources onto their hard disks. Users running
System 6.0.7 should use the Installer and Install script on the Network Products
Installer disk, which is part of the System 6.0.7 set users receive with their
Macintosh systems. The Network Products Installer disk does not contain the CTB
managers and other resources, but it prompts the user to insert the Communications
1 disk during the installation procedure.
The Basic Connectivity Set and Communications 1 disks should be shipped with your
CTB-aware product. Contact Apple's Software Licensing group (AppleLink
SW.LICENSE) for a licensing agreement to ship the disks.
Q Can any AppleTalk routines be called at interrupt time? Inside Macintosh says that
DDPWrite and DDPRead can't be called from interrupts. If all higher-level AppleTalk
protocols are based on DDP, it seems that they all would not work.
A The AppleTalk routines you can't call at interrupt time are the original AppleTalk
Pascal Interfaces listed in Inside Macintosh Volume II; these are also known as the
"Alternate Interface" AppleTalk routines, or ABPasIntf.
The Alternate Interface routines cannot be called at interrupt time because they
allocate the memory structures needed to make the equivalent assembly language
AppleTalk call. For example, when the NBPLookup routine is called, it's passed a
handle to an ABusRecord. NBPLookup then has to allocate an MPPParamBlock and move
the parameters from the ABusRecord into the newly allocated MPPParamBlock. Then
NBPLookup makes a LookupName call, passing it the MPPParamBlock. When
LookupName completes, NBPLookup must move results into the ABusRecord and
release the memory used by the MPPParamBlock. Since memory is allocated and
released within the routine, it cannot be called at interrupt time.
With that out of the way, the calls you can make at interrupt time (with some
restrictions listed below) are what Apple calls the "Preferred Interface" AppleTalk
routines. Most of the Preferred Interface routines are listed on page 562 of Inside
Macintosh Volume V. There are a few additional calls that were added after the
publication of Inside Macintosh Volume V; they're documented in the AppleTalk
chapter of Inside Macintosh Volume VI.
The Preferred Interface AppleTalk routines can be made at interrupt time as long as:
Q Why do I get only the left channel of a stereo sound out of my Macintosh IIcx?
A The only Macintosh models that combine the two stereo channels into one for
playback out of the internal speaker are the Macintosh SE/30 and the IIsi. All others
use just the left channel. If you would like to check for the machine's ability to do
mixing, you can use Gestalt. This is documented in Inside Macintosh Volume VI, page
22-70. Bit 1 of the Gestalt selector for sound will tell you whether the machine has
stereo mixing on the internal speaker.
Q Inside Macintosh Volume VI, page 2-22, recommends updating the window positions
in a file without changing the last modification date and time on the file. How do I alter
a file without automatically changing the timestamp?
A To modify the contents of a file's data or resource fork without changing the last
modified date, get the modified date before performing any save operations on the file
and restore it when you're done. You can use the PBHGetFInfo and PBHSetFInfo calls to
do this. A short Pascal snippet that modifies the contents of a known file's resource
fork without modifying its modification date is included in the Snippets folder on this
issue's Developer CD Series disc. The code shows how the parameter block is filled in
with the file's information at the start of the routine with a PBHGetFInfo call, and the
same data is then used without modification to set the file information at the end of the
routine with a PBHSetFInfo. Inside Macintosh Volume IV, page 150, tells you which
fields can be changed with PBHSetFInfo.
Q Help! I've just added Balloon Help to my application, but I'm having some problems.
Whenever a balloon appears, it immediately begins floating away off the top of the
screen. What can I do to stop this madness?
A It appears you failed to heed our warning when it comes to routines that can move
balloons. Consult Appendix D of Inside Macintosh X-Ref , "Routines That May Pop
Balloons or Cause Barometric Disturbances," for a complete listing of these help
balloon meteorological nightmares. In addition, be sure to call the new trap
HMSetBalloonContents:
OSErr HMSetBalloonContents (balloonContents: INTEGER);
CONST { types of balloon contents }
helium = 0;
air = 1;
water = 2;
whippedCream = 3;
with balloonContents set to something greater than helium.
Kudos to our readers who care enough to ask us terrific and well thought-out
questions. The answers are supplied by our teams of technical gurus; our thanks to all.
Special thanks to Pete "Luke" Alexander, Sonya Andreae, Mark Baumwell, Mike Bell,
Jim "Im" Beninghaus, Rich Collyer, Neil Day, Tim Dierks, Marcie "MG" Griffin, C.K.
Haun, Pete Helme, Dave Hersey, Dennis Hescox, Jim Luther, Joseph Maurer, Jim
Mensch, Guillermo Ortiz, Craig Prouse, Dave Radcliffe, Greg Robbins, Jack Robson,
Kent Sandvik, Paul Snively, Bryan "Stearno" Stearns, Forrest Tanaka, Vincent Tapia,
John Wang, and Scott "Zz" Zimmerman for the material in this Q & A column.*
Have more questions? Need more answers? Take a look at the Dev Tech Answers
library on AppleLink (updated weekly) or at the Q & A stack on the Developer CD
Series disc.*