When the IdentifierType argument is SQL_BEST_ROWID, SQLSpecialColumns returns the column or columns that uniquely identify each row in the table. These columns can always be used in a select-list or WHERE clause. SQLColumns, which is used to return a variety of information on the columns of a table, does not necessarily return the columns that uniquely identify each row, or columns that are automatically updated when any value in the row is updated by a transaction. For example, SQLColumns might not return the Oracle pseudo-column ROWID. This is why SQLSpecialColumns is used to return these columns. For more information, see Uses of Catalog Data.
.gif) Note |
|---|
| For more information about the general use, arguments, and returned data of ODBC catalog functions, see Catalog Functions. |
If there are no columns that uniquely identify each row in the table, SQLSpecialColumns returns a rowset with no rows; a subsequent call to SQLFetch or SQLFetchScroll on the statement returns SQL_NO_DATA.
If the IdentifierType, Scope, or Nullable arguments specify characteristics that are not supported by the data source, SQLSpecialColumns returns an empty result set.
If the SQL_ATTR_METADATA_ID statement attribute is set to SQL_TRUE, the CatalogName, SchemaName, and TableName arguments are treated as identifiers, so they cannot be set to a null pointer in certain situations. (For more information, see Arguments in Catalog Functions.)
SQLSpecialColumns returns the results as a standard result set, ordered by SCOPE.
The following columns have been renamed for ODBC 3.x. The column name changes do not affect backward compatibility because applications bind by column number.
|
ODBC 2.0 column
|
ODBC 3.x column
|
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
To determine the actual length of the COLUMN_NAME column, an application can call SQLGetInfo with the SQL_MAX_COLUMN_NAME_LEN option.
The following table lists the columns in the result set. Additional columns beyond column 8 (PSEUDO_COLUMN) can be defined by the driver. An application should gain access to driver-specific columns by counting down from the end of the result set rather than specifying an explicit ordinal position. For more information, see Data Returned by Catalog Functions.
|
Column name
|
Column number
|
Data type
|
Comments
|
| SCOPE (ODBC 1.0) | 1 | Smallint | Actual scope of the rowid. Contains one of the following values: SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION NULL is returned when IdentifierType is SQL_ROWVER. For a description of each value, see the description of Scope in "Syntax," earlier in this section. |
| COLUMN_NAME (ODBC 1.0) | 2 | Varchar not NULL | Column name. The driver returns an empty string for a column that does not have a name. |
| DATA_TYPE (ODBC 1.0) | 3 | Smallint not NULL | SQL data type. This can be an ODBC SQL data type or a driver-specific SQL data type. For a list of valid ODBC SQL data types, see SQL Data Types. For information about driver-specific SQL data types, see the driver's documentation. |
| TYPE_NAME (ODBC 1.0) | 4 | Varchar not NULL | Data source–dependent data type name; for example, "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY", or "CHAR ( ) FOR BIT DATA". |
| COLUMN_SIZE (ODBC 1.0) | 5 | Integer | The size of the column on the data source. For more information concerning column size, see Column Size, Decimal Digits, Transfer Octet Length, and Display Size. |
| BUFFER_LENGTH (ODBC 1.0) | 6 | Integer | The length in bytes of data transferred on an SQLGetData or SQLFetch operation if SQL_C_DEFAULT is specified. For numeric data, this size may be different than the size of the data stored on the data source. This value is the same as the COLUMN_SIZE column for character or binary data. For more information, see Column Size, Decimal Digits, Transfer Octet Length, and Display Size. |
| DECIMAL_DIGITS (ODBC 1.0) | 7 | Smallint | The decimal digits of the column on the data source. NULL is returned for data types where decimal digits are not applicable. For more information concerning decimal digits, see Column Size, Decimal Digits, Transfer Octet Length, and Display Size. |
| PSEUDO_COLUMN (ODBC 2.0) | 8 | Smallint | Indicates whether the column is a pseudo-column, such as Oracle ROWID: SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO | Note |
|---|
| For maximum interoperability, pseudo-columns should not be quoted with the identifier quote character returned by SQLGetInfo. |
|
After the application retrieves values for SQL_BEST_ROWID, the application can use these values to reselect that row within the defined scope. The SELECT statement is guaranteed to return either no rows or one row.
If an application reselects a row based on the rowid column or columns and the row is not found, the application can assume that the row was deleted or the rowid columns were modified. The opposite is not true: even if the rowid has not changed, the other columns in the row may have changed.
Columns returned for column type SQL_BEST_ROWID are useful for applications that need to scroll forward and back within a result set to retrieve the most recent data from a set of rows. The column or columns of the rowid are guaranteed not to change while positioned on that row.
The column or columns of the rowid may remain valid even when the cursor is not positioned on the row; the application can determine this by checking the SCOPE column in the result set.
Columns returned for column type SQL_ROWVER are useful for applications that need the ability to check whether any columns in a given row have been updated while the row was reselected using the rowid. For example, after reselecting a row using rowid, the application can compare the previous values in the SQL_ROWVER columns to the ones just fetched. If the value in a SQL_ROWVER column differs from the previous value, the application can alert the user that data on the display has changed.