Función SQLDisconnect

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

Resumen
SQLDisconnect cierra la conexión asociada a un identificador de conexión específico.

Sintaxis

  
SQLRETURN SQLDisconnect(  
     SQLHDBC     ConnectionHandle);  

Argumentos

ConnectionHandle
[Entrada] Identificador de conexión.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.

Diagnóstico

Cuando SQLDisconnect 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 SQLDisconnect 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).
01002	Error de desconexión	Error durante la desconexión. Sin embargo, la desconexión se realizó correctamente. (Function devuelve SQL_SUCCESS_WITH_INFO).
08003	Conexión no abierta	(DM) La conexión especificada en el argumento ConnectionHandle no estaba abierta.
25000	Estado de transacción no válido	Hubo una transacción en proceso en la conexión especificada por el argumento ConnectionHandle. La transacción permanece activa.
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 y antes de que se ejecutara la función SQLCancelHandle 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 multiproceso.
HY010	Error de secuencia de función	(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 SQLDisconnect . (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 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.
HY013	Error de administración de memoria	No se pudo procesar la llamada de función porque no se pudo acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY117	La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura.	(DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.
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 y la conexión todavía está activa. 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

Si una aplicación llama a SQLDisconnect después de que SQLBrowseConnect devuelva SQL_NEED_DATA y antes de que devuelva un código de retorno diferente, el controlador cancela el proceso de exploración de la conexión y devuelve la conexión a un estado no conectado.

Si una aplicación llama a SQLDisconnect mientras hay una transacción incompleta asociada al identificador de conexión, el controlador devuelve SQLSTATE 25000 (estado de transacción no válido), lo que indica que la transacción no cambia y la conexión está abierta. Una transacción incompleta es una que no se ha confirmado o revertido con SQLEndTran.

Si una aplicación llama a SQLDisconnect antes de liberar todas las instrucciones asociadas a la conexión, el controlador, después de que se desconecte correctamente del origen de datos, libera esas instrucciones y todos los descriptores que se han asignado explícitamente en la conexión. Sin embargo, si una o varias de las instrucciones asociadas a la conexión siguen ejecutándose de forma asincrónica, SQLDisconnect devuelve SQL_ERROR con un valor SQLSTATE de HY010 (error de secuencia de función). Además, SQLDisconnect liberará todas las instrucciones asociadas y todos los descriptores que se hayan asignado explícitamente en la conexión, si la conexión está en un estado suspendido o si SQLDisconnect se canceló correctamente mediante SQLCancelHandle.

Para obtener información sobre cómo una aplicación usa SQLDisconnect, vea Desconectar de un origen de datos o un controlador.

Desconexión de una conexión agrupada

Si la agrupación de conexiones está habilitada para un entorno compartido y una aplicación llama a SQLDisconnect en una conexión de ese entorno, la conexión se devuelve al grupo de conexiones y sigue estando disponible para otros componentes mediante el mismo entorno compartido.

Ejemplo de código

Consulte El programa ODBC de ejemplo, la función SQLBrowseConnect y la función SQLConnect.

Funciones relacionadas

Para información acerca de	Vea
Asignar un identificador	Función SQLAllocHandle
Conectarse a un origen de datos	Función SQLConnect
Conexión a un origen de datos mediante una cadena de conexión o un cuadro de diálogo	Función SQLDriverConnect
Ejecución de una operación de confirmación o reversión	Función SQLEndTran
Liberar un identificador de conexión	Función SQLFreeConnect

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC