16.9.4 SQLColAttribute, SQLColAttributeW

Organization of this subsection

(1) Function
(2) Format
(3) Arguments
(4) Return value
(5) SQLSTATE

(1) Function

This ODBC function returns descriptor information for a column in a result set.

(2) Format

For SQLColAttribute

SQLRETURN SQLColAttribute
(
  SQLHSTMT          StatementHandle,        /* In */
  SQLUSMALLINT      ColumnNumber,           /* In */
  SQLUSMALLINT      FieldIdentifier,        /* In */
  SQLPOINTER        CharacterAttributePtr,  /* Out */
  SQLSMALLINT       BufferLength,           /* In */
  SQLSMALLINT     * StringLengthPtr,        /* Out */
  SQLLEN          * NumericAttributePtr     /* Out */
)

For SQLColAttributeW

SQLRETURN SQLColAttributeW
(
  SQLHSTMT          StatementHandle,        /* In */
  SQLUSMALLINT      ColumnNumber,           /* In */
  SQLUSMALLINT      FieldIdentifier,        /* In */
  SQLPOINTER        CharacterAttributePtr,  /* Out */
  SQLSMALLINT       BufferLength,           /* In */
  SQLSMALLINT     * StringLengthPtr,        /* Out */
  SQLLEN          * NumericAttributePtr     /* Out */
)

To Page Top

(3) Arguments

StatementHandle

Specifies a statement handle.

ColumnNumber

Specifies the record number in the IRD from which the field value is to be obtained. This number is assigned sequentially in ascending order of the columns, beginning with 1. The number corresponds to the column number of the result set.

FieldIdentifier

Specifies an identifier that corresponds to the descriptor field of the IRD that is to be obtained.

The following table lists the field identifiers that can be specified.

Table 16‒8: Field identifiers that can be specified in FieldIdentifier of SQLColAttribute and SQLColAttributeW
No.	Field identifier
1	`SQL_COLUMN_LENGTH`
2	`SQL_COLUMN_PRECISION`
3	`SQL_COLUMN_SCALE`
4	`SQL_DESC_AUTO_UNIQUE_VALUE`
5	`SQL_DESC_BASE_COLUMN_NAME`
6	`SQL_DESC_BASE_TABLE_NAME`
7	`SQL_DESC_CASE_SENSITIVE`
8	`SQL_DESC_CATALOG_NAME`
9	`SQL_DESC_CONCISE_TYPE`
10	`SQL_DESC_COUNT`
11	`SQL_DESC_DISPLAY_SIZE`
12	`SQL_DESC_FIXED_PREC_SCALE`
13	`SQL_DESC_LABEL`
14	`SQL_DESC_LENGTH`
15	`SQL_DESC_LITERAL_PREFIX`
16	`SQL_DESC_LITERAL_SUFFIX`
17	`SQL_DESC_LOCAL_TYPE_NAME`
18	`SQL_DESC_NAME`
19	`SQL_DESC_NULLABLE`
20	`SQL_DESC_NUM_PREC_RADIX`
21	`SQL_DESC_OCTET_LENGTH`
22	`SQL_DESC_PRECISION`
23	`SQL_DESC_SCALE`
24	`SQL_DESC_SCHEMA_NAME`
25	`SQL_DESC_SEARCHABLE`
26	`SQL_DESC_TABLE_NAME`
27	`SQL_DESC_TYPE`
28	`SQL_DESC_TYPE_NAME`
29	`SQL_DESC_UNNAMED`
30	`SQL_DESC_UNSIGNED`
31	`SQL_DESC_UPDATABLE`

CharacterAttributePtr

Specifies a pointer to the buffer in which the descriptor field value of the IRD that corresponds to FieldIdentifier is to be returned. If the descriptor field value is not a character string, this argument is not used.

BufferLength

Specifies the length of *CharacterAttributePtr (in bytes). SQL_NTS cannot be specified.

StringLengthPtr

Specifies a pointer to the buffer in which is to be returned the total number of valid bytes (excluding the null terminating character) to be returned to *CharacterAttributePtr.

NumericAttributePtr

Specifies a pointer to the integer buffer in which the descriptor field value of the IRD that corresponds to FieldIdentifier is to be returned. If the descriptor field value is not a numeric value, this argument is not used.

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	Not all of the character string value could be stored because the `CharacterAttributePtr` buffer was too small (the character string value was truncated). The length of the untruncated character string value 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
`07005`	Prepared statement is not a cursor-specification.	The statement associated with `StatementHandle` did not return a result set.	Y
`07009`	Invalid descriptor index	The value specified in `ColumnNumber` is `0`. The value specified in `ColumnNumber` is greater than the number of columns in the result set.	Y
`24000`	Invalid cursor status	--	Y
`HY000`	General error		N
`HY001`	Memory allocation error		N
`HY008`	Operation cancelled		N
`HY010`	Function sequence error		N
`HY013`	Memory management error	The function call could not be processed because the memory object could not be accessed.	N
`HY090`	Invalid string or buffer length	A character string pointer is specified in `CharacterAttributePtr` and the value specified in `BufferLength` is less than or equal to `0`. An invalid value is specified in `BufferLength` (`SQL_NTS`).	Y
`HY091`	Invalid descriptor field identifier	The value specified in `FieldIdentifier` is neither a defined value nor an implementation-defined value.	Y
`HYC00`	Optional feature not implemented	The value specified in `FieldIdentifier` is not supported.	Y
`HYT01`	Connection timeout expired	A connection timeout occurred before the data source responded to the request. The connection timeout value can be specified by using `SQL_ATTR_CONNECTION_TIMEOUT` in `SQLSetConnectAttr` or `SQLSetConnectAttrW`.	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