Closes a server connection.
CS_RETCODE ct_close (connection, option); CS_CONNECTION *connection; CS_INT option;
(I) Handle for this SNA connection. This connection handle must already be allocated with ct_con_alloc. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
(I) Option, if any, to use for the close. The following table lists the symbolic values that are legal for option:
Value |
Meaning |
|---|---|
CS_UNUSED (-99999) |
ct_close logs out and closes the connection. If the connection has results pending, ct_close returns CS_FAIL. This is the default behavior. |
CS_FORCE_CLOSE (302) |
ct_close closes the connection 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. |
CS_KEEP_CON |
This option is ignored. CICS treats it like CS_UNUSED. |
ct_close returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. The most common reason for a ct_close failure is pending results on the connection. |
TDS_CONNECTION_TERMINATED (4997) |
The connection is not active. |
TDS_COMMAND_ACTIVE (-7) |
A command is in progress. |
TDS_RESULTS-STILL_ACTIVE (-50) |
Some results are still pending. |
The following code fragment demonstrates how ct_close is used with other functions at the end of a program to close the connection and return to CICS. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
/********************************************************************/
/* */
/* Subroutine to perform drop command handler, close server */
/* connection, and deallocate Connection Handler. */
/* */
/********************************************************************/
void close_connection ()
{
CS_INT rc;
/*------------------------------------------------------------------*/
/* drop the command handle */
/*------------------------------------------------------------------*/
rc = ct_cmd_drop (cmd);
if (rc == CS_FAIL)
{
strncpy (msgstr, "CT_CMD_DROP failed", msg_size);
error_out (rc) ;
}
/*------------------------------------------------------------------*/
/* close the server connection */
/*------------------------------------------------------------------*/
rc = ct_close (connection, (long) CS_UNUSED);
if (rc == CS_FAIL)
{
strncpy (msgstr, "CT_CLOSE failed", msg_size);
error_out (rc) ;
}
/*------------------------------------------------------------------*/
/* De_allocate the connection handle */
/*------------------------------------------------------------------*/
rc = ct_con_drop (connection);
if (rc == CS_FAIL)
{
strncpy (msgstr, "CT_CON_DROP failed", msg_size);
error_out (rc) ;
}
} /* end close_connection */
ct_close closes a server connection. All command handles associated with the connection are deallocated.
To deallocate a connection handle, an application can call ct_con_drop after the connection successfully closes.
The behavior of ct_close depends on the value of option, which determines the type of close. The following sections contain information on a type of close.
If the connection has any pending results, ct_close returns CS_FAIL. To correct the failure, use ct_close with the CS_FORCE_CLOSE option or read in all of your results.
Before terminating the connection with the server, ct_close sends a logout message to the server and reads the response to this message. The contents of this message do not affect the behavior of ct_close.
The connection is closed whether or not it has pending results.
Because this option sends no logout message 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.
Related functions
