Exits Client-Library.
%INCLUDE CTPUBLIC;
DCL 01 CONTEXT FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 OPTION FIXED BIN(31); CALL CTBEXIT (CONNECTION, RETCODE, OPTION);
(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.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(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. |
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. |
The following code fragment demonstrates the use of CTBEXIT. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------------*/
/* */
/* 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 ;
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.
Related functions:
