Call Level Interface Guide and Reference

SQLSetDescRec - Set Multiple Descriptor Fields for a Column or Parameter Data

Purpose

Specification: DB2 CLI 5.0 ODBC 3.0 ISO CLI

The SQLSetDescRec() function sets multiple descriptor fields that affect the data type and buffer bound to a column or parameter data.

Syntax

SQLRETURN   SQLSetDescRec    (SQLHDESC          DescriptorHandle,
                              SQLSMALLINT       RecNumber,
                              SQLSMALLINT       Type,
                              SQLSMALLINT       SubType,
                              SQLINTEGER        Length,
                              SQLSMALLINT       Precision,
                              SQLSMALLINT       Scale,
                              SQLPOINTER        DataPtr,
                              SQLINTEGER        *StringLengthPtr,
                              SQLINTEGER        *IndicatorPtr);

Function Arguments

Table 162. SQLSetDescRec Arguments

Data Type Argument Use Description
SQLHDESC DescriptorHandle input Descriptor handle. This must not be an IRD handle.
SQLSMALLINT RecNumber input Indicates the descriptor record that contains the fields to be set. Descriptor records are numbered from 0, with record number 0 being the bookmark record. This argument must be equal to or greater than 0. If RecNumber is greater than the value of SQL_DESC_COUNT, RecNumber is changed to the value of SQL_DESC_COUNT.
SQLSMALLINT Type input The value to which to set the SQL_DESC_TYPE field for the descriptor record.
SQLSMALLINT SubType input For records whose type is SQL_DATETIME or SQL_INTERVAL, this is the value to which to set the SQL_DESC_DATETIME_INTERVAL_CODE field.
SQLINTEGER Length input The value to which to set the SQL_DESC_OCTET_LENGTH field for the descriptor record.
SQLSMALLINT Precision input The value to which to set the PRECISION field for the descriptor record.
SQLSMALLINT Scale input The value to which to set the SCALE field for the descriptor record.
SQLPOINTER DataPtr Deferred Input or Output The value to which to set the SQL_DESC_DATA_PTR field for the descriptor record. DataPtr can be set to a null pointer to set the SQL_DESC_DATA_PTR field to a null pointer.
SQLINTEGER StringLengthPtr Deferred Input or Output The value to which to set the SQL_DESC_OCTET_LENGTH_PTR field for the descriptor record. StringLengthPtr can be set to a null pointer to set the SQL_DESC_OCTET_LENGTH_PTR field to a null pointer.
SQLINTEGER IndicatorPtr Deferred Input or Output The value to which to set the SQL_DESC_INDICATOR_PTR field for the descriptor record. IndicatorPtr can be set to a null pointer to set the SQL_DESC_INDICATOR_PTR field to a null pointer.

Data Type	Argument	Use	Description
SQLHDESC	`DescriptorHandle`	input	Descriptor handle. This must not be an IRD handle.
SQLSMALLINT	`RecNumber`	input	Indicates the descriptor record that contains the fields to be set. Descriptor records are numbered from 0, with record number 0 being the bookmark record. This argument must be equal to or greater than 0. If `RecNumber` is greater than the value of SQL_DESC_COUNT, `RecNumber` is changed to the value of SQL_DESC_COUNT.
SQLSMALLINT	`Type`	input	The value to which to set the SQL_DESC_TYPE field for the descriptor record.
SQLSMALLINT	`SubType`	input	For records whose type is SQL_DATETIME or SQL_INTERVAL, this is the value to which to set the SQL_DESC_DATETIME_INTERVAL_CODE field.
SQLINTEGER	`Length`	input	The value to which to set the SQL_DESC_OCTET_LENGTH field for the descriptor record.
SQLSMALLINT	`Precision`	input	The value to which to set the PRECISION field for the descriptor record.
SQLSMALLINT	`Scale`	input	The value to which to set the SCALE field for the descriptor record.
SQLPOINTER	`DataPtr`	Deferred Input or Output	The value to which to set the SQL_DESC_DATA_PTR field for the descriptor record. `DataPtr` can be set to a null pointer to set the SQL_DESC_DATA_PTR field to a null pointer.
SQLINTEGER	`StringLengthPtr`	Deferred Input or Output	The value to which to set the SQL_DESC_OCTET_LENGTH_PTR field for the descriptor record. `StringLengthPtr` can be set to a null pointer to set the SQL_DESC_OCTET_LENGTH_PTR field to a null pointer.
SQLINTEGER	`IndicatorPtr`	Deferred Input or Output	The value to which to set the SQL_DESC_INDICATOR_PTR field for the descriptor record. `IndicatorPtr` can be set to a null pointer to set the SQL_DESC_INDICATOR_PTR field to a null pointer.

Usage

An application can call SQLSetDescRec() to set the following fields for a single column or parameter:

SQL_DESC_TYPE
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR

(SQL_DESC_DATETIME_INTERVAL_CODE is also defined by ODBC but is not supported by DB2 CLI.)
Note: If a call to SQLSetDescRec() fails, the contents of the descriptor record identified by the RecNumber argument are undefined.

When binding a column or parameter, SQLSetDescRec() allows you to change multiple fields affecting the binding without calling SQLBindCol() or SQLBindParameter(), or making multiple calls to SQLSetDescField(). SQLSetDescRec() can set fields on a descriptor not currently associated with a statement. Note that SQLBindParameter() sets more fields than SQLSetDescRec(), can set fields on both an APD and an IPD in one call, and does not require a descriptor handle.

