Chapter 2: Functions

CTBEXIT

Description

Exits Client-Library.

Syntax

COPY CTPUBLIC.

01 CONTEXT          PIC S9(9) COMP SYNC.
01 RETCODE          PIC S9(9) COMP SYNC.
01 OPTION           PIC S9(9) COMP SYNC.

CALL 'CTBEXIT' USING CONTEXT RETCODE OPTION.

Parameters

CONTEXT

(I) A context structure. The context structure is defined in the program call CSBCTXALLOC. This value identifies the Client-Library context being exited.

If this value is invalid or nonexistent, CTBEXIT fails.

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

(O) Indicator specifying whether or not CTBEXIT closes connections for which results are pending.

CTBEXIT behaves in differently, depending on the value specified for OPTION. The following table lists the symbolic values that are legal for OPTION:

OPTION Value	CTBEXIT Action
CS-UNUSED (-99999)	Closes all open connections for which no results are pending and terminates Client-Library for this context. If results are pending for one or more connections, CTBEXIT returns CS-FAIL and does not terminate Client-Library.
CS-FORCE-EXIT (300)	Closes all open connections for this context, whether or not any results are pending, and terminates Client-Library for this context.

Returns

CTBEXIT returns one of the following values:

Value	Meaning
CS-SUCCEED (-1)	The routine completed successfully.
CS-FAIL (-2)	The routine failed.
TDS-INVALID-PARAMETER (-4)	A parameter contains an illegal value.
TDS-RESULTS-STILL-ACTIVE (-50)	Some results are still pending.
TDS-CONNECTION-TERMINATED (-4997)	The connection is not active.
TDS-WRONG-STATE (-6)	Program is in the wrong communication state to issue this call.

Examples

Example 1

The following code fragment demonstrates the use of CTBEXIT 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 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

CTBEXIT terminates a Client-Library context. It closes all open connections, deallocates internal data space and cleans up any platform-specific initialization.
CTBEXIT must be the last Client-Library routine called within a Client-Library context.
If an application needs to call Client-Library routines after it calls CTBEXIT, it can re-initialize Client-Library by calling CTBINIT again.
If results are pending on any of the context connections and OPTION is not passed as CS-FORCE-EXIT, CTBEXIT returns CS-FAIL. This means that Client-Library is not correctly terminated. The application must handle the pending results before calling CTBEXIT, or it can call CTBEXIT again, specifying CS-FORCE-EXIT.
To close a single connection, an application calls CTBCLOSE.
If CTBINIT is called for a context, the application must call CTBEXIT before it calls CSBCTXDROP to deallocate the context.