Level 1 subroutine
Return an array of structures containing column information.
call EDSColumns(HSTMT_IV, EDSTABLE_STRUCT, COLUMNNAME_SV, MAXROWS_IV, NUMROWS_IV, ARRAY_STRUCT )
•HSTMT_IV An input integer value indicating the statement handle.
•EDSTABLE_STRUCT An EDS input table structure that contains the following:
QUALIFIER_SV A string input value that indicates the table qualifier.
OWNER_SV A string input value that contains the string search pattern for table owner names.
TABLENAME_SV A string input value that contains the string search pattern for a table name.
•COLUMNNAME_SV An input string value containing the search pattern for column names.
•MAXROWS_IV An input integer value indicating the maximum number of rows in the result array.
•NUMROWS_IV An output integer value indicating the actual number of rows in the result array.
•ARRAY_STRUCT An output array of EDS_STRUCT structures that contain the result set.
Description
EDSColumns is used typically before statement execution, to retrieve information about columns for a table or tables from the data source's catalog. Note by contrast, that EDSDescribeCol describes the columns in a result set and that EDSNumResultCols returns the number of columns in a result set. EDSColumns does not describe computed columns in a fetch, nor does it return the number of columns referenced by a SELECT statement.
The OWNER_SV, NAME_SV, and COLUMNNAME_SV arguments accept search patterns. For more information about valid search patterns, see Catalog Commands.
EDSColumns returns results as an array of structures. The following table describes each returned value.
Element Name |
Data Type |
Comments |
QUALIFIER_SV |
string |
Table qualifier identifier; NULL if not applicable to the data source. |
OWNER_SV |
string |
Table owner identifier; NULL if not applicable to the data source. |
NAME_SV |
string |
Table identifier. |
COLUMNNAME_SV |
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. For precision information, see Precision. |
LENGTH |
integer |
The transfer size of the data; that is, the length in bytes of data transferred on an EDSGetData or EDSFetch operation if SQL_C_DEFAULT is specified. For numeric data, this size may be different from the size of the data stored on the data source. This value is the same as the PRECISION column for storing data. (For more information about length, see Length.) |
SCALE |
integer |
The scale of the column on the data source. For more scale information, see Scale. NULL is returned for data types where scale is not applicable. |
RADIX |
integer |
Either 10 or 2. If it is 10, the values in PRECISION and SCALE give the number of decimal digits allowed for the column. For example, a DECIMAL(12,5) column would return a RADIX of 10, a PRECISION of 12, and a SCALE of 5.
If it is 2, the values in PRECISION and SCALE give the number of bits allowed in the column. For example, a FLOAT column could return a RADIX of 2, a PRECISION of 53, and a SCALE of NULL.
Note that, for numeric data types, the data source and driver can return a RADIX of either 2 or 10. For example, a FLOAT column could return a RADIX of 10, a PRECISION of 15 and a SCALE of NULL.
NULL is returned for data types where radix is not applicable. |
NULLABLE |
integer |
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. |
REMARKS |
string |
A description of the column. |
If MAXROWS_IV=NUMROWS_IV, then there were more rows of data to fetch than there were structures in the array. To retrieve the full set of results, RESIZE the array and call the function again.
Return Values
EDSColumns returns EDS_SUCCESS, EDS_INVALID_HANDLE, or EDS_ERROR.
When EDSColumns 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 EDSColumns.
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 memory required to support execution or completion of the command. |
S1008 |
Operation cancelled |
Asynchronous processing was enabled for the statement handle. The command was called and before it completed execution, EDSCancel was called on the statement handle. Then the command 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 command was called. |
S1090 |
Invalid string or buffer length |
The value of one of the name length arguments was less than 0. |
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. A string search pattern was specified for the table owner, table name, or column name, and the data source does not support search patterns for one or more of those arguments. |
S1T00 |
Timeout expired |
The timeout period expired before the data source returned the result set. The timeout period is set through EDSSetStmtOption, EDS_QUERY_TIMEOUT. |
See Also
EDSBindCol assigns an ESL variable for a column in a result set.
EDSCancel cancels statement processing.
EDSColumnPrivileges returns privileges for a column or columns.
EDSExtendedFetch fetches a block of data or scrolls through a result set.
EDSFetch fetches a row of data.
EDSTables lists tables for the current connection.
EDSTablePrivileges lists privileges for a table or tables.
EDSStatistics lists indexes and statistics for a specified table.
