SQLSetConnectAttr

El controlador ODBC de SQL Server Native Client omite el valor de SQL_ATTR_CONNECTION_TIMEOUT.

SQL_ATTR_TRANSLATE_LIB también se ignora; especificando que otra biblioteca de traducción no es compatible. Para permitir que las aplicaciones se trasladen fácilmente para usar un controlador ODBC de Microsoft para SQL Server, cualquier valor configurado con SQL_ATTR_TRANSLATE_LIB se copiará en y fuera de un búfer en el Administrador de controladores.

El controlador ODBC de SQL Server Native Client implementa el aislamiento de transacciones de lectura repetible (REPEATABLE READ) como serializable.

En SQL Server 2005 se introdujo compatibilidad para un nuevo atributo de aislamiento de transacciones, SQL_COPT_SS_TXN_ISOLATION. Si SQL_COPT_SS_TXN_ISOLATION se establece en SQL_TXN_SS_SNAPSHOT, significa que la transacción tendrá lugar en el nivel de aislamiento de instantáneas.

Nota

SQL_ATTR_TXN_ISOLATION puede usarse para establecer todos los demás niveles de aislamiento salvo SQL_TXN_SS_SNAPSHOT. Si desea usar el aislamiento de instantáneas, debe establecer SQL_TXN_SS_SNAPSHOT a través de SQL_COPT_SS_TXN_ISOLATION. Sin embargo, puede recuperar el nivel de aislamiento mediante SQL_ATTR_TXN_ISOLATION o SQL_COPT_SS_TXN_ISOLATION.

La promoción de atributos de instrucción a atributos de conexión ODBC puede tener consecuencias imprevistas. Los atributos de instrucción que solicitan cursores de servidor para el procesamiento del conjunto de resultados pueden promoverse a la conexión. Por ejemplo, el establecimiento del atributo de instrucción ODBC SQL_ATTR_CONCURRENCY a un valor más restrictivo que el valor SQL_CONCUR_READ_ONLY predeterminado indica al controlador que use cursores dinámicos para todas las instrucciones enviadas en la conexión. Si se ejecuta una función de catálogo ODBC en una instrucción en la conexión, se devuelve SQL_SUCCESS_WITH_INFO y un registro de diagnóstico que indica que el comportamiento del cursor se ha modificado a solo lectura. Se produce un error al intentar ejecutar una instrucción SELECT de Transact-SQL que contiene una cláusula COMPUTE en la misma conexión.

El controlador ODBC de SQL Server Native Client admite varias extensiones específicas del controlador para los atributos de conexión ODBC definidos en sqlncli.h. El controlador ODBC de SQL Server Native Client puede exigir que el atributo se establezca antes de la conexión, o puede omitir el atributo si ya está establecido. En la tabla siguiente se enumeran las restricciones.

Atributo de SQL Server

Establecer antes o después de la conexión al servidor

SQL_COPT_SS_ANSI_NPW

Antes

SQL_COPT_SS_ATTACHDBFILENAME

Antes

SQL_COPT_SS_BCP

Antes

SQL_COPT_SS_BROWSE_CONNECT

Antes

SQL_COPT_SS_BROWSE_SERVER

Antes

SQL_COPT_SS_CONCAT_NULL

Antes

SQL_COPT_SS_CONNECTION_DEAD

Después

SQL_COPT_SS_ENCRYPT

Antes

SQL_COPT_SS_ENLIST_IN_DTC

Después

SQL_COPT_SS_ENLIST_IN_XA

Después

SQL_COPT_SS_FALLBACK_CONNECT

Antes

SQL_COPT_SS_FAILOVER_PARTNER

Antes

SQL_COPT_SS_INTEGRATED_SECURITY

Antes

SQL_COPT_SS_MARS_ENABLED

Antes

SQL_COPT_SS_OLDPWD

Antes

SQL_COPT_SS_PERF_DATA

Después

SQL_COPT_SS_PERF_DATA_LOG

Después

