Chapter 2: Functions

CTBINIT

Description

Initializes Client-Library.

Syntax

COPY CTPUBLIC.

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

CALL 'CTBINIT' USING CONTEXT RETCODE VERSION.

Parameters

CONTEXT: (I) A context structure. The context structure is defined in the program call CSBCTXALLOC. If this value is invalid or nonexistent, CTBINIT 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.

VERSION

(I) Version of Client-Library behavior that the application expects. The following table lists the symbolic values that are legal for VERSION:

Value	Meaning	Supported features
CS-VERSION-46	Application communicates with a version 4.6 Adaptive Server.	RPCs.
CS-VERSION-50	Application communicates with a version 10.0 Adaptive Server and above.	RPCs.

Returns

CTBINIT returns one of the following values:

Value	Meaning
CS-SUCCEED (-1)	The routine completed successfully.
TDS-WRONG-STATE (-6)	Program is in the wrong communication state to issue this call. The most likely cause is that this context already initiated.

Value

Meaning

CS-SUCCEED (-1)

The routine completed successfully.

TDS-WRONG-STATE (-6)

Program is in the wrong communication state to issue this call.

The most likely cause is that this context already initiated.

Examples

Example 1

The following code fragment demonstrates the use of CTBINIT. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”

     *****************************
	 *    PROGRAM INITIALIZATION *
     *****************************
            MOVE C-N    TO NO-MORE-MSGS-SW.
            MOVE C-N    TO NO-ERRORS-SW.
            MOVE C-Y    TO SW-DIAG.
            COMPUTE PAGE-CNT = PAGE-CNT + 1.
            PERFORM GET-SYSTEM-TIME.
            MOVE LOW-VALUES TO A5PANELO.
            MOVE -1         TO SERVERL.
        GET-INPUT-AGAIN.
            PERFORM DISPLAY-INITIAL-SCREEN.
            PERFORM GET-INPUT-DATA.
       ***********************************
       *    ALLOCATE A CONTEXT STRUCTURE *
       ***********************************
            MOVE ZERO TO CSL-CTX-HANDLE.
            CALL 'CSBCTXAL' USING CS-VERSION-50
                                  CSL-RC
                                  CSL-CTX-HANDLE.
            IF CSL-RC NOT EQUAL CS-SUCCEED
              THEN
                 MOVE SPACES TO MSGSTR
                 STRING 'CSBCTXAL failed' DELIMITED BY SIZE INTO MSGSTR
                 PERFORM PRINT-MSG
                 PERFORM ALL-DONE
            END-IF.
       **********************************
       * INTITIALIZE THE CLIENT-LIBRARY *
       **********************************
            CALL 'CTBINIT' USING CSL-CTX-HANDLE
                                 CSL-RC
                                 CS-VERSION-50.
            IF CSL-RC NOT EQUAL CS-SUCCEED
              THEN
                 MOVE SPACES TO MSGSTR
                 STRING 'CTBINIT failed' DELIMITED BY SIZE INTO MSGSTR
                 PERFORM PRINT-MSG
                 PERFORM ALL-DONE
            END-IF.
            PERFORM PROCESS-INPUT.
            PERFORM QUIT-CLIENT-LIBRARY.
            GOBACK.

Usage

CTBINIT initializes Client-Library. It sets up internal control structures and defines the version of Client-Library behavior that an application expects. Client-Library provides the requested behavior, regardless of the actual version of Client-Library in use.
CTBINIT must be the first Client-Library routine call after CSBCTXALLOC. Other Client-Library routines fail if they are called before CTBINIT.
Because an application calls CTBINIT before it sets up error handling, an application must check the CTBINIT return code to detect failure.
It is not an error for an application to call CTBINIT multiple times. Some applications cannot guarantee which of several modules executes first. In such a case, each module should contain a call to CTBINIT.