16.10.7 SQLSpecialColumns, SQLSpecialColumnsW

Organization of this subsection

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

(1) Function

This ODBC function acquires one of the following types of information about columns in a specified table:

Optimal set of columns that uniquely identifies a row in the table
Columns that are updated automatically when a value in the row is updated by a transaction

The driver returns the information as a result set for the specified SQL statement.

Note that the number of rows in the retrieval result set is always 0 because the driver does not support the function that updates columns automatically.

To Page Top

(2) Format

For SQLSpecialColumns

SQLRETURN SQLSpecialColumns
(
  SQLHSTMT       StatementHandle,    /* In */
  SQLUSMALLINT   IdentifierType,     /* In */
  SQLCHAR      * CatalogName,        /* In */
  SQLSMALLINT    NameLength1,        /* In */
  SQLCHAR      * SchemaName,         /* In */
  SQLSMALLINT    NameLength2,        /* In */
  SQLCHAR      * TableName,          /* In */
  SQLSMALLINT    NameLength3,        /* In */
  SQLUSMALLINT   Scope,              /* In */
  SQLUSMALLINT   Nullable            /* In */
)

For SQLSpecialColumnsW

SQLRETURN SQLSpecialColumnsW
(
  SQLHSTMT       StatementHandle,    /* In */
  SQLUSMALLINT   IdentifierType,     /* In */
  SQLWCHAR     * CatalogName,        /* In */
  SQLSMALLINT    NameLength1,        /* In */
  SQLWCHAR     * SchemaName,         /* In */
  SQLSMALLINT    NameLength2,        /* In */
  SQLWCHAR     * TableName,          /* In */
  SQLSMALLINT    NameLength3,        /* In */
  SQLUSMALLINT   Scope,              /* In */
  SQLUSMALLINT   Nullable            /* In */
)

To Page Top

(3) Arguments

StatementHandle

Specifies a statement handle.

Specify a value that was output by *OutputHandlePtr of SQLAllocHandle before this function is executed.

IdentifierType

Specifies one of the following values as the type of column to be returned:

IdentifierType	Description
`SQL_BEST_ROWID`	Returns the optimal column or set of columns that enables a row in the specified table to be uniquely identified by acquiring values from the columns. If the table contains an indexed column that enables a row to be uniquely identified, the driver returns that column. If the table does not contain such a column, the driver returns a temporary pseudo-column designed to identify rows.
`SQL_ROWVER`	Returns a column in the specified table, if any, that is automatically updated by the data source when a value in the row is updated by a transaction.

IdentifierType

Description

SQL_BEST_ROWID

Returns the optimal column or set of columns that enables a row in the specified table to be uniquely identified by acquiring values from the columns.

If the table contains an indexed column that enables a row to be uniquely identified, the driver returns that column. If the table does not contain such a column, the driver returns a temporary pseudo-column designed to identify rows.

SQL_ROWVER

Returns a column in the specified table, if any, that is automatically updated by the data source when a value in the row is updated by a transaction.

CatalogName

Specifies a catalog name for the table.

NameLength1

Specifies the length^# of *CatalogName.

SchemaName

Specifies a schema name for the table.

NameLength2

Specifies the length^# of *SchemaName.

TableName

Specifies a table name.

NameLength3

Specifies the length^# of *TableName.

Scope

Specifies one of the following values as the minimum required scope of the row ID:

Scope	Description
`SQL_SCOPE_CURROW`	The row ID is valid only while it is positioned on that row.
`SQL_SCOPE_TRANSACTION`	The row ID is valid only for the duration of the current transaction.
`SQL_SCOPE_SESSION`	The row ID is valid for the duration of the session (across transaction boundaries).

Nullable

Specifies whether special columns that store null values are to be returned.

Specify one of the following values:

Nullable	Description
`SQL_NO_NULLS`	Excludes special columns that can store null values. Some drivers cannot support `SQL_NO_NULLS`; these drivers return an empty result set if `SQL_NO_NULLS` is specified. We recommend that applications take this into account and specify `SQL_NO_NULLS` only if it is required.
`SQL_NULLABLE`	Returns special columns even if they store null values.

#

The length must be in bytes for SQLSpecialColumns and in characters for SQLSpecialColumnsW.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, 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
`08S01`	Communication link failure	--	N
`24000`	Invalid cursor status	The function was executed while a cursor was open.	Y
`40001`	Serialization failure	--	N
`40003`	Statement completion unknown		N
`HY000`	General error		N
`HY001`	Memory allocation error		Y
`HY008`	Operation cancelled		N
`HY009`	Invalid use of null pointer		N
`HY010`	Function sequence error		Y
`HY013`	Memory management error		N
`HY090`	Invalid string or buffer length		N
`HY097`	Invalid value specified in `IdentifierType`		N
`HY098`	Invalid value specified in `Scope`		N
`HY099`	Invalid value specified in `Nullable`		N
`HY117`	Connection suspended		N
`HYC00`	Optional feature not implemented		N
`HYT00`	Timeout expired		N
`HYT01`	Connection timeout expired		N
`IM001`	Driver does not support this function		N
`IM017`	Invalid asynchronous polling		N
`IM018`	Incomplete asynchronous execution		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