Función SQLEndTran

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 3.0: ISO 92

Resumen
SQLEndTran solicita una operación de confirmación o reversión para todas las operaciones activas en todas las instrucciones asociadas a una conexión. SQLEndTran también puede solicitar que se realice una operación de confirmación o reversión para todas las conexiones asociadas a un entorno.

Nota:

Para obtener más información sobre lo que el Administrador de controladores asigna esta función a cuando un ODBC 3.La aplicación x funciona con ODBC 2.Controlador x , consulte Asignación de funciones de reemplazo para compatibilidad con versiones anteriores de aplicaciones.

Sintaxis

  
SQLRETURN SQLEndTran(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle,  
     SQLSMALLINT   CompletionType);  

Argumentos

HandleType
[Entrada] Controle el identificador de tipo. Contiene SQL_HANDLE_ENV (si Handle es un identificador de entorno) o SQL_HANDLE_DBC (si Handle es un identificador de conexión).

Handle
[Entrada] Identificador del tipo indicado por HandleType, que indica el ámbito de la transacción. Consulte "Comentarios" para obtener más información.

CompletionType
[Entrada] Uno de los dos valores siguientes:

SQL_COMMIT SQL_ROLLBACK

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.

Diagnóstico

Cuando SQLEndTran devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado mediante una llamada a SQLGetDiagRec con el handleType y handle adecuados. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLEndTran 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.

SQLSTATE	Error	Descripción
01000	Advertencia general	Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
08003	Conexión no abierta	(DM) El handleType se SQL_HANDLE_DBC y el identificador no estaba en un estado conectado.
08007	Error de conexión durante la transacción	HandleType se SQL_HANDLE_DBC y se produjo un error en la conexión asociada a Handle durante la ejecución de la función y no se puede determinar si se produjo la confirmación solicitada o ROLLBACK antes del error.
25S01	Estado de transacción desconocido	Una o varias de las conexiones de Handle no pudieron completar la transacción con el resultado especificado y el resultado es desconocido.
25S02	La transacción todavía está activa	El controlador no pudo garantizar que todo el trabajo de la transacción global se pudiera completar de forma atómica y la transacción todavía está activa.
25S03	La transacción se revierte	El controlador no pudo garantizar que todo el trabajo de la transacción global se pudiera completar de forma atómica y todo el trabajo de la transacción activa en Handle se revierte.
40001	Error de serialización	La transacción se revierte debido a un interbloqueo de recursos con otra transacción.
40002	Infracción de restricción de integridad	CompletionType se SQL_COMMIT y el compromiso de los cambios provocó una infracción de restricción de integridad. Como resultado, la transacción se revierte.
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 *szMessageText 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 y antes de terminar de ejecutar la función SQLCancelHandle se llamó a en ConnectionHandle. A continuación, se llamó a la función de nuevo en ConnectionHandle. Se llamó a la función y antes de terminar de ejecutar SQLCancelHandle se llamó a en ConnectionHandle desde un subproceso diferente en una aplicación multithread.
HY010	Error de secuencia de funciones	(DM) Se llamó a una función de ejecución asincrónica para un identificador de instrucción asociado a ConnectionHandle y todavía se estaba ejecutando cuando se llamó a SQLEndTran . (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, SQLBulkOperations o SQLSetPos para un identificador de instrucción asociado a ConnectionHandle y se 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 una función que ejecuta de forma asincrónica (no esta) para el identificador con HandleType establecido en SQL_HANDLE_DBC 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 Handle y devueltos SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos.
HY012	Código de operación de transacción no válido	(DM) El valor especificado para el argumento CompletionType no se SQL_COMMIT ni SQL_ROLLBACK.
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.
HY092	Identificador de atributo o opción no válido	(DM) El valor especificado para el argumento HandleType no se SQL_HANDLE_ENV ni SQL_HANDLE_DBC.
HY115	SQLEndTran no está permitido para un entorno que contenga una conexión con la ejecución de funciones asincrónicas habilitada	(DM) HandleType no se puede establecer en SQL_HANDLE_ENV si la ejecución asincrónica de funciones de conexión está habilitada para una conexión en el entorno.
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, consulte la sección Comentarios de este tema.
HYC00	Característica opcional no implementada	El controlador o el origen de datos no admiten la operación ROLLBACK .
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 .
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.

Comentarios

Para odbc 3.x driver, si HandleType es SQL_HANDLE_ENV y Handle es un identificador de entorno válido, el Administrador de controladores llamará a SQLEndTran en cada controlador asociado al entorno. El argumento Handle para la llamada a un controlador será el identificador del entorno del controlador. Para odbc 2.x driver, si HandleType es SQL_HANDLE_ENV y Handle es un identificador de entorno válido y hay varias conexiones en un estado conectado en ese entorno, el Administrador de controladores llamará a SQLTransact en el controlador una vez para cada conexión en un estado conectado en ese entorno. El argumento Handle de cada llamada será el identificador de la conexión. En cualquier caso, el controlador intentará confirmar o revertir transacciones, dependiendo del valor de CompletionType, en todas las conexiones que están en un estado conectado en ese entorno. Las conexiones que no están activas no afectan a la transacción.

Nota:

SQLEndTran no se puede usar para confirmar ni revertir transacciones en un entorno compartido. SQLSTATE HY092 (identificador de atributo o opción no válido) se devolverá si se llama a SQLEndTran con Handle establecido en el identificador de un entorno compartido o el identificador de una conexión en un entorno compartido.

El Administrador de controladores devolverá SQL_SUCCESS solo si recibe SQL_SUCCESS para cada conexión. Si el Administrador de controladores recibe SQL_ERROR en una o varias conexiones, devuelve SQL_ERROR a la aplicación y la información de diagnóstico se coloca en la estructura de datos de diagnóstico del entorno. Para determinar qué conexión o conexiones no se pudieron realizar durante la operación de confirmación o reversión, la aplicación puede llamar a SQLGetDiagRec para cada conexión.

Nota:

El Administrador de controladores no simula una transacción global en todas las conexiones y, por tanto, no usa protocolos de confirmación en dos fases.

Si CompletionType es SQL_COMMIT, SQLEndTran emite una solicitud de confirmación para todas las operaciones activas en cualquier instrucción asociada a una conexión afectada. Si CompletionType es SQL_ROLLBACK, SQLEndTran emite una solicitud de reversión para todas las operaciones activas en cualquier instrucción asociada a una conexión afectada. Si no hay ninguna transacción activa, SQLEndTran devuelve SQL_SUCCESS sin ningún efecto en ningún origen de datos. Para obtener más información, consulte Confirmar y revertir transacciones.

Si el controlador está en modo de confirmación manual (llamando a SQLSetConnectAttr con el atributo SQL_ATTR_AUTOCOMMIT establecido en SQL_AUTOCOMMIT_OFF), se inicia implícitamente una nueva transacción cuando se ejecuta una instrucción SQL que se puede contener dentro de una transacción en el origen de datos actual. Para obtener más información, vea Modo de confirmación.

Para determinar cómo afectan las operaciones de transacción a los cursores, una aplicación llama a SQLGetInfo con las opciones SQL_CURSOR_ROLLBACK_BEHAVIOR y SQL_CURSOR_COMMIT_BEHAVIOR. Para obtener más información, vea los párrafos siguientes y vea también Efecto de las transacciones en cursores e instrucciones preparadas.

Si el valor de SQL_CURSOR_ROLLBACK_BEHAVIOR o SQL_CURSOR_COMMIT_BEHAVIOR es igual a SQL_CB_DELETE, SQLEndTran cierra y elimina todos los cursores abiertos en todas las instrucciones asociadas a la conexión y descarta todos los resultados pendientes. SQLEndTran deja cualquier instrucción presente en un estado asignado (no preparado); la aplicación puede reutilizarlas para las solicitudes SQL posteriores o puede llamar a SQLFreeStmt o SQLFreeHandle con un HandleType de SQL_HANDLE_STMT para desasignarlos.

Si el valor SQL_CURSOR_ROLLBACK_BEHAVIOR o SQL_CURSOR_COMMIT_BEHAVIOR es igual a SQL_CB_CLOSE, SQLEndTran cierra todos los cursores abiertos en todas las instrucciones asociadas a la conexión. SQLEndTran deja cualquier instrucción presente en un estado preparado; la aplicación puede llamar a SQLExecute para una instrucción asociada a la conexión sin llamar primero a SQLPrepare.

Si el valor SQL_CURSOR_ROLLBACK_BEHAVIOR o SQL_CURSOR_COMMIT_BEHAVIOR es igual a SQL_CB_PRESERVE, SQLEndTran no afecta a los cursores abiertos asociados a la conexión. Los cursores permanecen en la fila a la que apuntaban antes de la llamada a SQLEndTran.

Para controladores y orígenes de datos que admiten transacciones, llamando a SQLEndTran con SQL_COMMIT o SQL_ROLLBACK cuando ninguna transacción está activa devuelve SQL_SUCCESS (lo que indica que no hay ningún trabajo que confirmar o revertir) y no tiene ningún efecto en el origen de datos.

Cuando un controlador está en modo de confirmación automática, el Administrador de controladores no llama a SQLEndTran en el controlador. SQLEndTran siempre devuelve SQL_SUCCESS independientemente de si se llama a con un completionType de SQL_COMMIT o SQL_ROLLBACK.

Los controladores o orígenes de datos que no admiten transacciones (la opción SQLGetInfo SQL_TXN_CAPABLE es SQL_TC_NONE) siempre están en modo de confirmación automática y, por tanto, siempre devuelven SQL_SUCCESS para SQLEndTran tanto si se llaman con un tipo de finalización de SQL_COMMIT como SQL_ROLLBACK. Estos controladores y orígenes de datos no revierten realmente las transacciones cuando se solicita que lo haga.

Estado suspendido

En administradores de controladores que se publicaron antes de Windows 7, una transacción estaba activa si SQLEndTran devolvió SQL_ERROR del controlador. Sin embargo, era posible que la transacción se hubiera confirmado correctamente en el servidor, pero no se había notificado al controlador del cliente (por ejemplo, porque se produjo un error de red). Esto dejaría la conexión en un estado incorrecto. A partir de Windows 7, cuando SQLEndTran devuelve SQL_ERROR, la conexión podría estar en estado suspendido. En un estado suspendido, es posible llamar a funciones de solo lectura. Finalmente, la aplicación debe llamar a SQLDisconnect en una conexión suspendida para liberar recursos.

Si se cumplen todas las condiciones siguientes, la conexión se colocará en un estado suspendido:

• El controlador devuelve SQL_ERROR de SQLEndTran.

• El controlador es ODBC versión 3.8 o posterior.

• La versión de la aplicación es 3.8 o posterior; o bien, la aplicación ODBC 2.x o 3.x recompilada cancela correctamente la función SQLEndTran a través de SQLCancelHandle.

• El controlador no devolvió uno de los siguientes mensajes, lo que confirma que la transacción no se completó:

  • 25S03: La transacción se revierte

  • 40001: Error de serialización

  • 40002: Restricción de integridad

  • HYC00: característica opcional no implementada

Si se llamó a SQLEndTran en un identificador de entorno y una de sus conexiones cumplen las condiciones anteriores, todas las conexiones que se conectan al mismo controlador se colocarán en el estado suspendido.

Una vez que una aplicación llama a SQLDisconnect en una conexión suspendida, la conexión se puede usar para volver a conectarse a otro origen de datos o al mismo origen de datos.

Funciones relacionadas

Para obtener información sobre	Vea
Cancelación de una función que se ejecuta de forma asincrónica en un identificador de conexión.	Función SQLCancelHandle
Devolver información sobre un controlador o un origen de datos	Función SQLGetInfo
Liberar un identificador	Función SQLFreeHandle
Liberar un identificador de instrucción	Función SQLFreeStmt

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC
Ejecución asincrónica (método de sondeo)