Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 12 - Data Access Manager / Data Access Manager Reference

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

DBGetQueryResults

You can use the DBGetQueryResults function to retrieve the results of a query.

FUNCTION DBGetQueryResults (sessID: LongInt; 
                            VAR results: ResultsRecord; 
                            timeout: LongInt; statusProc: ProcPtr; 
                            asyncPB: DBAsyncParmBlkPtr): OSErr;

sessID

The session ID of the session from which you wish to retrieve results.

results

The results record, which contains handles to the retrieved data.

timeout

The value that the DBGetQueryResults function uses for the timeout parameter each time it calls the DBGetItem function. The timeout parameter specifies the maximum amount of time that the database extension should wait to receive results from the data server before canceling the DBGetItem function. Specify the timeout parameter in sixtieths of a second. To disable the timeout feature, set the timeout parameter to the kDBWaitForever constant. Some database extensions ignore the timeout parameter when you specify a nonzero value for the asyncPB parameter.

statusProc

A pointer to a status routine that you provide. The DBGetQueryResults function calls your status routine after it calls the DBGetItem function to retrieve a data item. When it calls the status routine, the DBGetQueryResults function provides the result of the DBGetItem function, the data type, the data length, the number of decimal places, the flags associated with the data item, and a pointer to the data item.

asyncPB

A pointer to an asynchronous parameter block. If specified, the DBGetQueryResults function calls the DBGetItem function asynchronously for each data item. As soon as the DBGetItem function has started execution, it returns control to your application. Your application must then call the Event Manager's WaitNextEvent function periodically to allow this asynchronous routine to run, and it must check the result field of the asynchronous parameter block to determine when the routine has completed execution.

DESCRIPTION

The DBGetQueryResults function retrieves the results returned by a query and places them in memory. If there is sufficient memory available, this function retrieves all of the results at once. If the DBGetQueryResults function runs out of memory, it places as much data as possible in memory, up to the last whole row. You can then make more memory available and call the DBGetQueryResults function again to retrieve more data.

You must allocate the results record and pass this record to the DBGetQueryResults function. The Data Access Manager allocates the handles inside the results record. When your application is finished using the results record, you must deallocate both the results record and the handles inside the results record.

The DBGetQueryResults function can be used to retrieve the results of any query, not only queries sent and executed by the DBStartQuery function.

SPECIAL CONSIDERATIONS

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

Trap macro	Selector
_DBGetQueryResults	$0A12

RESULT CODES

noErr	0	No error
userCanceledErr	-128	Function canceled by status routine
rcDBValue	-801	Data available
rcDBError	-802	Query execution ended in an error
rcDBBreak	-804	Function timed out
rcDBExec	-805	Query currently executing
rcDBBadSessID	-806	Session ID is invalid
rcDBAsyncNotSupp	-809	The database extension does not support asynchronous calls
rcDBPackNotInited	-813	The InitDBPack function has not yet been called

SEE ALSO

See Listing 12-1 beginning on page 12-18 for an example of the use of the DBGetQueryResults function. See page 12-56 for a description of the asynchronous parameter block. Descriptions of the DBStartQuery and DBGetItem functions begin on page 12-64 and page 12-84, respectively. For more information on results records, see "The Results Record" beginning on page 12-59 and "Getting Query Results" beginning on page 12-37. For more information on status routines, see "Writing a Status Routine for High-Level Functions" beginning on page 12-22.