SQLGetDescField function (CLI) - Get single field settings of descriptor record

Returns the current settings 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 SQLGetDescFieldW(). See Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

SQLRETURN   SQLGetDescField (
               SQLHDESC          DescriptorHandle,
               SQLSMALLINT       RecNumber,
               SQLSMALLINT       FieldIdentifier,
               SQLPOINTER        ValuePtr,           /* Value */
               SQLINTEGER        BufferLength,
               SQLINTEGER        *StringLengthPtr);  /* *StringLength */

Function arguments

Table 1. SQLGetDescField arguments
Data type	Argument	Use	Description
SQLHDESC	DescriptorHandle	input	Descriptor handle.
SQLSMALLINT	RecNumber	input	Indicates the descriptor record from which the application seeks information. Descriptor records are numbered from 0, with record number 0 being the bookmark record. If the FieldIdentifier argument indicates a field of the descriptor header record, RecNumber must be 0. If RecNumber is less than SQL_DESC_COUNT, but the row does not contain data for a column or parameter, a call to the SQLGetDescField() function returns the default values of the fields.
SQLSMALLINT	FieldIdentifier	input	Indicates the field of the descriptor whose value is to be returned.
SQLPOINTER	ValuePtr	output	Pointer to a buffer in which to return the descriptor information. The data type depends on the value of FieldIdentifier.
SQLINTEGER	BufferLength	input	If ValuePtr points to a character string, this argument is the length of ValuePtr. If ValuePtr is a pointer, but not to a string, then the BufferLength value is SQL_IS_POINTER. If the value in ValuePtr is of a Unicode data type the BufferLength argument must be an even number.
SQLSMALLINT *	StringLengthPtr	output	Pointer to the total number of bytes (excluding the number of bytes required for the null termination character) available to return in *ValuePtr.

Usage

An application can call SQLGetDescField() to return the value of a single field of a descriptor record. A call to SQLGetDescField() can return the setting of any field in any descriptor type, including header fields, record fields, and bookmark fields. An application can obtain the settings of multiple fields in the same or different descriptors, in arbitrary order, by making repeated calls to SQLGetDescField(). SQLGetDescField() can also be called to return CLI defined descriptor fields.

An application can experience performance impact if it calls the SQLGetDescField() function for an IRD before executing a statement. Calling the SQLGetDescField() function can cause the CLI driver to describe the statement, resulting in an extra network flow. When deferred prepare is on and the SQLGetDescField() function is called, you lose the benefit of deferred prepare because the describe information requires that the statement is prepared at the server.

The settings of multiple fields that describe the name, data type, and storage of column or parameter data can also be retrieved in a single call to the SQLGetDescRec() function. SQLGetStmtAttr() can be called to return the value of a single field in the descriptor header that has an associated statement attribute.

When an application calls SQLGetDescField() to retrieve the value of a field that is undefined for a particular descriptor type, the function returns SQLSTATE HY091 (Invalid descriptor field identifier). When an application calls SQLGetDescField() to retrieve the value of a field that is defined for a particular descriptor type, but has no default value and has not been set yet, the function returns SQL_SUCCESS but the value that is returned for the field is undefined. Refer to the list of initialization values of descriptor fields for any default values, which may exist.

The SQL_DESC_ALLOC_TYPE header field is available as read-only. This field is defined for all types of descriptors.

Each of these fields is defined either for the IRD only, or for both the IRD and the IPD.

SQL_DESC_AUTO_UNIQUE_VALUE    SQL_DESC_LITERAL_SUFFIX
SQL_DESC_BASE_COLUMN_NAME     SQL_DESC_LOCAL_TYPE_NAME
SQL_DESC_CASE_SENSITIVE       SQL_DESC_SCHEMA_NAME
SQL_DESC_CATALOG_NAME         SQL_DESC_SEARCHABLE
SQL_DESC_DISPLAY_SIZE         SQL_DESC_TABLE_NAME
SQL_DESC_FIXED_PREC_SCALE     SQL_DESC_TYPE_NAME
SQL_DESC_IDENTITY_VALUE       SQL_DESC_UNSIGNED
SQL_DESC_LABEL                SQL_DESC_UPDATABLE
SQL_DESC_LITERAL_PREFIX

Refer to the list of descriptor FieldIdentifier values for more information about the listed fields.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_NO_DATA
SQL_INVALID_HANDLE

SQL_NO_DATA is returned if RecNumber is greater than the number of descriptor records.

SQL_NO_DATA is returned if DescriptorHandle is an IRD handle and the statement is in the prepared or executed state, but there was no open cursor associated with it.

Diagnostics

Table 2. SQLGetDescField SQLSTATEs
SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
01004	Data truncated.	The buffer ValuePtr was not large enough to return the entire descriptor field, so the field was truncated. The length of the untruncated descriptor field is returned in StringLengthPtr. (Function returns SQL_SUCCESS_WITH_INFO.)
07009	Invalid descriptor index.	The value specified for the RecNumber argument was less than 1, the SQL_ATTR_USE_BOOKMARKS statement attribute was SQL_UB_OFF, and the field was not a header field or a CLI defined field. The FieldIdentifier argument was a record field, and the RecNumber argument was 0. The RecNumber argument was less than 0, and the field was not a header field or a CLI defined field.
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.
HY007	Associated statement is not prepared.	DescriptorHandle was associated with an IRD, and the associated statement handle was not in the prepared or executed state.
HY010	Function sequence error.	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. DescriptorHandle was associated with a StatementHandle for which `SQLExecute()` or `SQLExecDirect()` was called 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.
HY021	Inconsistent descriptor information.	The descriptor information checked during a consistency check was not consistent.
HY090	Invalid string or buffer length.	The value of one of the name length arguments was less than 0, but not equal to SQL_NTS.
HY091	Invalid descriptor field identifier.	FieldIdentifier was undefined for the DescriptorHandle. The value specified for the RecNumber argument was greater than the value in the SQL_DESC_COUNT field.

Restrictions

None.

Example

  /* see how the field SQL_DESC_PARAMETER_TYPE is set */
  cliRC = SQLGetDescField(hIPD,
                          1, /* look at the parameter */
                          SQL_DESC_PARAMETER_TYPE,
                          &descFieldParameterType, /* result */
                          SQL_IS_SMALLINT,
                          NULL);
 
  /* ... */

    /* see how the descriptor record field SQL_DESC_TYPE_NAME is set */
    rc = SQLGetDescField(hIRD,
                         (SQLSMALLINT)colCount,
                         SQL_DESC_TYPE_NAME, /* record field */
                         descFieldTypeName, /* result */
                         25,
                         NULL);
    /* ... */

    /* see how the descriptor record field SQL_DESC_LABEL is set */
    rc = SQLGetDescField(hIRD,
                         (SQLSMALLINT)colCount,
                         SQL_DESC_LABEL, /* record field */
                         descFieldLabel, /* result */
                         25,
                         NULL);