SQL_COPT_SS_PERF_DATA_LOG_NOW

Después

SQL_COPT_SS_PERF_QUERY

Después

SQL_COPT_SS_PERF_QUERY_INTERVAL

Después

SQL_COPT_SS_PERF_QUERY_LOG

Después

SQL_COPT_SS_PRESERVE_CURSORS

Antes

SQL_COPT_SS_QUOTED_IDENT

Antes o después

SQL_COPT_SS_TRANSLATE

Antes o después

SQL_COPT_SS_TRUST_SERVER_CERTIFICATE

Antes

SQL_COPT_SS_TXN_ISOLATION

Antes o después

SQL_COPT_SS_USE_PROC_FOR_PREP

Antes o después

SQL_COPT_SS_USER_DATA

Antes o después

SQL_COPT_SS_WARN_ON_CP_ERROR

Antes

SQL_COPT_SS_ANSI_NPW

SQL_COPT_SS_ANSI_NPW habilita o deshabilita el uso de la administración ISO de valores NULL en comparaciones y concatenación, relleno de tipos de datos de caracteres y advertencias. Para obtener más información, vea SET ANSI_NULLS, SET ANSI_PADDING, SET ANSI_WARNINGS y SET CONCAT_NULL_YIELDS_NULL.

Valor

Descripción

SQL_AD_ON

Valor predeterminado. La conexión usa el comportamiento ANSI predeterminado para administrar comparaciones de valores NULL, relleno, advertencias y concatenaciones de valores NULL.

SQL_AD_OFF

La conexión usa la administración definida por SQL Server de valores NULL, relleno de tipo de datos de caracteres y advertencias.

Si usa la agrupación de conexiones, SQL_COPT_SS_ANSI_NPW debe establecerse en la cadena de conexión en lugar de establecerse con SQLSetConnectAttr. Una vez realizada una conexión, cualquier intento por cambiar este atributo cuando se use la agrupación de conexiones dará lugar a un error que no se notificará.

SQL_COPT_SS_ATTACHDBFILENAME

SQL_COPT_SS_ATTACHDBFILENAME especifica el nombre del archivo principal de una base de datos adjuntable. Esta base de datos se adjunta y se convierte en la base de datos predeterminada para la conexión. Para usar SQL_COPT_SS_ATTACHDBFILENAME, debe especificar el nombre de la base de datos como el valor del atributo de conexión SQL_ATTR_CURRENT_CATALOG, o especificarlo en el parámetro DATABASE = de una función SQLDriverConnect. Si la base de datos se ha adjuntado previamente, SQL Server no volverá a adjuntarla.

Valor

Descripción

SQLPOINTER a una cadena de caracteres

La cadena contiene el nombre del archivo principal de la base de datos que va a adjuntarse. Incluya el nombre completo de la ruta de acceso al archivo.

SQL_COPT_SS_BCP

SQL_COPT_SS_BCP habilita las funciones de copia masiva en una conexión. Para obtener más información, vea Funciones de copia masiva.

Valor

Descripción

SQL_BCP_OFF

Valor predeterminado. Las funciones de copia masiva no están disponibles en la conexión.

SQL_BCP_ON

Las funciones de copia masiva están disponibles en la conexión.

SQL_COPT_SS_BROWSE_CONNECT

Este atributo se usa para personalizar el conjunto de resultados devuelto por SQLBrowseConnect. SQL_COPT_SS_BROWSE_CONNECT habilita o deshabilita la devolución de información adicional de una instancia enumerada de SQL Server. Esta información puede incluir datos como si el servidor es un clúster, nombres de instancias distintas y el número de versión.

Valor

Descripción

SQL_MORE_INFO_NO

Valor predeterminado. Devuelve una lista de servidores.

SQL_MORE_INFO_YES

En SQL Server 7.0, SQLBrowseConnect devuelve una lista de servidores; de lo contrario, SQLBrowseConnect devuelve una cadena extendida de propiedades de servidor.

