<< Click to Display Table of Contents >> Navigation:  »No topics above this level« DbiSetFieldMap

C syntax

DBIResult DBIFN DbiSetFieldMap (hCur, iFields, pFldDesc);

Delphi syntax

function DbiSetFieldMap (hCur: hDBICur; iFields: Word; pFldDesc: pFLDDesc): DBIResult stdcall;

Description

DbiSetFieldMap sets a field map of the table associated with the given cursor.

Parameters

hCur                Type: hDBICur                (Input)
Specifies the cursor handle.

iFields                Type: UINT16                (Input)
Specifies the number of fields to map.

pFldDesc                Type: pFLDDesc                (Input)
Pointer to an array of FLDDesc structures.

Usage

A field map allows the user to effectively reorder the fields of a table or to drop some of the fields from view. This function does not produce a new cursor, but modifies the existing one. The client application specifies a field map by building an array of field descriptors. The order of field descriptors in the array specifies the order in which the cursor presents the fields.

For Paradox, FoxPro, Access, and dBASE, all data retrieval functions map the returned records as specified in the field description; no type conversions are allowed. When a record is updated in a table with a field map, the unmapped fields are left unchanged. When a record is inserted in a table with a field map, the unmapped fields are set to blank.

Paradox: When a record is inserted in a table with a field map, the unmapped fields are set to blank or set to any defined default value.

Text: Since no description of the fields are available when the text file is created with DbiCreateTable, it is a good practice to set a field map on the cursor that is opened on that text file. The text driver uses this field map to interpret the data types of the fields in that text file. The DbiTranslateRecordStructure call can be used to convert the logical or physical fields of a given driver type (such as Paradox or dBASE) to the physical fields of the text driver. These resulting physical text fields can be used in the DbiSetFieldMap call. When a field map is set on a text table, iFldType, iFldNum, iUnits1, and iUnits2 must be set correctly in all the field descriptors.

Prerequisites

DbiGetFieldDescs must be called to retrieve the array of field descriptors for the table.

Completion state

The underlying table is not affected. All the original fields still exist; they are simply not visible. (To drop fields in the underlying table, use DbiDoRestructure.) Setting iFields to 0 removes any existing field map and allows the underlying fields to become visible again.

See also

DbiGetFieldDescs