Conformance
Version Introduced: ODBC 2.0
Standards Compliance: ODBC
Summary
f90SQLDrivers lists driver descriptions and driver attribute keywords. This function is implemented solely by the Driver Manager.
Syntax
| f90SQLDrivers | (EnvironmentHandle, Direction, DriverDescription, DriverDescriptionLength, DriverAttributes, DriverAttributesLength, iRet) |
| integer(SQLHENV_KIND),intent(in):: | EnvironmentHandle |
| integer(SQLUSMALLINT_KIND),intent(in):: | Direction |
| character(len=*):: | DriverDescription |
| integer(SQLSMALLINT_KIND):: | DriverDescriptionLength |
| character(len=*):: | DriverAttributes |
| integer(SQLSMALLINT_KIND):: | DriverAttributesLength |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
EnvironmentHandle [Input]
Environment handle.
Direction [Input]
Determines whether the Driver Manager fetches the next driver description in the list (SQL_FETCH_NEXT) or whether the search starts from the beginning of the list (SQL_FETCH_FIRST).
DriverDescription[Output]
Buffer in which to return the driver description.
DriverDescriptionLength [Output]
Buffer in which to return the total number of bytes (excluding the null-termination byte) available to return in DriverDescription. If the number of bytes available to return is greater than or equal to len(DriverDescription), the driver description in DriverDescription is truncated to len(DriverDescription) minus the length of a null-termination character.
DriverAttributes [Output]
Buffer in which to return the list of driver attribute value pairs (see "Comments").
DriverAttributesLength [Output]
Buffer in which to return the total number of bytes (excluding the null-termination byte) available to return in DriverAttributes. If the number of bytes available to return is greater than or equal to len(DriverAttributes), the list of attribute value pairs in DriverAttributes is truncated to len(DriverAttributes) minus the length of the null-termination character.
iRet [Output]
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLDrivers returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling f90SQLGetDiagRec with a HandleType of SQL_HANDLE_ENV and a Handle of EnvironmentHandle. The following table lists the SQLSTATE values commonly returned by f90SQLDrivers 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 | (DM) Driver Manager - specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 01004 | String data, right truncated | (DM) The buffer DriverDescription was
not large enough to return the entire driver description, so the description was
truncated. The length of the entire driver description is returned in DriverDescriptionLength.
(Function returns SQL_SUCCESS_WITH_INFO.) (DM) The buffer DriverAttributes was not large enough to return the entire list of attribute value pairs, so the list was truncated. The length of the untruncated list of attribute value pairs is returned in DriverAttributesLength. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 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 | (DM) The Driver Manager was unable to allocate memory required to support execution or completion of the function. |
| 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 DriverDescriptionBufferLength was less than 0. (DM) The value specified for argument DriverAttributesBufferLength was less than 0 or equal to 1. |
| HY103 | Invalid retrieval code | (DM) The value specified for the argument Direction was not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT. |
Comments
f90SQLDrivers returns the driver description in the DriverDescription buffer. It returns additional information about the driver in the DriverAttributes buffer as a list of keyword-value pairs. All keywords listed in the system information for drivers will be returned for all drivers, except for CreateDSN, which is used to prompt creation of data sources, and therefore is optional. Each pair is terminated with a null byte, and the entire list is terminated with a null byte (that is, two null bytes mark the end of the list). For example, a file-based driver using C syntax might return the following list of attributes ("\0" represents a null character):
FileUsage=1\0FileExtns=*.dbf\0\0
If DriverAttributes is not large enough to hold the entire list, the list is truncated, f90SQLDrivers returns SQLSTATE 01004 (Data truncated), and the length of the list (excluding the final null-termination byte) is returned in DriverAttributesLength.
Driver attribute keywords are added from the system information when the driver is installed.
An application can call f90SQLDrivers multiple times to retrieve all driver descriptions. The Driver Manager retrieves this information from the system information. When there are no more driver descriptions, f90SQLDrivers returns SQL_NO_DATA. If f90SQLDrivers is called with SQL_FETCH_NEXT immediately after it returns SQL_NO_DATA, it returns the first driver description.
If SQL_FETCH_NEXT is passed to f90SQLDrivers the very first time it is called, f90SQLDrivers returns the first data source name.
Because f90SQLDrivers is implemented in the Driver Manager, it is supported for all drivers regardless of a particular driver's standards compliance.
Related Subroutines
| For information about | See |
| Discovering and listing values required to connect to a data source | f90SQLBrowseConnect |
| Connecting to a data source | f90SQLConnect |
| Returning data source names | f90SQLDataSources |
| Connecting to a data source using a connection string or dialog box | f90SQLDriverConnect |