Función SQLSetConnectAttr
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 3.0: ISO 92
Resumen
SQLSetConnectAttr establece atributos que rigen aspectos de las conexiones.
Nota:
Para obtener más información sobre lo que asigna el Administrador de controladores a esta función cuando una aplicación ODBC 3*.x* está trabajando con un controlador ODBC 2*.x*, vea Mapping Replacement Functions for Backward Compatibility of Applications.
Sintaxis
SQLRETURN SQLSetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Argumentos
ConnectionHandle
[Entrada] Identificador de conexión.
Atributo
[Entrada] Atributo que se va a establecer, que aparece en "Comentarios".
ValuePtr
[Entrada] Puntero al valor que se va a asociar con Attribute. Según el valor de Attribute, ValuePtr será un valor entero sin signo o apuntará a una cadena de caracteres terminada en NULL. Tenga en cuenta que es posible que el tipo entero del argumento Attribute no sea una longitud fija, consulte la sección Comentarios para obtener más detalles.
StringLength
[Entrada] Si Attribute es un atributo definido por ODBC y ValuePtr apunta a una cadena de caracteres o a un búfer binario, este argumento debe ser la longitud de *ValuePtr. Para los datos de cadena de caracteres, este argumento debe contener el número de bytes de la cadena.
Si Attribute es un atributo definido por ODBC y ValuePtr es un entero, StringLength se omite.
Si Attribute es un atributo definido por el controlador, la aplicación indica la naturaleza del atributo en el Administrador de controladores estableciendo el argumento StringLength . StringLength puede tener los siguientes valores:
Si ValuePtr es un puntero a una cadena de caracteres, StringLength es la longitud de la cadena o SQL_NTS.
Si ValuePtr es un puntero a un búfer binario, la aplicación coloca el resultado de la macro SQL_LEN_BINARY_ATTR(length) en StringLength. Esto coloca un valor negativo en StringLength.
Si ValuePtr es un puntero a un valor distinto de una cadena de caracteres o una cadena binaria, StringLength debe tener el valor SQL_IS_POINTER.
Si ValuePtr contiene un valor de longitud fija, StringLength se SQL_IS_INTEGER o SQL_IS_UINTEGER, según corresponda.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.
Diagnóstico
Cuando SQLSetConnectAttr devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_DBC y un identificador de ConnectionHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLSetConnectAttr y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.
El controlador puede devolver SQL_SUCCESS_WITH_INFO para proporcionar información sobre el resultado de establecer una opción.
| SQLSTATE | Error | Descripción |
|---|---|---|
| 01000 | Advertencia general | Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S02 | Valor de opción cambiado | El controlador no admitía el valor especificado en ValuePtr y sustituyó un valor similar. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 08002 | Nombre de conexión en uso | El argumento Attribute se SQL_ATTR_ODBC_CURSORS y el controlador ya estaba conectado al origen de datos. |
| 08003 | Conexión no abierta | (DM) Se especificó un valor de atributo que requería una conexión abierta, pero connectionHandle no estaba en un estado conectado. |
| 08S01 | Error de vínculo de comunicación | Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento. |
| 24000 | Estado de cursor no válido | El argumento Attribute se SQL_ATTR_CURRENT_CATALOG y un conjunto de resultados estaba pendiente. |
| 25000 | Operación no válida mientras se encuentra en una transacción local | Una conexión estaba en una transacción local al intentar inscribirse en una conexión de transacción distribuida (DTC) estableciendo el atributo de conexión SQL_ATTR_ENLIST_IN_DTC. Ya se ha inscrito una conexión en un DTC. Se ha inscrito una conexión en una conexión de transacción distribuida y se inició una transacción local estableciendo SQL_ATTR_AUTOCOMMIT en SQL_AUTOCOMMIT_OFF. |
| 3D000 | Nombre de catálogo no válido | El argumento Attribute se SQL_CURRENT_CATALOG y el nombre de catálogo especificado no era válido. |
| HY000 | Error general | Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa. |
| HY001 | Error de asignación de memoria | El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función. |
| HY008 | Operación cancelada | El procesamiento asincrónico se ha habilitado para ConnectionHandle. Se llamó a la función SQLSetConnectAttr y antes de completar la ejecución, se llamó a la función SQLCancelHandle en ConnectionHandle y, a continuación, se llamó a la función SQLSetConnectAttr de nuevo en ConnectionHandle. O bien, se llamó a la función SQLSetConnectAttr y antes de completar la ejecución, se llamó a SQLCancelHandle en connectionHandle desde un subproceso diferente en una aplicación multiproceso. |
| HY009 | Uso no válido del puntero nulo | El argumento Attribute identificó un atributo de conexión que requería un valor de cadena y el argumento ValuePtr era un puntero nulo. |
| HY010 | Error de secuencia de funciones | (DM) Se llamó a una función de ejecución asincrónica para un StatementHandle asociado a ConnectionHandle y todavía se estaba ejecutando cuando se llamó a SQLSetConnectAttr . (DM) Se llamó a una función que ejecuta de forma asincrónica (no esta) para ConnectionHandle y todavía se estaba ejecutando cuando se llamó a esta función. (DM) SE llamó a SQLExecute, SQLExecDirect o SQLMoreResults para uno de los identificadores de instrucción asociados a ConnectionHandle y devueltos SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. (DM) SE llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para un StatementHandle asociado a ConnectionHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución. (DM) SE llamó a SQLBrowseConnect para connectionHandle y se devolvió SQL_NEED_DATA. Se llamó a esta función antes de que SQLBrowseConnect devolvió SQL_SUCCESS_WITH_INFO o SQL_SUCCESS. |
| HY011 | El atributo no se puede establecer ahora | El argumento Attribute se SQL_ATTR_TXN_ISOLATION y se abrió una transacción. |
| HY013 | Error de administración de memoria | No se pudo procesar la llamada de función porque no se pudo tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja. |
| HY024 | Valor de atributo no válido | Dado el valor attribute especificado, se especificó un valor no válido en ValuePtr. (El Administrador de controladores devuelve este valor SQLSTATE solo para los atributos de conexión y instrucción que aceptan un conjunto discreto de valores, como SQL_ATTR_ACCESS_MODE o SQL_ATTR_ASYNC_ENABLE. Para todos los demás atributos de conexión y instrucción, el controlador debe comprobar el valor especificado en ValuePtr). El argumento Attribute se SQL_ATTR_TRACEFILE o SQL_ATTR_TRANSLATE_LIB, y ValuePtr era una cadena vacía. |
| HY090 | Longitud de búfer o cadena no válida | (DM) *ValuePtr es una cadena de caracteres y el argumento StringLength era menor que 0, pero no se SQL_NTS. |
| HY092 | Identificador de atributo o opción no válido | (DM) El valor especificado para el argumento Attribute no era válido para la versión de ODBC compatible con el controlador. (DM) El valor especificado para el argumento Attribute era un atributo de solo lectura. |
| HY114 | El controlador no admite la ejecución de funciones asincrónicas de nivel de conexión | (DM) Una aplicación intentó habilitar la ejecución asincrónica de funciones con SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE para un controlador que no admite operaciones de conexión asincrónicas. |
| HY117 | La conexión se suspende debido al estado de transacción desconocido. Solo se permiten las funciones de desconexión y solo lectura. | (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran. |
| HY121 | La biblioteca de cursores y la agrupación compatible con controladores no se pueden habilitar al mismo tiempo | Para obtener más información, vea Agrupación de conexiones compatibles con controladores. |
| HYC00 | Característica opcional no implementada | El valor especificado para el argumento Attribute era un atributo de instrucción o conexión ODBC válido para la versión de ODBC compatible con el controlador, pero no era compatible con el controlador. |
| HYT01 | Se ha agotado el tiempo de espera de la conexión. | El período de tiempo de espera de conexión expiró antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | El controlador no admite esta función | (DM) El controlador asociado a ConnectionHandle no admite la función . |
| IM009 | No se puede cargar el archivo DLL de traducción | El controlador no pudo cargar el archivo DLL de traducción que se especificó para la conexión. Este error solo se puede devolver cuando attribute es SQL_ATTR_TRANSLATE_LIB. |
| IM017 | El sondeo está deshabilitado en modo de notificación asincrónica | Cada vez que se usa el modelo de notificación, el sondeo está deshabilitado. |
| IM018 | No se ha llamado a SQLCompleteAsync para completar la operación asincrónica anterior en este identificador. | Si la llamada de función anterior en el identificador devuelve SQL_STILL_EXECUTING y si el modo de notificación está habilitado, se debe llamar a SQLCompleteAsync en el identificador para realizar el procesamiento posterior y completar la operación. |
| S1118 | El controlador no admite notificaciones asincrónicas | SQL_ATTR_ASYNC_DBC_EVENT se estableció (después de realizar la conexión), pero el controlador no admite la notificación asincrónica. |
Cuando Attribute es un atributo de instrucción, SQLSetConnectAttr puede devolver cualquier SQLSTATEs devuelto por SQLSetStmtAttr.
Comentarios
Para obtener información general sobre los atributos de conexión, consulte Atributos de conexión.
Los atributos definidos actualmente y la versión de ODBC en la que se introdujeron se muestran en la tabla más adelante en esta sección; se espera que se definan más atributos para aprovechar los distintos orígenes de datos. ODBC reserva un intervalo de atributos; los desarrolladores de controladores deben reservar valores para su propio uso específico del controlador de Open Group.
Nota:
La capacidad de establecer atributos de instrucción en el nivel de conexión mediante una llamada a SQLSetConnectAttr está en desuso en ODBC 3*.x*. Las aplicaciones ODBC 3*.x* nunca deben establecer atributos de instrucción en el nivel de conexión. Los atributos de instrucción ODBC 3*.x* no se pueden establecer en el nivel de conexión, a excepción de los atributos SQL_ATTR_METADATA_ID y SQL_ATTR_ASYNC_ENABLE, que son atributos de conexión y atributos de instrucción y se pueden establecer en el nivel de conexión o en el nivel de instrucción.
Los controladores ODBC 3*.x* solo necesitan admitir esta funcionalidad si deben funcionar con aplicaciones ODBC 2*.x* que establecen las opciones de instrucción ODBC 2*.x* en el nivel de conexión. Para obtener más información, vea Asignación de SQLSetConnectOption en el Apéndice G: Instrucciones del controlador para la compatibilidad con versiones anteriores.
Una aplicación puede llamar a SQLSetConnectAttr en cualquier momento entre el momento en que se asigna y libera la conexión. Todos los atributos de conexión y instrucción establecidos correctamente por la aplicación para la conexión persisten hasta que se llama a SQLFreeHandle en la conexión. Por ejemplo, si una aplicación llama a SQLSetConnectAttr antes de conectarse a un origen de datos, el atributo persiste incluso si SQLSetConnectAttr produce un error en el controlador cuando la aplicación se conecta al origen de datos; si una aplicación establece un atributo específico del controlador, el atributo persiste incluso si la aplicación se conecta a un controlador diferente en la conexión.
Algunos atributos de conexión solo se pueden establecer antes de que se haya realizado una conexión; otros solo se pueden establecer después de realizar una conexión. En la tabla siguiente se indican los atributos de conexión que se deben establecer antes o después de realizar una conexión. Indica que el atributo se puede establecer antes o después de la conexión.
| Attribute | ¿Se establece antes o después de la conexión? |
|---|---|
| SQL_ATTR_ACCESS_MODE | [1] |
| SQL_ATTR_ASYNC_DBC_EVENT | Es posible usar el |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE | [4] |
| SQL_ATTR_ASYNC_DBC_PCALLBACK | Es posible usar el |
| SQL_ATTR_ASYNC_DBC_PCONTEXT | Es posible usar el |
| SQL_ATTR_ASYNC_ENABLE | [2] |
| SQL_ATTR_AUTO_IPD | Es posible usar el |
| SQL_ATTR_AUTOCOMMIT | [5] |
| SQL_ATTR_CONNECTION_DEAD | Después |
| SQL_ATTR_CONNECTION_TIMEOUT | Es posible usar el |
| SQL_ATTR_CURRENT_CATALOG | [1] |
| SQL_ATTR_DBC_INFO_TOKEN | Después |
| SQL_ATTR_ENLIST_IN_DTC | Después |
| SQL_ATTR_LOGIN_TIMEOUT | Antes |
| SQL_ATTR_METADATA_ID | Es posible usar el |
| SQL_ATTR_ODBC_CURSORS | Antes |
| SQL_ATTR_PACKET_SIZE | Antes |
| SQL_ATTR_QUIET_MODE | Es posible usar el |
| SQL_ATTR_TRACE | Es posible usar el |
| SQL_ATTR_TRACEFILE | Es posible usar el |
| SQL_ATTR_TRANSLATE_LIB | Después |
| SQL_ATTR_TRANSLATE_OPTION | Después |
| SQL_ATTR_TXN_ISOLATION | [3] |
[1] SQL_ATTR_ACCESS_MODE y SQL_ATTR_CURRENT_CATALOG se pueden establecer antes o después de conectarse, dependiendo del controlador. Sin embargo, las aplicaciones interoperables los establecen antes de conectarse porque algunos controladores no admiten cambiarlos después de conectarse.
[2] SQL_ATTR_ASYNC_ENABLE deben establecerse antes de que haya una instrucción activa.
[3] SQL_ATTR_TXN_ISOLATION solo se pueden establecer si no hay transacciones abiertas en la conexión. Algunos atributos de conexión admiten la sustitución de un valor similar si el origen de datos no admite el valor especificado en *ValuePtr. En tales casos, el controlador devuelve SQL_SUCCESS_WITH_INFO y SQLSTATE 01S02 (valor de opción cambiado). Por ejemplo, si Attribute es SQL_ATTR_PACKET_SIZE y *ValuePtr supera el tamaño máximo de paquete, el controlador sustituye el tamaño máximo. Para determinar el valor sustituido, una aplicación llama a SQLGetConnectAttr.
[4] Si SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE se establece antes de que se abra una conexión, el Administrador de controladores establecerá el atributo del controlador cuando el controlador se cargue durante una llamada a SQLBrowseConnect, SQLConnect o SQLDriverConnect. Antes de una llamada a SQLBrowseConnect, SQLConnect o SQLDriverConnect, el Administrador de controladores no sabe a qué controlador conectarse y no sabe si el controlador admite operaciones de conexión asincrónicas. Por lo tanto, el Administrador de controladores siempre devuelve SQL_SUCCESS. Pero, en caso de que el controlador no admita operaciones de conexión asincrónicas, se producirá un error en la llamada a SQLBrowseConnect, SQLConnect o SQLDriverConnect.
[5] Cuando SQL_ATTR_AUTOCOMMIT se establece en FALSE, las aplicaciones deben llamar a SQLEndTran(SQL_ROLLBACK) si alguna API devuelve SQL_ERROR para garantizar la coherencia transaccional.
El formato de información establecido en el búfer *ValuePtr depende del atributo especificado. SQLSetConnectAttr aceptará información de atributo en uno de los dos formatos diferentes: una cadena de caracteres terminada en NULL o un valor entero. El formato de cada uno se indica en la descripción del atributo. Las cadenas de caracteres a las que apunta el argumento ValuePtr de SQLSetConnectAttr tienen una longitud de bytes StringLength .
El argumento StringLength se omite si el atributo define la longitud, como es el caso de todos los atributos introducidos en ODBC 2*.x* o versiones anteriores.
| Atributo | Contenido de ValuePtr |
|---|---|
| SQL_ATTR_ACCESS_MODE (ODBC 1.0) | Valor SQLUINTEGER. el controlador o el origen de datos usan SQL_MODE_READ_ONLY como indicador de que la conexión no es necesaria para admitir instrucciones SQL que provocan que se produzcan actualizaciones. Este modo se puede usar para optimizar las estrategias de bloqueo, la administración de transacciones u otras áreas según corresponda al controlador o al origen de datos. El controlador no es necesario para evitar que dichas instrucciones se envíen al origen de datos. El comportamiento del controlador y del origen de datos cuando se le pide que procese instrucciones SQL que no son de solo lectura durante una conexión de solo lectura está definida por la implementación. SQL_MODE_READ_WRITE es el valor predeterminado. |
| SQL_ATTR_ASYNC_DBC_EVENT (ODBC 3.8) | Valor SQLPOINTER que es un identificador de eventos. La notificación de la finalización de funciones asincrónicas está habilitada mediante una llamada a SQLSetConnectAttr con el atributo SQL_ATTR_ASYNC_STMT_EVENT y especificando el identificador de eventos. Nota: El método de notificación no se admite con la biblioteca de cursores. Una aplicación recibirá un mensaje de error si intenta habilitar la biblioteca de cursores a través de SQLSetConnectAttr cuando está habilitado el método de notificación. |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE (ODBC 3.8) | Valor SQLUINTEGER que habilita o deshabilita la ejecución asincrónica de funciones seleccionadas en el identificador de conexión. Para obtener más información, consulte Ejecución asincrónica (método de sondeo). SQL_ASYNC_DBC_ENABLE_ON = Habilitar la operación asincrónica para las funciones relacionadas con la conexión especificadas. SQL_ASYNC_DBC_ENABLE_OFF = (valor predeterminado) Deshabilite la operación asincrónica para las funciones relacionadas con la conexión especificadas. Establecer SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE siempre es sincrónico (es decir, nunca devolverá SQL_STILL_EXECUTING). La ejecución asincrónica de operaciones de instrucciones está habilitada con SQL_ATTR_ASYNC_ENABLE. |
| SQL_ATTR_ASYNC_DBC_PCALLBACK (ODBC 3.8) | Valor SQLPOINTER que apunta a la estructura de contexto. Solo el Administrador de controladores puede llamar a la función SQLSetStmtAttr de un controlador con este atributo. |
| SQL_ATTR_ASYNC_DBC_PCONTEXT (ODBC 3.8) | Valor SQLPOINTER que apunta a la estructura de contexto. Solo el Administrador de controladores puede llamar a la función SQLSetStmtAttr de un controlador con este atributo. |
| SQL_ATTR_ASYNC_ENABLE (ODBC 3.0) | Valor de SQLULEN que especifica si una función denominada con una instrucción en la conexión especificada se ejecuta de forma asincrónica: SQL_ASYNC_ENABLE_OFF = Deshabilitar la compatibilidad de ejecución asincrónica de nivel de conexión para las operaciones de instrucciones (valor predeterminado). SQL_ASYNC_ENABLE_ON = Habilitar la compatibilidad con la ejecución asincrónica de nivel de conexión para las operaciones de instrucciones. Este atributo se puede establecer si SQLGetInfo con el tipo de información SQL_ASYNC_MODE devuelve SQL_AM_CONNECTION o SQL_AM_STATEMENT. |
| SQL_ATTR_AUTO_IPD (ODBC 3.0) | Valor SQLUINTEGER de solo lectura que especifica si se admite el rellenado automático del IPD después de una llamada a SQLPrepare : SQL_TRUE = Rellenado automático del IPD después de una llamada a SQLPrepare es compatible con el controlador. SQL_FALSE = El controlador no admite el rellenado automático del IPD después de una llamada a SQLPrepare . Los servidores que no admiten instrucciones preparadas no podrán rellenar el IPD automáticamente. Si se devuelve SQL_TRUE para el atributo de conexión de SQL_ATTR_AUTO_IPD, el atributo de instrucción SQL_ATTR_ENABLE_AUTO_IPD se puede establecer para activar o desactivar el rellenado automático del IPD. Si SQL_ATTR_AUTO_IPD es SQL_FALSE, no se puede establecer SQL_ATTR_ENABLE_AUTO_IPD en SQL_TRUE. El valor predeterminado de SQL_ATTR_ENABLE_AUTO_IPD es igual al valor de SQL_ATTR_AUTO_IPD. SQLGetConnectAttr puede devolver este atributo de conexión, pero SQLSetConnectAttr no puede establecerlo. |
| SQL_ATTR_AUTOCOMMIT (ODBC 1.0) | Valor SQLUINTEGER que especifica si se debe usar el modo de confirmación automática o manual: SQL_AUTOCOMMIT_OFF = El controlador usa el modo de confirmación manual y la aplicación debe confirmar o revertir explícitamente transacciones con SQLEndTran. SQL_AUTOCOMMIT_ON = El controlador usa el modo de confirmación automática. Cada instrucción se confirma inmediatamente después de que se ejecute. Este es el valor predeterminado. Las transacciones abiertas en la conexión se confirman cuando SQL_ATTR_AUTOCOMMIT se establece en SQL_AUTOCOMMIT_ON para cambiar del modo de confirmación manual al modo de confirmación automática. Para obtener más información, vea Modo de confirmación. Importante: algunos orígenes de datos eliminan los planes de acceso y cierran los cursores de todas las instrucciones de una conexión cada vez que se confirma una instrucción; el modo de confirmación automática puede provocar que esto ocurra después de que se ejecute cada instrucción noquery o cuando se cierre el cursor para una consulta. Para obtener más información, vea los tipos de información de SQL_CURSOR_COMMIT_BEHAVIOR y SQL_CURSOR_ROLLBACK_BEHAVIOR en SQLGetInfo y Effect of Transactions on Cursors and Prepared Statements (Efectos de transacciones en cursores e instrucciones preparadas). Cuando se ejecuta un lote en modo de confirmación automática, se pueden realizar dos cosas. Todo el lote se puede tratar como una unidad autocommitible, o cada instrucción de un lote se trata como una unidad autocommitible. Algunos orígenes de datos pueden admitir estos comportamientos y pueden proporcionar una manera de elegir uno o otro. Se define el controlador si un lote se trata como una unidad autocommitible o si cada instrucción individual dentro del lote se puede realizar automáticamente. |
| SQL_ATTR_CONNECTION_DEAD (ODBC 3.5) |
Valor SQLUINTEGER de solo lectura que indica el estado de la conexión. Si SQL_CD_TRUE, se ha perdido la conexión. Si SQL_CD_FALSE, la conexión sigue activa. |
| SQL_ATTR_CONNECTION_TIMEOUT (ODBC 3.0) | Valor SQLUINTEGER correspondiente al número de segundos que se espera a que se complete cualquier solicitud en la conexión antes de volver a la aplicación. El controlador debe devolver SQLSTATE HYT00 (tiempo de espera expirado) siempre que sea posible agotar el tiempo de espera en una situación que no esté asociada con la ejecución o el inicio de sesión de la consulta. Si ValuePtr es igual a 0 (valor predeterminado), no hay tiempo de espera. |
| SQL_ATTR_CURRENT_CATALOG (ODBC 2.0) | Cadena de caracteres que contiene el nombre del catálogo que va a usar el origen de datos. Por ejemplo, en SQL Server, el catálogo es una base de datos, por lo que el controlador envía una instrucción USE database al origen de datos, donde la base de datos es la base de datos especificada en *ValuePtr. Para un controlador de nivel único, el catálogo podría ser un directorio, por lo que el controlador cambia su directorio actual al directorio especificado en *ValuePtr. |
| SQL_ATTR_DBC_INFO_TOKEN (ODBC 3.8) | Valor SQLPOINTER usado para volver a establecer el token de información de conexión en el identificador DBC cuando el parámetro (*pRating) de SQLRateConnection no es igual a 100. SQL_ATTR_DBC_INFO_TOKEN es de solo establecimiento. No es posible usar SQLGetConnectAttr o SQLGetConnectOption para recuperar este valor. SqlSetConnectAttr del Administrador de controladores no aceptará SQL_ATTR_DBC_INFO_TOKEN, ya que una aplicación no debe establecer este atributo. Si un controlador devuelve SQL_ERROR después de establecer SQL_ATTR_DBC_INFO_TOKEN, se liberará la conexión que acaba de obtener del grupo. A continuación, el Administrador de controladores intentará obtener otra conexión del grupo. Consulte Desarrollo de reconocimiento de grupos de conexiones en un controlador ODBC para obtener más información. |
| SQL_ATTR_ENLIST_IN_DTC (ODBC 3.0) | Valor SQLPOINTER que especifica si se debe usar el controlador ODBC en transacciones distribuidas coordinadas por Los servicios de componentes de Microsoft. Pase un objeto de transacción OLE DTC que especifique la transacción que se va a exportar a SQL Server o SQL_DTC_DONE para finalizar la asociación DTC de la conexión. El cliente llama al método Microsoft Distributed Transaction Coordinator (MS DTC) OLE ITransactionDispenser::BeginTransaction para iniciar una transacción de 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_ATTR_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, consulte la documentación de MS DTC. |
| SQL_ATTR_LOGIN_TIMEOUT (ODBC 1.0) | Valor SQLUINTEGER correspondiente al número de segundos para esperar a que se complete una solicitud de inicio de sesión antes de volver a la aplicación. El valor predeterminado es dependiente del controlador. Si ValuePtr es 0, el tiempo de espera está deshabilitado y un intento de conexión esperará indefinidamente. Si el tiempo de espera especificado supera el tiempo de espera máximo de inicio de sesión en el origen de datos, el controlador sustituye ese valor y devuelve SQLSTATE 01S02 (valor de opción cambiado). |
| SQL_ATTR_METADATA_ID (ODBC 3.0) | Valor SQLUINTEGER que determina cómo se tratan los argumentos de cadena de las funciones de catálogo. Si SQL_TRUE, el argumento string de las funciones de catálogo se trata como identificadores. El caso no es significativo. En el caso de las cadenas no delimitadas, el controlador quita los espacios finales y la cadena se plega a mayúsculas. En el caso de las cadenas delimitadas, el controlador quita los espacios iniciales o finales y toma literalmente lo que sea entre los delimitadores. Si uno de estos argumentos se establece en un puntero nulo, la función devuelve SQL_ERROR y SQLSTATE HY009 (uso no válido del puntero NULO). Si SQL_FALSE, los argumentos de cadena de las funciones de catálogo no se tratan como identificadores. El caso es significativo. Pueden contener un patrón de búsqueda de cadenas o no, dependiendo del argumento . El valor predeterminado es SQL_FALSE. El argumento TableType de SQLTables, que toma una lista de valores, no se ve afectado por este atributo. SQL_ATTR_METADATA_ID también se puede establecer en el nivel de instrucción. (Es el único atributo de conexión que también es un atributo de instrucción). Para obtener más información, consulte Argumentos en funciones de catálogo. |
| SQL_ATTR_ODBC_CURSORS (ODBC 2.0) | Valor SQLULEN que especifica cómo usa el Administrador de controladores la biblioteca de cursores ODBC: SQL_CUR_USE_IF_NEEDED = El Administrador de controladores usa la biblioteca de cursores ODBC solo si es necesario. Si el controlador admite la opción SQL_FETCH_PRIOR en SQLFetchScroll, el Administrador de controladores usa las funcionalidades de desplazamiento del controlador. De lo contrario, usa la biblioteca de cursores ODBC. SQL_CUR_USE_ODBC = El Administrador de controladores usa la biblioteca de cursores ODBC. SQL_CUR_USE_DRIVER = El Administrador de controladores usa las funcionalidades de desplazamiento del controlador. Esta es la configuración predeterminada. Para obtener más información sobre la biblioteca de cursores ODBC, vea Apéndice F: Biblioteca de cursores ODBC. Advertencia: la biblioteca de cursores se quitará en una versión futura de Windows. Evite utilizar esta característica en nuevos trabajos de desarrollo y tenga previsto modificar las aplicaciones que actualmente la utilizan. Microsoft recomienda usar la funcionalidad de cursor del controlador. |
| SQL_ATTR_PACKET_SIZE (ODBC 2.0) | Valor SQLUINTEGER que especifica el tamaño del paquete de red en bytes. Nota: Muchos orígenes de datos no admiten esta opción o solo pueden devolver, pero no establecer el tamaño del paquete de red. Si el tamaño especificado supera el tamaño máximo de paquete o es menor que el tamaño mínimo del paquete, el controlador sustituye ese valor y devuelve SQLSTATE 01S02 (valor de opción cambiado). Si la aplicación establece el tamaño del paquete después de que ya se haya realizado una conexión, el controlador devolverá SQLSTATE HY011 (el atributo no se puede establecer ahora). |
| SQL_ATTR_QUIET_MODE (ODBC 2.0) | Un identificador de ventana (HWND). Si el identificador de ventana es un puntero nulo, el controlador no muestra ningún cuadro de diálogo. Si el identificador de ventana no es un puntero nulo, debe ser el identificador primario de la ventana de la aplicación. Este es el valor predeterminado. El controlador usa este identificador para mostrar cuadros de diálogo. Nota: El atributo de conexión SQL_ATTR_QUIET_MODE no se aplica a los cuadros de diálogo mostrados por SQLDriverConnect. |
| SQL_ATTR_TRACE (ODBC 1.0) | Valor SQLUINTEGER que indica al Administrador de controladores si se va a realizar el seguimiento: SQL_OPT_TRACE_OFF = Seguimiento desactivado (valor predeterminado) SQL_OPT_TRACE_ON = Seguimiento en Cuando el seguimiento está activado, el Administrador de controladores escribe cada llamada de función ODBC al archivo de seguimiento. Nota: Cuando el seguimiento está activado, el Administrador de controladores puede devolver SQLSTATE IM013 (error de archivo de seguimiento) desde cualquier función. Una aplicación especifica un archivo de seguimiento con la opción SQL_ATTR_TRACEFILE. Si el archivo ya existe, el Administrador de controladores se anexa al archivo. De lo contrario, crea el archivo. Si el seguimiento está activado y no se ha especificado ningún archivo de seguimiento, el Administrador de controladores escribe en el archivo SQL. INICIE SESIÓN en el directorio raíz. Una aplicación puede establecer la variable ODBCSharedTraceFlag para habilitar el seguimiento dinámicamente. A continuación, el seguimiento se habilita para todas las aplicaciones ODBC que se ejecutan actualmente. Si una aplicación desactiva el seguimiento, solo se desactiva para esa aplicación. Si la palabra clave Trace de la información del sistema se establece en 1 cuando una aplicación llama a SQLAllocHandle con un HandleType de SQL_HANDLE_ENV, el seguimiento está habilitado para todos los identificadores. Solo está habilitado para la aplicación que llamó a SQLAllocHandle. Llamar a SQLSetConnectAttr con un atributo de SQL_ATTR_TRACE no requiere que el argumento ConnectionHandle sea válido y no devolverá SQL_ERROR si ConnectionHandle es NULL. Este atributo se aplica a todas las conexiones. |
| SQL_ATTR_TRACEFILE (ODBC 1.0) | Cadena de caracteres terminada en NULL que contiene el nombre del archivo de seguimiento. El valor predeterminado del atributo SQL_ATTR_TRACEFILE se especifica con la palabra clave TraceFile en la información del sistema. Para obtener más información, vea Subclave ODBC. Llamar a SQLSetConnectAttr con un atributo de SQL_ATTR_TRACEFILE no requiere que el argumento ConnectionHandle sea válido y no devolverá SQL_ERROR si ConnectionHandle no es válido. Este atributo se aplica a todas las conexiones. |
| SQL_ATTR_TRANSLATE_LIB (ODBC 1.0) | Cadena de caracteres terminada en NULL que contiene el nombre de una biblioteca que contiene las funciones SQLDriverToDataSource y SQLDataSourceToDriver a las que el controlador accede para realizar tareas como la traducción del juego de caracteres. Esta opción solo se puede especificar si el controlador se ha conectado al origen de datos. El valor de este atributo se conservará entre las conexiones. Para obtener más información sobre la traducción de datos, vea Translation DLL and Translation DLL Function Reference. |
| SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) | Valor de marca de 32 bits que se pasa al archivo DLL de traducción. Este atributo solo se puede especificar si el controlador se ha conectado al origen de datos. Para obtener información sobre la traducción de datos, consulte Archivos DLL de traducción. |
| SQL_ATTR_TXN_ISOLATION (ODBC 1.0) | Máscara de bits de 32 bits que establece el nivel de aislamiento de transacción para la conexión actual. Una aplicación debe llamar a SQLEndTran para confirmar o revertir todas las transacciones abiertas en una conexión, antes de llamar a SQLSetConnectAttr con esta opción. Los valores válidos para ValuePtr se pueden determinar llamando a SQLGetInfo con InfoType igual a SQL_TXN_ISOLATION_OPTIONS. Para obtener una descripción de los niveles de aislamiento de transacción, vea la descripción del tipo de información de SQL_DEFAULT_TXN_ISOLATION en SQLGetInfo y Niveles de aislamiento de transacciones. |
[1] Estas funciones solo se pueden llamar de forma asincrónica si el descriptor es un descriptor de implementación, no un descriptor de aplicación.
Ejemplo de código
Consulte SQLConnect.
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Asignación de un identificador | Función SQLAllocHandle |
| Devolver el valor de un atributo de conexión | Función SQLGetConnectAttr |