Closes a server connection.
%INCLUDE CTPUBLIC;
DCL 01 CONNECTION FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 OPTION FIXED BIN(31); CALL CTBCLOSE (CONNECTION, RETCODE, OPTION);
(I) Handle for this connection. This connection handle must already be allocated with CTBCONALLOC. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(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) |
CTBCLOSE logs out and closes the connection. If the connection has results pending, CTBCLOSE returns CS_FAIL. This is the default behavior. |
CS_FORCE_CLOSE (302) |
CTBCLOSE closes the connection whether or not results are pending, and without notifying the server. This option is primarily for use when an application hangs waiting for a server response. |
CS_KEEP_CON |
This option is ignored. CICS treats it like CS_UNUSED. |
CTBCLOSE 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 CTBCLOSE 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 CTBCLOSE 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 SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------------*/
/* */
/* Subroutine to perform drop command handler, close server */
/* connection, and deallocate Connection Handler. */
/* */
/*------------------------------------------------------------------*/
CLOSE_CONNECTION: PROC ;
/*------------------------------------------------------------------*/
/* drop the command handle */
/*------------------------------------------------------------------*/
CALL CTBCMDDR( CSL_CMD_HANDLE,
CSL_RC ) ;
IF CSL_RC = CS_FAIL THEN
DO ;
MSGSTR = 'CTBCMDDROP failed' ;
CALL ERROR_OUT ;
END ;
/*------------------------------------------------------------------*/
/* close the server connection */
/*------------------------------------------------------------------*/
CALL CTBCLOSE( CSL_CON_HANDLE,
CSL_RC,
CS_UNUSED ) ;
IF CSL_RC = CS_FAIL THEN
DO ;
MSGSTR = 'CTBCLOSE failed' ;
CALL ERROR_OUT ;
END ;
/*------------------------------------------------------------------*/
/* DE_ALLOCATE THE CONNECTION HANDLE */
/*------------------------------------------------------------------*/
CALL CTBCONDR( CSL_CON_HANDLE,
CSL_RC ) ;
IF CSL_RC = CS_FAIL THEN
DO ;
MSGSTR = 'CTBCONDROP failed' ;
CALL ERROR_OUT ;
END ;
END CLOSE_CONNECTION ;
CTBCLOSE closes a server connection. All command handles associated with the connection are deallocated.
To deallocate a connection handle, an application can call CTBCONDROP after the connection successfully closes.
The behavior of CTBCLOSE 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, CTBCLOSE returns CS_FAIL. To correct the failure, use CTBCLOSE with the CS_FORCE_CLOSE option or read in all of your results.
Before terminating the connection with the server, CTBCLOSE 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 CTBCLOSE.
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:
