Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 12 - Data Access Manager / Data Access Manager Reference

Data Access Manager Routines / High-Level Interface: Handling Query Documents

DBStartQuery

Use the DBStartQuery function to initiate the process of sending a query to a data server.

FUNCTION DBStartQuery (VAR sessID: LongInt; query: QueryHandle;
                       statusProc: ProcPtr; 
                       asyncPB: DBAsyncParmBlkPtr): OSErr;

sessID

A session ID that identifies a session with the data server. If you specify 0 for this parameter, then the DBStartQuery function initiates a session and returns the session ID in the sessID parameter.

query

A handle to a query record.

statusProc

A pointer to a status routine that your application can use to update its windows after the query definition function has completed execution. (The DBStartQuery function does not attempt to update your application's windows.) The DBStartQuery function also calls your status routine before it initiates a session with a data server, after it calls the DBInit function, after it calls the DBSend function, and after it calls the DBExec function. Status routines are discussed in "Writing a Status Routine for High-Level Functions" beginning on page 12-22.

asyncPB

A pointer to an asynchronous parameter block. When specified, the DBStartQuery function calls the DBInit, DBSend, and DBExec functions asynchronously. As soon as the DBInit function has started execution, it returns control to your application. Your application must then call the Event Manager's WaitNextEvent function periodically to allow these asynchronous routines to run, and it must check the result field of the asynchronous parameter block to determine when each routine has completed execution.

DESCRIPTION

The DBStartQuery function performs the following tasks, in the order specified:

1. It calls the query definition function (if any) pointed to by the query record. The query definition function modifies the query record and the query, usually by asking the user for input. The query definition function can display a dialog box that gives the user the option of canceling the query; if the user does cancel the query, the DBStartQuery function returns the userCanceledErr result code.
2. If you specify a nonzero value for the statusProc parameter, the DBStartQuery function calls your status routine with the kDBUpdateWind constant in the message parameter so that your application can update its windows.
3. If you specify a nonzero value for the statusProc parameter, the DBStartQuery function calls your status routine with the kDBAboutToInit constant in the message parameter so that your application can display a dialog box informing the user that a session is about to be initiated with a data server, and giving the user the option of canceling execution of the function.
4. If the sessID parameter is 0, the DBStartQuery function calls the DBInit function to initiate a session, and returns a session ID.
5. If you specify a nonzero value for the statusProc parameter and the DBStartQuery function calls the DBInit function, the DBStartQuery function calls your status routine with the kDBInitComplete constant in the message parameter and the result of the DBInit function in the function result.
6. The DBStartQuery function calls the DBSend function to send the query to the data server.
7. If you specify a nonzero value for the statusProc parameter, the DBStartQuery function calls your status routine with the kDBSendComplete constant in the message parameter and the result of the DBSend function in the result parameter.
8. The DBStartQuery function calls the DBExec function to execute the query.
9. If you specify a nonzero value for the statusProc parameter, the DBStartQuery function calls your status routine with the kDBExecComplete constant in the message parameter and the result of the DBExec function in the result parameter.
10. If you specify a nonzero value for the statusProc parameter, the DBStartQuery function calls your status routine with the kDBStartQueryComplete constant in the message parameter and the result of the DBStartQuery function in the result parameter.

SPECIAL CONSIDERATIONS

The DBStartQuery 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 DBStartQuery function are

Trap macro	Selector
_DBStartQuery	$0811

RESULT CODES

noErr	0	No error
userCanceledErr	-128	User canceled the query
rcDBError	-802	Error initiating session, sending text, or executing query
rcDBBadSessID	-806	Session ID is invalid
rcDBBadDDev	-808	Couldn't find the specified database extension, or error occurred in opening database extension
rcDBAsyncNotSupp	-809	The database extension does not support asynchronous calls
rcDBPackNotInited	-813	The InitDBPack function has not yet been called

SEE ALSO

See "Using the High-Level Interface" beginning on page 12-14 for a general description of how the DBStartQuery function works in conjunction with other Data Access Manager routines. See Listing 12-1 beginning on page 12-18 for an example of the use of the DBStartQuery function. For a description of the query record, see page 12-57. For information on how to write a query definition function or status routine, see "Writing a Query Definition Function" beginning on page 12-52 and "Writing a Status Routine for High-Level Functions" beginning on page 12-22, respectively. Descriptions of the DBInit, DBSend, and DBExec functions begin on page 12-69, page 12-77, and page 12-79, respectively.