DB2 Version 10.1 for Linux, UNIX, and Windows

SQLSetDescField function (CLI) - Set a single field of a descriptor record

Sets the value of a single field of a descriptor record.

Specification:

CLI 5.0
ODBC 3.0
ISO CLI

Unicode equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLSetDescFieldW().

Syntax

SQLRETURN   SQLSetDescField  (SQLHDESC          DescriptorHandle,
                              SQLSMALLINT       RecNumber,
                              SQLSMALLINT       FieldIdentifier,
                              SQLPOINTER        ValuePtr,
                              SQLINTEGER        BufferLength);

Function arguments

Table 1. SQLSetDescField arguments
Data type	Argument	Use	Description
SQLHDESC	DescriptorHandle	input	Descriptor handle.
SQLSMALLINT	RecNumber	input	Indicates the descriptor record containing the field that the application seeks to set. Descriptor records are numbered from 0, with record number 0 being the bookmark record. The RecNumber argument is ignored for header fields.
SQLSMALLINT	FieldIdentifier	input	Indicates the field of the descriptor whose value is to be set. For more information, refer to the list of values for the descriptor FieldIdentifier argument.
SQLPOINTER	ValuePtr	input	Pointer to a buffer containing the descriptor information, or a four-byte value. The data type depends on the value of FieldIdentifier. If ValuePtr is a four-byte value, either all four of the bytes are used, or just two of the four are used, depending on the value of the FieldIdentifier argument.
SQLINTEGER	BufferLength	input	If FieldIdentifier is an ODBC-defined field and ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. For character string data, BufferLength should contain the number of bytes in the string. If FieldIdentifier is an ODBC-defined field and ValuePtr is an integer, BufferLength is ignored. If FieldIdentifier is a driver-defined field, the application indicates the nature of the field by setting the BufferLength argument. BufferLength can have the following values: If ValuePtr is a pointer to a character string, then BufferLength is the number of bytes needed to store the string or SQL_NTS. If ValuePtr is a pointer to a binary buffer, then the application places the result of the SQL_LEN_BINARY_ATTR(length) macro in BufferLength This places a negative value in BufferLength. If ValuePtr is a pointer to a value other than a character string or a binary string, then BufferLength should have the value SQL_IS_POINTER. If ValuePtr contains a fixed-length value, then BufferLength is either SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT, or SQL_IS_USMALLINT, as appropriate.

Usage

An application can call SQLSetDescField() to set any descriptor field one at a time. One call to SQLSetDescField() sets a single field in a single descriptor. This function can be called to set any field in any descriptor type, provided the field can be set. See the descriptor header and record field initialization values for more information.

Note: If a call to SQLSetDescField() fails, the contents of the descriptor record identified by the RecNumber argument are undefined.

Other functions can be called to set multiple descriptor fields with a single call of the function. The SQLSetDescRec() function sets a variety of fields that affect the data type and buffer bound to a column or parameter (the SQL_DESC_TYPE, SQL_DESC_DATETIME_INTERVAL_CODE, SQL_DESC_OCTET_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE, SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR, and SQL_DESC_INDICATOR_PTR fields). SQLBindCol() or SQLBindParameter() can be used to make a complete specification for the binding of a column or parameter. These functions each set a specific group of descriptor fields with one function call.

SQLSetDescField() can be called to change the binding buffers by adding an offset to the binding pointers (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, or SQL_DESC_OCTET_LENGTH_PTR). This changes the binding buffers without calling SQLBindCol() or SQLBindParameter(). This allows an application to quickly change SQL_DESC_DATA_PTR without concern for changing other fields, for example, SQL_DESC_DATA_TYPE.

Descriptor header fields are set by calling SQLSetDescField() with a RecNumber of 0, and the appropriate FieldIdentifier. Many header fields contain statement attributes, so can also be set by a call to SQLSetStmtAttr(). This allows applications to set a statement attribute without first obtaining a descriptor handle. A RecNumber of 0 is also used to set bookmark fields.

