Función SQLDataSources
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92
Resumen
SQLDataSources devuelve información sobre un origen de datos. Esta función solo la implementa el Administrador de controladores.
Sintaxis
SQLRETURN SQLDataSources(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT * NameLength1Ptr,
SQLCHAR * Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT * NameLength2Ptr);
Argumentos
EnvironmentHandle
[Entrada] Identificador de entorno.
Dirección
[Entrada] Determina el origen de datos sobre el que el Administrador de controladores devuelve información. Puede ser:
SQL_FETCH_NEXT (para capturar el siguiente nombre del origen de datos de la lista), SQL_FETCH_FIRST (para capturar desde el principio de la lista), SQL_FETCH_FIRST_USER (para capturar el primer DSN de usuario) o SQL_FETCH_FIRST_SYSTEM (para capturar el primer DSN del sistema).
Cuando Direction se establece en SQL_FETCH_FIRST, las llamadas posteriores a SQLDataSources con Direction establecida en SQL_FETCH_NEXT devuelven DSN de usuario y sistema. Cuando Direction se establece en SQL_FETCH_FIRST_USER, todas las llamadas subsiguientes a SQLDataSources con Direction establecida en SQL_FETCH_NEXT devolver solo los DSN de usuario. Cuando Direction se establece en SQL_FETCH_FIRST_SYSTEM, todas las llamadas posteriores a SQLDataSources con Direction establecida en SQL_FETCH_NEXT devuelven solo los DSN del sistema.
ServerName
[Salida] Puntero a un búfer en el que se va a devolver el nombre del origen de datos.
Si ServerName es NULL, NameLength1Ptr 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 ServerName.
BufferLength1
[Entrada] Longitud del búfer *ServerName , en caracteres; Esto no necesita ser más largo que SQL_MAX_DSN_LENGTH más el carácter de terminación null.
NameLength1Ptr
[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 *ServerName. Si el número de caracteres disponibles para devolver es mayor o igual que BufferLength1, el nombre del origen de datos de *ServerName se trunca a BufferLength1 menos la longitud de un carácter de terminación NULL.
Descripción
[Salida] Puntero a un búfer en el que se va a devolver la descripción del controlador asociado al origen de datos. Por ejemplo, dBASE o SQL Server.
Si Description es NULL, NameLength2Ptr 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 Description.
BufferLength2
[Entrada] Longitud en caracteres del búfer *Descripción .
NameLength2Ptr
[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 *Descripción. Si el número de caracteres disponibles para devolver es mayor o igual que BufferLength2, la descripción del controlador de *Description se trunca a BufferLength2 menos la longitud de un 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 SQLDataSources 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 SQLDataSources 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 *ServerName no era lo suficientemente grande como para devolver el nombre completo del origen de datos. Por lo tanto, el nombre se ha truncado. La longitud del nombre completo del origen de datos se devuelve en *NameLength1Ptr. (Function devuelve SQL_SUCCESS_WITH_INFO). (DM) El búfer *Descripción 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 del origen de datos notruncado se devuelve en *NameLength2Ptr. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| HY000 | Error general | (DM) 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. |
| HY103 | Código de recuperación no válido | (DM) El valor especificado para el argumento Direction no era igual a SQL_FETCH_FIRST, SQL_FETCH_FIRST_USER, SQL_FETCH_FIRST_SYSTEM 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
Dado que SQLDataSources se implementa en el Administrador de controladores, se admite para todos los controladores, independientemente del cumplimiento de estándares de un controlador determinado.
Una aplicación puede llamar a SQLDataSources varias veces para recuperar todos los nombres de origen de datos. El Administrador de controladores recupera esta información de la información del sistema. Cuando no hay más nombres de origen de datos, el Administrador de controladores devuelve SQL_NO_DATA. Si se llama a SQLDataSources con SQL_FETCH_NEXT inmediatamente después de que devuelve SQL_NO_DATA, devolverá el primer nombre del origen de datos. Para obtener información sobre cómo una aplicación usa la información devuelta por SQLDataSources, vea Elegir un origen de datos o un controlador.
Si SQL_FETCH_NEXT se pasa a SQLDataSources la primera vez que se llama, devolverá el primer nombre del origen de datos.
El controlador determina cómo se asignan los nombres de origen de datos a orígenes de datos reales.
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 |
| Conexión a un origen de datos mediante una cadena de conexión o un cuadro de diálogo | Función SQLDriverConnect |
| Devolver descripciones y atributos del controlador | Función SQLDrivers |