SQL_COPT_SS_BROWSE_SERVER

Este atributo se usa para personalizar el conjunto de resultados devuelto por SQLBrowseConnect. SQL_COPT_SS_BROWSE_SERVER especifica el nombre del servidor para el que SQLBrowseConnect devuelve la información.

Valor

Descripción

computername

SQLBrowseConnect devuelve una lista de instancias de SQL Server en el equipo especificado. No deben usarse barras diagonales inversas dobles (\\) para el nombre del servidor (por ejemplo, en lugar de \\MyServer, debe utilizarse MyServer).

NULL

Valor predeterminado. SQLBrowseConnect devuelve información para todos los servidores del dominio.

SQL_COPT_SS_CONCAT_NULL

SQL_COPT_SS_CONCAT_NULL habilita o deshabilita el uso de la administración ISO de valores NULL al concatenar cadenas. Para obtener más información, vea SET CONCAT_NULL_YIELDS_NULL.

Valor

Descripción

SQL_CN_ON

Valor predeterminado. La conexión usa el comportamiento ISO predeterminado para administrar valores NULL al concatenar cadenas.

SQL_CN_OFF

La conexión usa el comportamiento predeterminado definido por SQL Server para administrar valores NULL al concatenar cadenas.

SQL_COPT_SS_ENCRYPT

Controla el cifrado de una conexión.

El cifrado usa el certificado en el servidor. Una entidad de certificación debe comprobar el certificado, a menos que el atributo de conexión SQL_COPT_SS_TRUST_SERVER_CERTIFICATE se establezca en SQL_TRUST_SERVER_CERTIFICATE_YES o que la cadena de conexión contenga "TrustServerCertificate=yes". Si se cumple alguna de estas condiciones, puede usarse un certificado generado y firmado por el servidor para cifrar la conexión en caso de que no haya ningún certificado en el servidor.

Valor

Descripción

SQL_EN_ON

La conexión se cifrará.

SQL_EN_OFF

La conexión no se cifrará. Se trata del valor predeterminado.

SQL_COPT_SS_ENLIST_IN_DTC

El cliente llama al método OLE DB ITransactionDispenser::BeginTransaction de Microsoft DTC (Coordinador de transacciones distribuidas) para comenzar una transacción MS DTC y crear un objeto de transacción MS DTC que represente la transacción. A continuación, la aplicación llama a SQLSetConnectAttr con la opción SQL_COPT_SS_ENLIST_IN_DTC para asociar el objeto de transacción a la conexión ODBC. Toda la actividad de base de datos relacionada se realizará bajo la protección de la transacción MS DTC. La aplicación llama a SQLSetConnectAttr con SQL_DTC_DONE para finalizar la asociación DTC de la conexión. Para obtener más información, vea Transacciones distribuidas de MS DTC.

Valor

Descripción

Objeto DTC*

Objeto de transacción OLE de MS DTC que especifica la transacción que va exportarse a SQL Server.

SQL_DTC_DONE

Delimita el final de una transacción DTC.

SQL_COPT_SS_ENLIST_IN_XA

Para iniciar una transacción con un procesador de transacciones (TP) compatible con XA, el cliente llama a la función tx_begin de Open Group. A continuación, la aplicación llama a SQLSetConnectAttr con el parámetro SQL_COPT_SS_ENLIST_IN_XA establecido en TRUE para asociar la transacción XA a la conexión ODBC. Toda la actividad de base de datos relacionada se realizará bajo la protección de la transacción XA. Para finalizar una asociación XA con una conexión ODBC, el cliente debe llamar a SQLSetConnectAttr con el parámetro SQL_COPT_SS_ENLIST_IN_XA establecido en FALSE. Para obtener más información, vea la documentación de Microsoft DTC (Coordinador de transacciones distribuidas).

SQL_COPT_SS_FALLBACK_CONNECT

Ya no se admite este atributo porque SQL Server Native Client no admite la conexión a SQL Server 6.5.

