Close a server connection.
CS_RETCODE ct_close(connection, option) CS_CONNECTION *connection; CS_INT option;
A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.
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. |
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.
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 sample program.
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.
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.
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.
