SQLSetConnectAttr
适用于：
SQL Server Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics Analytics 平台系统（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 在比较和连接、字符数据类型填充以及警告中允许或禁止使用 ISO 对 NULL 的处理方式。 有关详细信息，请参阅 SET ANSI_NULLS、SET ANSI_PADDING、SET ANSI_WARNINGS 和 SET CONCAT_NULL_YIELDS_NULL。
| 值 | 说明 |
|---|---|
| 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 对 AlwaysOn 可用性组 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 将不会重新附加它。
| 值 | 说明 |
|---|---|
| 指向字符串的 SQLPOINTER | 该字符串包含要附加的数据库的主文件名称。 它包括该文件的完整路径名称。 |
SQL_COPT_SS_BCP
SQL_COPT_SS_BCP 支持针对连接的大容量复制函数。 有关详细信息，请参阅 大容量复制函数。
| 值 | 说明 |
|---|---|
| SQL_BCP_OFF | 默认。 无法对连接使用大容量复制函数。 |
| SQL_BCP_ON | 可以对连接使用大容量复制函数。 |
SQL_COPT_SS_BROWSE_CONNECT
此属性用于自定义 SQLBrowseConnect 返回的结果集。 SQL_COPT_SS_BROWSE_CONNECT启用或禁用从 SQL Server 的枚举实例返回其他信息。 这可以包含服务器是否是群集、不同实例的名称以及版本号等信息。
| 值 | 说明 |
|---|---|
| SQL_MORE_INFO_NO | 默认。 返回服务器列表。 |
| SQL_MORE_INFO_YES | SQLBrowseConnect 返回服务器属性的扩展字符串。 |
SQL_COPT_SS_BROWSE_SERVER
此属性用于自定义 SQLBrowseConnect 返回的结果集。 SQL_COPT_SS_BROWSE_SERVER指定 SQLBrowseConnect 返回信息的服务器名称。
| 值 | 说明 |
|---|---|
| computername | SQLBrowseConnect 返回指定计算机上的 SQL Server 实例列表。 不应将双反斜杠 （\\） 用于服务器名称（例如，应使用 \\MyServer，而不是 \\MyServer）。 |
| Null | 默认。 SQLBrowseConnect 返回域中所有服务器的信息。 |
SQL_COPT_SS_CONCAT_NULL
在连接字符串时，SQL_COPT_SS_CONCAT_NULL 允许或禁止使用 ISO 对 NULL 的处理方式。 有关详细信息，请参阅 SET CONCAT_NULL_YIELDS_NULL。
| 值 | 说明 |
|---|---|
| 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"，否则证书必须要由证书颁发机构验证。 如果满足上述条件之一且服务器上没有证书，则由服务器生成和签名的证书可以用于加密连接。
| 值 | 说明 |
|---|---|
| SQL_EN_ON | 将加密连接。 |
| SQL_EN_OFF | 将不加密连接。 这是默认情况。 |
SQL_COPT_SS_ENLIST_IN_DTC
客户端调用 Microsoft 分布式事务处理协调器 （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 关联。
| 值 | 说明 |
|---|---|
| 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 处理过程中提供的用户标识符和密码值。
| 值 | 说明 |
|---|---|
| SQL_IS_OFF | 默认。 SQL Server 身份验证用于验证登录时的用户标识符和密码。 |
| SQL_IS_ON | Windows 身份验证模式用于验证用户对 SQL Server 的访问权限。 |
SQL_COPT_SS_MARS_ENABLED
此属性启用或禁用多个活动结果集 (MARS)。 默认情况下，禁用 MARS。 在与 SQL Server 建立连接之前，应设置此属性。 打开连接 SQL Server 后，MARS 将在连接生命周期内保持启用或禁用状态。
| 值 | 说明 |
|---|---|
| SQL_MARS_ENABLED_NO | 默认。 禁用多个活动结果集 (MARS)。 |
| SQL_MARS_ENABLED_YES | 启用 MARS。 |
有关 MARS 的详细信息，请参阅使用多个活动结果集 （MARS）。
SQL_COPT_SS_MULTISUBNET_FAILOVER
如果应用程序连接到不同子网上的 AlwaysOn 可用性组可用性组（AG），则此连接属性将配置 SQL Server Native Client，以便更快地检测和连接到活动服务器（当前） 活动服务器。 例如：
SQLSetConnectAttr(hdbc, SQL_COPT_SS_MULTISUBNET_FAILOVER, SQL_IS_ON, SQL_IS_INTEGER)
有关 SQL Server Native Client 对 AlwaysOn 可用性组 AG 的支持的详细信息，请参阅 SQL Server Native Client Support for High Availability， Disaster Recovery。
| 值 | 说明 |
|---|---|
| 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 属性以允许客户端同时提供连接的旧密码和新密码。 设置此属性时，访问接口对于第一次连接或后续连接将不使用连接池，因为连接字符串将包含现在已更改的“旧密码”。
有关详细信息，请参阅以编程方式更改密码。
| 值 | 说明 |
|---|---|
| SQL_COPT_SS_OLD_PASSWORD | 指向包含旧密码的字符串的 SQLPOINTER。 此值是只写的，必须在连接到服务器之前设置。 |
SQL_COPT_SS_PERF_DATA
SQL_COPT_SS_PERF_DATA 启动或停止性能数据日志记录。 在启动数据日志记录之前必须设置数据日志文件名。 请参阅下面的 SQL_COPT_SS_PERF_DATA_LOG。
| 值 | 说明 |
|---|---|
| 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 启动或停止对长时间运行的查询的日志记录。 在启动日志记录之前必须提供查询日志文件名。 应用程序可以通过设置日志记录的时间间隔来定义“长时间运行”。
| 值 | 说明 |
|---|---|
| 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）时驱动程序是否会关闭游标（s）。
| 值 | 说明 |
|---|---|
| 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。
| 值 | 说明 |
|---|---|
| SQL_QI_OFF | SQL Server 连接不允许在提交的 Transact-SQL 中使用带引号的标识符。 |
| SQL_QI_ON | 默认。 连接允许在提交的 Transact-SQL 中使用带引号的标识符。 |
SQL_COPT_SS_TRANSLATE
SQL_COPT_SS_TRANSLATE 导致在交换 MBCS 数据时驱动程序在客户端和服务器代码页之间进行字符转换。 该属性仅影响存储在 SQL Serverchar、 varchar 和 文本列中的数据 。
| 值 | 说明 |
|---|---|
| SQL_XL_OFF | 在客户端和服务器之间交换字符数据时，驱动程序不将一种代码页的字符转换为另一种代码页的字符。 |
| SQL_XL_ON | 默认。 在客户端和服务器之间交换字符数据时，驱动程序将一种代码页的字符转换为另一种代码页的字符。 驱动程序自动配置字符转换，确定服务器上安装的代码页和客户端使用的代码页。 |
SQL_COPT_SS_TRUST_SERVER_CERTIFICATE
SQL_COPT_SS_TRUST_SERVER_CERTIFICATE 在使用加密时导致驱动程序启用或禁用证书验证。 此属性的值是可读/写的，但是在建立连接后设置它没有影响。
客户端应用程序可以在打开连接后查询此属性，以确定使用的实际加密和验证设置。
| 值 | 说明 |
|---|---|
| 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 来检索它。
| 值 | 说明 |
|---|---|
| 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
此属性确定在代码页转换期间丢失数据时系统是否会向您发出警告。 这仅适用于来自服务器的数据。
| 值 | 说明 |
|---|---|
| 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
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