SQL_COPT_SS_FAILOVER_PARTNER

Se usa para especificar o recuperar el nombre del asociado de conmutación por error usado para la creación de reflejo de la base de datos en SQL Server, y es una cadena de caracteres terminada en NULL que debe establecerse antes de que se realice la conexión a SQL Server.

Después de realizar la conexión, la aplicación puede consultar este atributo mediante SQLGetConnectAttr para determinar la identidad del asociado de conmutación por error. Si el servidor principal no tiene ningún asociado de conmutación por error, esta propiedad devolverá una cadena vacía. Esto permite que una aplicación inteligente almacene en memoria caché el servidor de copia de seguridad determinado más recientemente, pero dichas aplicaciones deben tener en cuenta que la información solo se actualiza cuando la conexión se establece por primera vez (o se restablece, si está agrupada) y puede quedar desfasada para conexiones a largo plazo.

Para obtener más información, vea Usar la creación de reflejo de bases de datos.

SQL_COPT_SS_INTEGRATED_SECURITY

SQL_COPT_SS_INTEGRATED_SECURITY fuerza el uso de la autenticación de Windows para la validación de acceso en el inicio sesión del servidor. Cuando se usa la autenticación de Windows, el controlador omite el identificador de usuario y los valores de contraseña proporcionados como parte del procesamiento de SQLConnect, SQLDriverConnect o SQLBrowseConnect.

Valor

Descripción

SQL_IS_OFF

Valor predeterminado. La autenticación de SQL Server se usa para validar el identificador de usuario y la contraseña en el inicio de sesión.

SQL_IS_ON

El modo de autenticación de Windows se usa para validar los derechos de acceso a SQL Server de un usuario.

SQL_COPT_SS_MARS_ENABLED

Este atributo habilita o deshabilita MARS (Multiple Active Result Sets, conjuntos de resultados activos múltiples). De forma predeterminada, MARS está deshabilitado. Este atributo debe establecerse antes de realizar una conexión a SQL Server. Una vez abierta la conexión a SQL Server, MARS seguirá habilitado o deshabilitado a lo largo de toda la conexión.

Valor

Descripción

SQL_MARS_ENABLED_NO

Valor predeterminado. MARS (Multiple Active Result Sets, conjuntos de resultados activos múltiples) está deshabilitado.

SQL_MARS_ENABLED_YES

MARS está habilitado.

Para obtener más información acerca de MARS, vea Utilizar conjuntos de resultados activos múltiples (MARS).

SQL_COPT_SS_OLDPWD

La expiración de contraseñas para la autenticación de SQL Server se introdujo en SQL Server 2005. Se ha agregado el atributo SQL_COPT_SS_OLDPWD para permitir que el cliente especifique la contraseña antigua y la nueva contraseña para la conexión. Cuando se establezca esta propiedad, el proveedor no usará el grupo de conexiones para la primera conexión o para conexiones posteriores, puesto que la cadena de conexión contendrá la “antigua contraseña” que ahora ha cambiado.

Para obtener más información, vea Cambiar las contraseñas mediante programación.

Valor

Descripción

SQL_COPT_SS_OLD_PASSWORD

SQLPOINTER a una cadena de caracteres que contiene la contraseña anterior. Este valor es de solo escritura y debe establecerse antes de la conexión al servidor.

SQL_COPT_SS_PERF_DATA

SQL_COPT_SS_PERF_DATA inicia o detiene el registro de datos de rendimiento. El nombre del archivo de registro de datos debe establecerse antes de iniciar el registro de datos. Vea SQL_COPT_SS_PERF_DATA_LOG a continuación.

Valor

Descripción

SQL_PERF_START

Inicia el muestreo de datos de rendimiento del controlador.

SQL_PERF_STOP

Detiene el muestreo de datos de rendimiento por parte de los controladores.

Para obtener más información, vea SQLGetConnectAttr.

SQL_COPT_SS_PERF_DATA_LOG

