Edit

Share via

CDynamicParameterAccessor Class

  • Article

Similar to CDynamicAccessor but obtains parameter information to be set by calling the ICommandWithParameters interface.

Syntax

class CDynamicParameterAccessor : public CDynamicAccessor

Requirements

Header: atldbcli.h

Members

Methods

Name Description
CDynamicParameterAccessor The constructor.
GetParam Retrieves the parameter data from the buffer.
GetParamCount Retrieves the number of parameters in the accessor.
GetParamIO Determines whether the specified parameter is an input or output parameter.
GetParamLength Retrieves the length of the specified parameter stored in the buffer.
GetParamName Retrieves the name of a specified parameter.
GetParamStatus Retrieves the status of the specified parameter stored in the buffer.
GetParamString Retrieves the string data of the specified parameter stored in the buffer.
GetParamType Retrieves the data type of a specified parameter.
SetParam Sets the buffer using the parameter data.
SetParamLength Sets the length of the specified parameter stored in the buffer.
SetParamStatus Sets the status of the specified parameter stored in the buffer.
SetParamString Sets the string data of the specified parameter stored in the buffer.

Remarks

The provider must support ICommandWithParameters for the consumer to use this class.

The parameter information is stored in a buffer created and managed by this class. Obtain parameter data from the buffer by using GetParam and GetParamType.

For an example demonstrating how to use this class to execute a SQL Server stored procedure and get the output parameter values, see the DynamicConsumer sample code in the Microsoft VCSamples repository on GitHub.

CDynamicParameterAccessor::CDynamicParameterAccessor

The constructor.

Syntax

typedef CDynamicParameterAccessor _ParamClass;
CDynamicParameterAccessor(
   DBBLOBHANDLINGENUM eBlobHandling = DBBLOBHANDLING_DEFAULT,
   DBLENGTH nBlobSize = 8000 )
   : CDynamicAccessor(eBlobHandling, nBlobSize )

Parameters

eBlobHandling
Specifies how the BLOB data is to be handled. The default value is DBBLOBHANDLING_DEFAULT. See CDynamicAccessor::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 CDynamicAccessor::SetBlobSizeLimit for details.

Remarks

See the CDynamicAccessor::CDynamicAccessor constructor for more information on BLOB handling.

CDynamicParameterAccessor::GetParam

Retrieves the nonstring data for a specified parameter from the parameter buffer.

Syntax

template <class ctype>bool GetParam(DBORDINAL nParam,
   ctype* pData) const throw();

template <class ctype> bool GetParam(TCHAR* pParamName,
   ctype* pData) const throw();

void* GetParam(DBORDINAL nParam) const throw();

void* GetParam(TCHAR* pParamName) const throw();

Parameters

ctype
A templated parameter that is the data type.

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

pParamName
[in] The parameter name.

pData
[out] The pointer to the memory containing the data retrieved from the buffer.

Return Value

For nontemplated versions, points to the memory containing the data retrieved from the buffer. For templated versions, returns true on success or false on failure.

Use GetParam to retrieve nonstring parameter data from the buffer. Use GetParamString to retrieve string parameter data from the buffer.

CDynamicParameterAccessor::GetParamCount

Retrieves the number of parameters stored in the buffer.

Syntax

DB_UPARAMS GetParamCount() const throw();

Return Value

The number of parameters.

CDynamicParameterAccessor::GetParamIO

Determines whether the specified parameter is an input or output parameter.

Syntax

bool GetParamIO(DBORDINAL nParam,
   DBPARAMIO* pParamIO) const throw();

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

pParamIO
A pointer to the variable containing the DBPARAMIO type (input or output) of the specified parameter. It is defined as follows:

typedef DWORD DBPARAMIO;

enum DBPARAMIOENUM {
    DBPARAMIO_NOTPARAM   = 0,
    DBPARAMIO_INPUT      = 0x1,
    DBPARAMIO_OUTPUT     = 0x2
};

Return Value

Returns true on success or false on failure.

CDynamicParameterAccessor::GetParamLength

Retrieves the length of the specified parameter stored in the buffer.

Syntax

bool GetParamLength(DBORDINAL nParam,
   DBLENGTH* pLength);

DBLENGTH* GetParamLength(DBORDINAL nParam) const throw();

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

pLength
[out] A pointer to the variable containing the length in bytes of the specified parameter.

Remarks

The first override returns true on success or false on failure. The second override points to the memory containing the length of the parameter.

CDynamicParameterAccessor::GetParamName

Retrieves the name of the specified parameter.

Syntax

LPOLESTR GetParamName(DBORDINAL nParam) const throw();

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

Return Value

The name of the specified parameter.

CDynamicParameterAccessor::GetParamStatus

Retrieves the status of the specified parameter stored in the buffer.

Syntax

bool GetParamStatus(DBORDINAL nParam,
   DBSTATUS* pStatus);

DBSTATUS* GetParamStatus(DBORDINAL nParam) const throw();

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

pStatus
[out] A pointer to the variable containing the DBSTATUS status of the specified parameter. For information on DBSTATUS values, see Status in the OLE DB Programmer's Reference, or search for DBSTATUS in oledb.h.

