16.9.3 SQLDescribeCol, SQLDescribeColW : Hitachi Advanced Database Application Development Guide

(1) Function

This ODBC function returns information about a column in the result set that is obtained by executing SQLPrepare. This information is also set in the fields of the IRD.

To Page Top

(2) Format

For SQLDescribeCol

SQLRETURN SQLDescribeCol
(
  SQLHSTMT         StatementHandle,     /* In */
  SQLUSMALLINT     ColumnNumber,        /* In */
  SQLCHAR        * ColumnName,          /* Out */
  SQLSMALLINT      BufferLength,        /* In */
  SQLSMALLINT    * NameLengthPtr,       /* Out */
  SQLSMALLINT    * DataTypePtr,         /* Out */
  SQLULEN        * ColumnSizePtr,       /* Out */
  SQLSMALLINT    * DecimalDigitsPtr,    /* Out */
  SQLSMALLINT    * NullablePtr          /* Out */
)

For SQLDescribeColW

SQLRETURN SQLDescribeColW
(
  SQLHSTMT         StatementHandle,     /* In */
  SQLUSMALLINT     ColumnNumber,        /* In */
  SQLWCHAR       * ColumnName,          /* Out */
  SQLSMALLINT      BufferLength,        /* In */
  SQLSMALLINT    * NameLengthPtr,       /* Out */
  SQLSMALLINT    * DataTypePtr,         /* Out */
  SQLULEN        * ColumnSizePtr,       /* Out */
  SQLSMALLINT    * DecimalDigitsPtr,    /* Out */
  SQLSMALLINT    * NullablePtr          /* Out */
)

To Page Top

(3) Arguments

StatementHandle

Specifies a statement handle.

ColumnNumber

Specifies a column number in result data.

ColumnName

Specifies a pointer to the buffer in which the column name is to be returned. For details about the names of retrieval result columns, see Rules in Specification format and rules for the SELECT statement in the manual HADB SQL Reference.

BufferLength

Specifies the length^# of the *ColumnName buffer. This length includes the null terminating character. SQL_NTS cannot be specified.

NameLengthPtr

Specifies a pointer to the buffer that stores the total valid length^# of the value that is set in *ColumnName. This length does not include the null terminating character.

Important: If the length^# of the *ColumnName column name stored here is greater than the value of BufferLength without the length^# of the null terminating character, the character string stored in ColumnName is truncated to the length^# equivalent to BufferLength without the null terminating character, and then the null terminating character is added at the end.

DataTypePtr

Specifies a pointer to the buffer in which the SQL data type of the column is to be returned. If the data type is unknown, the driver returns SQL_C_DEFAULT.

ColumnSizePtr

Specifies a pointer to the buffer in which the size of the column at the data source is to be returned. If the size of the column is unknown, the driver returns 0.

DecimalDigitsPtr

Specifies a pointer to the buffer in which the number of decimal places of the column at the data source is to be returned. If the number of decimal places is unknown or not applicable, the driver returns 0.

NullablePtr

Specifies a pointer to the buffer in which a value indicating whether the column allows NULL values is to be returned. One of the following values is returned:

SQL_NO_NULLS

The column allows NULL values.
SQL_NULLABLE

The column does not allow NULL values.

#

The length must be in bytes for SQLDescribeCol and in characters for SQLDescribeColW.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, 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	--	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
`07005`	Prepared statement is not a cursor-specification	--	Y
`07009`	Invalid descriptor index		Y
`08S01`	Communication link failure		N
`24000`	Invalid cursor status		Y
`HY000`	General error		N
`HY001`	Memory allocation error		N
`HY008`	Operation cancelled		N
`HY010`	Function sequence error		Y
`HY013`	Memory management error		N
`HY090`	Invalid string or buffer length	An invalid value (`SQL_NTS`) was specified in `BufferLength`.	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