Chapter 2: Functions

CTBCLOSE

Description

Closes a server connection.

Syntax

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.

Parameters

CONNECTION: (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.

RETCODE: (O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Return value,” in this section.

OPTION

(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.

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.

Returns

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.

Examples

Example 1

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.

Usage

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.