• 项目

SQLSetConnectAttr

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 引入了对新的事务隔离属性 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_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_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_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_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

在 SQL Server 7.0 中，SQLBrowseConnect 返回服务器列表；否则 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 关联。有关详细信息，请参阅 MS DTC 分布式事务。

值

说明

DTC 对象*

指定要导出到 SQL Server 的事务的 MS DTC OLE 事务对象。

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 事务的保护下执行所有相关的数据库活动。若要结束 XA 与 ODBC 连接的关联，客户端必须使用值为 FALSE 的 SQL_COPT_SS_ENLIST_IN_XA 参数调用 SQLSetConnectAttr。有关详细信息，请参阅 Microsoft 分布式事务处理协调器文档。

SQL_COPT_SS_FALLBACK_CONNECT

不再支持此属性，因为 SQL Server Native Client 不支持连接到 SQL Server 6.5。

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_OLDPWD

在 SQL Server 2005 中引入了 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）时控制驱动程序是否为您关闭游标。

值

说明

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 和 text 列中的数据。

值

说明

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 Server Native Client 不支持连接到 SQL Server 6.5。

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 的详细信息，请参阅客户端连接中的服务主体名称 (SPN) (ODBC)。

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...