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

DBGetItem

Retrieve the next data item from the data server

#include <DatabaseAccess.h> Data Access Manager

OSErr DBGetItem( sessID, timeout, dataType, len, places, flags,

buffer, asyncPB);

long sessID ; is the session ID

long timeout; is the maximum amount of time that the

database extension should wait to receive

results

DBType * dataType; specifies the data type that you expect the

next data item to be

short *len ; specifies the length of the data buffer

short * places; specifies the number of decimal places for

the data item

short *flags; set to indicate information about the data

item

void * buffer; is a pointer to the location where you want

the retrieved data item to be stored

DBAsyncParmBlkPtr asyncPB; is a pointer to the asynchronous parameter

block

returns Error Code; 0=no error

The DBGetItem function retrieves the next data item from the data server.

You can also use this function to obtain information about the next data item

without retrieving the data. You can use the DBGetItem function after you

have executed a query and the DBState function has returned the rcDBValue

result code, indicating that data is available. 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.

sessID is the session ID that was returned by the DBInit function.

timeout specifies 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 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 specifies 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.

Data types are discussed under Getting Query Results in

Processing Query Results .

len is 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 specifies 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 is 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 is a pointer to the asynchronous parameter block. If you do not want

to call the function asynchronously, set this parameter to NIL

Returns: an operating system Error Code.

noErr (0) No error; no next data item

rcDBNull (-800) The data item was NULL

rcDBValue (-801) A nonzero data item was successfully retrieved

rcDBError (-802) Execution ended in an error

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

Referenced by (17):