Inside Macintosh: Interapplication Communication /

Chapter 12 - Data Access Manager / Data Access Manager Reference

Data Access Manager Routines / Low-Level Interface: Retrieving Results

DBGetItem

After you have executed a query and the DBState function returns the rcDBValue result code, indicating that data is available, you can use the DBGetItem function to retrieve the next data item. You can also use this function to obtain information about the next data item without retrieving the data.

FUNCTION DBGetItem (sessID: LongInt; timeout: LongInt; 
                    VAR dataType: DBType; VAR len: Integer;
                    VAR places: Integer; VAR flags: Integer;
                    buffer: Ptr; asyncPB: DBAsyncParmBlkPtr)
                    : OSErr;

sessID

The session ID that was returned by the DBInit function.

timeout

The maximum amount of time that the database extension should wait to receive results from the data server before canceling the function. Specify the timeout parameter in ticks (sixtieths of a second). To disable the timeout feature, set the timeout parameter to the kDBWaitForever constant. If the timeout period expires, the DBGetItem function returns the rcDBBreak result code. The DBGetItem function ignores the timeout parameter if you call the function asynchronously.

One use for the timeout parameter is to call the DBGetItem function periodically with a short value set for this parameter in order to return control to your application while a query is executing. Your application can then retrieve the next data item as soon as execution of the query is complete without having to call the DBState function to determine when data is available.

dataType

The data type that you expect the next data item to be. If the item is not of the expected data type, the database extension returns the rcDBBadType result code. If you want to retrieve the next data item regardless of type, set the dataType parameter to the typeAnyType constant. To skip the next data item, set the dataType parameter to the typeDiscard constant. The data server sets the dataType parameter to the actual type of the data item when it retrieves the data item or returns information about the data item.

len

The length of the data buffer pointed to by the buffer parameter. If you use the DBGetItem function to obtain information only (by setting the buffer parameter to NIL), then the data server ignores the len parameter. The data server sets the len parameter to the actual length of the data item when it retrieves the data item or returns information about the data item.

places

Returns the number of decimal places in data items of types typeMoney and typeDecimal. For all other data types, the data server returns 0 for the places parameter.

flags

If the least significant bit of the flags parameter is set to 1, the data item is in the last column of the row. If the third bit of this parameter is set to 1, the data item is NULL. You can use the constants kDBLastColFlag and kDBNullFlag to test for these flag bits.

buffer

A pointer to the location where you want the retrieved data item to be stored. You must ensure that the location you specify contains enough space for the data item that will be returned. To determine the data type, length, and number of decimal places of the next data item without retrieving it, specify NIL for the buffer parameter.

asyncPB

A pointer to an asynchronous parameter block. If you do not want to call the function asynchronously, set this parameter to NIL.

DESCRIPTION

The DBGetItem function retrieves the next data item from the data server. You can repeat the DBGetItem function as many times as is necessary to retrieve all of the data returned by the data source in response to a query.

SPECIAL CONSIDERATIONS

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

Trap macro	Selector
_DBGetItem	$100C

RESULT CODES

noErr	0	No error
rcDBNull	-800	The data item was NULL
rcDBValue	-801	Data available was successfully retrieved
rcDBError	-802	Error executing function
rcDBBadType	-803	Next data item not of requested data type
rcDBBreak	-804	Function timed out
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

For a discussion of data types, see "Getting Query Results" beginning on page 12-37. To retrieve all of a query's data items at once, use the high-level function DBGetQueryResults; a description of that function begins on page 12-66. For a description of the asynchronous parameter block, see page 12-56. See Listing 12-5 beginning on page 12-34 for an example that illustrates the use of the DBGetItem function.