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 |