SQLSetConnectAttr
適用於:SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse Analytics Analytics Platform System (PDW)
SQL Server Native Client ODBC 驅動程式會忽略SQL_ATTR_CONNECTION_TIMEOUT的設定。
也會忽略SQL_ATTR_TRANSLATE_LIB;不支援指定另一個翻譯連結庫。 若要讓應用程式輕鬆地移植到使用適用於 SQL Server 的 Microsoft ODBC 驅動程式,任何以 SQL_ATTR_TRANSLATE_LIB 設定的值都會複製到驅動程式管理員中的緩衝區和緩衝區中。
SQL Server Native Client ODBC 驅動程式會將可重複的讀取交易隔離實作為可串行化。
SQL Server 2005 (9.x) 引進了對新交易隔離屬性的支援,SQL_COPT_SS_TXN_ISOLATION。 將SQL_COPT_SS_TXN_ISOLATION設定為 SQL_TXN_SS_SNAPSHOT表示交易將在快照集隔離等級下進行。
注意
SQL_ATTR_TXN_ISOLATION可用來設定除了SQL_TXN_SS_SNAPSHOT以外的所有其他隔離等級。 如果您想要使用快照集隔離,您必須透過SQL_COPT_SS_TXN_ISOLATION設定SQL_TXN_SS_SNAPSHOT。 不過,您可以使用SQL_ATTR_TXN_ISOLATION或SQL_COPT_SS_TXN_ISOLATION來擷取隔離等級。
將 ODBC 語句屬性升階至連接屬性可能會產生非預期的結果。 要求伺服器數據指標處理結果集處理的語句屬性可以升階至連線。 例如,將 ODBC 語句屬性設定SQL_ATTR_CONCURRENCY為比預設SQL_CONCUR_READ_ONLY更嚴格的值,會指示驅動程式針對連接上提交的所有語句使用動態數據指標。 在連接上的語句上執行 ODBC 目錄函式會傳回SQL_SUCCESS_WITH_INFO和診斷記錄,指出數據指標行為已變更為只讀。 嘗試在相同連線上執行包含 COMPUTE 子句的 Transact-SQL SELECT 語句失敗。
SQL Server Native Client ODBC 驅動程式支援一些 sqlncli.h 中定義的 ODBC 連接屬性的驅動程式特定擴充功能。 SQL Server Native Client ODBC 驅動程式可能需要在連接之前設定屬性,或者如果屬性已經設定,它可能會忽略該屬性。 下表列出限制。
SQL Server 屬性 | 在與伺服器連接之前或之後設定 |
---|---|
SQL_COPT_SS_ANSI_NPW | 之前 |
SQL_COPT_SS_APPLICATION_INTENT | 之前 |
SQL_COPT_SS_ATTACHDBFILENAME | 之前 |
SQL_COPT_SS_BCP | 之前 |
SQL_COPT_SS_BROWSE_CONNECT | 之前 |
SQL_COPT_SS_BROWSE_SERVER | 之前 |
SQL_COPT_SS_CONCAT_NULL | 之前 |
SQL_COPT_SS_CONNECTION_DEAD | 之後 |
SQL_COPT_SS_ENCRYPT | 之前 |
SQL_COPT_SS_ENLIST_IN_DTC | 之後 |
SQL_COPT_SS_ENLIST_IN_XA | 之後 |
SQL_COPT_SS_FALLBACK_CONNECT | 之前 |
SQL_COPT_SS_FAILOVER_PARTNER | 之前 |
SQL_COPT_SS_INTEGRATED_SECURITY | 之前 |
SQL_COPT_SS_MARS_ENABLED | 之前 |
SQL_COPT_SS_MULTISUBNET_FAILOVER | 之前 |
SQL_COPT_SS_OLDPWD | 之前 |
SQL_COPT_SS_PERF_DATA | 之後 |
SQL_COPT_SS_PERF_DATA_LOG | 之後 |
SQL_COPT_SS_PERF_DATA_LOG_NOW | 之後 |
SQL_COPT_SS_PERF_QUERY | 之後 |
SQL_COPT_SS_PERF_QUERY_INTERVAL | 之後 |
SQL_COPT_SS_PERF_QUERY_LOG | 之後 |
SQL_COPT_SS_PRESERVE_CURSORS | 之前 |
SQL_COPT_SS_QUOTED_IDENT | 或 |
SQL_COPT_SS_TRANSLATE | 或 |
SQL_COPT_SS_TRUST_SERVER_CERTIFICATE | 之前 |
SQL_COPT_SS_TXN_ISOLATION | 或 |
SQL_COPT_SS_USE_PROC_FOR_PREP | 或 |
SQL_COPT_SS_USER_DATA | 或 |
SQL_COPT_SS_WARN_ON_CP_ERROR | 之前 |
針對相同會話、資料庫或 SQL Server 狀態使用連線前屬性和對等的 Transact-SQL 命令,可能會產生非預期的行為。 例如,
SQLSetConnectAttr(SQL_COPT_SS_QUOTED_IDENT, SQL_QI_ON) // turn ON via attribute
SQLDriverConnect(...);
SQLExecDirect("SET QUOTED_IDENTIFIER OFF") // turn OFF via Transact-SQL
SQLSetConnectAttr(SQL_ATTR_CURRENT_CATALOG, ...) // restores to pre-connect attribute value
SQL_COPT_SS_ANSI_NPW
SQL_COPT_SS_ANSI_NPW啟用或停用比較和串連、字元數據類型填補和警告中使用NULL的 ISO 處理。 如需詳細資訊,請參閱 SET ANSI_NULLS、SET ANSI_PADDING、SET ANSI_WARNINGS和 SET CONCAT_NULL_YIELDS_NULL。
值 | Description |
---|---|
SQL_AD_ON | 預設。 聯機會使用 ANSI 預設行為來處理 NULL 比較、填補、警告和 NULL 串連。 |
SQL_AD_OFF | 聯機會使用 SQL Server 定義的 NULL 處理、字元數據類型填補和警告。 |
如果您使用連線共用,SQL_COPT_SS_ANSI_NPW應該在 連接字串 中設定,而不是使用 SQLSetConnectAttr。 建立連線之後,使用連接共享時,任何變更此屬性的嘗試都會以無訊息方式失敗。
SQL_COPT_SS_APPLICATION_INTENT
宣告連接到伺服器時的應用程式工作負載類型。 可能的值為 Readonly 和 ReadWrite。 例如:
SQLSetConnectAttr(hdbc, SQL_COPT_SS_APPLICATION_INTENT, TEXT("Readonly"), SQL_NTS)
預設值為 ReadWrite。 如需 SQL Server Native Client 對 Always On 可用性群組 AG 支援的詳細資訊,請參閱 SQL Server Native Client Support for High Availability, Disaster Recovery。
SQL_COPT_SS_ATTACHDBFILENAME
SQL_COPT_SS_ATTACHDBFILENAME指定可附加資料庫的主要檔名。 此資料庫會附加,而且變成連接的預設資料庫。 若要使用SQL_COPT_SS_ATTACHDBFILENAME您必須將資料庫的名稱指定為連接屬性的值,SQL_ATTR_CURRENT_CATALOG或 SQLDriverConnect 的 DATABASE = 參數中。 如果資料庫先前已附加,SQL Server 將不會重新附加它。
值 | Description |
---|---|
對字元字串的 SQLPOINTER | 字串包含要附加之資料庫的主要檔名。 包含檔案的完整路徑名稱。 |
SQL_COPT_SS_BCP
SQL_COPT_SS_BCP可在連線上啟用大量複製函式。 如需詳細資訊,請參閱 大量複製函式。
值 | Description |
---|---|
SQL_BCP_OFF | 預設。 線上上無法使用大量複製函式。 |
SQL_BCP_ON | 大量複製函式可在連線上使用。 |
SQL_COPT_SS_BROWSE_CONNECT
這個屬性是用來自定義 SQLBrowseConnect 所傳回的結果集。 SQL_COPT_SS_BROWSE_CONNECT會啟用或停用從列舉的 SQL Server 實例傳回其他資訊。 這可以包含資訊,例如伺服器是否為叢集、不同實例的名稱,以及版本號碼。
值 | Description |
---|---|
SQL_MORE_INFO_NO | 預設。 傳回伺服器的清單。 |
SQL_MORE_INFO_YES | SQLBrowseConnect 會傳回伺服器屬性的擴充字串。 |
SQL_COPT_SS_BROWSE_SERVER
這個屬性是用來自定義 SQLBrowseConnect 所傳回的結果集。 SQL_COPT_SS_BROWSE_SERVER指定 SQLBrowseConnect 傳回資訊的伺服器名稱。
值 | Description |
---|---|
computername | SQLBrowseConnect 會傳回指定電腦上的 SQL Server 實例清單。 雙反斜杠 (\\) 不應該用於伺服器名稱(例如,應該使用 \\MyServer,而不是 \\MyServer)。 |
NULL | 預設。 SQLBrowseConnect 會傳回網域中所有伺服器的資訊。 |
SQL_COPT_SS_CONCAT_NULL
SQL_COPT_SS_CONCAT_NULL啟用或停用串連字串時使用NULL的 ISO 處理。 如需詳細資訊,請參閱 SET CONCAT_NULL_YIELDS_NULL。
值 | Description |
---|---|
SQL_CN_ON | 預設。 連接會在串連字串時,使用 ISO 預設行為來處理 NULL 值。 |
SQL_CN_OFF | 連接會在串連字串時,使用 SQL Server 定義的行為來處理 NULL 值。 |
SQL_COPT_SS_ENCRYPT
控制連接的加密。
加密會使用伺服器上的憑證。 除非連線屬性 SQL_COPT_SS_TRUST_SERVER_CERTIFICATE設定為 SQL_TRUST_SERVER_CERTIFICATE_YES,否則 連接字串 包含 “TrustServerCertificate=yes” 的聯機屬性,否則必須由證書頒發機構單位驗證。 如果上述任一條件成立,如果伺服器上沒有憑證,伺服器所產生的憑證和簽署即可用來加密連線。
值 | Description |
---|---|
SQL_EN_ON | 線上將會加密。 |
SQL_EN_OFF | 線上將不會加密。 這是預設值。 |
SQL_COPT_SS_ENLIST_IN_DTC
用戶端會呼叫 Microsoft Distributed Transaction Coordinator (MS DTC) OLE DB ITransactionDispenser::BeginTransaction 方法來開始 MS DTC 交易,並建立代表交易的 MS DTC 交易物件。 然後,應用程式會使用 SQL_COPT_SS_ENLIST_IN_DTC 選項呼叫 SQLSetConnectAttr ,以將交易物件與 ODBC 連接產生關聯。 所有相關資料庫活動都會在 MS DTC 交易的保護下執行。 應用程式會呼叫 具有 SQL_DTC_DONE 的 SQLSetConnectAttr ,以結束連線的 DTC 關聯。
值 | Description |
---|---|
DTC 物件* | MS DTC OLE 交易物件,指定要匯出至 SQL Server 的交易。 |
SQL_DTC_DONE | 分隔 DTC 交易的結尾。 |
SQL_COPT_SS_ENLIST_IN_XA
若要使用符合 XA 規範的交易處理器 (TP) 開始 XA 交易,用戶端會呼叫 Open Group tx_begin 函式。 然後,應用程式會使用TRUE的 SQL_COPT_SS_ENLIST_IN_XA 參數呼叫 SQLSetConnectAttr ,以將 XA 交易與 ODBC 連接產生關聯。 所有相關資料庫活動都會在 XA 交易的保護下執行。 若要結束與 ODBC 連接的 XA 關聯,客戶端必須使用 FALSE 的 SQL_COPT_SS_ENLIST_IN_XA 參數呼叫 SQLSetConnectAttr 。 如需詳細資訊,請參閱Microsoft分散式交易協調器檔。
SQL_COPT_SS_FALLBACK_CONNECT
不再支援這個屬性。
SQL_COPT_SS_FAILOVER_PARTNER
用來指定或擷取用於 SQL Server 中資料庫鏡像的故障轉移夥伴名稱,而且它是一個 Null 終止的字元字串,在最初建立 SQL Server 的連線之前必須設定。
建立連線之後,應用程式可以使用 SQLGetConnectAttr 查詢此屬性,以判斷故障轉移夥伴的身分識別。 如果主要伺服器沒有容錯移轉夥伴,此屬性將會傳回空字串。 這可讓智慧型手機應用程式快取最近決定的備份伺服器,但這類應用程式應該注意,只有在第一次建立連線時才會更新資訊,或如果集區已重設,而且可能會成為長期連線的過期狀態。
如需詳細資訊,請參閱使用資料庫鏡像。
SQL_COPT_SS_INTEGRATED_SECURITY
SQL_COPT_SS_INTEGRATED_SECURITY強制使用 Windows 驗證進行伺服器登入的存取驗證。 使用 Windows 驗證時,驅動程式會忽略 SQLConnect、SQLDriverConnect 或 SQLBrowseConnect 處理所提供的使用者識別碼和密碼值。
值 | Description |
---|---|
SQL_IS_OFF | 預設。 SQL Server 驗證可用來驗證登入時的使用者標識碼和密碼。 |
SQL_IS_ON | Windows 驗證模式是用來驗證使用者對 SQL Server 的訪問許可權。 |
SQL_COPT_SS_MARS_ENABLED
此屬性會啟用或停用多個作用中結果集 (MARS)。 根據預設,MARS 會停用。 建立 SQL Server 的連線之前,應該先設定此屬性。 開啟 SQL Server 連線之後,MARS 將會在連線存留期維持啟用或停用狀態。
值 | Description |
---|---|
SQL_MARS_ENABLED_NO | 預設。 停用多個作用中結果集 (MARS)。 |
SQL_MARS_ENABLED_YES | MARS 已啟用。 |
如需 MARS 的詳細資訊,請參閱 使用多個使用中結果集 (MARS) 。
SQL_COPT_SS_MULTISUBNET_FAILOVER
如果您的應用程式連線到不同子網上的 Always On 可用性群組可用性群組 (AG),此聯機屬性會設定 SQL Server Native Client,以提供更快速的偵測和連線至 (目前) 使用中伺服器。 例如:
SQLSetConnectAttr(hdbc, SQL_COPT_SS_MULTISUBNET_FAILOVER, SQL_IS_ON, SQL_IS_INTEGER)
如需 SQL Server Native Client 對 Always On 可用性群組 AG 支援的詳細資訊,請參閱 SQL Server Native Client Support for High Availability, Disaster Recovery。
值 | Description |
---|---|
SQL_IS_ON | 如果有故障轉移,SQL Server Native Client 提供更快速的重新連線。 |
SQL_IS_OFF | 如果有故障轉移,SQL Server Native Client 將無法提供更快的重新連線。 |
SQL_COPT_SS_OLDPWD
SQL Server 2005 (9.x) 引進了 SQL Server 驗證的密碼到期日。 已新增 SQL_COPT_SS_OLDPWD 屬性,以允許用戶端提供連線的舊密碼和新密碼。 設定此屬性時,提供者將不會針對第一個連接或後續連接使用連接集區,因為 連接字串 會包含現在已變更的「舊密碼」。
如需詳細資訊,請參閱 以程式設計方式變更密碼。
值 | Description |
---|---|
SQL_COPT_SS_OLD_PASSWORD | SQLPOINTER 到包含舊密碼的字元字串。 這個值是唯寫的,而且必須先設定,才能連線到伺服器。 |
SQL_COPT_SS_PERF_DATA
SQL_COPT_SS_PERF_DATA啟動或停止效能數據記錄。 在開始數據記錄之前,必須先設定數據記錄檔名稱。 請參閱下方SQL_COPT_SS_PERF_DATA_LOG。
值 | Description |
---|---|
SQL_PERF_START | 啟動驅動程式取樣效能數據。 |
SQL_PERF_STOP | 停止計數器取樣效能數據。 |
如需詳細資訊,請參閱 SQLGetConnectAttr。
SQL_COPT_SS_PERF_DATA_LOG
SQL_COPT_SS_PERF_DATA_LOG指派用來記錄效能數據的記錄檔名稱。 記錄檔名稱是 ANSI 或 Unicode,根據應用程式編譯而以 Null 結尾的字串。 StringLength 自變數應SQL_NTS。
SQL_COPT_SS_PERF_DATA_LOG_NOW
SQL_COPT_SS_PERF_DATA_LOG_NOW指示驅動程式將統計數據記錄專案寫入磁碟。 StringLength 自變數應SQL_NTS。
SQL_COPT_SS_PERF_QUERY
SQL_COPT_SS_PERF_QUERY會啟動或停止長時間執行的查詢記錄。 必須先提供查詢記錄檔名稱,才能開始記錄。 應用程式可以藉由設定記錄的間隔來定義「長時間執行」。
值 | Description |
---|---|
SQL_PERF_START | 啟動長時間執行的查詢記錄。 |
SQL_PERF_STOP | 停止長時間執行的查詢記錄。 |
如需詳細資訊,請參閱 SQLGetConnectAttr。
SQL_COPT_SS_PERF_QUERY_INTERVAL
SQL_COPT_SS_PERF_QUERY_INTERVAL以毫秒為單位設定查詢記錄閾值。 未在閾值內解析的查詢會記錄在長時間執行的查詢記錄檔中。 查詢閾值沒有上限。 零的查詢臨界值會導致記錄所有查詢。
SQL_COPT_SS_PERF_QUERY_LOG
SQL_COPT_SS_PERF_QUERY_LOG指派記錄檔的名稱,以記錄長時間執行的查詢數據。 記錄檔名稱是 ANSI 或 Unicode,根據應用程式編譯而以 Null 結尾的字串。 StringLength 自變數應SQL_NTS或以位元組為單位的字元串長度。
SQL_COPT_SS_PRESERVE_CURSORS
這個屬性可讓您查詢和設定當您認可/回復交易時,連接是否會保留數據指標。 此設定為SQL_PC_ON或SQL_PC_OFF。 預設值為 SQL_PC_OFF。 此設定可控制當您呼叫 SQLEndTran (或 SQLTransact) 時,驅動程式是否會為您關閉數據指標。
值 | Description |
---|---|
SQL_PC_OFF | 預設。 使用 SQLEndTran 認可或回復交易時,數據指標會關閉。 |
SQL_PC_ON | 使用 SQLEndTran 認可或回復交易時,數據指標不會關閉,除非在異步模式中使用靜態或索引鍵集數據指標時。 如果在數據指標母體擴展未完成時發出回復,則會關閉數據指標。 |
SQL_COPT_SS_QUOTED_IDENT
SQL_COPT_SS_QUOTED_IDENT允許在連接上提交的 ODBC 和 Transact-SQL 語句中加上引號的標識符。 藉由提供引號標識碼,SQL Server Native Client ODBC 驅動程式會允許無效的物件名稱,例如 “My Table”,其中包含標識符中的空格字元。 如需詳細資訊,請參閱 SET QUOTED_IDENTIFIER。
值 | Description |
---|---|
SQL_QI_OFF | SQL Server 連接不允許送出 Transact-SQL 中的引號識別碼。 |
SQL_QI_ON | 預設。 線上允許在提交的 Transact-SQL 中加上引號的標識碼。 |
SQL_COPT_SS_TRANSLATE
SQL_COPT_SS_TRANSLATE會導致驅動程式在交換 MBCS 數據時,轉譯用戶端與伺服器代碼頁之間的字元。 屬性只會影響儲存在 SQL Serverchar、 varchar 和 text 數據行中的數據。
值 | Description |
---|---|
SQL_XL_OFF | 驅動程式不會將字元從一個代碼頁轉譯為客戶端與伺服器之間交換的字元數據。 |
SQL_XL_ON | 預設。 驅動程式會將字元從一個代碼頁轉譯為客戶端與伺服器之間交換的字元數據。 驅動程式會自動設定字元轉譯,判斷伺服器上所安裝的代碼頁,以及用戶端所使用的代碼頁。 |
SQL_COPT_SS_TRUST_SERVER_CERTIFICATE
SQL_COPT_SS_TRUST_SERVER_CERTIFICATE會導致驅動程式在使用加密時啟用或停用憑證驗證。 此屬性是讀取/寫入值,但在建立連接之後加以設定沒有任何作用。
用戶端應用程式可以在開啟連接之後查詢此屬性,以便判斷使用中的實際加密和驗證設定。
值 | Description |
---|---|
SQL_TRUST_SERVER_CERTIFICATE_NO | 預設。 未啟用憑證驗證的加密。 |
SQL_TRUST_SERVER_CERTIFICATE_YES | 已啟用無憑證驗證的加密。 |
SQL_COPT_SS_TXN_ISOLATION
SQL_COPT_SS_TXN_ISOLATION設定 SQL Server 特定的快照集隔離屬性。 快照集隔離無法使用 SQL_ATTR_TXN_ISOLATION來設定,因為此值是 SQL Server 特定的。 不過,可以使用 SQL_ATTR_TXN_ISOLATION 或 SQL_COPT_SS_TXN_ISOLATION 來擷取。
值 | Description |
---|---|
SQL_TXN_SS_SNAPSHOT | 表示從某個交易中,您無法看到在其他交易中所做的變更,而且即使重新查詢也看不到變更。 |
如需快照集隔離的詳細資訊,請參閱 使用快照集隔離。
SQL_COPT_SS_USE_PROC_FOR_PREP
不再支援這個屬性。
SQL_COPT_SS_USER_DATA
SQL_COPT_SS_USER_DATA設定用戶數據指標。 用戶數據是每個連線記錄的客戶端擁有記憶體。
如需詳細資訊,請參閱 SQLGetConnectAttr。
SQL_COPT_SS_WARN_ON_CP_ERROR
這個屬性會判斷您是否會在代碼頁轉換期間遺失數據時收到警告。 這僅適用於來自伺服器的數據。
值 | Description |
---|---|
SQL_WARN_YES | 在代碼頁轉換期間遇到數據遺失時產生警告。 |
SQL_WARN_NO | (預設值)在代碼頁轉換期間遇到數據遺失時,請勿產生警告。 |
服務主體名稱的 SQLSetConnectAttr 支援 (SPN)
SQLSetConnectAttr 可用來設定新連接屬性的值,SQL_COPT_SS_SERVER_SPN和SQL_COPT_SS_FAILOVER_PARTNER_SPN。 當連接開啟時,無法設定這些屬性;如果您嘗試在連線開啟時設定這些屬性,則會傳回錯誤 HY011,並顯示「目前作業無效」訊息。 (SQLSetConnectOption 也可以用來設定這些值。
如需SPN的詳細資訊,請參閱用戶端連接 (ODBC) 中的服務主體名稱 (SPN)。
SQL_COPT_SS_CONNECTION_DEAD
這是唯讀屬性。
如需SQL_COPT_SS_CONNECTION_DEAD的詳細資訊,請參閱 SQLGetConnectAttr 和 連接到資料來源 (ODBC) 。
範例
此範例會記錄效能數據。
SQLPERF* pSQLPERF;
SQLINTEGER nValue;
// See if you are already logging. SQLPERF* will be NULL if not.
SQLGetConnectAttr(hDbc, SQL_COPT_SS_PERF_DATA, &pSQLPERF,
sizeof(SQLPERF*), &nValue);
if (pSQLPERF == NULL)
{
// Set the performance log file name.
SQLSetConnectAttr(hDbc, SQL_COPT_SS_PERF_DATA_LOG,
(SQLPOINTER) "\\My LogDirectory\\MyServerLog.txt", SQL_NTS);
// Start logging...
SQLSetConnectAttr(hDbc, SQL_COPT_SS_PERF_DATA,
(SQLPOINTER) SQL_PERF_START, SQL_IS_INTEGER);
}
else
{
// Take a snapshot now so that your performance statistics are discernible.
SQLSetConnectAttr(hDbc, SQL_COPT_SS_PERF_DATA_LOG_NOW, NULL, 0);
}
// ...perform some action...
// ...take a performance data snapshot...
SQLSetConnectAttr(hDbc, SQL_COPT_SS_PERF_DATA_LOG_NOW, NULL, 0);
// ...perform more actions...
// ...take another snapshot...
SQLSetConnectAttr(hDbc, SQL_COPT_SS_PERF_DATA_LOG_NOW, NULL, 0);
// ...and disable logging.
SQLSetConnectAttr(hDbc, SQL_COPT_SS_PERF_DATA,
(SQLPOINTER) SQL_PERF_STOP, SQL_IS_INTEGER);
// Continue on...
另請參閱
SQLSetConnectAttr 函式
ODBC API 實作詳細數據
大量複製函式
SET ANSI_NULLS (Transact-SQL)
SET ANSI_PADDING (Transact-SQL)
SET ANSI_WARNINGS (Transact-SQL)
SET CONCAT_NULL_YIELDS_NULL (Transact-SQL)
SET QUOTED_IDENTIFIER (Transact-SQL)
SQLPrepare 函式
SQLGetInfo