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.
Funciones relacionadas
| 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 |