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 follows.

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 source.
dwFlags (continued)	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 SetParameterInfo so 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 may 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 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.
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 bytes, for DBTYPE_BYTES, 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 bytes, for DBTYPE_BYTES, if the parameter does not have a defined length. ~0 (bitwise, the value is not 0; that is, 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; that is, all bits are set to 1).
wType	The indicator of the parameter’s data type.
bPrecision	If wType is a numeric type, bPrecision is the maximum number of digits, expressed in base 10. Otherwise, this is ~0 (bitwise, the value is not 0; that is, all bits are set to 1).
bScale	If wType 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, this is ~0 (bitwise, the value is not 0; that is, all bits are set to 1).

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, but it does not support command preparation. However, no command text was currently set on the Command object and no parameter information had been specified with SetParameterInfo.

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 SetParameterInfo.

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

Comments

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

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

If SetParameterInfo has been called for at least one parameter, GetParameterInfo returns the parameter information only for those parameters for which SetParameterInfo has been called. It does this even if the provider can derive information about the parameters for which SetParameterInfo was not 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.