SQLSetConnectAttr

  • 發行項

適用於：SQL ServerAzure SQL DatabaseAzure SQL 受控執行個體Azure Synapse AnalyticsAnalytics Platform System (PDW)

SQL Server Native Client ODBC 驅動程式會忽略SQL_ATTR_CONNECTION_TIMEOUT的設定。

也會忽略SQL_ATTR_TRANSLATE_LIB;不支援指定另一個翻譯程式庫。 若要讓應用程式輕鬆地移植到使用 Microsoft ODBC Driver for SQL Server，任何以 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 Server char 、 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