Edit

Share via

CDynamicAccessor Class

  • Article

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 an ISequentialStream or IStream object. 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 one ISequentialStream object 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