Conformance
Version Introduced: ODBC 1.0
Standards Compliance: ISO 92
Summary
f90SQLDescribeCol returns the result descriptor - column name, type, column size, decimal digits, and nullability - for one column in the result set. This information also is available in the fields of the IRD.
Syntax
| f90SQLDescribeCol | (StatementHandle, ColumnNumber, ColumnName, ColumnNameStrLength, DataType, ColumnSize, DecimalDigits, Nullable, iRet) |
| integer(SQLHSTMT_KIND), intent(in):: | StatementHandle |
| integer(SQLSMALLINT_KIND),intent(in):: | ColumnNumber |
| character(len=*),intent(out):: | ColumnName |
| integer(SQLSMALLINT_KIND):: | ColumnNameStrLength |
| integer(SQLSMALLINT_KIND):: | DataType |
| integer(SQLUINTEGER_KIND):: | ColumnSize |
| integer(SQLSMALLINT_KIND):: | DecimalDigits |
| integer(SQLSMALLINT_KIND):: | Nullable |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
StatementHandle [Input]
Statement handle.
ColumnNumber [Input]
Column number of result data, ordered sequentially in increasing column order, starting at 1. The ColumnNumber argument can also be set to 0 to describe the bookmark column.
ColumnName [Output]
Buffer in which to return the column name. This value is read from the SQL_DESC_NAME field of the IRD. If the column is unnamed or the column name cannot be determined, the driver returns an empty string.
ColumnNameStrLength [Output]
Buffer in which to return the total number of bytes (excluding the null-termination byte) available to return in ColumnName. If the number of bytes available to return is greater than or equal to Len(ColumnName), the column name in ColumnName is truncated to Len(ColumnName) minus the length of a null-termination character.
DataType [Output]
Buffer in which to return the SQL data type of the column. This value is read from the SQL_DESC_CONCISE_TYPE field of the IRD. This will be one of the values in the
SQL Data Types or a driver-specific SQL data type. If the data type cannot be determined, the driver returns SQL_UNKNOWN_TYPE.
In ODBC 3.0, SQL_TYPE_DATE, SQL_TYPE_TIME, or SQL_TYPE_TIMESTAMP is returned in DataType for date, time, or timestamp data, respectively; in ODBC 2.x, SQL_DATE, SQL_TIME, or SQL_TIMESTAMP is returned. The Driver Manager performs the required mappings when an ODBC 2.x application is working with an ODBC 3.0 driver, or an ODBC 3.0 application is working with an ODBC 2.x driver.
When ColumnNumber is equal to 0 (for a bookmark column), SQL_BINARY is returned in DataType for variable-length bookmarks. (SQL_INTEGER is returned if bookmarks are used by an ODBC 3.0 application working with an ODBC 2.x driver, or an ODBC 2.x application working with an ODBC 3.0 driver.)
ColumnSize [Output]
Buffer in which to return the size of the column on the data source. If the column size cannot be determined, the driver returns 0.
DecimalDigits [Output]
Buffer in which to return the number of decimal digits of the column on the data source. If the number of decimal digits cannot be determined or is not applicable, the driver returns 0.
Nullable [Output]
Buffer in which to return a value that indicates whether the column allows NULL values. This value is read from the SQL_DESC_NULLABLE field of the IRD. The value is one of the following:
- SQL_NO_NULLS: The column does not allow NULL values.
- SQL_NULLABLE: The column allows NULL values.
- SQL_NULLABLE_UNKNOWN: The driver cannot determine if the column allows NULL values.
iRet [Output]
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLDescribeCol returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling f90SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. The following table lists the SQLSTATE values commonly returned by f90SQLDescribeCol and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
| SQLSTATE | Error | Description |
| 01000 | General warning | Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 01004 | String data, right truncated | The buffer ColumnName was not large
enough to return the entire column name, so the column name was truncated. The length of the untruncated column name is returned in ColumnNameStrLength. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 07005 | Prepared statement not a cursor-specification | The statement associated with the StatementHandle did not return a result set. There were no columns to describe. |
| 07009 | Invalid descriptor index | (DM) The value specified for the argument ColumnNumber
was equal to 0, and the SQL_ATTR_USE_BOOKMARKS statement option was SQL_UB_OFF. The value specified for the argument ColumnNumber was greater than the number of columns in the result set. |
| 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. |
| HY000 | 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 f90SQLGetDiagRec in the MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation failure | The driver was unable to allocate memory required to support execution or completion of the function. |
| HY008 | Operation canceled | Asynchronous processing was enabled for the StatementHandle.
The function was called and, before it completed execution, f90SQLCancel
was called on the StatementHandle. Then the function was called again on the StatementHandle. The function was called and, before it completed execution, f90SQLCancel was called on the StatementHandle from a different thread in a multithread application. |
| HY010 | Function sequence error | (DM) An asynchronously executing function (not
this one) was called for the StatementHandle and was still executing when this
function was called. (DM) The function was called prior to calling f90SQLPrepare, f90SQLExecute, or a catalog function on the statement handle. (DM) f90SQLExecute, f90SQLExecDirect, f90SQLBulkOperations, or f90SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns. |
| HY013 | Memory management error | The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions. |
| HY090 | Invalid string or buffer length | (DM) The value specified for argument Len(ColumnName) was less than 0. |
| HYT01 | Connection timeout expired | The connection timeout period expired before the data source responded to the request. The connection timeout period is set through f90SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver does not support this function | (DM) The driver associated with the StatementHandle does not support the function. |
f90SQLDescribeCol can return any SQLSTATE that can be returned by f90SQLPrepare or f90SQLExecute when called after f90SQLPrepare and before f90SQLExecute, depending on when the data source evaluates the SQL statement associated with the statement handle.
For performance reasons, an application should not call f90SQLDescribeCol before executing a statement.
Comments
An application typically calls f90SQLDescribeCol after a call to f90SQLPrepare and before or after the associated call to f90SQLExecute. An application can also call f90SQLDescribeCol after a call to f90SQLExecDirect.
f90SQLDescribeCol retrieves the column name, type, and length generated by a SELECT statement. If the column is an expression, ColumnName is either an empty string or a driver-defined name.
Note: ODBC supports SQL_NULLABLE_UNKNOWN as an extension, even though the X/Open and SQL Access Group Call Level Interface specification does not specify the option for f90SQLDescribeCol.
Related Subroutines
| For information about | See |
| Binding a buffer to a column in a result set | f90SQLBindCol |
| Canceling statement processing | f90SQLCancel |
| Returning information about a column in a result set | f90SQLColAttribute |
| Fetching multiple rows of data | f90SQLFetch |
| Returning the number of result set columns | f90SQLNumResultCols |
| Preparing a statement for execution | f90SQLPrepare |