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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC