SQLDrivers

Conformance

Version Introduced:ODBC 2.0
Standards Compliance:ODBC

Summary

SQLDrivers lists driver descriptions and driver attribute keywords. This function is implemented solely by the Driver Manager.

Syntax

SQLRETURN SQLDrivers(
SQLHENVEnvironmentHandle,
SQLUSMALLINTDirection,
SQLCHAR *DriverDescription,
SQLSMALLINTBufferLength1,
SQLSMALLINT *DescriptionLengthPtr,
SQLCHAR *DriverAttributes,
SQLSMALLINTBufferLength2,
SQLSMALLINT *AttributesLengthPtr);

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]
Pointer to a buffer in which to return the driver description.

BufferLength1

[Input]
Length of the *DriverDescription buffer, in bytes.

DescriptionLengthPtr

[Output]
Pointer to a 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 BufferLength1, the driver description in *DriverDescription is truncated to BufferLength1 minus the length of a null-termination character.

DriverAttributes

[Output]
Pointer to a buffer in which to return the list of driver attribute value pairs (see “Comments”).

BufferLength2

[Input]
Length of the *DriverAttributes buffer, in bytes. If the *DriverDescription value is a Unicode string (when calling SQLDriversW), the BufferLength argument must be an even number.

AttributesLengthPtr

[Output]
Pointer to a 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 BufferLength2, the list of attribute value pairs in *DriverAttributes is truncated to BufferLength2 minus the length of the null-termination character.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLDrivers returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_ENV and a Handle of EnvironmentHandle. The following table lists the SQLSTATE values commonly returned by SQLDrivers 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.

Comments

SQLDrivers 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, SQLDrivers returns SQLSTATE 01004 (Data truncated), and the length of the list (excluding the final null-termination byte) is returned in *AttributesLengthPtr.

Driver attribute keywords are added from the system information when the driver is installed. For more information, see Chapter 18, “Installing ODBC Components.”

An application can call SQLDrivers multiple times to retrieve all driver descriptions. The Driver Manager retrieves this information from the system information. When there are no more driver descriptions, SQLDrivers returns SQL_NO_DATA. If SQLDrivers is called with SQL_FETCH_NEXT immediately after it returns SQL_NO_DATA, it returns the first driver description. For information about how an application uses the information returned by SQLDrivers, see “Choosing a Data Source or Driver” in Chapter 6, “Connecting to a Data Source or Driver.”

If SQL_FETCH_NEXT is passed to SQLDrivers the very first time it is called, SQLDrivers returns the first data source name.

Because SQLDrivers is implemented in the Driver Manager, it is supported for all drivers regardless of a particular driver’s standards compliance.

Related Functions