Call Level Interface Guide and Reference

SQLGetDescField - Get Single Field Settings of Descriptor Record

Purpose

Specification: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLGetDescField() returns the current settings of a single field of a descriptor record.

Syntax

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

Function Arguments

Table 98. 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 SQLGetDescField() will return the default values of the fields. For more information, see SQLSetDescField() Initialization of Descriptor Fields.
SQLSMALLINT FieldIdentifier input Indicates the field of the descriptor whose value is to be returned. For more information, see SQLSetDescField() FieldIdentifier Arguments.
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 should be the length of *ValuePtr.
If ValuePtr is a pointer, but not to a string, then BufferLength should have the value SQL_IS_POINTER.
If ValuePtr is not a pointer, then BufferLength should have the value SQL_IS_NOT_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.

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 `SQLGetDescField()` will return the default values of the fields. For more information, see `SQLSetDescField()` Initialization of Descriptor Fields.
SQLSMALLINT	`FieldIdentifier`	input	Indicates the field of the descriptor whose value is to be returned. For more information, see `SQLSetDescField()` FieldIdentifier Arguments.
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 should be the length of `ValuePtr`. If `ValuePtr` is a pointer, but not to a string, then `BufferLength` should have the value SQL_IS_POINTER. If `ValuePtr` is not a pointer, then `BufferLength` should have the value SQL_IS_NOT_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 DB2 CLI defined descriptor fields.

For performance reasons, an application should not call SQLGetDescField() for an IRD before executing a statement.

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 SQLGetDescRec(). SQLGetStmtAttr() can be called to return the setting of a single field in the descriptor header that is also a 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 returned for the field is undefined. For more information, see SQLSetDescField() Initialization of Descriptor Fields.

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

The following record fields are available as read-only. 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_LABEL                SQL_DESC_UNSIGNED
SQL_DESC_LITERAL_PREFIX       SQL_DESC_UPDATABLE

For a description of the above fields, and fields that can be set in a descriptor header or record, see the SQLSetDescField() section. For more information on descriptors, see Using Descriptors.

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 99. SQLGetDescField SQLSTATEs

SQLSTATE Description Explanation
01000 Warning. Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
HY013 Unexpected memory handling error. The HandleType argument was SQL_HANDLE_DBC, SQL_HANDLE_STMT, or SQL_HANDLE_DESC; and the function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY021 Inconsistent descriptor information. The descriptor information checked during a consistency check was not consistent. For more information, see SQLSetDescField() Consistency Checks.
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_BOOKMARK statement attribute was SQL_UB_OFF, and the field was not a header field or a DB2 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 DB2 CLI defined field.
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 the memory required to support execution or completion of the function.
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.
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 Descriptor type out of range. FieldIdentifier was undefined for the DescriptorHandle.
The value specified for the RecNumber argument was greater than the value in the SQL_DESC_COUNT field.

SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
HY013	Unexpected memory handling error.	The `HandleType` argument was SQL_HANDLE_DBC, SQL_HANDLE_STMT, or SQL_HANDLE_DESC; and the function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY021	Inconsistent descriptor information.	The descriptor information checked during a consistency check was not consistent. For more information, see `SQLSetDescField()` Consistency Checks.
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_BOOKMARK statement attribute was SQL_UB_OFF, and the field was not a header field or a DB2 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 DB2 CLI defined field.
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 the memory required to support execution or completion of the function.
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.
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	Descriptor type out of range.	`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.

CLI Sample dbuse.c

(The complete sample dbuse.c is also available here .)

 
/* From the CLI sample DBUSE.C */
/* ... */
 
    /* bind the file-parameter
    /* see how the header field SQL_DESC_ALLOC_TYPE is set. */
    sqlrc = SQLGetDescField( hIPD,
                             0, /* ignored for header fields */
                             SQL_DESC_ALLOC_TYPE,
                             &descFieldAllocType, /* The result */
                             SQL_IS_SMALLINT,
                             NULL ); /* ignored */
    STMT_HANDLE_CHECK( hstmt, sqlrc); 
    
/* ... */
 
    /* see how the field SQL_DESC_PARAMETER_TYPE is set. */
    sqlrc = SQLGetDescField( hIPD,
                             1, /* Look at the parameter */
                             SQL_DESC_PARAMETER_TYPE,
                             &descFieldParameterType, /* The result */
                             SQL_IS_SMALLINT,
                             NULL ); /* ignored */
    STMT_HANDLE_CHECK( hstmt, sqlrc);    
    
/* ... */
 
        /* see how the descriptor record field SQL_DESC_TYPE_NAME is set */
        rc = SQLGetDescField( hIRD,
                              (SQLSMALLINT)colCount, 
                              SQL_DESC_TYPE_NAME, /* record field */ 
                              descFieldTypeName, /* The result */
                              25,
                              NULL ); /* ignored */
        STMT_HANDLE_CHECK( hstmt, sqlrc);

References

[ Top of Page | Previous Page | Next Page ]