Función SQLDrivers

Conformidad
Versión introducida: Cumplimiento de estándares odbc 2.0: ODBC

Resumen
SQLDrivers enumera las descripciones de controladores y las palabras clave de atributo del controlador. Esta función solo la implementa el Administrador de controladores.

Sintaxis

  
SQLRETURN SQLDrivers(  
     SQLHENV         EnvironmentHandle,  
     SQLUSMALLINT    Direction,  
     SQLCHAR *       DriverDescription,  
     SQLSMALLINT     BufferLength1,  
     SQLSMALLINT *   DescriptionLengthPtr,  
     SQLCHAR *       DriverAttributes,  
     SQLSMALLINT     BufferLength2,  
     SQLSMALLINT *   AttributesLengthPtr);  

Argumentos

EnvironmentHandle
[Entrada] Identificador de entorno.

Dirección
[Entrada] Determina si el Administrador de controladores captura la siguiente descripción del controlador en la lista (SQL_FETCH_NEXT) o si la búsqueda comienza desde el principio de la lista (SQL_FETCH_FIRST).

DriverDescription
[Salida] Puntero a un búfer en el que se va a devolver la descripción del controlador.

Si DriverDescription es NULL, DescriptionLengthPtr seguirá devolviendo el número total de caracteres (excepto el carácter de terminación NULL para los datos de caracteres) disponible para devolver en el búfer al que apunta DriverDescription.

BufferLength1
[Entrada] Longitud del búfer *DriverDescription , en caracteres.

DescripciónLengthPtr
[Salida] Puntero a un búfer en el que se devuelve el número total de caracteres (excepto el carácter de terminación NULL) disponible para devolver en *DriverDescription. Si el número de caracteres disponibles para devolver es mayor o igual que BufferLength1, la descripción del controlador en *DriverDescription se trunca a BufferLength1 menos la longitud de un carácter de terminación NULL.

DriverAttributes
[Salida] Puntero a un búfer en el que se va a devolver la lista de pares de valores de atributo de controlador (vea "Comentarios").

Si DriverAttributes es NULL, AttributesLengthPtr seguirá devolviendo el número total de bytes (excepto el carácter de terminación NULL para los datos de caracteres) disponible para devolver en el búfer al que apunta DriverAttributes.

BufferLength2
[Entrada] Longitud del búfer *DriverAttributes , en caracteres. Si el valor *DriverDescription es una cadena Unicode (al llamar a SQLDriversW), el argumento BufferLength debe ser un número par.

AttributesLengthPtr
[Salida] Puntero a un búfer en el que se devuelve el número total de bytes (excepto el byte de terminación NULL) disponible para devolver en *DriverAttributes. Si el número de bytes disponibles para devolver es mayor o igual que BufferLength2, la lista de pares de valores de atributo en *DriverAttributes se trunca a BufferLength2 menos la longitud del carácter de terminación null.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLDrivers devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado mediante una llamada a SQLGetDiagRec con un handleType de SQL_HANDLE_ENV y un identificador de EnvironmentHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLDrivers y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

Comentarios

SQLDrivers devuelve la descripción del controlador en el búfer *DriverDescription . Devuelve información adicional sobre el controlador en el búfer *DriverAttributes como una lista de pares de palabra clave-valor. Todas las palabras clave enumeradas en la información del sistema para los controladores se devolverán para todos los controladores, excepto createDSN, que se usa para solicitar la creación de orígenes de datos y, por tanto, es opcional. Cada par finaliza con un byte nulo y la lista completa finaliza con un byte nulo (es decir, dos bytes nulos marcan el final de la lista). Por ejemplo, un controlador basado en archivos mediante la sintaxis de C podría devolver la siguiente lista de atributos ("\0" representa un carácter nulo):

FileUsage=1\0FileExtns=*.dbf\0\0  

Si *DriverAttributes no es lo suficientemente grande como para contener toda la lista, la lista se trunca, SQLDrivers devuelve SQLSTATE 01004 (datos truncados) y la longitud de la lista (excepto el byte final de terminación NULL) se devuelve en *AttributesLengthPtr.

Las palabras clave de atributo de controlador se agregan desde la información del sistema cuando se instala el controlador. Para obtener más información, vea Instalación de componentes ODBC.

Una aplicación puede llamar a SQLDrivers varias veces para recuperar todas las descripciones del controlador. El Administrador de controladores recupera esta información de la información del sistema. Cuando no hay más descripciones de controladores, SQLDrivers devuelve SQL_NO_DATA. Si se llama a SQLDrivers con SQL_FETCH_NEXT inmediatamente después de que devuelve SQL_NO_DATA, devuelve la primera descripción del controlador. Para obtener información sobre cómo una aplicación usa la información devuelta por SQLDrivers, vea Elegir un origen de datos o un controlador.

Si SQL_FETCH_NEXT se pasa a SQLDrivers la primera vez que se llama, SQLDrivers devuelve el primer nombre del origen de datos.

Dado que SQLDrivers se implementa en el Administrador de controladores, se admite para todos los controladores, independientemente del cumplimiento de estándares de un controlador determinado.

Funciones relacionadas

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC