16.6.1 SQLGetDescField, SQLGetDescFieldW

(1) Function

This ODBC function returns the value of a descriptor field specified in the arguments.

To Page Top

(2) Format

• For SQLGetDescField

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

• For SQLGetDescFieldW

  SQLRETURN SQLGetDescFieldW
  (
    SQLHDESC        DescriptorHandle,         /* In */
    SQLSMALLINT     RecNumber,                /* In */
    SQLSMALLINT     FieldIdentifier,          /* In */
    SQLPOINTER      ValuePtr,                 /* Out */
    SQLINTEGER      BufferLength,             /* In */
    SQLINTEGER    * StringLengthPtr           /* Out */
  )

To Page Top

(3) Arguments

DescriptorHandle

Specifies a descriptor handle.

RecNumber

Specifies a column number (ARD or IRD) or a parameter number (APD or IPD).

If FieldIdentifier indicates a header field, this argument is ignored.

FieldIdentifier

Specifies the field (header or record field) of the descriptor whose value is to be returned. For details about the attributes that can be specified, see 16.17 Attributes that can be specified in SQLGetDescField, SQLGetDescFieldW, SQLSetDescField, and SQLSetDescFieldW.

ValuePtr

Specifies a pointer to the buffer in which the descriptor information is to be returned. NULL can also be specified in this argument.

BufferLength

If the data type of the descriptor field specified in FieldIdentifier is character string or binary, this argument specifies the length of *ValuePtr (in bytes). If it is any other data type, this argument is ignored. SQL_NTS cannot be specified.

StringLengthPtr

Specifies a pointer to the buffer that stores the valid length of the value that is set in *ValuePtr.

A value is set in ValuePtr even when NULL is specified in this argument.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA, or SQL_INVALID_HANDLE.

To Page Top

(5) SQLSTATE

This ODBC function returns one of the following SQLSTATE values:

SQLSTATE	Description	Remarks	Returned
01000	General warning	--	N
01004	Character string data was right-truncated	The column name was truncated because the value specified in BufferLength was smaller than the length of the column name in bytes. The length of the untruncated column name is stored in *StringLengthPtr. The function returns SQL_SUCCESS_WITH_INFO.	Y
01S51	Code replacement occurred during conversion of character encoding	A character code that cannot be converted was detected and then replaced with the specified character. The function returns SQL_SUCCESS_WITH_INFO.	Y
07009	Invalid descriptor index	The value specified in RecNumber is less than or equal to 0.	Y
08S01	Communication link failure	--	N
HY001	Memory allocation error		N
HY007	Associated statement is not prepared		Y
HY010	Function sequence error	Before this function was executed, SQLExecute, SQLExecDirect, SQLExecDirectW, or SQLParamData was called for StatementHandle associated with DescriptorHandle and returned SQL_NEED_DATA. Since then, the setting of runtime data parameters or runtime data columns has not been completed.	Y
HY013	Memory management error	--	N
HY021	Inconsistent descriptor information		N
HY090	Invalid string or buffer length	*ValuePtr is a character string and the value specified in BufferLength is less than 0. An invalid value (SQL_NTS) was specified in BufferLength.	Y
HY091	Invalid descriptor field identifier	FieldIdentifier is not an ODBC-defined field.	Y
HYT01	Connection timeout expired	--	N
IM001	Driver does not support this function		N

Legend:

Y: This SQLSTATE might be returned by the HADB ODBC driver.

N: This SQLSTATE is not returned by the HADB ODBC driver.

--: None

To Page Top