SQLConnect － 连接至数据源

用途

SQLConnect() 建立与目标数据库的连接。

在调用此函数之前，必须使用 SQLAllocHandle() 分配连接句柄。

在使用 SQLAllocHandle() 分配语句句柄之前，必须调用此函数。

语法

SQLRETURN   SQLConnect       (
                SQLHDBC           ConnectionHandle,  /* hdbc */
                SQLCHAR      *FAR ServerName,        /* szDSN */
                SQLSMALLINT       NameLength1,       /* cbDSN */
                SQLCHAR      *FAR UserName,          /* szUID */
                SQLSMALLINT       NameLength2,       /* cbUID */
                SQLCHAR      *FAR Authentication,    /* szAuthStr */
                SQLSMALLINT       NameLength3);      /* cbAuthStr */

函数自变量

表 36. SQLConnect 自变量

注意事项

未注册的用户（在 DB2eSYSUSERS 表中不存在的用户）当在 SQLGetDiagRec() CLI 函数调用期间试图连接到加密的 DB2 Everyplace 数据库时，将接收到警告消息 42704（未定义对象）。已注册的用户将不会接收到此警告。与此相反，在 SQLConnect() 函数调用期间，未注册和已注册的用户都能够连接至数据库，而不会接收到警告消息。

用法

SQLConnect() 可用来连接至不同位置的数据源。

要访问本地设备上的数据源，应将 ServerName 自变量设置为数据源名称。DB2 Everyplace 会忽略数据源名称，而访问本地数据源。

对于使用辅助存储设备的应用程序，ServerName 自变量接受指向在本地存在的 DataSource 位置的字符串，或接受在支持的辅助存储设备（如 IBM Microdrive、Sony Memory Stick、Compact Flash、SD Memory Card 或 MultiMediaCard）上的存储位置的字符串。ServerName 字符串的格式是：

ServerName=Device:/Path/DataSource

Device

这是在其上存储 DataSource 的设备的名称。保留字符 # 用来访问任何 Compact Flash (CF) Type II 存储设备（在具有 CF 支持的 Palm OS 设备上）。辅助存储器是使用保留字符 # 进行寻址的。#0 和 #1 指定要访问哪个辅助存储器槽。# 相当于 #0。例如：

ServerName=#:/storage/

DB2 Everyplace 连接至第一个 CF 槽中的 IBM Microdrive 的 storage 目录中的 DataSource。

Path

这是 Device 上 DataSource 的路径。当指定 Path 而未指定 Device:/ 时，使用相对于应用程序位置的本地文件系统路径。不应将文件写入卷的根目录中。某些介质类型不支持在根目录中放入文件。例如：

ServerName=dir1/dir2/DATA1

注意:

DB2 Everyplace 中没有路径长度限制。

如果应用程序位于本地文件系统上的 /myapp 中，则 DB2 Everyplace 连接至 /myapp/dir1/dir2/ 中的 DataSource。DataSource 名 DATA1 被忽略。

DataSource

可选：要连接的数据源的名称。DB2 Everyplace 忽略此名称。

要使用“远程查询和存储过程”适配器访问远程存储过程， 使用 ServerName 自变量来标识数据库的位置和名称。对于使用“远程查询”和“存储过程”适配器来存取远程数据库的应用程序，ServerName 自变量接受以下 URL 格式：

http://IPAddress:portNumber/path?DB=DataSource 

如果使用 Windows CE 对象存储器而不是常规文件系统，则：

• 将 CLI 函数 SQLConnect 的路径参数设置为 "@:\"

或

• 在 CLP 中，执行“connect to @:\”

Windows CE 对象存储器中没有“目录”概念。 当使用对象存储器时，用户不能定义在其中创建表的目录或路径。 在相同的名称空间中创建对象存储器中的所有表。 由于此限制，不能同时建立多个与对象存储器的连接。 在文件系统的根路径中创建连接串行化目的的锁文件。

当使用对象存储器时，与使用常规文件系统时不同，不能手工删除 DB2 Everyplace 文件。

示例

连接至以本地方式存在于 c:\dir1\dir2\ 中的数据源。数据源名称 DS1 被忽略：

ServerName=c:/dir1/dir2/DS1

连接至使用 UNIX 文件系统表示法且以本地方式存在于 /dir1/dir2/ 中的数据源：

ServerName=/dir1/dir2/

连接至以本地方式存在于相对于应用程序路径的 dir1\ 目录中的数据源。如果应用程序位于 c:\myapp\ 中，则访问 c:\myapp\dir1\ 数据源：

ServerName=dir1\

连接至辅助存储器槽 1 中的存储内存上的 /dir1/ 目录中的数据源：

ServerName=#1:/dir1/

使用远程查询和存储过程适配器连接至端口 8080 上的 DB2 Everyplace Sync Server 192.168.0.1 以及 mysample 数据库。

ServerName=
 http://192.168.0.1:8080/db2e/servlet/com.ibm.mobileservices.adapter
                .agent.AgentServlet?DB=mysample

使用 Windows CE 存储器连接到数据源。

ServerName=@:\
 

连接串行化

有关连接串行化的信息，请参阅连接串行化。

连接认证

数据库加密需要基本用户认证。DB2 Everyplace 使用“用户名”和“认证”来在连接时认证用户。

认证按如下方式工作：如果 DB2eSYSUSERS 目录表在 SQLConnect 连接至的数据库中不存在，则忽略 “用户名”和“认证”信息。DB2 Everyplace 将已注册和未注册用户区别开来。 已注册用户是通过 GRANT SQL 语句添加的且在 DB2eSYSUSERS 表中列示的用户。 连接时，如果有 DB2eSYSUSERS 表且“用户名”属于已注册用户，则尝试认证。 如果“认证”参数中给定的密码不正确，则返回错误（42505）。 如果“用户名”是未注册的，则 SQLConnect 函数将成功。 然而，对 SQLGetDiagRec 的后续调用将返回警告 42704（未定义对象）。这允许应用程序区分成功连接的已注册用户和成功连接的未注册用户。 有关更多信息，请参阅本地数据加密的概述、*** 和GRANT。

返回码

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

诊断

表 37. SQLConnect SQLSTATE

限制

在可以执行任何 SQL 语句之前，必须调用 SQLConnect()。

相关概念

• 连接串行化
• SQLAllocHandle － 分配句柄
• SQLDisconnect － 与数据源断开连接

相关参考

• DB2 CLI 函数描述的关键
• DB2 CLI 函数摘要
• SQLAllocHandle － 分配句柄
• SQLDisconnect － 与数据源断开连接