Initializes Client-Library.
%INCLUDE CTPUBLIC;
DCL 01 CONTEXT FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 VERSION FIXED BIN(31); CALL CTBINIT (CONNECTION, RETCODE, VERSION);
(I) A context structure. The context structure is defined in the program call CSBCTXALLOC. If this value is invalid or nonexistent, CTBINIT fails.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(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 SQL Server and above. |
RPCs. |
CTBINIT returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_MEM_ERROR (-3) |
The routine failed due to a memory allocation error. |
CS_FAIL (-2) |
The routine failed for other reasons.
|
TDS_INVALID_PARAMETER (-4) |
A parameter contains an illegal value. The most likely cause is an erroneous version number. |
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. |
The following code fragment demonstrates how CTBINIT is used with other functions to initialize a program. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
CTBINIT returns CS_FAIL
if Client-Library cannot provide version-level behavior.
/*------------------------------------------------------------------*/
/* program initialization */
/*------------------------------------------------------------------*/
DIAG_MSGS_INITIALIZED = TRUE ;
MSG_TEXT_2 = 'Press Clear To Exit';
NO_ERRORS_SW = TRUE ;
PAGE_CNT = PAGE_CNT + 1;
SERVERL = -1 ;
DO I1 = 1 TO 13 ;
RSLTNO( I1 ) = BLANK ;
END ;
CALL GET_SYSTEM_TIME ;
GET_INPUT_AGAIN:
CALL DISPLAY_INITIAL_SCREEN ;
CALL GET_INPUT_DATA ;
/*------------------------------------------------------------------*/
/* allocate a context structure */
/*------------------------------------------------------------------*/
CALL CSBCTXAL( CS_VERSION_50,
CSL_RC,
CSL_CTX_HANDLE );
IF CSL_RC ^= CS_SUCCEED THEN
DO;
MSGSTR = 'CSCTXALLOC failed';
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE;
END;
/*------------------------------------------------------------------*/
/* initialize the Client-Library */
/*------------------------------------------------------------------*/
CALL CTBINIT( CSL_CTX_HANDLE,
CSL_RC,
CS_VERSION_50 );
IF CSL_RC ^= CS_SUCCEED THEN
DO;
MSGSTR = 'CTBINIT failed';
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE;
END;
CALL PROCESS_INPUT ;
CALL QUIT_CLIENT_LIBRARY ;
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.
Related functions:
