MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

ICommandWithParameters::GetParameterInfo

Gets a list of the command’s parameters, their names, and their types.

HRESULT GetParameterInfo (
   ULONG *          pcParams,
   DBPARAMINFO **   prgParamInfo,
   OLECHAR **       ppNamesBuffer);

Parameters

pcParams

[out]
A pointer to memory in which to return the number of parameters in the command. If an error occurs, *pcParams is set to zero.

prgParamInfo

[out]
A pointer to memory in which to return an array of parameter information structures. The command allocates memory for the array, as well as the strings, and returns the address to this memory. The consumer releases the array memory with IMalloc::Free when it no longer needs the parameter information. If *pcParams is zero on output or an error occurs, the provider does not allocate any memory and ensures that *prgParamInfo is a null pointer on output. Parameters are returned in ascending order according to the iOrdinal element of the PARAMINFO structure.

Here is the DBPARAMINFO structure:

   typedef struct tagDBPARAMINFO {
      DBPARAMFLAGS   dwFlags;
      ULONG          iOrdinal;
      LPOLESTR       pwszName;
      ITypeInfo *    pTypeInfo;
      ULONG          ulParamSize;
      DBTYPE         wType;
      BYTE           bPrecision;
      BYTE           bScale;
   } DBPARAMINFO;

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

Element	Description
dwFlags	A bitmask describing parameter characteristics; these values have the following meaning: DBPARAMFLAGS_ISINPUT—Whether a parameter accepts values on input. Not set if this is unknown. DBPARAMFLAGS_ISOUTPUT—Whether a parameter returns values on output. Not set if this is unknown. Providers support only those parameter types that make sense for their data store. DBPARAMFLAGS_ISSIGNED—Whether a parameter is signed. This is ignored if the type is inherently signed, such as DBTYPE_I2 or if the sign does not apply to the type, such as DBTYPE_BSTR. It is generally used in ICommandWithParameters::SetParameterInfo so that the consumer can tell the provider if a provider-specific type name refers to a signed or unsigned type. DBPARAMFLAGS_ISNULLABLE—Whether a parameter accepts NULLs. If nullability is unknown, this flag is set. DBPARAMFLAGS_ISLONG—Whether a parameter contains a BLOB that contains very long data. The definition of very long data is provider specific. The flag setting corresponds to the value of the IS_LONG column in the PROVIDER_TYPES schema rowset for the data type. When this flag is set, the BLOB is best manipulated through one of the storage interfaces. Although such BLOBs can be sent in a single piece with ICommand::Execute, there can be provider-specific problems in doing so. For example, the BLOB might be truncated due to machine limits on memory. Furthermore, when this flag is set, the provider might not be able to accurately return the maximum length of the BLOB data in ulParamSize in ICommandWithParameters::GetParameterInfo. When this flag is not set, the BLOB can be accessed either through ICommand::Execute or through a storage interface. For more information, see "Accessing BLOB Data" in Chapter 7, "BLOBs and COM Objects." DBPARAMFLAGS_SCALEISNEGATIVE—Set if the parameter type is DBTYPE_VARNUMERIC and bScale represents the absolute value of the negative scale of the parameter. This flag is used when setting data in a DBTYPE_VARNUMERIC parameter. For more information, refer to "Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL" in Appendix A.
iOrdinal	The ordinal of the parameter. Parameters are numbered from left to right as they appear in the command, with the first parameter in the command having an iOrdinal value of 1.
pwszName	The name of the parameter; it is a null pointer if there is no name. Names are normal names. The colon prefix (where used within SQL text) is stripped.
pTypeInfo	ITypeInfo describes the type—if pTypeInfo is not a null pointer.
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).
wType	The indicator of the parameter's data type, or a type from which the data can be converted for the parameter if the provider cannot determine the exact data type of the parameter.
bPrecision	If wType is a numeric type or DBTYPE_TIMESTAMP, bPrecision is the maximum number of digits, expressed in base 10. Otherwise, this is ~0 (bitwise, the value is not 0; all bits are set to 1). Note Some 1.x or 2.x providers, for whom the precision is fixed for DBTYPE_TIMESTAMP, may return ~0 for the precision of DBTYPE_TIMESTAMP parameters.
bScale	If wType is a numeric type with a fixed scale or if wType is DBTYPE_TIMESTAMP, bScale is the number of digits to the right (if bScale is positive) or left (if bScale is negative) of the decimal point. Otherwise, this is ~0 (bitwise, the value is not 0; all bits are set to 1). Note Some 1.x or 2.x providers, for whom the scale is fixed for DBTYPE_TIMESTAMP, may return ~0 for the scale of DBTYPE_TIMESTAMP parameters.

ppNamesBuffer

[out]
A pointer to memory in which to store all string values (names used within the *pwszName element of the DBPARAMINFO structures) with a single, globally allocated buffer. Specifying a null pointer for ppNamesBuffer suspends the return of parameter names. The command allocates memory for the buffer and returns the address to this memory. The consumer releases the memory with IMalloc::Free when it no longer needs the parameter information. If *pcParams is zero on output or an error occurs, the provider does not allocate any memory and ensures that *ppNamesBuffer is a null pointer on output.

Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the buffer may contain one or more strings, each with its own null-termination character, and may contain embedded null termination characters.

Return Code

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

pcParams or prgParamInfo was a null pointer.

E_OUTOFMEMORY

The provider was unable to allocate sufficient memory in which to return the parameter data array or parameter names.

DB_E_NOCOMMAND

The provider can derive parameter information. However, no command text was currently set on the command object and no parameter information had been specified with ICommandWithParameters::SetParameterInfo.

Note Some 2.1 or earlier providers that support command preparation may return DB_E_NOTPREPARED when the command text has not been set.

DB_E_NOTPREPARED

The provider can derive parameter information, and it supports command preparation. However, the command was in an unprepared state and no parameter information was specified with ICommandWithParameters::SetParameterInfo.

DB_E_PARAMUNAVAILABLE

The provider cannot derive parameter information from the command, and ICommandWithParameters::SetParameterInfo has not been called.

Comments

This method makes no logical change to the state of the object.

If ICommandWithParameters::SetParameterInfo has not been called for any parameters or ICommandWithParameters::SetParameterInfo has been called with cParams equal to zero, ICommandWithParameters::GetParameterInfo returns information about the parameters only if the provider can derive parameter information. If the provider cannot derive parameter information, ICommandWithParameters::GetParameterInfo returns DB_E_PARAMUNAVAILABLE.

If ICommandWithParameters::SetParameterInfo has been called for at least one parameter, ICommandWithParameters::GetParameterInfo returns the parameter information only for those parameters for which SetParameterInfo has been called. The provider does not return a warning in this case because it often cannot determine the number of parameters and therefore cannot determine whether it has returned information for all parameters. It is provider-specific whether or not the provider also returns derived information about the parameters for which ICommandWithParameters::SetParameterInfo was not called. For performance reasons, even providers that can derive this additional parameter information will usually return only the information that was specified when ICommandWithParameters::SetParameterInfo was called.

Note Providers are permitted to overwrite parameter information set by the consumer with the actual parameter information for the statement or stored procedure. However, they are not encouraged to do so if such validation requires a round-trip to the server. Consumers must not rely on providers to validate parameter information in this manner.