Core subroutine
Return column descriptor information for a result set.
call EDSColAttributes(HSTMT_IV, COLNUM_IV, DESCTYPE_IV, CHAROUTPUT_SV, NUMBYTES_IV, INTOUTPUT_IV )
•HSTMT_IV An input integer value indicating the statement handle.
•COLNUM_IV An input integer value containing the column number.
•DESCTYPE_IV An input integer value indicating one of the following descriptor types:
EDS_COLUMN_COUNT
EDS_COLUMN_NAME
EDS_COLUMN_TYPE
EDS_COLUMN_LENGTH
EDS_COLUMN_PRECISION
EDS_COLUMN_SCALE
EDS_COLUMN_DISPLAY_SIZE
EDS_COLUMN_NULLABLE
EDS_COLUMN_UNSIGNED
EDS_COLUMN_MONEY
EDS_COLUMN_UPDATABLE
EDS_COLUMN_AUTO_INCREMENT
EDS_COLUMN_CASE_SENSITIVE
EDS_COLUMN_SEARCHABLE
EDS_COLUMN_TYPE_NAME
•CHAROUTPUT_SV An output string value that is only used to return information for descriptor types EDS_COLUMN_NAME or EDS_COLUMN_TYPE_NAME.
•NUMBYTES_IV An output integer value indicating the total number of bytes available to return in CHAROUTPUT_SV.
•INTOUTPUT_IV An output integer value that is only used to return descriptor information for numeric descriptor types, such as EDS_COLUMN_LENGTH.
Description
Depending on when the data source evaluates the SQL statement associated with the statement handle, EDSColAttributes can return any SQLSTATE that can be returned by EDSExecute when called after EDSPrepare and before EDSExecute. Descriptor information is returned as a character string or descriptor dependent format, or as an integer value, depending on the descriptor type.
This command is an extensible alternative to EDSDescribeCol, which returns a fixed set of descriptor information based on ANSI-89 SQL. EDSColAttributes allows access to the more extensive set of descriptor information available in ISO SQL 2 and DBMS vendor extensions.
The following is a list of the valid descriptor types that you can request using the DESCTYPE_IV argument and the information returned for each one in either CHAROUTPUT_SV or INTOUTPUT_IV.
DESCTYPE_IV |
CHAROUTPUT_SV |
INTOUTPUT_IV |
EDS_COLUMN_COUNT |
Unused |
Number of columns available in the result set. |
EDS_COLUMN_NAME |
Column name |
Unused |
EDS_COLUMN_TYPE |
Unused |
ODBC SQL data type. |
EDS_COLUMN_LENGTH |
Unused |
The transfer size of the data; that is, the length in bytes of data transferred on an EDSGetData or EDSFetch operation if EDS_SQL_DEFAULT is specified. For numeric data, this size may be different from the size of the data stored on the data source. |
EDS_COLUMN_PRECISION |
Unused |
The precision of the column on the data source. |
EDS_COLUMN_SCALE |
Unused |
The scale of the column on the data source. |
EDS_COLUMN _DISPLAY_SIZE |
Unused |
Maximum number of characters required to display data from the column. |
EDS_COLUMN_NULLABLE |
Unused |
EDS_NO_NULLS if the column does not accept NULL values.
EDS_NULLABLE if the column accepts NULL values
EDS_NULLABLE_UNKNOWN if it is not known if the column accepts NULL values. |
EDS_COLUMN_UNSIGNED |
Unused |
TRUE if the column is unsigned (or non-numeric).
FALSE if the column is signed. |
EDS_COLUMN_MONEY |
Unused |
TRUE if the column is money data type.
FALSE if the column is not money data type. |
EDS_COLUMN_TYPE_NAME |
Data source - dependent data type name; for example, “CHAR”, “VARCHAR”, “MONEY”, “LONGVARBINARY”, or “CHAR ( ) FOR BIT DATA”. |
Unused |
EDS_COLUMN_UPDATABLE |
Unused |
Column is described by the values for the defined constants: EDS_ATTR_READONLY EDS_ATTR_WRITE EDS_ATTR_READWRITE_UNKNOWN EDS_COLUMN_UPDATABLE indicates whether a column in the result set can be updated. This is based on the data type, user privileges, and the definition of the result set itself. If it is unclear whether a column is can be updated, EDS_ATTR_READWRITE_UNKNOWN should be returned. |
EDS_COLUMN_AUTO_INCREMENT |
Unused |
TRUE if the column is autoincrement.
FALSE if the column is not autoincrement or is non-numeric.
Autoincrement is valid for numeric data type columns only. Your application can insert values into an autoincrement column, but cannot update values in the column. |
EDS_COLUMN_CASE_SENSITIVE |
Unused |
TRUE if the column is treated as case-sensitive for collations.
FALSE if the column is not treated as case-sensitive for collations or is non-character. |
EDS_COLUMN_SEARCHABLE |
Unused |
EDS_UNSEARCHABLE if the column cannot be used in a WHERE clause.
EDS_LIKE_ONLY if the column can be used in a WHERE clause only with the LIKE predicate.
EDS_ALL_EXCEPT_LIKE if the column can be used in a WHERE clause with all comparison operators except LIKE.
EDS_SEARCHABLE if the column can be used in a WHERE clause with any comparison operator.
Columns of type EDS_LONGVARCHAR and EDS_LONGVARBINARY usually return EDS_LIKE_ONLY. |
The descriptor type EDS_COLUMN_DISPLAY_SIZE returns the maximum number of characters required to display data from the specified column.
If DESCTYPE_IV is EDS_COLUMN_COUNT, ICOL_IV is ignored. Columns are numbered sequentially from left to right starting with one and may be described in any order.
If DESCTYPE_IV is EDS_COLUMN_NAME and NUMBYTES_IV is 0, the column is unnamed.
If DESCTYPE_IV is EDS_COLUMN_TYPE_NAME and NUMBYTES_IV is 0, the type is unknown.
If DESCTYPE_IV is not EDS_COLUMN_NAME or EDS_COLUMN_TYPE_NAME, CHAROUTPUT_SV and NUMBYTES_IV will be ignored by the function.
If DESCTYPE_IV is EDS_COLUMN_NAME or EDS_COLUMN_TYPE_NAME, INTOUTPUT_IV will be ignored by the function.
Return Values
EDSColAttributes returns EDS_SUCCESS, EDS_SUCCESS_WITH_INFO, EDS_INVALID_HANDLE, or EDS_ERROR.
When EDSColAttributes 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 EDSColAttributes.
The following table lists possible SQLSTATE values.
SQL STATE |
Error |
Description |
24000 |
Invalid cursor state |
The statement associated with the statement handle did not return a result set. There were no columns to describe. |
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 memory required to support execution or completion of the function. |
S1002 |
Invalid column number |
The value specified for the argument COLNUM_IV was 0. The value specified for the argument COLNUM_IV was greater than the number of columns in the result set. |
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 |
The function was called prior to calling EDSPrepare or EDSExecDirect for the statement handle. An asynchronously executing function (not this one) was called for the statement handle and was still executing when this function was called. |
S1091 |
Descriptor type out of range |
The value specified for the argument DESCTYPE was not equal to: EDS_COLUMN_COUNT EDS_COLUMN_NAME EDS_COLUMN_TYPE EDS_COLUMN_LENGTH EDS_COLUMN_PRECISION EDS_COLUMN_SCALE EDS_COLUMN_DISPLAY_SIZE EDS_COLUMN_NULLABLE EDS_COLUMN_UNSIGNED EDS_COLUMN_MONEY EDS_COLUMN_UPDATABLE EDS_COLUMN_AUTO_INCREMENT EDS_COLUMN_CASE_SENSITIVE EDS_COLUMN_SEARCHABLE EDS_COLUMN_TYPE_NAME or a value defined by the driver. |
S1T00 |
Timeout expired |
The timeout period expired before the data source returned the requested information. The timeout period is set through EDSSetStmtOption, EDS_QUERY_TIMEOUT. |
See Also
EDSNumResultCols retrieves the number of columns in a result set.
EDSDescribeCol describes a column of a result set.
EDSFetch fetches a row of a result set.
