Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 12 - Data Access Manager / Data Access Manager Reference

Data Access Manager Routines / Installing and Removing Result Handlers

DBInstallResultHandler

The DBInstallResultHandler function installs a result handler for the data type specified by the dataType parameter. The result handler is then used by the DBResultsToText function to convert data of the specified type into a character string.

FUNCTION DBInstallResultHandler (dataType: DBType; 
                                 theHandler: ProcPtr; 
                                 isSysHandler: Boolean): OSErr;

dataType

The type of result handler to install.

theHandler

A pointer to a result handler.

isSysHandler

A Boolean value that specifies whether the result handler is an application result handler--to be used only when the DBResultsToText function is called by the application that installed the result handler--or a system result handler--to be used by every application running on the system. If the isSysHandler parameter is TRUE, the result handler is a system result handler.

DESCRIPTION

When you install an application result handler, it replaces any result handler with the same name previously installed by that application. Similarly, when you install a system result handler, it replaces any existing system result handler with the same name. Before you temporarily replace an existing result handler, use the DBGetResultHandler function to obtain a pointer to the present handler, and save the present result handler in your application's private storage. Then you can reinstall the original result handler when you are finished using the temporary one.

Because an application result handler is used in preference to a system result handler if both are available, you can temporarily replace a system result handler for purposes of your application by installing an application result handler for the same data type. You can then use the DBRemoveResultHandler function to remove the application result handler and return to using the system result handler whenever you wish.

SPECIAL CONSIDERATIONS

The DBInstallResultHandler function may move or purge memory. You should not call this routine from within an interrupt, such as in a completion routine or a VBL task.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the DBInstallResultHandler function are

Trap macro	Selector
_DBInstallResultHandler	$0514

RESULT CODES

noErr	0	No error
rcDBPackNotInited	-813	The InitDBPack function has not yet been called

SEE ALSO

See page 12-68 for a description of the DBResultsToText function. For information on application and system result handlers, see "Converting Query Results to Text" beginning on page 12-43; that section also lists the data types for which Apple provides system result handlers. Listing 12-6 on page 12-46 shows a sample result handler. The DBRemoveResultHandler function is described on page 12-90, and the DBGetResultHandler function is described next.