ICommandWithParameters::SetParameterInfo

Specifies the native data type of each parameter.

Syntax

HRESULT SetParameterInfo (
   DB_UPARAMS              cParams,
   const DB_UPARAMS        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, 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;
     DBLENGTH       ulParamSize;
     DBPARAMFLAGS   dwFlags;
     BYTE           bPrecision;
     BYTE           bScale;
  } DBPARAMBINDINFO;
  

  The elements of this structure are used as described in the following table.

  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 ICommandWithParameters::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" below. 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: The maximum length of the parameters in characters (for DBTYPE_STR and DBTYPE_WSTR) or in bytes (for DBTYPE_BYTES and DBTYPE_VARNUMERIC), if one is defined. For example, a parameter for a CHAR(5) column in an SQL table has a maximum length of 5. The maximum length of the data type in characters (for DBTYPE_STR and DBTYPE_WSTR) or in bytes (for DBTYPE_BYTES and DBTYPE_VARNUMERIC), if the parameter does not have a defined length. ~0 (bitwise, the value is not 0; all bits are set to 1) if neither the parameter nor the data type has a defined maximum length. For data types that do not have a length, this is set to ~0 (bitwise, the value is not 0; 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 DBTYPE_DBTIMESTAMP or 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 or if wType is DBTYPE_DBTIMESTAMP, 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 ICommandWithParameters::SetParameterInfo was called. The parameter type information specified in ICommandWithParameters::SetParameterInfo was used.

  ICommandWithParameters::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_BADORDINAL
  An element of rgParamOrdinals 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 (but not all) elements of rgParamBindInfo, 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

This method does not set type information for any parameter if it does not successfully set type information for every parameter. Otherwise, this method sets information for all parameters.

Providers generally derive parameter type information from the data store and return it to the consumer through ICommandWithParameters::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 store. For these providers, the consumer must supply the native parameter type information through ICommandWithParameters::SetParameterInfo. The provider uses the type information specified by ICommandWithParameters::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 store. 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 ICommandWithParameters::SetParameterInfo, the provider converts the data to a string before sending it to the data store. Because the data store is expecting a LONG, this will likely result in an error.

When the consumer calls ICommandWithParameters::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".

When the consumer specifies a storage object of type DBTYPE_IUNKNOWN for a parameter, the consumer should call ICommandWithParameters::SetParameterInfo to designate a standard type name for the parameter that corresponds to the contents of the storage object (for example, "DBTYPE_WCHAR" for a Unicode stream). This standard type name must match the parameter type expected by the data store; the consumer should not specify a standard type name different from the data store type and expect the provider to perform a conversion. For maximum interoperability, providers are encouraged to accept the OLE DB DBTYPEs as synonyms for the standard type names.

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.

After the consumer calls ICommandWithParameters::SetParameterInfo to specify the parameter type information, it can call ICommandWithParameters::GetParameterInfo to retrieve the type indicator for each parameter. These values ? which are based on the information specified in ICommandWithParameters::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 ICommandWithParameters::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.

Calling SetParameterInfo with (0, NULL, NULL) discards existing parameter information and should return S_OK. However, if DB_S_TYPEINFOOVERRIDDEN is returned instead, consumers should query for verification that the method succeeded.

See Also

Reference

ICommandWithParameters::GetParameterInfo