Chapter 2: Functions

CTBCONDROP

Description

Deallocates a connection handle.

Syntax

COPY CTPUBLIC.

01 CONNECTION PIC S9(9) COMP SYNC.
01 RETCODE PIC S9(9) COMP SYNC.

CALL ‘CTBCONDR' USING CONNECTION RETCODE.

Parameters

CONNECTION: (I) Handle for this connection. This must be the same value specified in the CTBCONALLOC call that initialized this connection.

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.

Returns

CTBCONDROP 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 CTBCONDROP failure is that the connection is still open.
TDS-CONNECTION-TERMINATED (-4997)	The connection is not active.

Value

Meaning

CS-SUCCEED (-1)

The routine completed successfully.

CS-FAIL (-2)

The routine failed.

The most common reason for a CTBCONDROP failure is that the connection is still open.

TDS-CONNECTION-TERMINATED (-4997)

The connection is not active.

Examples

Example 1

The following code fragment demonstrates the use of CTBCONDROP 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.
       *===================================================
       *==                                               ==
       *== Subroutine to perform exit client library and ==
       *== deallocate context structure.                 ==
       *==                                               ==
       *===================================================
        QUIT-CLIENT-LIBRARY.
       ***************************
       * EXIT THE CLIENT LIBRARY *
       ***************************
            CALL 'CTBEXIT' USING CSL-CTX-HANDLE
                                 CSL-RC
                                 CS-UNUSED.
            IF CSL-RC = CS-FAIL
              THEN
                MOVE SPACES TO MSGSTR
                STRING 'CTBEXIT failed' DELIMITED BY SIZE INTO MSGSTR
                PERFORM PRINT-MSG
            END-IF.
       *************************************
       * DE-ALLOCATE THE CONTEXT STRUCTURE *
       *************************************
            CALL 'CSBCTXDR' USING CSL-CTX-HANDLE
                                  CSL-RC.
            IF CSL-RC = CS-FAIL
              THEN
                MOVE SPACES TO MSGSTR
                STRING 'CSBCTXDR failed' DELIMITED BY SIZE INTO MSGSTR
                PERFORM PRINT-MSG
            END-IF.
            EXEC CICS RETURN END-EXEC.
        QUIT-CLIENT-LIBRARY-EXIT.
            EXIT.

Usage

CTBCONDROP deallocates a connection handle and all command handles associated with that connection.
Once a connection handle is deallocated, it cannot be reused. To allocate a new connection handle, an application calls CTBCONALLOC.
An application cannot deallocate a connection handle until the connection it represents successfully closes. To close a connection, an application calls CTBCLOSE.