Conformance
Version Introduced: ODBC 1.0
Standards Compliance: ODBC
Summary
f90SQLDescribeParam returns the description of a parameter marker associated with a prepared SQL statement. This information is also available in the fields of the IPD.
Syntax
| f90SQLDescribeParam | (Statementhandle, ParameterNumber, DataType, ParameterSize, DecimalDigits, Nullable, iRet) |
| integer(SQLHSTMT_KIND),intent(in):: | Statementhandle |
| integer(SQLUSMALLINT_KIND),intent(in):: | ParameterNumber |
| integer(SQLSMALLINT_KIND):: | DataType |
| integer(SQLUINTEGER_KIND):: | ParameterSize |
| integer(SQLSMALLINT_KIND):: | DecimalDigits |
| integer(SQLSMALLINT_KIND):: | Nullable |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
Statementhandle [Input]
Statement handle.
ParameterNumber [Input]
Parameter marker number ordered sequentially in increasing parameter order, starting at 1.
DataType [Output]
Buffer in which to return the SQL data type of the parameter. This value is read from the SQL_DESC_CONCISE_TYPE record field of the IPD. This will be one of the values in Table 4.2, Chapter 4, or a driver-specific SQL data type.
In ODBC 3.0, SQL_TYPE_DATE, SQL_TYPE_TIME, or SQL_TYPE_TIMESTAMP will be returned in DataType for date, time, or timestamp data, respectively; in ODBC 2.x, SQL_DATE, SQL_TIME, or SQL_TIMESTAMP will be 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.)
ParameterSize [Output]
Pointer to a buffer in which to return the size of the column or expression of the corresponding parameter marker as defined by the data source.
DecimalDigits [Output]
Pointer to a buffer in which to return the number of decimal digits of the column or expression of the corresponding parameter as defined by the data source.
Nullable [Output]
Pointer to a buffer in which to return a value that indicates whether the parameter allows NULL values. This value is read from the SQL_DESC_NULLABLE field of the IPD. One of the following:
- SQL_NO_NULLS: The parameter does not allow NULL values (this is the default value).
- SQL_NULLABLE: The parameter allows NULL values.
- SQL_NULLABLE_UNKNOWN: The driver cannot determine if the parameter allows NULL values.
iRet [Output]
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLDescribeParam returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may 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 f90SQLDescribeParam 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.) |
| 07009 | Invalid descriptor index | (DM) The value specified for the argument ParameterNumber
is less than 1. The value specified for the argument ParameterNumber was greater than the number of parameters in the associated SQL statement. The parameter marker was part of a non-DML statement. The parameter marker was part of a SELECT list. |
| 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. |
| 21S01 | Insert value list does not match column list | The number of parameters in the INSERT statement did not match the number of columns in the table named in the statement. |
| 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 error | 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) The function was called prior to calling f90SQLPrepare or f90SQLExecDirect
for the Statementhandle. (DM) An asynchronously executing function (not this one) was called for the Statementhandle and was still executing when this function was called. (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. |
| 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. |
Comments
Parameter markers are numbered in increasing parameter order, starting with 1, in the order they appear in the SQL statement.
f90SQLDescribeParam does not return the type (input, input/output, or output) of a parameter in an SQL statement. Except in calls to procedures, all parameters in SQL statements are input parameters. To determine the type of each parameter in a call to a procedure, an application calls f90SQLProcedureColumns.
Related Subroutines
| For information about | See |
| Binding a buffer to a parameter | f90SQLBindParameter |
| Canceling statement processing | f90SQLCancel |
| Executing a prepared SQL statement | f90SQLExecute |
| Preparing a statement for execution | f90SQLPrepare |