DB2 10.5 for Linux, UNIX, and Windows

SQLDisconnect function (CLI) - Disconnect from a data source

Closes the connection associated with the database connection handle.

Specification:

CLI 1.1
ODBC 1.0
ISO CLI

SQLEndTran() must be called before calling SQLDisconnect() if an outstanding transaction exists on this connection.

After calling this function, either call SQLConnect() to connect to another database, or use SQLFreeHandle() to free the connection handle.

Syntax

SQLRETURN   SQLDisconnect (SQLHDBC        ConnectionHandle;) /* hdbc */

Function arguments

Table 1. SQLDisconnect arguments
Data type	Argument	Use	Description
SQLHDBC	ConnectionHandle	input	Connection handle

Usage

If an application calls SQLDisconnect() before it has freed all the statement handles associated with the connection, CLI 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, a problem was encountered on the clean up subsequent to the disconnect, or if there is no current connection because of an event that occurred independently of the application (such as communication failure).

After a successful SQLDisconnect() call, the application can re-use ConnectionHandle to make another SQLConnect() or SQLDriverConnect() request.

An application should not rely on SQLDisconnect() to close cursors (with both stored procedures and regular client applications). In both cases the cursor should be closed using SQLCloseCursor(), then the statement handle freed using SQLFreeHandle().

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLDisconnect SQLSTATEs
SQLSTATE	Description	Explanation
01002	Disconnect error.	An error occurred during the disconnect. However, the disconnect succeeded. (Function returns SQL_SUCCESS_WITH_INFO.)
08003	Connection is closed.	The connection specified in the argument ConnectionHandle was not open.
25000 25501	Invalid transaction state.	There was a transaction in process on the connection specified by the argument ConnectionHandle. The transaction remains active, and the connection cannot be disconnected. Note: This error does not apply to stored procedures written in CLI.
25501	Invalid transaction state.	There was a transaction in process on the connection specified by the argument ConnectionHandle. The transaction remains active, and the connection cannot be disconnected.
58004	Unexpected system failure.	Unrecoverable system error.
HY001	Memory allocation failure.	DB2® CLI is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
HY010	Function sequence error.	The function was called while in a data-at-execute (SQLParamData(), SQLPutData()) operation.
HY013	Unexpected memory handling error.	DB2 CLI was unable to access memory required to support execution or completion of the function.

Restrictions

None.

Example

  SQLHANDLE hdbc; /* connection handle */

  /* ... */
  
  /* disconnect from the database */
    cliRC = SQLDisconnect(hdbc);