The statement attribute SQL_ATTR_USE_BOOKMARKS should always be set before calling SQLSetDescRec() with a RecNumber argument of 0 to set bookmark fields. While this is not mandatory, it is strongly recommended.

Consistency Checks

A consistency check is performed by DB2 CLI automatically whenever an application sets the SQL_DESC_DATA_PTR field of the APD, ARD, or IPD. Calling SQLSetDescRec() always prompts a consistency check. If any of the fields is inconsistent with other fields, SQLSetDescRec() will return SQLSTATE HY021, "Inconsistent descriptor information."

Application Descriptors

Whenever an application sets the SQL_DESC_DATA_PTR field of an APD, ARD, or IPD, DB2 CLI checks that the value of the SQL_DESC_TYPE field and the values applicable to that SQL_DESC_TYPE field are valid and consistent. This check is always perform when SQLBindParameter() or SQLBindCol() is called, or when SQLSetDescRec() is called for an APD, ARD, or IPD. This consistency check includes the following checks on application descriptor fields:

The SQL_DESC_TYPE field must be one of the valid C or SQL types. The SQL_DESC_CONCISE_TYPE field must be one of the valid C or SQL types.
If the SQL_DESC_TYPE field indicates a numeric type, the SQL_DESC_PRECISION and SQL_DESC_SCALE fields are verified to be valid.
If the SQL_DESC_CONCISE_TYPE field is a time data type the SQL_DESC_PRECISION field is verified to be a valid seconds precision.

The SQL_DESC_DATA_PTR field of an IPD is not normally set; however, an application can do so to force a consistency check of IPD fields. A consistency check cannot be performed on an IRD. The value that the SQL_DESC_DATA_PTR field of the IPD is set to is not actually stored, and cannot be retrieved by a call to SQLGetDescField() or SQLGetDescRec(); the setting is made only to force the consistency check.

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 163. SQLSetDescRec SQLSTATEs

SQLSTATE Description Explanation
01000 Warning. Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
07009 Invalid descriptor index. The RecNumber argument was set to 0, and the DescriptorHandle was an IPD handle.
The RecNumber argument was less than 0.
The RecNumber argument was greater than the maximum number of columns or parameters that the data source can support, and the DescriptorHandle argument was an APD, IPD, or ARD.
The RecNumber argument was equal to 0, and the DescriptorHandle argument referred to an implicitly allocated APD. (This error does not occur with an explicitly allocated application descriptor, because it is not known whether an explicitly allocated application descriptor is an APD or ARD until execute time.)
08S01 Communication link failure. The communication link between DB2 CLI and the data source to which it was connected failed before the function completed processing.
HY000 General error. An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause.
HY001 Memory allocation failure. DB2 CLI was unable to allocate memory required to support execution or completion of the function.
HY010 Function sequence error. The DescriptorHandle was associated with a StatementHandle for which an asynchronously executing function (not this one) was called and was still executing when this function was called.
SQLExecute() or SQLExecDirect() was called for the StatementHandle with which the DescriptorHandle was associated and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.
HY013 Unexpected memory handling error. DB2 CLI was unable to access memory required to support execution or completion of the function.
HY016 Cannot modify an implementation row descriptor. The DescriptorHandle argument was associated with an IRD.
HY021 Inconsistent descriptor information. The Type field, or any other field associated with the TYPE field in the descriptor, was not valid or consistent.
Descriptor information checked during a consistency check was not consistent. (See Consistency Checks in SQLSetDescField().)

SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
07009	Invalid descriptor index.	The `RecNumber` argument was set to 0, and the `DescriptorHandle` was an IPD handle. The `RecNumber` argument was less than 0. The `RecNumber` argument was greater than the maximum number of columns or parameters that the data source can support, and the `DescriptorHandle` argument was an APD, IPD, or ARD. The `RecNumber` argument was equal to 0, and the `DescriptorHandle` argument referred to an implicitly allocated APD. (This error does not occur with an explicitly allocated application descriptor, because it is not known whether an explicitly allocated application descriptor is an APD or ARD until execute time.)
08S01	Communication link failure.	The communication link between DB2 CLI and the data source to which it was connected failed before the function completed processing.
HY000	General error.	An error occurred for which there was no specific SQLSTATE. The error message returned by `SQLGetDiagRec()` in the `*MessageText` buffer describes the error and its cause.
HY001	Memory allocation failure.	DB2 CLI was unable to allocate memory required to support execution or completion of the function.
HY010	Function sequence error.	The `DescriptorHandle` was associated with a `StatementHandle` for which an asynchronously executing function (not this one) was called and was still executing when this function was called. `SQLExecute()` or `SQLExecDirect()` was called for the `StatementHandle` with which the `DescriptorHandle` was associated and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.
HY013	Unexpected memory handling error.	DB2 CLI was unable to access memory required to support execution or completion of the function.
HY016	Cannot modify an implementation row descriptor.	The `DescriptorHandle` argument was associated with an IRD.
HY021	Inconsistent descriptor information.	The `Type` field, or any other field associated with the TYPE field in the descriptor, was not valid or consistent. Descriptor information checked during a consistency check was not consistent. (See Consistency Checks in `SQLSetDescField()`.)

Restrictions

None.

Example

See the README file in the sqllib\samples\cli (or sqllib/samples/cli) subdirectory for a list of appropriate samples.

References

[ Top of Page | Previous Page | Next Page ]