MDAC 2.5 SDK - ODBC Programmer's Reference
Chapter 21: ODBC API Reference

SQLSetDescRec

Conformance

Version Introduced: ODBC 3.0
Standards Compliance: ISO 92

Summary

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);

Arguments

DescriptorHandle

[Input]
Descriptor handle. This must not be an IRD handle.

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.

Type

[Input]
The value to which to set the SQL_DESC_TYPE field for the descriptor record.

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.

Length

[Input]
The value to which to set the SQL_DESC_OCTET_LENGTH field for the descriptor record.

Precision

[Input]
The value to which to set the SQL_DESC_PRECISION field for the descriptor record.

Scale

[Input]
The value to which to set the SQL_DESC_SCALE field for the descriptor record.

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.

The DataPtr argument can be set to a null pointer to set the SQL_DESC_DATA_PTR field to a null pointer. If the handle in the DescriptorHandle argument is associated with an ARD, this unbinds the column.

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.

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.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLSetDescRec returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_DESC and a Handle of DescriptorHandle. The following table lists the SQLSTATE values commonly returned by SQLSetDescRec and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATE	Error	Description
01000	General warning	Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
07009	Invalid descriptor index	The RecNumber argument was set to 0, and the DescriptorHandle referred to 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 the driver and the data source to which the driver was connected failed before the function completed processing.
HY000	General error	An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLGetDiagRec in the *MessageText buffer describes the error and its cause.
HY001	Memory allocation error	The driver was unable to allocate memory required to support execution or completion of the function.
HY010	Function sequence error	(DM) 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. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos 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	Memory management error	The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
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 SQL_DESC_TYPE field in the descriptor, was not valid or consistent. Descriptor information checked during a consistency check was not consistent. (See "Consistency Checks," later in this section.)
HY090	Invalid string or buffer length	(DM) The driver was an ODBC 2.x driver, the descriptor was an ARD, the ColumnNumber argument was set to 0, and the value specified for the argument BufferLength was not equal to 4.
HYT01	Connection timeout expired	The connection timeout period expired before the data source responded to the request. The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Driver does not support this function	(DM) The driver associated with the DescriptorHandle does not support the function.

Comments

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

SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE (for records whose type is SQL_DATETIME or SQL_INTERVAL)
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR

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.

Note 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 the driver automatically whenever an application sets the SQL_DESC_DATA_PTR field of an APD, ARD, or IPD. If any of the fields is inconsistent with other fields, SQLSetDescRec will return SQLSTATE HY021 (Inconsistent descriptor information).

Whenever an application sets the SQL_DESC_DATA_PTR field of an APD, ARD, or IPD, the driver 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 performed 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 descriptor fields:

The SQL_DESC_TYPE field must be one of the valid ODBC C or SQL types or a driver-specific SQL type. The SQL_DESC_CONCISE_TYPE field must be one of the valid ODBC C or SQL types or a driver-specific C or SQL type, including the concise datetime and interval types.
If the SQL_DESC_TYPE record field is SQL_DATETIME or SQL_INTERVAL, the SQL_DESC_DATETIME_INTERVAL_CODE field must be one of the valid datetime or interval codes. (See the description of the SQL_DESC_DATETIME_INTERVAL_CODE field in SQLSetDescField.)
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 or timestamp data type, an interval type with a seconds component, or one of the interval data types with a time component, the SQL_DESC_PRECISION field is verified to be a valid seconds precision.
If the SQL_DESC_CONCISE_TYPE is an interval data type, the SQL_DESC_DATETIME_INTERVAL_PRECISION field is verified to be a valid interval leading precision value.

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.

Related Functions

For information about	See
Binding a column	SQLBindCol
Binding a parameter	SQLBindParameter
Getting a single descriptor field	SQLGetDescField
Getting multiple descriptor fields	SQLGetDescRec
Setting single descriptor fields	SQLSetDescField