SQLGetDescField - Get descriptor field

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.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. The corresponding Unicode function is SQLGetDescFieldW(). Refer to Unicode in DB2 for iCLI for more information about Unicode support for DB2 CLI.

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	Indicates the descriptor record from which the application seeks information. Descriptor records are numbered from 1, with the record number 1 being the first item in the descriptor. If the fDescType argument indicates a field of the descriptor header record ( SQL_DESC_ALLOC_TYPE or SQL_DESC_COUNT), irec must be 0.
SQLSMALLINT	fDescType	Input	Indicates the field of the descriptor whose value is to be returned. 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