SQL_COPT_SS_PERF_DATA_LOG asigna el nombre del archivo de registro utilizado para grabar datos de rendimiento. El nombre del archivo de registro es una cadena ANSI o Unicode terminada en NULL, en función de la compilación de la aplicación. El argumento StringLength debe ser SQL_NTS.

SQL_COPT_SS_PERF_DATA_LOG_NOW

SQL_COPT_SS_PERF_DATA_LOG_NOW indica al controlador que escriba una entrada de registro de estadísticas en el disco. El argumento StringLength debe ser SQL_NTS.

SQL_COPT_SS_PERF_QUERY

SQL_COPT_SS_PERF_QUERY inicia o detiene el registro de consultas de ejecución prolongada. El nombre del archivo de registro de consultas debe suministrarse antes de iniciar el registro. La aplicación puede definir la "ejecución prolongada" estableciendo el intervalo para el registro.

Valor

Descripción

SQL_PERF_START

Inicia el registro de consultas de ejecución prolongada.

SQL_PERF_STOP

Detiene el registro de las consultas de ejecución prolongada.

Para obtener más información, vea SQLGetConnectAttr.

SQL_COPT_SS_PERF_QUERY_INTERVAL

SQL_COPT_SS_PERF_QUERY_INTERVAL establece el umbral de registro de consultas en milisegundos. Las consultas que no se resuelven dentro del umbral se graban en el archivo de registro de consultas de ejecución prolongada. No existe un límite superior en el umbral de consultas. Un valor de umbral de consulta igual a cero da lugar al registro de todas las consultas.

SQL_COPT_SS_PERF_QUERY_LOG

SQL_COPT_SS_PERF_QUERY_LOG asigna el nombre de un archivo de registro para grabar los datos de consulta de ejecución prolongada. El nombre del archivo de registro es una cadena ANSI o Unicode terminada en NULL, en función de la compilación de la aplicación. El argumento StringLength debería ser SQL_NTS o la longitud de la cadena en bytes.

SQL_COPT_SS_PRESERVE_CURSORS

Este atributo permite consultar y establecer si la conexión conservará o no los cursores al confirmar o revertir una transacción. El valor es SQL_PC_ON o SQL_PC_OFF. El valor predeterminado es SQL_PC_OFF. Este valor controla si el controlador cerrará o no cerrará los cursores cuando llame a SQLEndTran (o SQLTransact).

Valor

Descripción

SQL_PC_OFF

Valor predeterminado. Los cursores se cierran cuando la transacción se confirma o se revierte mediante SQLEndTran.

SQL_PC_ON

Los cursores no se cierran cuando la transacción se confirma o se revierte mediante SQLEndTran, excepto cuando se utiliza un cursor estático o un cursor controlado por conjunto de claves en modo asincrónico. Si se emite una reversión antes de que se complete el rellenado del cursor, se cierra el cursor.

SQL_COPT_SS_QUOTED_IDENT

SQL_COPT_SS_QUOTED_IDENT permite el uso de identificadores entre comillas en instrucciones ODBC y Transact-SQL enviadas en la conexión. Si se especifican identificadores entre comillas, el controlador ODBC de SQL Server Native Client admite nombres de objeto no válidos, como "Mi Tabla", que contiene un carácter de espacio en el identificador. Para obtener más información, vea SET QUOTED_IDENTIFIER.

Valor

Descripción

SQL_QI_OFF

La conexión SQL Server no permite identificadores entre comillas en el Transact-SQL enviado.

SQL_QI_ON

Valor predeterminado. La conexión permite identificadores entre comillas en el Transact-SQL enviado.

SQL_COPT_SS_TRANSLATE

SQL_COPT_SS_TRANSLATE hace que el controlador traduzca los caracteres entre las páginas de códigos del cliente y del servidor a medida que se intercambian datos MBCS. El atributo solo afecta a los datos almacenados en columnas SQL Serverchar, varchar y text.

Valor

Descripción

SQL_XL_OFF

