Important: The information in this document is obsolete and should not be used for new development.
DBGetItem
After you have executed a query and theDBState
function returns thercDBValue
result code, indicating that data is available, you can use theDBGetItem
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 thetimeout
parameter to thekDBWaitForever
constant. If the timeout period expires, theDBGetItem
function returns thercDBBreak
result code. TheDBGetItem
function ignores thetimeout
parameter if you call the function asynchronously.- One use for the
timeout
parameter is to call theDBGetItem
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 theDBState
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 thedataType
parameter to thetypeAnyType
constant. To skip the next data item, set thedataType
parameter to thetypeDiscard
constant. The data server sets thedataType
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 theDBGetItem
function to obtain information only (by setting thebuffer
parameter toNIL
), then the data server ignores thelen
parameter. The data server sets thelen
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
andtypeDecimal
. For all other data types, the data server returns 0 for theplaces
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 isNULL
. You can use the constantskDBLastColFlag
andkDBNullFlag
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 thebuffer
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
TheDBGetItem
function retrieves the next data item from the data server. You can repeat theDBGetItem
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
TheDBGetItem
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 theDBGetItem
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 calledSEE 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 functionDBGetQueryResults
; 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 theDBGetItem
function.