CDynamicParameterAccessor Class
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
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