Specifies the native data type of each parameter.
HRESULT SetParameterInfo (
ULONG cParams,
const ULONG rgParamOrdinals[],
const DBPARAMBINDINFO rgParamBindInfo[]);
Parameters
cParams
[in]
The number of parameters for which to set type information. If cParams is zero, the type information for all parameters is discarded, and rgParamOrdinals and rgParamBindInfo are ignored.
rgParamOrdinals
[in]
An array of cParams ordinals. These are the ordinals of the parameters for which to set type information. Type information for parameters whose ordinals are not specified is not affected.
rgParamBindInfo
[in]
An array of cParams DBPARAMBINDINFO structures. If rgParamBindInfo is a null pointer, then the type information for the parameters specified by the ordinals in rgParamOrdinals is discarded.
The DBPARAMBINDINFO structure is:
typedef struct tagDBPARAMBINDINFO {
LPOLESTR pwszDataSourceType;
LPOLESTR pwszName;
ULONG ulParamSize;
DBPARAMFLAGS dwFlags;
BYTE bPrecision;
BYTE bScale;
} DBPARAMBINDINFO;
The elements of this structure are used as follows.
| Element | Description |
| pwszDataSourceType | A pointer to the provider-specific name of the parameter’s data type or a standard data type name. This name is not returned by GetParameterInfo; instead, the provider maps the data type specified by this name to an OLE DB type indicator and returns that type indicator. For a list of standard data type names, see ""Comments."" If pwszDataSourceType is null, the provider attempts a default conversion from the data type specified in the binding for the parameter, or returns E_INVALIDARG if it cannot perform default parameter conversions. |
| pwszName | The name of the parameter. This is a null pointer if the parameter does not have a name. The consumer must specify a name for all or none of the parameters set at any time. If the provider does not support named parameters, this argument is ignored and the provider is not required to verify that all or none of the parameters are named. |
| ulParamSize | The maximum possible length of a value in the parameter. For parameters that use a fixed-length data type, this is the size of the data type. For parameters that use a variable-length data type, this is one of the following:
For data types that do not have a length, this is set to ~0 (bitwise, the value is not 0; that is, all bits are set to 1). This argument is ignored if pwszDataSourceType is null. |
| dwFlags | See the dwFlags element of the DBPARAMINFO structure in GetParameterInfo. |
| bPrecision | If pwszDataSourceType is a numeric type, bPrecision is the maximum number of digits, expressed in base 10. Otherwise, it is ignored. This argument is ignored if pwszDataSourceType is null. |
| bScale | If pwszDataSourceType is a numeric type with a fixed scale, bScale is the number of digits to the right (if bScale is positive) or left (if bScale is negative) of the decimal point. Otherwise, it is ignored. This argument is ignored if pwszDataSourceType is null. |
Return Code
S_OK
The method succeeded.
DB_S_TYPEINFOOVERRIDDEN
The provider was capable of deriving the parameter type information and SetParameterInfo was called. The parameter type information specified in SetParameterInfo was used.
SetParameterInfo replaced parameter type information specified in a previous call to SetParameterInfo.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
cParams was not zero and rgParamOrdinals was a null pointer.
An element of rgParamOrdinals was zero.
In an element of rgParamBindInfo, the pwszDataSourceType element was a null pointer, and the provider does not support default parameter conversions.
In an element of rgParamBindInfo, the dwFlags element was invalid.
DB_E_BADPARAMETERNAME
In an element of rgParamBindInfo, the pwszName element specified an invalid parameter name. The provider does not check whether the name was correct for the specified parameter, just whether it was a valid parameter name.
In one or more elements of rgParamBindInfo, but not all, pwszName was null.
In one or more elements of rgParamBindInfo, pwszName was null and one or more parameters previously set and not overridden were specified with a non-null pwszName.
In one or more elements of rgParamBindInfo, pwszName was non-null and one or more parameters previously set and not overridden were specified with a null pwszName.
DB_E_BADTYPENAME
In an element of rgParamBindInfo, the pwszDataSourceType element specified an invalid data type name. The provider does not check whether the data type was correct for the specified parameter, just whether it was a data type name supported by the provider.
DB_E_OBJECTOPEN
A rowset was open on the command.
Comments
Providers generally derive parameter type information from the data source and return it to the consumer through GetParameterInfo. Consumers then use this information to build parameter accessors for use with ICommand::Execute.
Some providers—notably many SQL database providers—cannot derive parameter type information from the data source. For these providers, the consumer must supply the native parameter type information through SetParameterInfo. The provider uses the type information specified by SetParameterInfo to determine how to convert parameter data from the type supplied by the consumer (as indicated by the wType value in the binding structure) to the native type used by the data source. When the consumer specifies a data type with known precision, scale, and size values, any information supplied by the consumer for precision, scale, or size should be ignored by the provider.
The information that the consumer supplies must be correct and must be supplied for all parameters. Providers that cannot derive parameter type information cannot verify the supplied information against the parameter metadata, although they can determine that the specified values are legal values for the provider. Such providers sometimes cannot even determine the number of parameters in the command. The result of executing a command using incorrect parameter information or passing parameter information for the wrong number of parameters is undefined. For example, if the parameter type is LONG and the consumer specifies a type indicator of DBTYPE_STR in SetParameterInfo, the provider converts the data to a string before sending it to the data source. Because the data source is expecting a LONG, this will likely result in an error.
When the consumer calls SetParameterInfo, it specifies a provider-specific data type name (as derived from the PROVIDER_TYPES schema rowset) or a standard type name. If the consumer passes a standard type name, the provider maps it to a provider-specific type name. For example, a provider for an SQL DBMS might map ""DBTYPE_I2"" to ""SMALLINT"".
The following is a list of standard type names and their associated type indicators. This list contains many commonly known types. Individual providers may allow other, provider-specific names as well.
| Standard type name | Type indicator |
| ""DBTYPE_I1"" | DBTYPE_I1 |
| "DBTYPE_I2" | DBTYPE_I2 |
| "DBTYPE_I4" | DBTYPE_I4 |
| "DBTYPE_I8" | DBTYPE_I8 |
| "DBTYPE_UI1" | DBTYPE_UI1 |
| "DBTYPE_UI2" | DBTYPE_UI2 |
| "DBTYPE_UI4" | DBTYPE_UI4 |
| "DBTYPE_UI8" | DBTYPE_UI8 |
| "DBTYPE_R4" | DBTYPE_R4 |
| "DBTYPE_R8" | DBTYPE_R8 |
| "DBTYPE_CY" | DBTYPE_CY |
| "DBTYPE_DECIMAL" | DBTYPE_DECIMAL |
| "DBTYPE_NUMERIC" | DBTYPE_NUMERIC |
| "DBTYPE_BOOL" | DBTYPE_BOOL |
| "DBTYPE_ERROR" | DBTYPE_ERROR |
| "DBTYPE_UDT" | DBTYPE_UDT |
| "DBTYPE_VARIANT" | DBTYPE_VARIANT |
| "DBTYPE_IDISPATCH" | DBTYPE_IDISPATCH |
| "DBTYPE_IUNKNOWN" | DBTYPE_IUNKNOWN |
| "DBTYPE_GUID" | DBTYPE_GUID |
| "DBTYPE_DATE" | DBTYPE_DATE |
| "DBTYPE_DBDATE" | DBTYPE_DBDATE |
| "DBTYPE_DBTIME" | DBTYPE_DBTIME |
| "DBTYPE_DBTIMESTAMP" | DBTYPE_DBTIMESTAMP |
| "DBTYPE_BSTR" | DBTYPE_BSTR |
| "DBTYPE_CHAR" | DBTYPE_STR |
| "DBTYPE_VARCHAR" | DBTYPE_STR |
| "DBTYPE_LONGVARCHAR" | DBTYPE_STR |
| "DBTYPE_WCHAR" | DBTYPE_WSTR |
| "DBTYPE_WVARCHAR" | DBTYPE_WSTR |
| "DBTYPE_WLONGVARCHAR" | DBTYPE_WSTR |
| "DBTYPE_BINARY" | DBTYPE_BYTES |
| "DBTYPE_VARBINARY" | DBTYPE_BYTES |
| "DBTYPE_LONGVARBINARY" | DBTYPE_BYTES |
After the consumer calls SetParameterInfo to specify the parameter type information, it can call GetParameterInfo to retrieve the type indicator for each parameter. These values—which are based on the information specified in SetParameterInfo—represent the best fit of OLE DB types to the native parameter types. The provider guarantees that, if the consumer uses these types in a parameter accessor, it will be able to convert the data from the OLE DB type to the native parameter type.
If the provider can derive parameter type information and the consumer calls SetParameterInfo, SetParameterInfo uses the specified type information and returns DB_S_TYPEINFOOVERRIDDEN. Because deriving type information can be an expensive operation, this may result in more efficient code.
See Also