SQLDataSources -获取数据源列表
SQLDataSources() 返回可用目标数据库的列表，一次一个。 必须对数据库进行编目才能可用。
有关编目的更多信息，请参阅 SQLConnect() 的使用说明，或参阅 "使用关系数据库 (RDB) 目录项" (WRKRDBDIRE) 命令的联机帮助。
通常在建立连接之前调用 SQLDataSources() ，以确定可连接到的数据库。
如果您在 SQL 服务器模式下运行 Db2 for i CLI，则在使用 SQLDataSources() 时会受到一些限制。
有关以服务器方式运行的更多信息，请参阅 在服务器方式下运行 Db2 for i CLI 的限制。
Unicode (UTF-16) 等效: 此函数还可以与 Unicode (UTF-16) 字符集配合使用。 相应的 Unicode 函数是 SQLDataSourcesW() 。有关 DB2® CLI 的 Unicode 支持的更多信息，请参阅 Db2 for i CLI 中的 Unicode 。
语法
SQLRETURN SQLDataSources (SQLHENV EnvironmentHandle,
SQLSMALLINT Direction,
SQLCHAR *ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT *NameLength1Ptr,
SQLCHAR *Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT *NameLength2Ptr);函数自变量
| 数据类型 | 自变量 | 使用 | 描述 |
|---|---|---|---|
| SQL经 V | EnvironmentHandle | 输入 | 环境句柄。 |
| SQLSMALLINT | 方向 | 输入 | 应用程序使用此选项来请求列表中的第一个数据源名称或列表中的下一个数据源名称。 方向 只能采用以下值:
|
| SQLCHAR * | ServerName | 输出 | 指向缓冲区的指针，用于保存检索到的数据源名称。 |
| SQLSMALLINT | BufferLength1 | 输入 | ServerName指向的缓冲区的最大长度 (以字符计)。 这应该小于或等于 SQL_MAX_DSN_LENGTH + 1。 |
| SQLSMALLINT * | NameLength1Ptr | 输出 | 指向存储 ServerName 中可返回的最大字符数的位置的指针。 |
| SQLCHAR * | 描述 | 输出 | 指向返回数据源描述的缓冲区的指针。 Db2 for i CLI 返回与编目到数据库管理系统 (DBMS) 的数据库相关联的 注释 字段。 |
| SQLSMALLINT | BufferLength2 | 输入 | 描述 缓冲区的最大长度 (以字符计)。 |
| SQLSMALLINT * | NameLength2Ptr | 输出 | 指向位置的指针，该函数返回可用于返回数据源描述的实际字符数。 |
用法
应用程序可以随时通过将 Direction 设置为 SQL_FETCH_FIRST 或 SQL_FETCH_NEXT 来调用此函数。
如果指定了 SQL_FETCH_FIRST ，那么将始终返回列表中的第一个数据库。
如果指定了 SQL_FETCH_NEXT:
- 直接跟随 SQL_FETCH_FIRST 调用，将返回列表中的第二个数据库
- 在任何其他
SQLDataSources()调用之前，将返回列表中的第一个数据库 - 当列表中没有更多数据库时，将返回 SQL_NO_DATA_FOUND。 如果再次调用该函数，那么将返回第一个数据库。
- 任何其他时间，将返回列表中的下一个数据库。
返回码
- SQL_SUCCESS
- sql_success_with_info
- SQL_ERROR
- sql_invalid_handle
- sql_noo_data_found
错误状态
| SQLSTATE | 描述 | 说明 |
|---|---|---|
| 01004 | 数据已截断 | 自变量 ServerName 中返回的数据源名称比自变量 BufferLength1中指定的值长。 自变量 NameLength1Ptr 包含完整数据源名称的长度。 （函数返回 SQL_SUCCESS_WITH_INFO。） 自变量 描述 中返回的数据源名称比自变量 BufferLength2中指定的值长。 自变量 NameLength2Ptr 包含完整数据源描述的长度。 （函数返回 SQL_SUCCESS_WITH_INFO。） |
| 58004 | 意外的系统故障 | 不可恢复的系统错误。 |
| HY000 | 一般错误 | 发生了错误，没有为其定义特定 SQLSTATE ，也没有为其定义特定 SQLSTATE。 SQLError() 在参数 ErrorMsg 中返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配失败 | Db2 for i CLI 无法分配支持处理或完成功能所需的内存。 |
| HY009 | 参数值无效 | 参数 ServerName, NameLength1Ptr, Description, 或 NameLength2Ptr 是一个空指针。 方向的值无效。 |
| HY013 | 意外内存处理错误 | Db2 for i CLI 无法访问支持处理或完成该功能所需的内存。 |
| HY103 | 方向选项超出范围 | 为自变量 Direction 指定的值不等于 SQL_FETCH_FIRST 或 SQL_FETCH_NEXT。 |
授权
无。
示例
注: 通过使用代码示例，您同意 代码许可证和免责声明信息的条款。
/* From CLI sample datasour.c */
/* ... */
#include <stdio.h>
#include <stdlib.h>
#include <sqlcli1.h>
#include "samputil.h" /* Header file for CLI sample code */
/* ... */
/*******************************************************************
** main
** - initialize
** - terminate
*******************************************************************/
int main() {
SQLHANDLE henv ;
SQLRETURN rc ;
SQLCHAR source[SQL_MAX_DSN_LENGTH + 1], description[255] ;
SQLSMALLINT buffl, desl ;
/* ... */
/* allocate an environment handle */
rc = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv ) ;
if ( rc != SQL_SUCCESS ) return( terminate( henv, rc ) ) ;
/* list the available data sources (servers) */
printf( "The following data sources are available:\n" ) ;
printf( "ALIAS NAME Comment(Description)\n" ) ;
printf( "----------------------------------------------------\n" ) ;
while ( ( rc = SQLDataSources( henv,
SQL_FETCH_NEXT,
source,
SQL_MAX_DSN_LENGTH + 1,
&buffl,
description,
255,
&desl
)
) != SQL_NO_DATA_FOUND
) printf( "%-30s %s\n", source, description ) ;
rc = SQLFreeHandle( SQL_HANDLE_ENV, henv ) ;
if ( rc != SQL_SUCCESS ) return( terminate( henv, rc ) ) ;
return( SQL_SUCCESS ) ;
}