SQLConnect-连接到数据源

SQLConnect() 建立与目标数据库的连接。应用程序可以选择提供目标 SQL 数据库，授权名称和认证字符串。

在调用此函数之前，必须调用 SQLAllocConnect() 。

必须先调用此函数，然后才能调用 SQLAllocStmt()。

Unicode (UTF-16) 等效: 此函数还可以与 Unicode (UTF-16) 字符集配合使用。相应的 Unicode 函数是 SQLConnectW() 。有关 DB2® CLI 的 Unicode 支持的更多信息，请参阅 Db2 for i CLI 中的 Unicode 。

语法

SQLRETURN SQLConnect (SQLHDBC         hdbc,
                      SQLCHAR         *szDSN,
                      SQLSMALLINT     cbDSN,
                      SQLCHAR         *szUID,
                      SQLSMALLINT     cbUID,
                      SQLCHAR         *szAuthStr,
                      SQLSMALLINT     cbAuthStr);

函数自变量

表 1. SQLConnect 参数
数据类型	自变量	使用	描述
SQLHDBC	hdbc	输入	连接句柄。
SQLCHAR *	szDSN	输入	数据源: 数据库的名称或别名。
SQLSMALLINT	cbDSN	输入	szDSN 参数的内容长度。
SQLCHAR *	szUID	输入	授权名称 (用户标识)。
SQLSMALLINT	cbUID	输入	szUID 参数的内容长度。
SQLCHAR *	szAuthStr	输入	认证字符串 (密码)。
SQLSMALLINT	cbAuthStr	输入	szAuthStr 参数内容的长度。

用法

您可以使用 SQLSetConnectOption()在应用程序中定义各种连接特征 (选项)。

SQLConnect() 的输入长度参数（cbDSN, cbUID、cbAuthStr）可以设置为相关数据的实际长度 - 此不包含任何空结束符 - 或者设置为 SQL_NTS，以指示相关数据为空结束符。

除非将 szDSN 和 szUID 自变量值括在引号内，否则将在处理前除去这些自变量值的前导和尾部空格。

输入参数 szUID 和 szAuthStr 区分大小写。

当以服务器模式运行时，必须同时传递 szUID 和 szAuthStr 才能代表当前用户以外的用户 ID 运行连接。如果参数为 NULL 或两者均为 NULL ，那么将使用对运行 CLI 程序的当前作业有效的用户标识来启动连接。

必须已在系统上定义数据源才能使连接功能工作。在 IBM i 平台上，可以使用 "处理关系数据库目录条目"(WRKRDBDIRE) 命令确定已定义的数据源，并可选择定义其他数据源。

如果应用程序未提供目标数据库 (szDSN) ，那么 CLI 将使用本地数据库作为缺省值。

与 *LOCAL 关系数据库的非服务器方式连接必须为连接 szUID 指定 NULL 或当前用户。在这种情况下，不会验证密码。使用非服务器方式连接时，应用程序不应从用户获取连接 szUID 作为输入，因为 SQLConnect 不会验证与连接关联的密码。

返回码

SQL_SUCCESS
sql_success_with_info
SQL_ERROR
sql_invalid_handle

诊断

表 2。 SQLConnect SQLSTAT
SQLSTATE	描述	说明
08001	无法连接到数据源	驱动程序无法与数据源 (服务器) 建立连接。
08002	连接正在使用中	指定的 hdbc 已用于与数据源建立连接，并且该连接仍处于打开状态。
08004	数据源已拒绝建立连接	数据源 (服务器) 已拒绝建立连接。
28000	授权规范无效	为参数 szUID 指定的值或为参数 szAuthStr 指定的值违反了数据源定义的限制。
58004	系统错误	不可恢复的系统错误。
HY001	内存分配失败	驱动程序无法分配支持功能处理或完成所需的内存。
HY009	参数值无效	为自变量 cbDSN 指定的值小于 0 ，但不等于 SQL_NTS ，并且自变量 szDSN 不是空指针。为自变量 cbUID 指定的值小于 0 ，但不等于 SQL_NTS ，并且自变量 szUID 不是空指针。为参数 cbAuthStr 指定的值小于 0，但不等于 SQL_NTS，并且参数 szAuthStr 不是空指针。在 szDSN、szUID 或 szAuthStr 参数中发现了不匹配的双引号（"）。
HY013 *	内存管理问题	驱动程序无法访问支持处理或完成功能所需的内存。
HY501 *	无效的数据源名称	在自变量 szDSN中指定了无效的数据源名称。

限制

不支持 IBM® DBMS 的隐式连接（或默认数据库）选项。必须先调用 SQLConnect() ，然后才能处理任何 SQL 语句。 Db2 for i 不支持在单个作业中多个同时连接到同一数据源。

在较新发行版上使用 Db2 for i CLI 时， SQLConnect() 可能会迂到 SQL0144 消息。这指示数据源 (服务器) 具有必须删除的过时 SQL 程序包。要删除这些软件包，请在数据源上运行以下命令:

   DLTSQLPKG SQLPKG(QGPL/QSQCLI*)

下一个 SQLConnect() 将创建新的 SQL 程序包。

示例

请参阅 SQLAllocEnv -分配环境句柄中的示例。

SQLConnect-连接到数据源

语法

函数自变量

用法

返回码

诊断

限制

示例

引用