SQLGetDescField

Purpose

SQLGetDescField() obtains a value from a descriptor. SQLGetDescField() is a more extensible alternative to the SQLGetDescRec() function.

This function is similar to that of SQLDescribeCol() but SQLGetDescField() can retrieve data from parameter descriptors as well as row descriptors.

Syntax

SQLRETURN SQLGetDescField  (SQLHDESC       hdesc,
                            SQLSMALLINT    irec,
                            SQLSMALLINT    fDescType,
                            SQLPOINTER     rgbDesc,
                            SQLINTEGER     bLen,
                            SQLINTEGER     *sLen);

Function arguments

Table 1. SQLGetDescField arguments
Data type	Argument	Use	Description
SQLHDESC	hdesc	Input	Descriptor handle.
SQLSMALLINT	irec	Input	The number of records in the descriptor matches the number of columns in the result set for a row descriptor, or the number of parameters in a parameter descriptor.
SQLSMALLINT	fDescType	Input	See Table 2.
SQLPOINTER	rgbDesc	Output	Pointer to buffer.
SQLINTEGER	bLen	Input	Length of descriptor buffer (rgbDesc).
SQLINTEGER *	sLen	Output	Actual number of bytes in the descriptor to return. If this argument contains a value equal to or higher than the length rgbDesc buffer, truncation occurs.

Table 2. fDescType descriptor types
Descriptor	Type	Description
SQL_DESC_ALLOC_TYPE	SMALLINT	Either SQL_DESC_ALLOC_USER if the application explicitly allocated the descriptor, or SQL_DESC_ALLOC_AUTO if the implementation automatically allocated the descriptor.
SQL_DESC_COUNT	SMALLINT	The number of records in the descriptor is returned in rgbDesc.
SQL_DESC_DATA_PTR	SQLPOINTER	Retrieve the data pointer field for irec.
SQL_DESC_DATETIME_INTERVAL_CODE	SMALLINT	Retrieve the interval code for records with a type of SQL_DATETIME. The interval code further defines the SQL_DATETIME data type. The code values are SQL_CODE_DATE, SQL_CODE_TIME, and SQL_CODE_TIMESTAMP.
SQL_DESC_INDICATOR_PTR	SQLPOINTER	Retrieve the indicator pointer field for irec.
SQL_DESC_LENGTH_PTR	SQLPOINTER	Retrieve the length pointer field for irec.
SQL_DESC_LENGTH	INTEGER	Retrieve the LENGTH field of irec.
SQL_DESC_NAME	CHAR(128)	Retrieve the NAME field of irec.
SQL_DESC_NULLABLE	SMALLINT	If irec can contain nulls, then SQL_NULLABLE is returned in rgbDesc. Otherwise, SQL_NO_NULLS is returned in rgbDesc.
SQL_DESC_PRECISION	SMALLINT	Retrieve the PRECISION field of irec.
SQL_DESC_SCALE	SMALLINT	Retrieve the SCALE field of irec.
SQL_DESC_TYPE	SMALLINT	Retrieve the TYPE field of irec.
SQL_DESC_UNNAMED	SMALLINT	This is SQL_NAMED if the NAME field is an actual name, or SQL_UNNAMED if the NAME field is an implementation-generated name.

Usage

The number of records in the descriptor corresponds to the number of columns in the result set, if the descriptor is row descriptor, or the number of parameters, for a parameter descriptor.

Calling SQLGetDescField() with fDescType set to SQL_DESC_COUNT is an alternative to calling SQLNumResultCols() to determine whether any columns can be returned.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

Diagnostics

Table 3. SQLGetDescField SQLSTATEs
SQLSTATE	Description	Explanation
HY009	Argument value that is not valid	The value specified for the argument fDescType or irec is not valid. The argument rgbDesc or sLen is a null pointer.
HY013 *	Memory management problem	The driver is unable to access the memory required to support the processing or completion of the function.
HY021	Internal descriptor that is not valid	The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid.