DB2 10.5 for Linux, UNIX, and Windows

SQLSetDescRec function (CLI) - Set multiple descriptor fields for a column or parameter data

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

Specification:

CLI 5.0
ODBC 3.0
ISO CLI

Syntax

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

Function arguments

Table 1. 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, SQL_DESC_COUNT is changed to the value of RecNumber.
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, this is the value to which to set the SQL_DESC_DATETIME_INTERVAL_CODE field.
SQLLEN	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 SQL_DESC_PRECISION field for the descriptor record.
SQLSMALLINT	Scale	input	The value to which to set the SQL_DESC_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.
SQLLEN *	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.
SQLLEN *	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 can only be updated if SQL_DESC_TYPE indicates SQL_DATETIME.

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.

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 2. 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 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 is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
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.
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.
HY094	Invalid scale value.	The value specified for pfParamType was either SQL_DECIMAL or SQL_NUMERIC and the value specified for DecimalDigits was less than 0 or greater than the value for the argument pcbColDef (precision). The value specified for pfParamType was SQL_C_TYPE_TIMESTAMP and the value for pfParamType was either SQL_CHAR or SQL_VARCHAR and the value for DecimalDigits was less than 0 or greater than 9. The value specified for pfParamType was SQL_C_TIMESTAMP_EXT and the value for DecimalDigits was less than 0 or greater than 12.

Restrictions

None.

Example

  SQLSMALLINT type;
  SQLINTEGER length, datalen;
  SQLSMALLINT id_no;
  /* ... */

  /* set multiple descriptor fields for a column or parameter data */
  rc = SQLSetDescRec(hARD, 1, type, 0, length, 0, 0, &id_no, &datalen, NULL);