SQLConnect 函數 (CLI)-連接至資料來源
用途
規格: | CLI 1.1 | ODBC 1.0 | ISO CLI |
當您呼叫 SQLConnect() 函數時,必須提供目標資料庫名稱。 當您建立與資料庫的非授信連線時,也必須指定資料庫鑑別的使用者 ID 及相關聯的密碼。
在使用 SQLAllocHandle()
函數配置陳述式控點之前,必須先建立連線。
語法
SQLRETURN SQLConnect (
SQLHDBC ConnectionHandle, /* hdbc */
SQLCHAR *ServerName, /* szDSN */
SQLSMALLINT ServerNameLength, /* cbDSN */
SQLCHAR *UserName, /* szUID */
SQLSMALLINT UserNameLength, /* cbUID */
SQLCHAR *Authentication, /* szAuthStr */
SQLSMALLINT AuthenticationLength); /* cbAuthStr */
函數引數
資料類型 | 引數 | 使用 | 說明 |
---|---|---|---|
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()
函數的輸入長度引數 (ServerNameLength、 UserNameLength、 AuthenticationLength) 可以設為元素中相關聯資料的實際長度 (SQLCHAR 或 SQLWCHAR) ,不包括任何空值終止字元。 您可以將長度引數設為 SQL_NTS ,以指出相關聯的資料以空值結尾。
ServerName 和 UserName 引數值不得包含任何空格字元。
CLI 驅動程式支援密碼有限制的特殊字元。
SQLConnect()
函數呼叫來配置陳述式控點 ( ServerName、 UserName及 Authentication 引數指標都設為 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
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);