<< Click to Display Table of Contents >> Navigation:  »No topics above this level« Preparing the record buffer and retrieving field descriptors

A successful call to DbiOpenTable returns a cursor handle to the application. Before it can use the cursor handle to access data in the table, the application must prepare the record buffer. Preparing the record buffer includes allocating memory for it and, in some cases, initializing it.

The application can also set up an array in which to retrieve the field descriptors for each field contained in the table. To determine the required sizes of the record buffer and the array of field descriptors, the application calls DbiGetCursorProps. This call is usually made immediately after the DbiOpenTable call, and returns the required information in the CURProps structure.

Example

The following code sample gets the cursor properties, allocates the record buffer, sets up an array for the field descriptors, and gets the field descriptors:

DBIResult   rslt;

pCHAR       pRecBuf;

CURProps    curProps;

pFLDDesc    pFldArray;

…

// Get the table properties

rslt = DbiGetCursorProps(hCursor, &curProps);

if (rslt == DBIERR_NONE)

{

 // Allocate the record buffer

 pRecBuf = malloc(curProps.iRecBufSize);

 // Check result of malloc

 …

 // Get an array of field descriptors

 pFldArray = (pFLDDesc) malloc(sizeof(FLDDesc) * curProps.iFields);

 // Check result of malloc

 …

 rslt = DbiGetFieldDescs(hCursor, pFldArray);

 …

 free(pFldArray);

 free(pRecBuf);

}

Getting the cursor properties

When the application calls DbiGetCursorProps, the cursor properties CURProps structure is returned with information describing the most commonly used cursor properties. CURProps contains the following fields:

 

Memory allocation elements

The following elements are significant when allocating memory:

iFields
Specifies the number of fields in the table. Use this number to allocate an array to receive the field descriptors for the table. The size of the array is:

 iFields * sizeof(FLDDesc)

 

iRecSize
Specifies the record size, depending on the translation mode for the cursor. If the translation mode is xltFIELD, iRecSize specifies the logical record size. In other words, it is the size of the record if all fields were represented as BDE logical types. If the translation mode is xltNONE, iRecSize specifies the physical record size, which is the same as iRecBufSize.

iRecBufSize
Specifies the physical record size. This is the size of the record buffer that you must allocate in order to retrieve the records by using DbiGetNextRecordefq.7b, DbiGetPriorRecord, and other functions. For example,

 pRecBuf = (pBYTE)malloc(curProps.iRecBufSize);

Initializing the record buffer

Initialize the record buffer with a call to DbiInitRecord if a new record is to be inserted. This function initializes each field in the record buffer, including BLOB fields, to blanks based on the data type defined. For Paradox tables, default values are used to initialize the fields if default values are specified in the table.

Getting the field descriptors

After memory has been allocated for the array of field descriptors, the application can retrieve the field descriptors with a call to DbiGetFieldDescs. The field descriptors provide the application with information that it needs to address and manipulate each field within the record buffer. DbiGetFieldDescs returns an array of FLDDesc structures, with information describing each field in the table:

szName
Specifies the name of the field.

iFldType
Specifies the type of the field. Depending on the translate mode property of this cursor the field type returned could be physical or logical. If the translate mode is xltFIELD, the field type returned is a BDE logical type; if the mode is xltNONE, the field type returned is the driver's corresponding physical type. For more information about physical and logical data types, see Using the function reference and Data structures.

iSubType
Specifies the subtype of the field. This could be a BDE logical subtype or a driver physical subtype, depending on the translate mode.

iUnits1
Specifies the number of characters, digits, and so on. For logical field types, this number is consistent across drivers. For physical field types, the interpretation of this field can be dependent on the driver and also on the specific field type. For most drivers, if the field is of the numeric type, iUnits1 is the precision and iUnits2 is the scale.

iUnits2
Specifies the number of decimal places, and so on. For logical field types, this number is consistent across drivers. For physical field types, the interpretation of this field can depend on the driver and also on the specific field type. For most drivers, if the field is of the numeric type, iUnits1 is the precision and iUnits2 is the scale.

The following three fields together specify the layout of the record buffer:

iOffset
Specifies the offset of this field in the record buffer. The offset depends on the translation mode. If the mode is xltFIELD, it is the offset of the field within a logical record.

iLen
Specifies the length of this field. The length depends on the translation mode; that is, it could be the length of the logical or physical representation of the field. The application developer uses this value to allocate a buffer in which to retrieve the field value.

iNullOffset
Specifies the offset of the NULL indicator for this field in the record buffer. If zero, there is no NULL indicator. Otherwise, iNullOffset is the offset to an INT16 value, which is -1 if the field is NULL (SQL only).

efldvVchk
Specifies whether or not validity checks are associated with this field (Paradox and SQL drivers only).

efldrRights
Specifies the field level rights for this field.

 

 Preparing to access a table%!AL(`preparingtoaccess')

 Accessing and updating tables%!AL(`accessingtables')