Chapter 2: Functions

CSBCTXDROP

Description

Deallocates a context structure.

Syntax

COPY CTPUBLIC.

01 CONTEXT          PIC S9(9) COMP SYNC.
01 RETCODE          PIC S9(9) COMP SYNC.
 
CALL 'CSBCTXDR' USING CONNECTION RETCODE.

Parameters

CONTEXT: (I) A context structure.

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

Returns

CSBCTXDROP returns one of the following values:

Value	Meaning
CS-SUCCEED (-1)	The routine completed successfully.
CS-FAIL (-2)	The routine failed. The most common cause for a CSBCTXDROP failure is that the context contains an open connection.

Value

Meaning

CS-SUCCEED (-1)

The routine completed successfully.

CS-FAIL (-2)

The routine failed.

The most common cause for a CSBCTXDROP failure is that the context contains an open connection.

Examples

Example 1

The following code fragment demonstrates the use of CSBCTXDROP at the end of a program, after results have been processed. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”

      		*===================================================
       *==                                               ==
       *== 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

CSBCTXDROP deallocates a context structure.
A context structure describes a particular context, or operating environment, for a set of server connections.
Once a context has been deallocated, it cannot be reused. To allocate a new context, an application calls CSBCTXALLOC.
A Client-Library application cannot call CSBCTXDROP to deallocate a context structure until it has called CTBEXIT to clean up Client-Library space associated with the context.
CSBCTXDROP fails if the context contains an open connection.