Level 1 subroutine
Retrieve information about columns in a specified table.
call EDSSpecialColumns(HSTMT_IV, TYPE_IV, TABLE_STRUCT, SCOPE_IV, NULLABLE_IV, MAXROWS_IV, NUMROWS_IV, ARRAY_STRUCT)
•HSTMT_IV An input integer value that indicates the statement handle for retrieving results.
•TYPE_IV An input integer value indicating the type of column to return: EDS_BEST_ROWID or EDS_ROWVER (as listed in "Description").
•TABLE_STRUCT An input EDSTABLE_STRUCT structure that contains column names.
•SCOPE_IV An input integer value that indicates the minimum required scope of the row ID. The returned row ID may be of greater scope; it must be one of the following:
EDS_SCOPE_CURROW
EDS_SCOPE_TRANSACTION
EDS_SCOPE_SESSION.
•NULLABLE_IV An input integer value that indicates whether to return special columns that can have a NULL value. To exclude special columns that can have null values, set NULLABLE_IV to EDS_NO_NULLS. To return special columns even if they can have null values, set NULLABLE_IV to EDS_NULLABLE
•MAXROWS_IV An input integer value indicating the maximum number of rows in the result ARRAY_STRUCT.
•NUMROWS_IV An output integer value indicating the actual number of rows in the result array.
•ARRAY_STRUCT An output array of EDSSPCOLS_STRUCT structures, ordered by scope.
Description
EDSSpecialColumns retrieves the following information about columns within a specified table:
•The optimal set of columns that uniquely identifies a row in the table
•Columns that are automatically updated when any value in the row is updated by a transaction
The following table lists the data returned in the structure EDSSPCOLS_STRUCT:
Name |
Data Type |
Comments |
SCOPE |
integer |
Actual scope of the row ID. Contains one of the following values: EDS_SCOPE_CURROW EDS_SCOPE_TRANSACTION EDS_SCOPE_SESSION For a description of each value, see the description of the SCOPE_IV argument. |
COLUMN_NAME |
string |
Column identifier. |
DATA_TYPE |
integer |
ODBC SQL data type. For a list of valid ODBC SQL data types, see SQL Data Types.. |
TYPE_NAME |
string |
Data source–dependent data type name; for example, “CHAR”, “VARCHAR”, “MONEY”, “LONG VARBINARY”, or “CHAR ( ) FOR BIT DATA”. |
PRECISION |
integer |
The precision of the column on the data source. NULL is returned for data types where precision is not applicable. For more information concerning precision, see Section C.3. |
LENGTH |
integer |
The length in bytes required for the data type in its binary form in the data source (e.g. 10 for CHAR(10), 4 for INTEGER, 2 for SMALLINT). For more information, see Section C.3. |
SCALE |
integer |
The scale of the column on the data source. NULL is returned for data types where scale is not applicable. For more information concerning scale, see Default Data Type Conversions. |
EDSSpecialColumns allows an ESL application to provide its own custom scrollable cursor functionality. The functionality is similar to that provided by EDSExtendedFetch and EDSSetScrollOptions.
The following table lists valid values for the TYPE argument.
TYPE |
Description |
EDS_BEST_ROWID |
Returns the optimal column or set of columns that, by retrieving values from the column or columns, allows any row in the specified table to be uniquely identified. A column can be either a pseudo-column specifically designed for this purpose (as in Oracle ROWID or Ingres TID) or the column or columns of any unique index for the table. |
EDS_ROWVER |
Returns the column or columns in the specified table, if any, that are automatically updated by the data source when any value in the row is updated by any transaction (as in SQLBase ROWID or Sybase TIMESTAMP). |
The following table lists values for the SCOPE argument.
Constant |
Description |
EDS_SCOPE_CURROW |
The ROWID is guaranteed to be valid only while positioned on that row. A later reselect using ROWID may not return a row if the row was updated or deleted by another transaction. |
EDS_SCOPE_TRANSACTION |
The ROWID is guaranteed to be valid for the duration of the current transaction. |
EDS_SCOPE_SESSION |
The ROWID is guaranteed to be valid for the duration of the session (across transaction boundaries). |
EDSSpecialColumns returns results as an array of EDSSPCOLS_STRUCT structures.
Once your application retrieves values for EDS_BEST_ROWID, your 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 your application reselects a row based on the ROWID column or columns and the row is not found, then your 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 type EDS_BEST_ROWID are useful for applications that need to scroll forwards and backwards 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; your application can determine this by checking the SCOPE column in the result set.
Columns returned for type EDS_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, your application can compare the previous ROWVER value to the one just fetched. If the row differs from the previous EDS_ROWVER value, your application can alert the user that data on the display has changed.
Return Value
EDSSpecialColumns returns EDS_SUCCESS, EDS_ERROR, or EDS_INVALID_HANDLE.
When EDSSpecialColumns returns EDS_ERROR, you can obtain an associated SQLSTATE value with more specific information by calling EDSError. The following table lists each typical SQLSTATE value and explains each one in the context of the command EDSSpecialColumns.
The following table lists possible SQLSTATE values:
SQL STATE |
Error |
Description |
08S01 |
Communication link failure |
The communication link between the driver and the data source to which the driver was connected failed before the function completed processing. |
24000 |
Invalid cursor state |
Results were pending on the statement handle from a previous SELECT statement or a cursor associated with the statement handle had not been closed. |
IM001 |
Driver does not support this function |
The driver associated with the statement handle does not support the function. |
S1000 |
General error |
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by EDSError in the argument ERRORTEXT describes the error and its cause. |
S1001 |
Memory allocation failure |
The driver was unable to allocate the memory required to support execution or completion of the function. |
S1008 |
Operation cancelled |
Asynchronous processing was enabled for the statement handle. The function was called and before it completed execution, EDSCancel was called on the statement handle. Then the function was called again on the statement handle. |
S1010 |
Function sequence error |
An asynchronously executing function (not this one) was called for the statement handle and was still executing when this function was called. |
S1097 |
Column type out of range |
An invalid TYPE_IV value was specified. |
S1098 |
Scope type out of range |
An invalid SCOPE value was specified. |
S1099 |
Nullable type out of range |
An invalid NULLABLE_IV value was specified. |
S1C00 |
Driver not capable |
A table qualifier or a table owner was specified and the driver or data source does not support one or both of the qualifiers. |
S1T00 |
Timeout expired |
The timeout period expired before the data source returned the requested result set. The timeout period is set through EDSSetStmtOption, EDS_QUERY_TIMEOUT. |
See Also
EDSColumns retrieves a list of columns for the specified table.
EDSExtendedFetch fetches a block of data from the result set.
EDSSetScrollOptions set the number of rows received by EDSExtendedFetch.
