SQLDisconnect() - Disconnect from a data source

SQLDisconnect() closes the connection that is associated with the database connection handle. Before you call SQLDisconnect(), you must call SQLEndTran() if an outstanding transaction exists on this connection. After you call this function, either call SQLConnect() to connect to another database, or callSQLFreeHandle().

ODBC specifications for SQLDisconnect()

Table 1. SQLDisconnect() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
1.0 Yes Yes

Syntax

SQLRETURN   SQLDisconnect    (SQLHDBC           hdbc);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLDisconnect() arguments
Data type Argument Use Description
SQLHDBC hdbc input Specifies the connection handle of the connection to close.

Usage

If you call SQLDisconnect() before you free all the statement handles associated with the connection, Db2 ODBC frees them after it successfully disconnects from the database.

If SQL_SUCCESS_WITH_INFO is returned, it implies that even though the disconnect from the database is successful, additional error or implementation-specific information is available. For example, if a problem was encountered during the cleanup processing, subsequent to the disconnect, or if an event occurred independently of the application (such as communication failure) that caused the current connection to be lost, SQLDisconnect() issues SQL_SUCCESS_WITH_INFO.

After a successful SQLDisconnect() call, you can reuse the connection handle you specified in the hdbc argument to make another SQLConnect() or SQLDriverConnect() request.

Return codes

After you call SQLDisconnect(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. SQLDisconnect() SQLSTATEs
SQLSTATE Description Explanation
01002 Disconnect error. An error occurs during the disconnect. However, the disconnect succeeds. SQLDisconnect returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
08003 Connection is closed. The specified connection in the hdbc argument is not open.
25000 or 25501 Invalid transaction state. A transaction is in process for the connection that the hdbc argument specifies. The transaction remains active, and the connection cannot be disconnected.

This error does not apply to stored procedures that are written in Db2 ODBC.
58004 Unexpected system failure. Unrecoverable system error.
HY001 Memory allocation failure. Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY010 Function sequence error. The function is called during a data-at-execute operation. (That is, the function is called during a procedure that uses the SQLParamData() or SQLPutData() functions.)
HY013 Unexpected memory handling error. Db2 ODBC is not able to access the memory that is required to support execution or completion of the function.

Example

Refer to SQLDriverConnect() for a related example.