Remarks

The first override returns true on success or false on failure. The second override points to the memory containing the status of the specified parameter.

CDynamicParameterAccessor::GetParamString

Retrieves the string data of the specified parameter stored in the buffer.

Syntax

bool GetParamString(DBORDINAL nParam,
   CSimpleStringA& strOutput) throw();

bool GetParamString(DBORDINAL nParam,
   CSimpleStringW& strOutput) throw();

bool GetParamString(DBORDINAL nParam,
   CHAR* pBuffer,
   size_t* pMaxLen) throw();

bool GetParamString(DBORDINAL nParam,
   WCHAR* pBuffer,
   size_t* pMaxLen) throw();

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

strOutput
[out] The ANSI (CSimpleStringA) or Unicode (CSimpleStringW) string data of the specified parameter. You should pass a parameter of type CString, for example:

CString MyString;
rs.GetParamString(1, MyString);

pBuffer
[out] A pointer to the ANSI (CHAR) or Unicode (WCHAR) string data of the specified parameter.

pMaxLen
[out] A pointer to the size of the buffer pointed to by pBuffer (in characters, including the terminating NULL).

Remarks

Returns true on success or false on failure.

If pBuffer is NULL, this method will set the required buffer size in the memory pointed to by pMaxLen and return true without copying the data.

This method will fail if the buffer pBuffer is not large enough to contain the whole string.

Use GetParamString to retrieve string parameter data from the buffer. Use GetParam to retrieve nonstring parameter data from the buffer.

CDynamicParameterAccessor::GetParamType

Retrieves the data type of a specified parameter.

Syntax

bool GetParamType(DBORDINAL nParam,
   DBTYPE* pType) const throw();

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

pType
[out] A pointer to the variable containing the data type of the specified parameter.

Return Value

Returns true on success or false on failure.

CDynamicParameterAccessor::SetParam

Sets the parameter buffer using the specified (non-string) data.

Syntax

template <class ctype>
bool SetParam(DBORDINAL nParam,
   constctype* pData,
   DBSTATUS status = DBSTATUS_S_OK) throw();

template <class ctype>
bool SetParam(TCHAR* pParamName,
   const ctype* pData,
   DBSTATUS status = DBSTATUS_S_OK) throw();

Parameters

ctype
A templated parameter that is the data type.

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. For example:

WCHAR* wszSQL = L"SELECT * FROM Authors WHERE State='?' AND LName='?'";

CCommand<CDynamicParameterAccessor> rs;
//...
rs.SetParam<LONG>(1, &m_BillingID);
rs.SetParam<CString>(2, &m_strFirstName);

pParamName
[in] The parameter name.

pData
[in] The pointer to the memory containing the data to be written to the buffer.

status
[in] The DBSTATUS column status. For information on DBSTATUS values, see Status in the OLE DB Programmer's Reference, or search for DBSTATUS in oledb.h.

Return Value

Returns true on success or false on failure.

Use SetParam to set nonstring parameter data in the buffer. Use SetParamString to set string parameter data in the buffer.

CDynamicParameterAccessor::SetParamLength

Sets the length of the specified parameter stored in the buffer.

Syntax

bool SetParamLength(DBORDINAL nParam,
   DBLENGTH length);

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

length
[in] The length in bytes of the specified parameter.

Remarks

Returns true on success or false on failure.

CDynamicParameterAccessor::SetParamStatus

Sets the status of the specified parameter stored in the buffer.

Syntax

bool SetParamStatus(DBORDINAL nParam,
   DBSTATUS status);

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

status
[in] The DBSTATUS status of the specified parameter. For information on DBSTATUS values, see Status in the OLE DB Programmer's Reference, or search for DBSTATUS in oledb.h.

Remarks

Returns true on success or false on failure.

CDynamicParameterAccessor::SetParamString

Sets the string data of the specified parameter stored in the buffer.

Syntax

bool SetParamString(DBORDINAL nParam,
   constCHAR* pString,
   DBSTATUS status = DBSTATUS_S_OK) throw();bool SetParamString(DBORDINAL nParam,
   constWCHAR* pString,
   DBSTATUS status = DBSTATUS_S_OK) throw();

Parameters

nParam
[in] The parameter number (offset from 1). Parameter 0 is reserved for return values. The parameter number is the index of the parameter based on its order in the SQL or stored procedure call. See SetParam for an example.

pString
[in] A pointer to the ANSI (CHAR) or Unicode (WCHAR) string data of the specified parameter. See DBSTATUS in oledb.h.

status
[in] The DBSTATUS status of the specified parameter. For information on DBSTATUS values, see Status in the OLE DB Programmer's Reference, or search for DBSTATUS in oledb.h.

Remarks

Returns true on success or false on failure.

SetParamString will fail if you try to set a string that is larger than the maximum size specified for pString.

Use SetParamString to set string parameter data in the buffer. Use SetParam to set nonstring parameter data in the buffer.

See also

OLE DB Consumer Templates
OLE DB Consumer Templates Reference
CAccessor Class
CDynamicAccessor Class
CManualAccessor Class