All Databases Inside Mac - DAM/Ed/PPC/Slot

DBStartQuery

Call a query

#include <DatabaseAccess.h> Data Access Manager

OSErr DBStartQuery( sessID, query, statusProc, asyncPB );

long * sessID ; specifies a session ID

QueryHandle query ; a handle to the query record.

ProcPtr statusProc ; a pointer to a status routine

DBAsyncParmBlkPtr asyncPB ; a pointer to an asynchronous parameter block.

returns Error Code; 0=no error

The DBStartQuery function performs the following tasks, in the order

specified:

1. It calls the query definition function (if any) pointed to by the

QueryRecord. The query definition function modifies the QueryRecord 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.

sessID specifies a session ID if your application or another application has

already initiated a session with the data server. If you specify NIL for

this parameter, then the DBStartQuery function initiates a session

and returns the session ID in the sessID parameter.

query specifies a handle to the QueryRecord

statusProc specifies 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 the section,

Writing a Status Routine for High-Level Functions .

asyncPB a pointer to an asynchronous parameter block. 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 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.

Returns: an operating system Error Code.

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

Referenced by (18):