Note: The statement attribute SQL_ATTR_USE_BOOKMARKS should always be set before calling SQLSetDescField() to set bookmark fields. While this is not mandatory, it is strongly recommended.

Sequence of setting descriptor fields

When setting descriptor fields by calling SQLSetDescField(), the application must follow a specific sequence:

The application must first set the SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE, or SQL_DESC_DATETIME_INTERVAL_CODE field.
Note: SQL_DESC_DATETIME_INTERVAL_CODE is defined by ODBC but not supported by CLI.
After one of these fields has been set, the application can set an attribute of a data type, and the driver sets data type attribute fields to the appropriate default values for the data type. Automatic defaulting of type attribute fields ensures that the descriptor is always ready to use once the application has specified a data type. If the application explicitly sets a data type attribute, it is overriding the default attribute.
After one of the fields listed in Step 1 has been set, and data type attributes have been set, the application can set SQL_DESC_DATA_PTR. This prompts a consistency check of descriptor fields. If the application changes the data type or attributes after setting the SQL_DESC_DATA_PTR field, then the driver sets SQL_DESC_DATA_PTR to a null pointer, unbinding the record. This forces the application to complete the proper steps in sequence, before the descriptor record is usable.

Initialization of descriptor fields

When a descriptor is allocated, the fields in the descriptor can be initialized to a default value, be initialized without a default value, or be undefined for the type of descriptor. Refer to the list of descriptor header and record field initialization values for details.

The fields of an IRD have a default value only after the statement has been prepared or executed and the IRD has been populated, not when the statement handle or descriptor has been allocated. Until the IRD has been populated, any attempt to gain access to a field of an IRD will return an error.

Some descriptor fields are defined for one or more, but not all, of the descriptor types (ARDs and IRDs, and APDs and IPDs). When a field is undefined for a type of descriptor, it is not needed by any of the functions that use that descriptor. Because a descriptor is a logical view of data, rather than an actual data structure, these extra fields have no effect on the defined fields.

The fields that can be accessed by SQLGetDescField() are not necessarily set by SQLSetDescField(). Fields that can be set by SQLSetDescField() are described in the descriptor header and record field initialization values list.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLSetDescField SQLSTATEs
SQLSTATE	Description	Explanation
01000	General warning	Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
01S02	Option value changed.	CLI did not support the value specified in ValuePtr (if ValuePtr was a pointer) or the value in ValuePtr (if ValuePtr was a four-byte value), or ValuePtr was invalid because of SQL constraints or requirements, so CLI substituted a similar value. (Function returns SQL_SUCCESS_WITH_INFO.)
07009	Invalid descriptor index.	The FieldIdentifier argument was a header field, and the RecNumber argument was not 0. The RecNumber argument was 0 and the DescriptorHandle was an IPD. The RecNumber argument was less than 0.
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 or columns.
HY016	Cannot modify an implementation row descriptor.	The DescriptorHandle argument was associated with an IRD, and the FieldIdentifier argument was not SQL_DESC_ARRAY_STATUS_PTR.
HY021	Inconsistent descriptor information.	The TYPE field, or any other field associated with the TYPE field in the descriptor, was not valid or consistent. The TYPE field was not a valid CLI C type. Descriptor information checked during a consistency check was not consistent.
HY091	Invalid descriptor field identifier.	The value specified for the FieldIdentifier argument was not a CLI defined field and was not a defined value. The value specified for the RecNumber argument was greater than the value in the SQL_DESC_COUNT field. The FieldIdentifier argument was SQL_DESC_ALLOC_TYPE.
HY092	Option type out of range.	The value specified for the Attribute argument was not valid.
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.
HY105	Invalid parameter type.	The value specified for the SQL_DESC_PARAMETER_TYPE field was invalid. (For more information, see the InputOutputType Argument section in SQLBindParameter().)

Restrictions

None.

Example

  /* set a single field of a descriptor record */
  rc = SQLSetDescField(hARD,
                       1,
                       SQL_DESC_TYPE,
                       (SQLPOINTER)SQL_SMALLINT,
                       SQL_IS_SMALLINT);