| title | ms.custom | ms.date | ms.reviewer | ms.suite | ms.technology | ms.tgt_pltfrm | ms.topic | f1_keywords | dev_langs | helpviewer_keywords | ms.assetid | caps.latest.revision | author | ms.author | manager | |||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Record Field Exchange Functions | Microsoft Docs |
11/04/2016 |
|
article |
|
|
|
6e4c5c1c-acb7-4c18-bf51-bf7959a696cd |
13 |
mikeblome |
mblome |
ghogen |
This topic lists the Record Field Exchange (RFX, Bulk RFX, and DFX) functions used to automate the transfer of data between a recordset object and its data source and to perform other operations on the data.
If you are using the ODBC-based classes and you have implemented bulk row fetching, you must manually override the DoBulkFieldExchange member function of CRecordset by calling the Bulk RFX functions for each data member corresponding to a data source column.
If you have not implemented bulk row fetching in the ODBC-based classes, or if you are using the DAO-based classes, then ClassWizard will override the DoFieldExchange member function of CRecordset or CDaoRecordset by calling the RFX functions (for ODBC classes) or the DFX functions (for DAO classes) for each field data member in your recordset.
The record field exchange functions transfer data each time the framework calls DoFieldExchange or DoBulkFieldExchange. Each function transfers a specific data type.
For more information about how these functions are used, see the articles Record Field Exchange: How RFX Works (ODBC). For more information about bulk row fetching, see the article Recordset: Fetching Records in Bulk (ODBC).
For columns of data that you bind dynamically, you can also call the RFX or DFX functions yourself, as explained in the articles Recordset: Dynamically Binding Data Columns (ODBC). Additionally, you can write your own custom RFX or DFX routines, as explained in Technical Note 43 (for ODBC) and Technical Note 53 (for DAO).
For an example of RFX and Bulk RFX functions as they appear in the DoFieldExchange and DoBulkFieldExchange functions, see RFX_Text and [RFX_Text_Bulk]#rfx_text_bulk). DFX functions are very similar to the RFX functions.
| RFX_Binary | Transfers arrays of bytes of type CByteArray. |
| RFX_Bool | Transfers Boolean data. |
| RFX_Byte | Transfers a single byte of data. |
| RFX_Date | Transfers time and date data using CTime or TIMESTAMP_STRUCT. |
| RFX_Double | Transfers double-precision float data. |
| RFX_Int | Transfers integer data. |
| RFX_Long | Transfers long integer data. |
| RFX_LongBinary | Transfers binary large object (BLOB) data with an object of the CLongBinary class. |
| RFX_Single | Transfers float data. |
| RFX_Text | Transfers string data. |
| RFX_Binary_Bulk | Transfers arrays of byte data. |
| RFX_Bool_Bulk | Transfers arrays of Boolean data. |
| RFX_Byte_Bulk | Transfers arrays of single bytes. |
| RFX_Date_Bulk | Transfers arrays of data of type TIMESTAMP_STRUCT. |
| RFX_Double_Bulk | Transfers arrays of double-precision, floating-point data. |
| RFX_Int_Bulk | Transfers arrays of integer data. |
| RFX_Long_Bulk | Transfers arrays of long integer data. |
| RFX_Single_Bulk | Transfers arrays of floating-point data. |
| RFX_Text_Bulk | Transfers arrays of data of type LPSTR. |
| DFX_Binary | Transfers arrays of bytes of type CByteArray. |
| DFX_Bool | Transfers Boolean data. |
| DFX_Byte | Transfers a single byte of data. |
| DFX_Currency | Transfers currency data, of type COleCurrency. |
| DFX_DateTime | Transfers time and date data, of type COleDateTime. |
| DFX_Double | Transfers double-precision float data. |
| DFX_Long | Transfers long integer data. |
| DFX_LongBinary | Transfers binary large object (BLOB) data with an object of the CLongBinary class. For DAO, it is recommended that you use DFX_Binary instead. |
| DFX_Short | Transfers short integer data. |
| DFX_Single | Transfers float data. |
| DFX_Text | Transfers string data. |
=============================================
Transfers arrays of bytes between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_BINARY, SQL_VARBINARY, or SQL_LONGVARBINARY.
void RFX_Binary(
CFieldExchange* pFX,
const char* szName,
CByteArray& value,
int nMaxLength = 255);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type CByteArray, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
nMaxLength
The maximum allowed length of the string or array being transferred. The default value of nMaxLength is 255. Legal values are 1 to INT_MAX. The framework allocates this amount of space for the data. For best performance, pass a value large enough to accommodate the largest data item you expect.
Data in the data source of these types is mapped to and from type CByteArray in the recordset.
See RFX_Text.
Header: afxdb.h
Transfers Boolean data between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_BIT.
void RFX_Bool(
CFieldExchange* pFX,
const char* szName,
BOOL& value);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type BOOL, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
See RFX_Text.
Header: afxdb.h
Transfers single bytes between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_TINYINT.
void RFX_Byte(
CFieldExchange* pFX,
const char* szName,
BYTE& value);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type BYTE, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
See RFX_Text.
Header: afxdb.h
Transfers CTime or TIMESTAMP_STRUCT data between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_DATE, SQL_TIME, or SQL_TIMESTAMP.
void RFX_Date(
CFieldExchange* pFX,
const char* szName,
CTime& value);
void RFX_Date(
CFieldExchange* pFX,
const char* szName,
TIMESTAMP_STRUCT& value);
void RFX_Date(
CFieldExchange* pFX,
const char* szName,
COleDateTime& value);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member; the value to be transferred. The various versions of the function take different data types for value:
The first version of the function takes a reference to a CTime object. For a transfer from recordset to data source, this value is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
The second version of the function takes a reference to a TIMESTAMP_STRUCT structure. You must set up this structure yourself before the call. Neither dialog data exchange (DDX) support nor code wizard support is available for this version. The third version of the function works similarly to the first version except that it takes a reference to a COleDateTime object.
The CTime version of the function imposes the overhead of some intermediate processing and has a somewhat limited range. If you find either of these factors too limiting, use the second version of the function. But note its lack of code wizard and DDX support and the requirement that you set up the structure yourself.
See RFX_Text.
Header: afxdb.h
Transfers double float data between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_DOUBLE.
void RFX_Double(
CFieldExchange* pFX,
const char* szName,
double& value);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type double, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
See RFX_Text.
Header: afxdb.h
Transfers integer data between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_SMALLINT.
void RFX_Int(
CFieldExchange* pFX,
const char* szName,
int& value);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type int, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
See RFX_Text.
Header: afxdb.h
Transfers long integer data between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_INTEGER.
void RFX_Long(
CFieldExchange* pFX,
const char* szName,
LONG&
value );
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type long, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
See RFX_Text.
Header: afxdb.h
Transfers binary large object (BLOB) data using class CLongBinary between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_LONGVARBINARY or SQL_LONGVARCHAR.
void RFX_LongBinary(
CFieldExchange* pFX,
const char* szName,
CLongBinary& value);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type CLongBinary, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
See RFX_Text.
Header: afxdb.h
Transfers floating-point data between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_REAL.
void RFX_Single(
CFieldExchange* pFX,
const char* szName,
float& value);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type float, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
See RFX_Text.
Header: afxdb.h
Transfers CString data between the field data members of a CRecordset object and columns of a record on the data source of ODBC type SQL_LONGVARCHAR, SQL_CHAR, SQL_VARCHAR, SQL_DECIMAL, or SQL_NUMERIC.
void RFX_Text(
CFieldExchange* pFX,
const char* szName,
CString& value,
int nMaxLength = 255,
int nColumnType = SQL_VARCHAR,
short nScale = 0);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type CString, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
nMaxLength
The maximum allowed length of the string or array being transferred. The default value of nMaxLength is 255. Legal values are 1 to INT_MAX). The framework allocates this amount of space for the data. For best performance, pass a value large enough to accommodate the largest data item you expect.
nColumnType
Used mainly for parameters. An integer indicating the data type of the parameter. The type is an ODBC data type of the form SQL_XXX.
nScale
Specifies the scale for values of ODBC type SQL_DECIMAL or SQL_NUMERIC. nScale is only useful when setting parameter values. For more information, see the topic "Precision, Scale, Length, and Display Size" in Appendix D of the ODBC SDK Programmer's Reference.
Data in the data source of all of these types is mapped to and from CString in the recordset.
This example shows several calls to RFX_Text. Notice also the two calls to CFieldExchange::SetFieldType. For parameters you must write the call to SetFieldType and its RFX call. The output column call and its associated RFX calls are normally written by a code wizard.
void CCustomer::DoFieldExchange(CFieldExchange* pFX)
{
pFX->SetFieldType(CFieldExchange::outputColumn);
// Macros such as RFX_Text() and RFX_Int() are dependent on the
// type of the member variable, not the type of the field in the database.
// ODBC will try to automatically convert the column value to the requested type
RFX_Long(pFX, _T("[CustomerID]"), m_CustomerID);
RFX_Text(pFX, _T("[ContactFirstName]"), m_ContactFirstName);
RFX_Text(pFX, _T("[PostalCode]"), m_PostalCode);
RFX_Text(pFX, _T("[L_Name]"), m_L_Name);
RFX_Long(pFX, _T("[BillingID]"), m_BillingID);
pFX->SetFieldType(CFieldExchange::inputParam);
RFX_Text(pFX, _T("Param"), m_strParam);
}Header: afxdb.h
Transfers multiple rows of byte data from a column of an ODBC data source to a corresponding array in a CRecordset-derived object.
void RFX_Binary_Bulk(
CFieldExchange* pFX,
LPCTSTR szName,
BYTE** prgByteVals,
long** prgLengths,
int nMaxLength);
pFX
A pointer to a CFieldExchange object. This object contains information to define the context for each call of the function. For more information, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
prgByteVals
A pointer to an array of BYTE values. This array will store the data to be transferred from the data source to the recordset.
prgLengths
A pointer to an array of long integers. This array will store the length in bytes of each value in the array pointed to by prgByteVals. Note that the value SQL_NULL_DATA will be stored if the corresponding data item contains a Null value. For more details, see the ODBC API function SQLBindCol in the ODBC SDK Programmer's Reference.
nMaxLength
The maximum allowed length of the values stored in the array pointed to by prgByteVals. To ensure that data will not be truncated, pass a value large enough to accommodate the largest data item you expect.
The data source column can have an ODBC type of SQL_BINARY, SQL_VARBINARY, or SQL_LONGVARBINARY. The recordset must define a field data member of type pointer to BYTE.
If you initialize prgByteVals and prgLengths to NULL, then the arrays they point to will be allocated automatically, with sizes equal to the rowset size.
Note
Bulk record field exchange only transfers data from the data source to the recordset object. In order to make your recordset updateable, you must use the ODBC API function SQLSetPos.
For more information, see the articles Recordset: Fetching Records in Bulk (ODBC) and Record Field Exchange (RFX).
See RFX_Text_Bulk.
Header: afxdb.h
Transfers multiple rows of Boolean data from a column of an ODBC data source to a corresponding array in a CRecordset-derived object.
void RFX_Bool_Bulk(
CFieldExchange* pFX,
LPCTSTR szName,
BOOL** prgBoolVals,
long** prgLengths);
pFX
A pointer to a CFieldExchange object. This object contains information to define the context for each call of the function. For more information, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
prgBoolVals
A pointer to an array of BOOL values. This array will store the data to be transferred from the data source to the recordset.
prgLengths
A pointer to an array of long integers. This array will store the length in bytes of each value in the array pointed to by prgBoolVals. Note that the value SQL_NULL_DATA will be stored if the corresponding data item contains a Null value. For more details, see the ODBC API function SQLBindCol in the ODBC SDK Programmer's Reference.
The data source column must have an ODBC type of SQL_BIT. The recordset must define a field data member of type pointer to BOOL.
If you initialize prgBoolVals and prgLengths to NULL, then the arrays they point to will be allocated automatically, with sizes equal to the rowset size.
Note
Bulk record field exchange only transfers data from the data source to the recordset object. To make your recordset updateable, you must use the ODBC API function SQLSetPos.
For more information, see the articles Recordset: Fetching Records in Bulk (ODBC) and Record Field Exchange (RFX).
See RFX_Text_Bulk.
Header: afxdb.h
Transfers multiple rows of single bytes from a column of an ODBC data source to a corresponding array in a CRecordset-derived object.
void RFX_Byte_Bulk(
CFieldExchange* pFX,
LPCTSTR szName,
BYTE** prgByteVals,
long** prgLengths);
pFX
A pointer to a CFieldExchange object. This object contains information to define the context for each call of the function. For more information, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
prgByteVals
A pointer to an array of BYTE values. This array will store the data to be transferred from the data source to the recordset.
prgLengths
A pointer to an array of long integers. This array will store the length in bytes of each value in the array pointed to by prgByteVals. Note that the value SQL_NULL_DATA will be stored if the corresponding data item contains a Null value. For more details, see the ODBC API function SQLBindCol in the ODBC SDK Programmer's Reference.
The data source column must have an ODBC type of SQL_TINYINT. The recordset must define a field data member of type pointer to BYTE.
If you initialize prgByteVals and prgLengths to NULL, then the arrays they point to will be allocated automatically, with sizes equal to the rowset size.
Note
Bulk record field exchange only transfers data from the data source to the recordset object. To make your recordset updateable, you must use the ODBC API function SQLSetPos.
For more information, see the articles Recordset: Fetching Records in Bulk (ODBC) and Record Field Exchange (RFX).
See RFX_Text_Bulk.
Header: afxdb.h
Transfers multiple rows of TIMESTAMP_STRUCT data from a column of an ODBC data source to a corresponding array in a CRecordset-derived object.
void RFX_Date_Bulk(
CFieldExchange* pFX,
LPCTSTR szName,
TIMESTAMP_STRUCT** prgTSVals,
long** prgLengths);
pFX
A pointer to a CFieldExchange object. This object contains information to define the context for each call of the function. For more information, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
prgTSVals
A pointer to an array of TIMESTAMP_STRUCT values. This array will store the data to be transferred from the data source to the recordset. For more information about the TIMESTAMP_STRUCT data type, see the topic "C Data Types" in Appendix D of the ODBC SDK Programmer's Reference.
prgLengths
A pointer to an array of long integers. This array will store the length in bytes of each value in the array pointed to by prgTSVals. Note that the value SQL_NULL_DATA will be stored if the corresponding data item contains a Null value. For more details, see the ODBC API function SQLBindCol in the ODBC SDK Programmer's Reference.
The data source column can have an ODBC type of SQL_DATE, SQL_TIME, or SQL_TIMESTAMP. The recordset must define a field data member of type pointer to TIMESTAMP_STRUCT.
If you initialize prgTSVals and prgLengths to NULL, then the arrays they point to will be allocated automatically, with sizes equal to the rowset size.
Note
Bulk record field exchange only transfers data from the data source to the recordset object. To make your recordset updateable, you must use the ODBC API function SQLSetPos.
For more information, see the articles Recordset: Fetching Records in Bulk (ODBC) and Record Field Exchange (RFX).
See RFX_Text_Bulk.
Header: afxdb.h
Transfers multiple rows of double-precision, floating-point data from a column of an ODBC data source to a corresponding array in a CRecordset-derived object.
void RFX_Double_Bulk(
CFieldExchange* pFX,
LPCTSTR szName,
double** prgDblVals,
long** prgLengths);
pFX
A pointer to a CFieldExchange object. This object contains information to define the context for each call of the function. For more information, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
prgDblVals
A pointer to an array of double values. This array will store the data to be transferred from the data source to the recordset.
prgLengths
A pointer to an array of long integers. This array will store the length in bytes of each value in the array pointed to by prgDblVals. Note that the value SQL_NULL_DATA will be stored if the corresponding data item contains a Null value. For more details, see the ODBC API function SQLBindCol in the ODBC SDK Programmer's Reference.
The data source column must have an ODBC type of SQL_DOUBLE. The recordset must define a field data member of type pointer to double.
If you initialize prgDblVals and prgLengths to NULL, then the arrays they point to will be allocated automatically, with sizes equal to the rowset size.
Note
Bulk record field exchange only transfers data from the data source to the recordset object. To make your recordset updateable, you must use the ODBC API function SQLSetPos.
For more information, see the articles Recordset: Fetching Records in Bulk (ODBC) and Record Field Exchange (RFX).
See RFX_Text_Bulk.
Header: afxdb.h
Transfers integer data between the field data members of a CRecordset object and the columns of a record on the data source of ODBC type SQL_SMALLINT.
void RFX_Int(
CFieldExchange* pFX,
const char* szName,
int& value);
pFX
A pointer to an object of class CFieldExchange. This object contains information to define the context for each call of the function. For more information about the operations a CFieldExchange object can specify, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type int, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
See RFX_Text.
Header: afxdb.h
Transfers multiple rows of long integer data from a column of an ODBC data source to a corresponding array in a CRecordset-derived object.
void RFX_Long_Bulk(
CFieldExchange* pFX,
LPCTSTR szName,
long** prgLongVals,
long** prgLengths);
pFX
A pointer to a CFieldExchange object. This object contains information to define the context for each call of the function. For more information, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
prgLongVals
A pointer to an array of long integers. This array will store the data to be transferred from the data source to the recordset.
prgLengths
A pointer to an array of long integers. This array will store the length in bytes of each value in the array pointed to by prgLongVals. Note that the value SQL_NULL_DATA will be stored if the corresponding data item contains a Null value. For more details, see the ODBC API function SQLBindCol in the ODBC SDK Programmer's Reference.
The data source column must have an ODBC type of SQL_INTEGER. The recordset must define a field data member of type pointer to long.
If you initialize prgLongVals and prgLengths to NULL, then the arrays they point to will be allocated automatically, with sizes equal to the rowset size.
Note
Bulk record field exchange only transfers data from the data source to the recordset object. To make your recordset updateable, you must use the ODBC API function SQLSetPos.
For more information, see the articles Recordset: Fetching Records in Bulk (ODBC) and Record Field Exchange (RFX).
See RFX_Text_Bulk.
Header: afxdb.h
Transfers multiple rows of floating-point data from a column of an ODBC data source to a corresponding array in a CRecordset-derived object.
void RFX_Single_Bulk(
CFieldExchange* pFX,
LPCTSTR szName,
float** prgFltVals,
long** prgLengths);
pFX
A pointer to a CFieldExchange object. This object contains information to define the context for each call of the function. For more information, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
prgFltVals
A pointer to an array of float values. This array will store the data to be transferred from the data source to the recordset.
prgLengths
A pointer to an array of long integers. This array will store the length in bytes of each value in the array pointed to by prgFltVals. Note that the value SQL_NULL_DATA will be stored if the corresponding data item contains a Null value. For more details, see the ODBC API function SQLBindCol in the ODBC SDK Programmer's Reference.
The data source column must have an ODBC type of SQL_REAL. The recordset must define a field data member of type pointer to float.
If you initialize prgFltVals and prgLengths to NULL, then the arrays they point to will be allocated automatically, with sizes equal to the rowset size.
Note
Bulk record field exchange only transfers data from the data source to the recordset object. To make your recordset updateable, you must use the ODBC API function SQLSetPos.
For more information, see the articles Recordset: Fetching Records in Bulk (ODBC) and Record Field Exchange (RFX).
See RFX_Text_Bulk.
Header: afxdb.h
Transfers multiple rows of character data from a column of an ODBC data source to a corresponding array in a CRecordset-derived object.
void RFX_Text_Bulk(
CFieldExchange* pFX,
LPCTSTR szName,
LPSTR* prgStrVals,
long** prgLengths,
int nMaxLength);
pFX
A pointer to a CFieldExchange object. This object contains information to define the context for each call of the function. For more information, see the article Record Field Exchange: How RFX Works.
szName
The name of a data column.
prgStrVals
A pointer to an array of LPSTR values. This array will store the data to be transferred from the data source to the recordset. Note that with the current version of ODBC, these values cannot be Unicode.
prgLengths
A pointer to an array of long integers. This array will store the length in bytes of each value in the array pointed to by prgStrVals. This length excludes the null termination character. Note that the value SQL_NULL_DATA will be stored if the corresponding data item contains a Null value. For more details, see the ODBC API function SQLBindCol in the ODBC SDK Programmer's Reference.
nMaxLength
The maximum allowed length of the values stored in the array pointed to by prgStrVals, including the null termination character. To ensure that data will not be truncated, pass a value large enough to accommodate the largest data item you expect.
The data source column can have an ODBC type of SQL_LONGVARCHAR, SQL_CHAR, SQL_VARCHAR, SQL_DECIMAL, or SQL_NUMERIC. The recordset must define a field data member of type LPSTR.
If you initialize prgStrVals and prgLengths to NULL, then the arrays they point to will be allocated automatically, with sizes equal to the rowset size.
Note
Bulk record field exchange only transfers data from the data source to the recordset object. To make your recordset updateable, you must use the ODBC API function SQLSetPos.
For more information, see the articles Recordset: Fetching Records in Bulk (ODBC) and Record Field Exchange (RFX).
You must manually write calls in your DoBulkFieldExchange override. This example shows a call to RFX_Text_Bulk, as well as a call to RFX_Long_Bulk, for data transfer. These calls are preceded by a call to CFieldExchange::SetFieldType. Note that for parameters, you must call the RFX functions instead of the Bulk RFX functions.
void CMultiCustomer::DoBulkFieldExchange(CFieldExchange* pFX)
{
pFX->SetFieldType(CFieldExchange::outputColumn);
RFX_Long_Bulk(pFX, _T("[CustomerID]"), &m_pCustomerID, &m_pcCustomerID);
RFX_Text_Bulk(pFX, _T("[ContactFirstName]"), &m_pContactFirstName, &m_pcContactFirstName, 50);
RFX_Text_Bulk(pFX, _T("[PostalCode]"), &m_pPostalCode, &m_pcPostalCode, 50);
RFX_Text_Bulk(pFX, _T("[L_Name]"), &m_pL_Name, &m_pcL_Name, 50);
RFX_Long_Bulk(pFX, _T("[BillingID]"), &m_pBillingID, &m_pcBillingID);
pFX->SetFieldType(CFieldExchange::inputParam);
RFX_Text(pFX, _T("Param"), m_strParam);
}Header: afxdb.h
Transfers arrays of bytes between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_Binary(
CDaoFieldExchange* pFX,
LPCTSTR szName,
CByteArray& value,
int nPreAllocSize = AFX_DAO_BINARY_DEFAULT_SIZE,
DWORD dwBindOptions = 0);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type CByteArray, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
nPreAllocSize
The framework preallocates this amount of memory. If your data is larger, the framework will allocated more space as needed. For better performance, set this size to a value large enough to prevent reallocations. The default size is defined in the AFXDAO.H file as AFX_DAO_BINARY_DEFAULT_SIZE.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_DISABLE_FIELD_CACHE, does not use double buffering, and you must call SetFieldDirty and SetFieldNull yourself. The other possible value, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering, and you do not have to do extra work to mark fields dirty or Null. For performance and memory reasons, avoid this value unless your binary data is relatively small.
Note
You can control whether data is double buffered for all fields by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_BYTES in DAO and type CByteArray in the recordset.
See DFX_Text.
Header: afxdao.h
Transfers Boolean data between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_Bool(
CDaoFieldExchange* pFX,
LPCTSTR szName,
BOOL& value,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type BOOL, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_BOOL in DAO and type BOOL in the recordset.
See DFX_Text.
Header: afxdao.h
Transfers single bytes between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_Byte(
CDaoFieldExchange* pFX,
LPCTSTR szName,
BYTE& value,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type BYTE, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_BYTES in DAO and type BYTE in the recordset.
See DFX_Text.
Header: afxdao.h
Transfers currency data between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_Currency(
CDaoFieldExchange* pFX,
LPCTSTR szName,
COleCurrency& value,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, this value is taken from the specified data member, of type COleCurrency. For a transfer from data source to recordset, the value is stored in the specified data member.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_CURRENCY in DAO and type COleCurrency in the recordset.
See DFX_Text.
Header: afxdao.h
Transfers time and date data between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_DateTime(
CDaoFieldExchange* pFX,
LPCTSTR szName,
COleDateTime& value,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. The function takes a reference to a COleDateTime object. For a transfer from recordset to data source, this value is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_DATE in DAO and type COleDateTime in the recordset.
Note
COleDateTime replaces CTime and TIMESTAMP_STRUCT for this purpose in the DAO classes. CTime and TIMESTAMP_STRUCT are still used for the ODBC-based data access classes.
See DFX_Text.
Header: afxdao.h
Transfers double float data between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_Double(
CDaoFieldExchange* pFX,
LPCTSTR szName,
double& value,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type double, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_R8 in DAO and type double float in the recordset.
See DFX_Text.
Header: afxdao.h
Transfers long integer data between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_Long(
CDaoFieldExchange* pFX,
LPCTSTR szName,
long& value,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type long, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_I4 in DAO and type long in the recordset.
See DFX_Text.
Header: afxdao.h
Important It is recommended that you use DFX_Binary instead of this function.
void AFXAPI DFX_LongBinary(
CDaoFieldExchange* pFX,
LPCTSTR szName,
CLongBinary& value,
DWORD dwPreAllocSize = AFX_DAO_LONGBINARY_DEFAULT_SIZE,
DWORD dwBindOptions = 0);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type CLongBinary, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
dwPreAllocSize
The framework preallocates this amount of memory. If your data is larger, the framework will allocated more space as needed. For better performance, set this size to a value large enough to prevent reallocations.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DISABLE_FIELD_CACHE, does not use double buffering. The other possible value is AFX_DAO_ENABLE_FIELD_CACHE. Uses double buffering, and you do not have to do extra work to mark fields dirty or Null. For performance and memory reasons, avoid this value unless your binary data is relatively small.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
DFX_LongBinary is provided for compatibility with the MFC ODBC classes. The DFX_LongBinary function transfers binary large-object (BLOB) data using class CLongBinary between the field data members of a CDaoRecordset object and the columns of a record on the data source. Data is mapped between type DAO_BYTES in DAO and type CLongBinary in the recordset.
See DFX_Text.
Header: afxdao.h
Transfers short integer data between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_Short(
CDaoFieldExchange* pFX,
LPCTSTR szName,
short& value,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type short, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_I2 in DAO and type short in the recordset.
Note
DFX_Short is equivalent to RFX_Int for the ODBC-based classes.
See DFX_Text.
Header: afxdao.h
Transfers floating-point data between the field data members of a CDaoRecordset object and the columns of a record on the data source.
void AFXAPI DFX_Single(
CDaoFieldExchange* pFX,
LPCTSTR szName,
float& value,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type float, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_R4 in DAO and type float in the recordset.
See DFX_Text.
Header: afxdao.h
Transfers CString data between the field data members of a CDaoRecordset object and columns of a record on the data source.
void AFXAPI DFX_Text(
CDaoFieldExchange* pFX,
LPCTSTR szName,
CString& value,
int nPreAllocSize = AFX_DAO_TEXT_DEFAULT_SIZE,
DWORD dwBindOptions = AFX_DAO_ENABLE_FIELD_CACHE);
pFX
A pointer to an object of class CDaoFieldExchange. This object contains information to define the context for each call of the function.
szName
The name of a data column.
value
The value stored in the indicated data member — the value to be transferred. For a transfer from recordset to data source, the value, of type CString, is taken from the specified data member. For a transfer from data source to recordset, the value is stored in the specified data member.
nPreAllocSize
The framework preallocates this amount of memory. If your data is larger, the framework will allocated more space as needed. For better performance, set this size to a value large enough to prevent reallocations.
dwBindOptions
An option that lets you take advantage of MFC's double buffering mechanism for detecting recordset fields that have changed. The default, AFX_DAO_ENABLE_FIELD_CACHE, uses double buffering. The other possible value is AFX_DAO_DISABLE_FIELD_CACHE. If you specify this value, MFC does no checking on this field. You must call SetFieldDirty and SetFieldNull yourself.
Note
You can control whether data is double buffered by default by setting CDaoRecordset::m_bCheckCacheForDirtyFields.
Data is mapped between type DAO_CHAR in DAO (or, if the symbol _UNICODE is defined, DAO_WCHAR) and type CString in the recordset. n
This example shows several calls to DFX_Text. Notice also the two calls to CDaoFieldExchange::SetFieldType. You must write the first call to SetFieldType and its DFX call. The second call and its associated DFX calls are normally written by the code wizard that generated the class.
void CCustSet::DoFieldExchange(CDaoFieldExchange* pFX)
{
pFX->SetFieldType(CDaoFieldExchange::param);
DFX_Text(pFX, _T("Param"), m_strParam);
pFX->SetFieldType(CDaoFieldExchange::outputColumn);
DFX_Short(pFX, _T("EmployeeID"), m_EmployeeID);
DFX_Text(pFX, _T("LastName"), m_LastName);
DFX_Short(pFX, _T("Age"), m_Age);
DFX_DateTime(pFX, _T("hire_date"), m_hire_date);
DFX_DateTime(pFX, _T("termination_date"), m_termination_date);
CDaoRecordset::DoFieldExchange(pFX);
}Header: afxdao.h
Macros and Globals
CRecordset::DoFieldExchange
CRecordset::DoBulkFieldExchange
CDaoRecordset::DoFieldExchange