CDynamicAccessor Class
Allows you to access a data source when you have no knowledge of the database schema (the database's underlying structure).
Syntax
class CDynamicAccessor : public CAccessorBase
Requirements
Header: atldbcli.h
Members
Methods
| 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. |
Remarks
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.
CDynamicAccessor::AddBindEntry
Adds a bind entry to the output columns.
Syntax
HRESULT AddBindEntry(const DBCOLUMNINFO& info) throw();
Parameters
info
[in] A DBCOLUMNINFO structure containing column information. See "DBCOLUMNINFO Structures" in IColumnsInfo::GetColumnInfo in the OLE DB Programmer's Reference.
Return Value
One of the standard HRESULT values.
Remarks
Use this method when overriding the default accessor created with CDynamicAccessor (see How Do I Fetch Data?).
CDynamicAccessor::CDynamicAccessor
Instantiates and initializes the CDynamicAccessor object.
Syntax
CDynamicAccessor(DBBLOBHANDLINGENUM eBlobHandling = DBBLOBHANDLING_DEFAULT,
DBLENGTH nBlobSize = 8000);
Parameters
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.
Remarks
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.
CDynamicAccessor::Close
Unbinds all the columns, releases the allocated memory, and releases the IAccessor interface pointer in the class.
Syntax
void Close() throw();
CDynamicAccessor::GetBlobHandling
Retrieves the BLOB handling value for the current row.
Syntax
const DBBLOBHANDLINGENUM GetBlobHandling() const;
Remarks
Returns the BLOB handling value eBlobHandling as set by SetBlobHandling.
CDynamicAccessor::GetBlobSizeLimit
Retrieves the maximum BLOB size in bytes.
Syntax
const DBLENGTH GetBlobSizeLimit() const;
Remarks
Returns the BLOB handling value nBlobSize as set by SetBlobSizeLimit.
CDynamicAccessor::GetBookmark
Retrieves the bookmark for the current row.
Syntax
HRESULT GetBookmark(CBookmark< >* pBookmark) const throw();
Parameters
pBookmark
[out] A pointer to the CBookmark object.
Return Value
One of the standard HRESULT values.
Remarks
You need to set DBPROP_IRowsetLocate to VARIANT_TRUE to retrieve a bookmark.
CDynamicAccessor::GetColumnCount
Retrieves the number of columns.
Syntax
DBORDINAL GetColumnCount() const throw();
Return Value
The number of columns retrieved.
CDynamicAccessor::GetColumnFlags
Retrieves the column characteristics.
Syntax
bool GetColumnFlags(DBORDINAL nColumn,
DBCOLUMNFLAGS* pFlags) const throw();
Parameters
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.
Return Value
Returns true if the column characteristics are successfully retrieved. Otherwise, it returns false.
Remarks
The column number is offset from one. Column zero is a special case; it is the bookmark if available.
CDynamicAccessor::GetColumnInfo
Returns the column metadata needed by most consumers.
Syntax
HRESULT GetColumnInfo(IRowset* pRowset,
DBORDINAL* pColumns,
DBCOLUMNINFO** ppColumnInfo,
OLECHAR** ppStringsBuffer) throw();
Parameters
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.
Return Value
One of the standard HRESULT values.
Remarks
See IColumnsInfo::GetColumnInfo in the OLE DB Programmer's Reference for information on the data types DBORDINAL, DBCOLUMNINFO, and OLECHAR.
CDynamicAccessor::GetColumnName
Retrieves the name of the specified column.
Syntax
LPOLESTR GetColumnName(DBORDINAL nColumn) const throw();
Parameters
nColumn
[in] The column number. Column numbers start with 1. A value of 0 refers to the bookmark column, if any.
Return Value
The name of the specified column.
CDynamicAccessor::GetColumnType
Retrieves the data type of a specified column.
Syntax
bool GetColumnType(DBORDINAL nColumn,
DBTYPE* pType) const throw();
Parameters
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.
Return Value
Returns true on success or false on failure.
CDynamicAccessor::GetLength
Retrieves the length of the specified column.
Syntax
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();
Parameters
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.
Return Value
Returns true if the specified column is found. Otherwise, this function returns false.
Remarks
The first override takes the column number, and the second and third overrides take the column name in ANSI or Unicode format, respectively.
CDynamicAccessor::GetOrdinal
Retrieves the column number given a column name.
Syntax
bool GetOrdinal(const CHAR* pColumnName,
DBORDINAL* pOrdinal) const throw();
bool GetOrdinal(const WCHAR* pColumnName,
DBORDINAL* pOrdinal) const throw();
Parameters
pColumnName
[in] A pointer to a character string containing the column name.
pOrdinal
[out] A pointer to the column number.
Return Value
Returns true if a column with the specified name is found. Otherwise, this function returns false.
CDynamicAccessor::GetStatus
Retrieves the status of the specified column.
Syntax
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();
Parameters
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.
Return Value
Returns true if the specified column is found. Otherwise, this function returns false.
CDynamicAccessor::GetValue
Retrieves the data for a specified column.
Syntax
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();
Parameters
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.
Return Value
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.
Remarks
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.
CDynamicAccessor::SetBlobHandling
Sets the BLOB handling value for the current row.
Syntax
bool SetBlobHandling(DBBLOBHANDLINGENUM eBlobHandling);
Parameters
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).
Remarks
You should call SetBlobHandling before calling Open.
The constructor method CDynamicAccessor sets the BLOB handling value to DBBLOBHANDLING_DEFAULT.
CDynamicAccessor::SetBlobSizeLimit
Sets the maximum BLOB size in bytes.
Syntax
void SetBlobSizeLimit(DBLENGTH nBlobSize);
Parameters
nBlobSize
Specifies the BLOB size limit.
Remarks
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.
CDynamicAccessor::SetLength
Sets the length of the specified column.
Syntax
bool SetLength(DBORDINAL nColumn,
DBLENGTH nLength)throw();
bool SetLength(const CHAR* pColumnName,
DBLENGTH nLength) throw();
bool SetLength(const WCHAR* pColumnName,
DBLENGTH nLength) throw();
Parameters
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.
Return Value
Returns true if the specified column length is set successfully. Otherwise, this function returns false.
CDynamicAccessor::SetStatus
Sets the status of the specified column.
Syntax
bool SetStatus(DBORDINAL nColumn,
DBSTATUS status)throw();
bool SetStatus(const CHAR* pColumnName,
DBSTATUS status) throw();
bool SetStatus(const WCHAR* pColumnName,
DBSTATUS status) throw();
Parameters
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.
Return Value
Returns true if the specified column status is set successfully. Otherwise, this function returns false.
CDynamicAccessor::SetValue
Stores data to a specified column.
Syntax
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( );
Parameters
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.
Return Value
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.
See also
OLE DB Consumer Templates
OLE DB Consumer Templates Reference
CAccessor Class
CDynamicParameterAccessor Class
CManualAccessor Class
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for