El controlador no traduce los caracteres de una página de códigos a otra en los datos de caracteres intercambiados entre el cliente y el servidor.

SQL_XL_ON

Valor predeterminado. El controlador traduce los caracteres de una página de códigos a otra en los datos de caracteres intercambiados entre el cliente y el servidor. El controlador configura automáticamente la traducción de caracteres, determinando la página de códigos instalada en el servidor y que está usando el cliente.

SQL_COPT_SS_TRUST_SERVER_CERTIFICATE

SQL_COPT_SS_TRUST_SERVER_CERTIFICATE hace que el controlador habilite o deshabilite la validación de certificados cuando se utiliza el cifrado. Este atributo es un valor de lectura/escritura, pero si se establece después de que se haya establecido una conexión no tiene ningún efecto.

Las aplicaciones cliente podrán consultar esta propiedad una vez que se haya abierto una conexión para determinar la configuración real de cifrado y validación que se está usando.

Valor

Descripción

SQL_TRUST_SERVER_CERTIFICATE_NO

Valor predeterminado. No está habilitado el cifrado sin validación de certificados.

SQL_TRUST_SERVER_CERTIFICATE_YES

Está habilitado el cifrado sin validación de certificados.

SQL_COPT_SS_TXN_ISOLATION

SQL_COPT_SS_TXN_ISOLATION establece el atributo de aislamiento de instantáneas específico de SQL Server. El aislamiento de instantáneas no puede establecerse mediante SQL_ATTR_TXN_ISOLATION porque el valor es específico de SQL Server. Sin embargo, puede recuperarse mediante SQL_ATTR_TXN_ISOLATION o SQL_COPT_SS_TXN_ISOLATION.

Valor

Descripción

SQL_TXN_SS_SNAPSHOT

Indica desde una transacción no pueden verse los cambios realizados en otras transacciones y que no podrá ver los cambios aunque realice una nueva consulta.

Para obtener más información acerca del aislamiento de instantáneas, vea Trabajar con aislamiento de instantánea.

SQL_COPT_SS_USE_PROC_FOR_PREP

Ya no se admite este atributo porque SQL Server Native Client no admite la conexión a SQL Server 6.5.

SQL_COPT_SS_USER_DATA

SQL_COPT_SS_USER_DATA establece el puntero a los datos del usuario. Los datos del usuario son memoria propiedad del cliente y se registran por conexión.

Para obtener más información, vea SQLGetConnectAttr.

SQL_COPT_SS_WARN_ON_CP_ERROR

Este atributo determina si obtendrá una advertencia si se pierden datos durante la conversión de una página de códigos. Esto solo se aplica a los datos que provienen del servidor.

Valor

Descripción

SQL_WARN_YES

Generar advertencias cuando se produzca la pérdida de datos durante la conversión de la página de códigos.

SQL_WARN_NO

(Valor predeterminado) No generar advertencias cuando se produzca la pérdida de datos durante la conversión de la página de códigos.

Compatibilidad de SQLSetConnectAttr con los nombres principales de servicio (SPN)

SQLSetConnectAttr puede usarse para establecer el valor de los nuevos atributos de conexión SQL_COPT_SS_SERVER_SPN y SQL_COPT_SS_FAILOVER_PARTNER_SPN. Estos atributos no pueden establecerse cuando hay una conexión abierta; si intenta establecer estos atributos cuando hay una conexión abierta, se devuelve el error HY011 con el mensaje "Operación no válida en este momento". (SQLSetConnectOption también puede usarse para establecer estos valores.)

Para obtener más información acerca de los SPN, vea Nombres de entidad de seguridad del servicio (SPN) en conexiones de cliente (ODBC).

SQL_COPT_SS_CONNECTION_DEAD

Este atributo es de solo lectura.

Para obtener más información acerca de SQL_COPT_SS_CONNECTION_DEAD, vea SQLGetConnectAttr y Conectar con un origen de datos (ODBC).

Ejemplo

En este ejemplo se registran los datos de rendimiento.

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