Compartir a través de


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.

SQLSTATE Error Descripción
01000 Advertencia general (DM) Mensaje informativo específico del Administrador de controladores. (Function devuelve SQL_SUCCESS_WITH_INFO).
01004 Datos de cadena, truncados a la derecha (DM) El búfer *DriverDescription no era lo suficientemente grande como para devolver la descripción completa del controlador. Por lo tanto, la descripción se ha truncado. La longitud de la descripción completa del controlador se devuelve en *DescriptionLengthPtr. (Function devuelve SQL_SUCCESS_WITH_INFO).

(DM) El búfer *DriverAttributes no era lo suficientemente grande como para devolver la lista completa de pares de valores de atributo. Por lo tanto, la lista se ha truncado. La longitud de la lista notruncada de pares de valores de atributo se devuelve en *AttributesLengthPtr. (Function devuelve SQL_SUCCESS_WITH_INFO).
HY000 Error general Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa.
HY001 Error de asignación de memoria (DM) El Administrador de controladores no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función.
HY010 Error de secuencia de función (DM) SQLExecute, SQLExecDirect o SQLMoreResults se llamó a para statementHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos.
HY013 Error de administración de memoria No se pudo procesar la llamada de función porque no se pudo tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY090 Longitud de búfer o cadena no válida (DM) El valor especificado para el argumento BufferLength1 era menor que 0.

(DM) El valor especificado para el argumento BufferLength2 era menor que 0 o igual que 1.
HY103 Código de recuperación no válido (DM) El valor especificado para el argumento Direction no era igual a SQL_FETCH_FIRST o SQL_FETCH_NEXT.
HY117 La conexión se suspende debido al estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura. (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.

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.

Para información acerca de Vea
Detección y enumeración de valores necesarios para conectarse a un origen de datos Función SQLBrowseConnect
Conectarse a un origen de datos Función SQLConnect
Devolver nombres de origen de datos Función SQLDataSources
Conexión a un origen de datos mediante una cadena de conexión o un cuadro de diálogo Función SQLDriverConnect

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC