Chapter 3: Functions

CTBCONDROP

Description

Deallocates a connection handle.

Syntax

%INCLUDE CTPUBLIC;

DCL
     01 CONNECTION        FIXED BIN(31) INIT(0);
     01 RETCODE           FIXED BIN(31) INIT(0);
 
CALL CTBCONDR (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 “Returns,” 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 how CTBCONDROP 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 ;

/*------------------------------------------------------------------*/
/*                                                                  */
/* Subroutine to perform exit client library and deallocate context */
/* structure.                                                       */
/*                                                                  */
/*------------------------------------------------------------------*/
 QUIT_CLIENT_LIBRARY: PROC ;
 
/*------------------------------------------------------------------*/
/* exit the Client Library                                          */
/*------------------------------------------------------------------*/
 
         CALL CTBEXIT( CSL_CTX_HANDLE,
                       CSL_RC,
                       CS_UNUSED ) ;
 
         IF CSL_RC = CS_FAIL THEN
         DO ;
           MSGSTR = 'CTBEXIT failed' ;
           CALL ERROR_OUT ;
         END ;
 /*------------------------------------------------------------------*/
 /* de-allocate the context stricture                                */
 /*------------------------------------------------------------------*/
 
         CALL CSBCTXDR( CSL_CTX_HANDLE,
                        CSL_RC ) ;
 
         IF CSL_RC = CS_FAIL THEN
         DO ;
           MSGSTR = 'CSBCTXDROP failed' ;
           CALL ERROR_OUT ;
         END ;
 
         EXEC CICS RETURN ;
 
 END QUIT_CLIENT_LIBRARY ;

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.