Closes a server connection.
COPY CTPUBLIC.
01 CONNECTION PIC S9(9) COMP SYNC. 01 RETCODE PIC S9(9) COMP SYNC. 01 OPTION PIC S9(9) COMP SYNC.
CALL 'CTBCLOSE' USING 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 “Return value,” 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 the use of CTBCLOSE at the end of a program, after results processed. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”
*===========================================================
*== ==
*== Subroutine to perform drop command handler, close ==
*== server connection, and deallocate Connection Handler. ==
*== ==
*===========================================================
CLOSE-CONNECTION.
***************************
* DROP THE COMMAND HANDLE *
***************************
CALL 'CTBCMDDR' USING CSL-CMD-HANDLE
CSL-RC.
IF CSL-RC = CS-FAIL
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCMDDR failed' DELIMITED BY
SIZE INTO MSGSTR
PERFORM PRINT-MSG
END-IF.
*******************************
* CLOSE THE SERVER CONNECTION *
*******************************
CALL 'CTBCLOSE' USING CSL-CON-HANDLE
CSL-RC
CS-UNUSED.
IF CSL-RC = CS-FAIL
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCLOSE failed' DELIMITED BY
SIZE INTO MSGSTR
PERFORM PRINT-MSG
END-IF.
*************************************
* DE-ALLOCATE THE CONNECTION HANDLE *
*************************************
CALL 'CTBCONDR' USING CSL-CON-HANDLE
CSL-RC.
IF CSL-RC = CS-FAIL
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCONDR failed' DELIMITED BY
SIZE INTO MSGSTR
PERFORM PRINT-MSG
END-IF.
CLOSE-CONNECTION-EXIT.
EXIT.
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.
Default close behavior (OPTION is CS-UNUSED)
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.
Forced close behavior (OPTION is CS-FORCE-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
