| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CDynamicAccessor Class |
CDynamicAccessor Class |
11/04/2016 |
|
|
374b13b7-1f09-457d-9e6b-df260ff4d178 |
Allows you to access a data source when you have no knowledge of the database schema (the database's underlying structure).
class CDynamicAccessor : public CAccessorBaseHeader: atldbcli.h
| Name | Description |
|---|---|
| AddBindEntry | Adds a bind entry to the output columns when overriding the default accessor. |
| CDynamicAccessor | Instantiates and initializes the CDynamicAccessor object. |
| Close | Unbinds all the columns, releases the allocated memory, and releases the IAccessor interface pointer in the class. |
| GetBlobHandling | Retrieves the BLOB handling value for the current row. |
| GetBlobSizeLimit | Retrieves the maximum BLOB size in bytes. |
| GetBookmark | Retrieves the bookmark for the current row. |
| GetColumnCount | Retrieves the number of columns in the rowset. |
| GetColumnFlags | Retrieves the column characteristics. |
| GetColumnInfo | Retrieves the column metadata. |
| GetColumnName | Retrieves the name of a specified column. |
| GetColumnType | Retrieves the data type of a specified column. |
| GetLength | Retrieves the maximum possible length of a column in bytes. |
| GetOrdinal | Retrieves the column index given a column name. |
| GetStatus | Retrieves the status of a specified column. |
| GetValue | Retrieves the data from the buffer. |
| SetBlobHandling | Sets the BLOB handling value for the current row. |
| SetBlobSizeLimit | Sets the maximum BLOB size in bytes. |
| SetLength | Sets the length of the column in bytes. |
| SetStatus | Sets the status of a specified column. |
| SetValue | Stores the data to the buffer. |
Use CDynamicAccessor methods to obtain column information such as column names, column count, data type, and so on. You then use this column information to create an accessor dynamically at run time.
The column information is stored in a buffer that is created and managed by this class. Obtain data from the buffer using GetValue.
For a discussion and examples of using the dynamic accessor classes, see Using Dynamic Accessors.
Adds a bind entry to the output columns.
HRESULT AddBindEntry(const DBCOLUMNINFO& info) throw();info
[in] A DBCOLUMNINFO structure containing column information. See "DBCOLUMNINFO Structures" in IColumnsInfo::GetColumnInfo in the OLE DB Programmer's Reference.
One of the standard HRESULT values.
Use this method when overriding the default accessor created with CDynamicAccessor (see How Do I Fetch Data?).
Instantiates and initializes the CDynamicAccessor object.
CDynamicAccessor(DBBLOBHANDLINGENUM eBlobHandling = DBBLOBHANDLING_DEFAULT,
DBLENGTH nBlobSize = 8000);eBlobHandling
Specifies how the binary large object (BLOB) data is to be handled. The default value is DBBLOBHANDLING_DEFAULT. See SetBlobHandling for a description of the DBBLOBHANDLINGENUM values.
nBlobSize
The maximum BLOB size in bytes; column data over this value is treated as a BLOB. The default value is 8,000. See SetBlobSizeLimit for details.
If you use the constructor to initialize the CDynamicAccessor object, you can specify how it will bind BLOBs. BLOBs can contain binary data such as graphics, sound, or compiled code. The default behavior is to treat columns more than 8,000 bytes as BLOBs and try to bind them to an ISequentialStream object. However, you can specify a different value to be the BLOB size.
You can also specify how CDynamicAccessor handles column data that qualifies as BLOB data: it can handle BLOB data in the default manner; it can skip (does not bind) BLOB data; or it can bind BLOB data in provider-allocated memory.
Unbinds all the columns, releases the allocated memory, and releases the IAccessor interface pointer in the class.
void Close() throw();Retrieves the BLOB handling value for the current row.
const DBBLOBHANDLINGENUM GetBlobHandling() const;Returns the BLOB handling value eBlobHandling as set by SetBlobHandling.
Retrieves the maximum BLOB size in bytes.
const DBLENGTH GetBlobSizeLimit() const;Returns the BLOB handling value nBlobSize as set by SetBlobSizeLimit.
Retrieves the bookmark for the current row.
HRESULT GetBookmark(CBookmark< >* pBookmark) const throw();pBookmark
[out] A pointer to the CBookmark object.
One of the standard HRESULT values.
You need to set DBPROP_IRowsetLocate to VARIANT_TRUE to retrieve a bookmark.
Retrieves the number of columns.
DBORDINAL GetColumnCount() const throw();The number of columns retrieved.
Retrieves the column characteristics.
bool GetColumnFlags(DBORDINAL nColumn,
DBCOLUMNFLAGS* pFlags) const throw();nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
pFlags
[out] A pointer to a bitmask that describes column characteristics. See "DBCOLUMNFLAGS Enumerated Type" in IColumnsInfo::GetColumnInfo in the OLE DB Programmer's Reference.
Returns true if the column characteristics are successfully retrieved. Otherwise, it returns false.
The column number is offset from one. Column zero is a special case; it is the bookmark if available.
Returns the column metadata needed by most consumers.
HRESULT GetColumnInfo(IRowset* pRowset,
DBORDINAL* pColumns,
DBCOLUMNINFO** ppColumnInfo,
OLECHAR** ppStringsBuffer) throw();pRowset
[in] A pointer to the IRowset interface.
pColumns
[out] A pointer to memory in which to return the number of columns in the rowset; this number includes the bookmark column, if there is one.
ppColumnInfo
[out] A pointer to memory in which to return an array of DBCOLUMNINFO structures. See "DBCOLUMNINFO Structures" in IColumnsInfo::GetColumnInfo in the OLE DB Programmer's Reference.
ppStringsBuffer
[out] A pointer to memory in which to return a pointer to storage for all string values (names used either within columnid or for pwszName) within a single allocation block.
One of the standard HRESULT values.
See IColumnsInfo::GetColumnInfo in the OLE DB Programmer's Reference for information on the data types DBORDINAL, DBCOLUMNINFO, and OLECHAR.
Retrieves the name of the specified column.
LPOLESTR GetColumnName(DBORDINAL nColumn) const throw();nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
The name of the specified column.
Retrieves the data type of a specified column.
bool GetColumnType(DBORDINAL nColumn,
DBTYPE* pType) const throw();nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
pType
[out] A pointer to the data type of the specified column.
Returns true on success or false on failure.
Retrieves the length of the specified column.
bool GetLength(DBORDINAL nColumn,
DBLENGTH* pLength) const throw();
bool GetLength(const CHAR* pColumnName,
DBLENGTH* pLength) const throw();
bool GetLength(const WCHAR* pColumnName,
DBLENGTH* pLength) const throw();nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
pColumnName
[in] A pointer to a character string containing the column name.
pLength
[out] A pointer to the integer containing the length of the column in bytes.
Returns true if the specified column is found. Otherwise, this function returns false.
The first override takes the column number, and the second and third overrides take the column name in ANSI or Unicode format, respectively.
Retrieves the column number given a column name.
bool GetOrdinal(const CHAR* pColumnName,
DBORDINAL* pOrdinal) const throw();
bool GetOrdinal(const WCHAR* pColumnName,
DBORDINAL* pOrdinal) const throw();pColumnName
[in] A pointer to a character string containing the column name.
pOrdinal
[out] A pointer to the column number.
Returns true if a column with the specified name is found. Otherwise, this function returns false.
Retrieves the status of the specified column.
bool GetStatus(DBORDINAL nColumn,
DBSTATUS* pStatus) const throw();
bool GetStatus(const CHAR* pColumnName,
DBSTATUS* pStatus) const throw();
bool GetStatus(const WCHAR* pColumnName,
DBSTATUS* pStatus) const throw();nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
pColumnName
[in] A pointer to a character string containing the column name.
pStatus
[out] A pointer to the variable containing the column status. See DBSTATUS in the OLE DB Programmer's Reference for more information.
Returns true if the specified column is found. Otherwise, this function returns false.
Retrieves the data for a specified column.
void* GetValue(DBORDINAL nColumn) const throw();
void* GetValue(const CHAR* pColumnName) const throw();
void* GetValue(const WCHAR* pColumnName) const throw();
template < class ctype >
bool GetValue(DBORDINAL nColumn, ctype* pData) const throw();
template < class ctype >
bool GetValue(const CHAR* pColumnName, ctype* pData) const throw();
template < class ctype >
bool GetValue(const WCHAR* pColumnName, ctype* pData) const throw();ctype
[in] A templated parameter that handles any data type except string types (CHAR*, WCHAR*), which require special handling. GetValue uses the appropriate data type based on what you specify here.
nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
pColumnName
[in] The column name.
pData
[out] The pointer to the contents of the specified column.
If you want to pass string data, use the nontemplated versions of GetValue. The nontemplated versions of this method return void*, which points to the part of the buffer that contains the specified column data. Returns NULL if the column is not found.
For all other data types, it is simpler to use the templated versions of GetValue. The templated versions return true on success or false on failure.
Use the nontemplated versions to return columns that contain strings and the templated versions for columns that contain other data types.
In debug mode, you will get an assertion if the size of pData is unequal to the size of the column to which it points.
Sets the BLOB handling value for the current row.
bool SetBlobHandling(DBBLOBHANDLINGENUM eBlobHandling);eBlobHandling
Specifies how the BLOB data is to be handled. It can take the following values:
-
DBBLOBHANDLING_DEFAULT: Handle column data larger than nBlobSize (as set by
SetBlobSizeLimit) as BLOB data and retrieve it through anISequentialStreamorIStreamobject. This option will attempt to bind every column containing data larger than nBlobSize or listed as DBTYPE_IUNKNOWN as BLOB data. -
DBBLOBHANDLING_NOSTREAMS: Handle column data larger than nBlobSize (as set by
SetBlobSizeLimit) as BLOB data and retrieve it through reference in provider-allocated, consumer-owned memory. This option is useful for tables that have more than one BLOB column, and the provider supports only oneISequentialStreamobject per accessor. -
DBBLOBHANDLING_SKIP: Skip (do not bind) columns qualifying as containing BLOBs (the accessor will not bind or retrieve the column value but it will still retrieve the column status and length).
You should call SetBlobHandling before calling Open.
The constructor method CDynamicAccessor sets the BLOB handling value to DBBLOBHANDLING_DEFAULT.
Sets the maximum BLOB size in bytes.
void SetBlobSizeLimit(DBLENGTH nBlobSize);nBlobSize
Specifies the BLOB size limit.
Sets the maximum BLOB size in bytes; column data larger than this value is treated as a BLOB. Some providers give extremely large sizes for columns (such as 2 GB). Rather than attempting to allocate memory for a column this size, you would typically try to bind these columns as BLOBs. In that way you don't have to allocate all the memory, but you can still read all the data without fear of truncation. However, there are some cases in which you might want to force CDynamicAccessor to bind large columns in their native data types. To do this, call SetBlobSizeLimit before calling Open.
The constructor method CDynamicAccessor sets the maximum BLOB size to a default value of 8,000 bytes.
Sets the length of the specified column.
bool SetLength(DBORDINAL nColumn,
DBLENGTH nLength)throw();
bool SetLength(const CHAR* pColumnName,
DBLENGTH nLength) throw();
bool SetLength(const WCHAR* pColumnName,
DBLENGTH nLength) throw();nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
nLength
[in] The length of the column in bytes.
pColumnName
[in] A pointer to a character string containing the column name.
Returns true if the specified column length is set successfully. Otherwise, this function returns false.
Sets the status of the specified column.
bool SetStatus(DBORDINAL nColumn,
DBSTATUS status)throw();
bool SetStatus(const CHAR* pColumnName,
DBSTATUS status) throw();
bool SetStatus(const WCHAR* pColumnName,
DBSTATUS status) throw();nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
status
[in] The column status. See DBSTATUS in the OLE DB Programmer's Reference for more information.
pColumnName
[in] A pointer to a character string containing the column name.
Returns true if the specified column status is set successfully. Otherwise, this function returns false.
Stores data to a specified column.
template <class ctype>
bool SetValue(
DBORDINAL nColumn,
constctype& data) throw( );
template <class ctype>
bool SetValue(
const CHAR * pColumnName,
const ctype& data) throw( );
template <class ctype>
bool SetValue(
const WCHAR *pColumnName,
const ctype& data) throw( );ctype
[in] A templated parameter that handles any data type except string types (CHAR*, WCHAR*), which require special handling. GetValue uses the appropriate data type based on what you specify here.
pColumnName
[in] A pointer to a character string containing the column name.
data
[in] The pointer to the memory containing the data.
nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
If you want to set string data, use the nontemplated versions of GetValue. The nontemplated versions of this method return void*, which points to the part of the buffer that contains the specified column data. Returns NULL if the column is not found.
For all other data types, it is simpler to use the templated versions of GetValue. The templated versions return true on success or false on failure.
OLE DB Consumer Templates
OLE DB Consumer Templates Reference
CAccessor Class
CDynamicParameterAccessor Class
CManualAccessor Class