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.

 

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

 

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.

 

References

 

Parent topic:

DB2 UDB CLI functions