符合性
推出版本：ODBC 3.0 標準合規：ISO 92
總結
SQLGetConnectAttr 回傳目前連線屬性的設定。
Note
欲了解更多關於當 ODBC 3*.x* 應用程式與 ODBC 2*.x* 驅動程式相符時，驅動程式管理器會將此功能對應到什麼，請參見「 應用程式向下相容性映射替換函式」。
Syntax
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
論點
ConnectionHandle
[輸入] 連線控制代碼。
Attribute
[輸入]屬性要取回。
ValuePtr
[輸出]一個指向記憶體的指標，用來回傳由 屬性指定的屬性目前值。 對於整數型屬性，有些驅動程式可能只寫入緩衝區的低 32 位元或 16 位元，而高階位元則保持不變。 因此，應用程式應先使用 SQLULEN 緩衝區，並在呼叫此函式前將該值初始化為 0。
若 ValuePtr 為 NULL，StringLengthPtr 仍會回傳 ValuePtr 指向緩衝區中可返回的總位元組數（不含字元資料的空終止字元）。
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 中可回傳的總位元組數（不含空終端字元）。 若屬性值為字串，且可回傳的位元組數大於 BufferLength 減去空終止字元長度，則 *ValuePtr 中的資料會截斷為 BufferLength 減去空終止字元長度，並由驅動程式進行空終止。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。
Diagnostics
當 SQLGetConnectAttr 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可以透過呼叫 SQLGetDiagRec 並設定 HandleType 為 SQL_HANDLE_DBC 和 Handle 為ConnectorHandle 來取得相關的 SQLSTATE 值。 下表列出 SQLGetConnectAttr 通常回傳的 SQLSTATE 值，並在此函式的情境中解釋每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 說明 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字串數據，右截斷 | *ValuePtr 中回傳的資料被截斷為 BufferLength 減去一個零終端字元的長度。 未截斷字串值的長度會以 *StringLengthPtr 回傳。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08003 | 線上未開啟 | （DM） 指定了一個需要開啟連線的 屬性 值。 |
| 08S01 | 通訊連結故障 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| HY000 | 一般誤差 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 診斷資料結構中以 SQLGetDiagField 中參數 MessageText 回傳的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY010 | 函式順序錯誤 | （DM） SQLBrowseConnect 被呼叫取得 ConnectionHandle 並回傳SQL_NEED_DATA。 此函式在 SQLBrowseConnect 回傳 SQL_SUCCESS_WITH_INFO 或 SQL_SUCCESS 之前就被呼叫。 （DM） SQLExecute、 SQLExecDirect 或 SQLMoreResults 被呼叫 ConnectionHandle 並回傳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 | 未實作選擇性功能 | 參數屬性所指定的 值是驅動 程式支援的 ODBC 版本的有效 ODBC 連線屬性，但驅動程式不支援。 |
| HYT01 | 連線已逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 對應至 ConnectionHandle 的驅動程式不支援 函式。 |
評論
關於連線屬性的一般資訊，請參見 連線屬性。
關於可設定屬性的清單，請參見 SQLSetConnectAttr。 注意，如果 Attribute 指定一個回傳字串的屬性， ValuePtr 必須是該字串緩衝區的指標。 回傳字串（包括空終止字元）的最大長度將是 BufferLength 位元組。
根據屬性不同，應用程式在呼叫 SQLGetConnectattr 前不必建立連線。 然而，若呼叫 SQLGetConnectAttr 且指定的屬性沒有預設值，且先前未被 SQLSetConnectAttr 設定， SQLGetConnectAttr 會回傳 SQL_NO_DATA。
若 Attribute SQL_ATTR_ TRACE 或 SQL_ATTR_ TRACEFILE，則 ConnectionHandle 不必有效，且 SQLGetConnectAttr 不會回傳 SQL_ERROR 或 SQL_INVALID_HANDLE，若 ConnectionHandle 無效。 這些屬性適用於所有連線。 如果有其他參數無效，SQLGetConnectAttr 會回傳 SQL_ERROR 或 SQL_INVALID_HANDLE。
雖然應用程式可以透過 SQLSetConnectAttr 設定語句屬性，但無法使用 SQLGetConnectAttr 來取得語句屬性值;必須呼叫 SQLGetStmtAttr 來取得陳述式屬性的設定。
SQL_ATTR_AUTO_IPD 與 SQL_ATTR_CONNECTION_DEAD 連線屬性皆可透過呼叫 SQLGetConnectAttr 回傳，但無法透過呼叫 SQLSetConnectAttr 來設定。
Note
SQLGetConnectAttr 沒有非同步支援。 在實作 SQLGetConnectAttr 時，驅動程式可以透過減少該資訊從伺服器傳送或請求的次數來提升效能。
相關函數
| 如需相關信息 | 看！ |
|---|---|
| 傳回語句屬性的設定 | SQLGetStmtAttr 函式 |
| 設定連線屬性 | SQLSetConnectAttr 函式 |
| 設定環境屬性 | SQLSetEnvAttr Function |
| 設定語句屬性 | SQLSetStmtAttr 函式 |