SQLGetConnectAttr 函式
一致性
引進版本：ODBC 3.0 標準合規性：ISO 92
摘要
SQLGetConnectAttr 會傳回連接屬性的目前設定。
注意
如需 Driver Manager 在 ODBC 3*.x* 應用程式使用 ODBC 2*.x* 驅動程式時將此函式對應至哪些資訊，請參閱 對應應用程式回溯相容性的 取代函式。
語法
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
引數
ConnectionHandle
[輸入] 連線控制代碼。
屬性
[輸入]要擷取的屬性。
ValuePtr
[輸出]記憶體指標，用來傳回 Attribute 所 指定屬性的目前值。 對於整數類型屬性，某些驅動程式可能只會寫入較低的 32 位或 16 位緩衝區，並將較高順序的位維持不變。 因此，應用程式應該使用 SQLULEN 的緩衝區，並將值初始化為 0，再呼叫此函式。
如果 ValuePtr 為 Null， StringLengthPtr 仍會傳回可供 ValuePtr 指向 的緩衝區中傳回的位元組總數（不包括字元資料的 Null 終止字元）。
BufferLength
[輸入]如果 Attribute 是 ODBC 定義的屬性，而 ValuePtr 指向字元字串或二進位緩衝區，則這個引數應該是 * ValuePtr 的長度。 如果 Attribute 是 ODBC 定義的屬性，而 *ValuePtr 是整數， 則會忽略 BufferLength 。 如果 *ValuePtr 中的 值是 Unicode 字串（呼叫 SQLGetConnectAttrW 時）， BufferLength 引數必須是偶 數。
如果 Attribute 是驅動程式定義的屬性，應用程式會藉由設定 BufferLength 引數，將屬性的性質指示給驅動程式管理員。 BufferLength 可以具有下列值：
如果 *ValuePtr 是字元字串的指標， BufferLength 是字串的長度。
如果 *ValuePtr 是二進位緩衝區的指標，應用程式會將SQL_LEN_BINARY_ATTR（ length ） 宏的結果放在 BufferLength 中 。 這會在 BufferLength 中 放置負值。
如果 *ValuePtr 是字元字串或二進位字串以外的值指標， BufferLength 的值應該SQL_IS_POINTER。
如果 *ValuePtr 包含固定長度的資料類型， BufferLength 會視需要SQL_IS_INTEGER或SQL_IS_UINTEGER。
StringLengthPtr
[輸出]緩衝區的指標，用來傳回 * ValuePtr 中傳回的位元組總數（不包括 Null 終止字元）。 如果屬性值是字元字串，而且可傳回的位元組數目大於 BufferLength 減去 Null 終止字元的長度，則 *ValuePtr 中的資料 會截斷為 BufferLength 減去 Null 終止字元的長度，而且由驅動程式以 Null 終止。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLGetConnectAttr 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 SQLGetDiagRec 和 ConnectionHandle 的 Handle SQL_HANDLE_DBC Type 呼叫 SQLGetDiagRec ，即可從診斷資料結構取得相關聯的 SQLSTATE 值。 下表列出 SQLGetConnectAttr 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字串資料，右截斷 | 在 * ValuePtr 中傳回的資料被截斷為 BufferLength 減去 Null 終止字元的長度。 未建構字串值的長度會在 *StringLengthPtr 中 傳回。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08003 | 連線未開啟 | （DM） 已指定需要開啟連線的屬性值 。 |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 SQLGetDiagField 自 變數 MessageText 從診斷資料結構傳回的錯誤訊息會描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY010 | 函式順序錯誤 | （DM） 已針對 ConnectionHandle 呼叫 SQLBrowseConnect ，並傳回SQL_NEED_DATA。 此函式是在 SQLBrowseConnect 傳回SQL_SUCCESS_WITH_INFO或SQL_SUCCESS之前 呼叫的。 （DM） 已針對 ConnectionHandle 呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 不正確字串或緩衝區長度 | （DM） *ValuePtr 是字元字串，BufferLength 小於零，但不等於SQL_NTS。 |
| HY092 | 不正確屬性/選項識別碼 | 針對引數 Attribute 指定的值對驅動程式支援的 ODBC 版本無效。 |
| HY114 | 驅動程式不支援連線層級非同步函式執行 | （DM） 應用程式嘗試為不支援非同步連接作業的驅動程式啟用非同步函式執行，SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE。 |
| HY117 | 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。 |
| HYC00 | 未實作選擇性功能 | 為引數 Attribute 指定的值是驅動程式所支援之 ODBC 版本的有效 ODBC 連接屬性，但驅動程式不支援。 |
| HYT01 | 已超過連線逾時 | 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 對應至 ConnectionHandle 的 驅動程式不支援 函式。 |
註解
如需連接屬性的一般資訊，請參閱 連接屬性 。
如需可設定的屬性清單，請參閱 SQLSetConnectAttr 。 請注意，如果 Attribute 指定傳回字串的屬性， ValuePtr 必須是字串緩衝區的指標。 傳回字串的最大長度，包括 Null 終止字元，將是 BufferLength 位元組。
根據 屬性，應用程式不需要在呼叫 SQLGetConnectAttr 之前建立連線。 不過，如果 呼叫 SQLGetConnectAttr 且指定的屬性沒有預設值，而且先前呼叫 SQLSetConnectAttr 尚未設定， SQLGetConnectAttr 會傳回SQL_NO_DATA。
如果 Attribute SQL_ATTR_ TRACE 或 SQL_ATTR_ TRACEFILE， ConnectionHandle 就不需要有效，而且 如果 ConnectionHandle 無效，SQLGetConnectAttr 將不會傳回SQL_ERROR或SQL_INVALID_HANDLE。 這些屬性會套用至所有連線。 如果另一個引數無效，SQLGetConnectAttr 會傳回SQL_ERROR或SQL_INVALID_HANDLE。
雖然應用程式可以使用 SQLSetConnectAttr 來設定語句屬性 ，但應用程式無法使用 SQLGetConnectAttr 來擷取語句屬性值;它必須呼叫 SQLGetStmtAttr 來擷取語句屬性的設定。
SQL_ATTR_AUTO_IPD和SQL_ATTR_CONNECTION_DEAD連接屬性都可以由對 SQLGetConnectAttr 的呼叫 傳回，但無法由對 SQLSetConnectAttr 的呼叫 設定。
注意
SQLGetConnectAttr 沒有非同步支援 。 實作 SQLGetConnectAttr 時，驅動程式可以藉由將從伺服器傳送或要求的資訊次數降至最低，以改善效能。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 傳回語句屬性的設定 | SQLGetStmtAttr 函式 |
| 設定連接屬性 | SQLSetConnectAttr 函式 |
| 設定環境屬性 | SQLSetEnvAttr 函式 |
| 設定語句屬性 | SQLSetStmtAttr 函式 |