SQLConnect 函數 (CLI)-連接至資料來源

建立與目標資料庫的連線或信任連線。

用途

規格: CLI 1.1 ODBC 1.0 ISO CLI

當您呼叫 SQLConnect() 函數時,必須提供目標資料庫名稱。 當您建立與資料庫的非授信連線時,也必須指定資料庫鑑別的使用者 ID 及相關聯的密碼。

在使用 SQLAllocHandle() 函數配置陳述式控點之前,必須先建立連線。

Unicode Equivalent: 此函數也可以與 Unicode 字集搭配使用。 對應的 Unicode 函數為 SQLConnectW()。 如需 ANSI 至 Unicode 函數對映的相關資訊,請參閱 Unicode 函數 (CLI)

語法

SQLRETURN   SQLConnect       (
               SQLHDBC           ConnectionHandle,       /* hdbc */
               SQLCHAR           *ServerName,             /* szDSN */
               SQLSMALLINT       ServerNameLength,       /* cbDSN */
               SQLCHAR           *UserName,               /* szUID */
               SQLSMALLINT       UserNameLength,         /* cbUID */
               SQLCHAR           *Authentication,         /* szAuthStr */
               SQLSMALLINT       AuthenticationLength);  /* cbAuthStr */

函數引數

表 1. SQLConnect 引數
資料類型 引數 使用 說明
SQLHDBC ConnectionHandle 輸入(input) 連線控點
SQLCHAR * ServerName 輸入(input) 資料來源: 資料庫的名稱或別名。
SQLSMALLINT ServerName長度 輸入(input) 儲存 ServerName 引數所需的 SQLCHAR 元素 (或此函數的 Unicode 變式的 SQLWCHAR 元素) 數目。
SQLCHAR * UserName 輸入(input) 授權名稱 (使用者 ID)
SQLSMALLINT UserName長度 輸入(input) 儲存 UserName 引數所需的 SQLCHAR 元素 (或此函數 Unicode 變式的 SQLWCHAR 元素) 數目。
SQLCHAR * 鑑別 輸入(input) 鑑別-字串 (密碼)
SQLSMALLINT AuthenticationLength 輸入(input) 儲存 Authentication 引數所需的 SQLCHAR 元素 (或此函數 Unicode 變式的 SQLWCHAR 元素) 數目。

使用情形

目標資料庫名稱也稱為資料來源名稱或資料庫別名。 應用程式可以透過呼叫 SQLDataSources() 函數來取得可用於連線的資料庫清單。

SQLConnect() 函數的輸入長度引數 (ServerNameLengthUserNameLengthAuthenticationLength) 可以設為元素中相關聯資料的實際長度 (SQLCHAR 或 SQLWCHAR) ,不包括任何空值終止字元。 您可以將長度引數設為 SQL_NTS ,以指出相關聯的資料以空值結尾。

ServerNameUserName 引數值不得包含任何空格字元。

CLI 驅動程式支援密碼有限制的特殊字元。

使用 CLI 驅動程式的儲存程序可以發出含有空值引數的 SQLConnect() 函數呼叫來配置陳述式控點 ( ServerNameUserNameAuthentication 引數指標都設為 NULL ,且它們各自的長度引數都設為 0 或 SQL_NTS):
cliRC = SQLConnect(hdbc, NULL, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);
CLI 應用程式中,包括使用 CLI 驅動程式的儲存程序,您無法在沒有連線控點的情況下配置陳述式控點。 透過使用空值引數呼叫 SQLConnect() 函數,您會隱含地建立連線控點。

具有空值引數的 SQLConnect() 函數呼叫仍然需要先呼叫 SQLAllocHandle() 函數。 不過, SQLEndTran() 函數不需要先呼叫 SQLDisconnect() 函數。

若要建立信任連線,請在呼叫 SQLConnect() 函數之前指定 SQL_ATTR_USE_TRUSTED_CONTEXT 連線屬性。 如果資料庫伺服器不接受連線作為信任連線,則會傳回訊息。

回覆碼

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

表 2. SQLConnect SQLSTATE
SQLSTATE 說明 說明
01679 無法建立信任連線。 CLI 要求信任連線,但連線的信任屬性不符合資料庫伺服器上的任何信任環境定義物件。 容許連線,但它是一般連線,而不是授信連線。
08001 無法與資料來源連接。 CLI 無法建立與資料來源 (伺服器) 的連線。

已拒絕連線要求,因為已存在透過內嵌式 SQL 建立的現有連線。

08002 連接使用中。 指定的 ConnectionHandle 已用來建立與資料來源的連線,且連線仍然開啟。
08004 應用程式伺服器拒絕建立連線。 資料來源 (伺服器) 拒絕建立連線。
28000 無效的授權規格。 指定給引數 UserName 的值或指定給引數 Authentication 的值違反資料來源定義的限制。
58004 非預期的系統失效。 無法復原的系統錯誤。
HY001 記憶體配置失敗。 Db2® CLI 無法配置支援執行或完成函數所需的記憶體。 這可能是處理層次記憶體已被應用程式處理耗盡。 如需處理層次記憶體限制的相關資訊,請查閱作業系統配置。
HY013 非預期的記憶體處理錯誤。 Db2 CLI 無法存取支援執行或完成函數所需的記憶體。
HY090 無效的字串或緩衝區長度。 指定給引數 ServerName長度 的值小於 0 ,但不等於 SQL_NTS ,且引數 ServerName 不是空值指標。

指定給引數 UserNameLength 的值小於 0 ,但不等於 SQL_NTS ,且引數 UserName 不是空值指標。

指定給引數 AuthenticationLength 的值小於 0 ,但不等於 SQL_NTS ,且引數 Authentication 不是空值指標。

HY501 無效的資料來源名稱。 在引數 ServerName中指定無效的資料來源名稱。
HYT00 逾時過期。 在資料來源傳回結果集之前,逾時期間已過期。 可以使用 SQLSetStmtAttr()的 SQL_ATTR_QUERY_TIMEOUT 屬性來設定逾時期間。
附註: 此 SQLSTATE 僅適用於 .Net 應用程式。

限制

  • 不支援 IBM® 資料庫的隱含連線 (或預設資料庫) 選項。
  • 必須先建立連線,才能發出任何 SQL 陳述式。
  • 當指定憑證鑑別時,您無法在 SQLConnect() 函數中指定使用者 ID 和密碼引數 (鑑別參數)。 當 db2cli.ini 配置檔或 IBM Data Server Driver 配置檔中的 Authentication 關鍵字設為 CERTIFICATE時,會指定憑證鑑別。

範例

  /* connect to the database */
  cliRC = SQLConnect(hdbc,
                     (SQLCHAR *)db1Alias,
                     SQL_NTS,
                     (SQLCHAR *)user,
                     SQL_NTS,
                     (SQLCHAR *)pswd,
                     SQL_NTS);