ct_close

Description

Close a server connection.

Syntax

CS_RETCODE ct_close(connection, option)
 
 CS_CONNECTION    *connection;
 CS_INT                       option;

Parameters

connection: A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

option

The option to use for the close. The following table lists the symbolic values for option:

Value of option	Meaning
CS_UNUSED (10.0+ servers only)	Default behavior. ct_close sends a logout message to the server and reads the response to this message before closing the connection. If the connection has results pending, ct_close returns CS_FAIL.
CS_FORCE_CLOSE	The connection is closed whether or not results are pending, and without notifying the server. This option is primarily for use when an application is hung waiting for a server response. It is also useful if ct_results, ct_fetch, or ct_cancel returns CS_FAIL.

Value of option

Meaning

CS_UNUSED

(10.0+ servers only)

Default behavior.

ct_close sends a logout message to the server and reads the response to this message before closing the connection.

If the connection has results pending, ct_close returns CS_FAIL.

CS_FORCE_CLOSE

The connection is closed whether or not results are pending, and without notifying the server.

This option is primarily for use when an application is hung waiting for a server response. It is also useful if ct_results, ct_fetch, or ct_cancel returns CS_FAIL.

Returns

ct_close returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.
CS_PENDING	Asynchronous network I/O is in effect. See “Asynchronous programming”. If asynchronous network I/O is in effect and ct_close is called with option as CS_FORCE_CLOSE, it returns CS_SUCCEED or CS_FAIL immediately to indicate the network response. In this case, no completion callback event occurs.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”. Note that ct_close does not return CS_BUSY when called with option as CS_FORCE_CLOSE.

The most common reason for a ct_close(CS_UNUSED) failure is pending results on the connection.

Examples

Example 1

          CS_RETCODE   retcode;

           CS_INT       close_option;

          close_option = (status != CS_SUCCEED)? CS_FORCE_CLOSE :

                CS_UNUSED;

           retcode = ct_close(connection, close_option);

           if (retcode != CS_SUCCEED)

                ex_error("ex_con_cleanup: ct_close() failed");

                return retcode;

This code excerpt is from the exutils.c example program.

Usage

To deallocate a CS_CONNECTION, an application can call ct_con_drop after the connection has been successfully closed.
A connection can become unusable due to error. If this occurs, Client-Library marks the connection as “dead.” An application can use the CS_CON_STATUS property to determine if a connection has been marked “dead.”

If a connection has been marked dead, an application must call ct_close(CS_FORCE_CLOSE) to close the connection and ct_con_drop to drop its CS_CONNECTION structure.

An exception to this rule occurs for certain types of results-processing errors. If a connection is marked “dead” while processing results, the application can try calling ct_cancel(CS_CANCEL_ALL or CS_CANCEL_ATTN) to revive the connection. If this fails, the application must close the connection and drop its CS_CONNECTION structure.
When a connection is closed, all open cursors on that connection are automatically closed.
If the connection is using asynchronous network I/O, ct_close returns CS_PENDING. When the server response arrives, Client-Library closes the connection and then calls the completion callback installed for the connection.
The behavior of ct_close depends on the value of option, which determines the type of close. Each section below contains information about a specific type of close.

Default close behavior

If the connection has any pending results, ct_close returns CS_FAIL. If the connection has any open cursor(s), the server closes the cursor(s) when Client-Library closes the connection.
When connected to a 10.0+ server, ct_close sends a logout message to the server and reads the response to this message before terminating the connection. The contents of this message do not affect ct_close’s behavior.
An application cannot call ct_close(CS_UNUSED) when an asynchronous operation is pending.

CS_FORCE_CLOSE behavior

The connection is closed whether or not it has an open cursor or pending results.
ct_close does not behave asynchronously when called with the CS_FORCE_CLOSE option. When ct_close(CS_FORCE_CLOSE) is called to close an asynchronous connection, it returns CS_SUCCEED or CS_FAIL immediately, to indicate the network response. In this case, no completion callback event occurs.
CS_FORCE_CLOSE is useful when:
- A connection has been marked as dead.
- An application is hung, waiting for a server response.
- An application cannot call ct_close(CS_UNUSED) because results are pending.
Because no logout message is sent to the server, the server cannot tell whether the close is intentional or whether it is the result of a lost connection or crashed client.
An application can call ct_close(CS_FORCE_CLOSE) when an asynchronous operation is pending.