Important: The information in this document is obsolete and should not be used for new development.
DBStartQuery
Use theDBStartQuery
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 thesessID
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.) TheDBStartQuery
function also calls your status routine before it initiates a session with a data server, after it calls theDBInit
function, after it calls theDBSend
function, and after it calls theDBExec
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 theDBInit
,DBSend
, andDBExec
functions asynchronously. As soon as theDBInit
function has started execution, it returns control to your application. Your application must then call the Event Manager'sWaitNextEvent
function periodically to allow these asynchronous routines to run, and it must check theresult
field of the asynchronous parameter block to determine when each routine has completed execution.DESCRIPTION
TheDBStartQuery
function performs the following tasks, in the order specified:
- 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 theuserCanceledErr
result code.- If you specify a nonzero value for the
statusProc
parameter, theDBStartQuery
function calls your status routine with thekDBUpdateWind
constant in themessage
parameter so that your application can update its windows.- If you specify a nonzero value for the
statusProc
parameter, theDBStartQuery
function calls your status routine with thekDBAboutToInit
constant in themessage
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.- If the
sessID
parameter is 0, theDBStartQuery
function calls theDBInit
function to initiate a session, and returns a session ID.- If you specify a nonzero value for the
statusProc
parameter and theDBStartQuery
function calls theDBInit
function, theDBStartQuery
function calls your status routine with thekDBInitComplete
constant in themessage
parameter and the result of theDBInit
function in the function result.- The
DBStartQuery
function calls theDBSend
function to send the query to the data server.- If you specify a nonzero value for the
statusProc
parameter, theDBStartQuery
function calls your status routine with thekDBSendComplete
constant in themessage
parameter and the result of theDBSend
function in theresult
parameter.- The
DBStartQuery
function calls theDBExec
function to execute the query.- If you specify a nonzero value for the
statusProc
parameter, theDBStartQuery
function calls your status routine with thekDBExecComplete
constant in themessage
parameter and the result of theDBExec
function in theresult
parameter.- If you specify a nonzero value for the
statusProc
parameter, theDBStartQuery
function calls your status routine with thekDBStartQueryComplete
constant in themessage
parameter and the result of theDBStartQuery
function in theresult
parameter.
SPECIAL CONSIDERATIONS
TheDBStartQuery
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 theDBStartQuery
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 calledSEE ALSO
See "Using the High-Level Interface" beginning on page 12-14 for a general description of how theDBStartQuery
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 theDBStartQuery
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 theDBInit
,DBSend
, andDBExec
functions begin on page 12-69, page 12-77, and page 12-79, respectively.