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
Data type | Argument | Use | Description |
---|---|---|---|
SQLHDESC | hdesc | Input | Descriptor handle. A descriptor handle is obtained using the SQLGetStmtAttr API with the attribute SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_APP_ROW_DESC, SQL_ATTR_IMP_ROW_DESC or SQL_ATTR_IMP_PARAM_DESC. |
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. |
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. |
SQL_DESC_CCSID | INTEGER | Retrieve the CCSID value of irec |
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
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. |