Allocates a context structure.
%INCLUDE CTPUBLIC;
DCL 01 VERSION FIXED BIN(31); 01 RETCODE FIXED BIN(31) INIT(0); 01 CONTEXT FIXED BIN(31) INIT(0); CALL CSBCTXAL (VERSION, RETCODE, CONTEXT);
(I) Version of Client-Library behavior that the application expects. The following table lists the symbolic values that are legal for VERSION:
Value |
Indicates |
Supported features |
|---|---|---|
CS_VERSION_46 |
Communicates with Adaptive Server release 4.6. |
RPCs.
|
CS_VERSION_50 |
Communicates with Adaptive Server release 10.0 and above. |
RPCs. |
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(O) Variable where this newly-allocated context structure returns. This is the name used by CTBINIT when it initializes Client-Library.
CSBCTXALLOC 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 CSBCTXALLOC failure is a lack of available memory. |
The following code fragment demonstrates how CSBCTXALLOC works with other functions to initialize a program. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
This is the initial version of Client-Library.
/*------------------------------------------------------------------*/
/* 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 ;
CSBCTXALLOC allocates a context structure.
A context structure contains information that describes an application context. For example, a context structure defines the version of Client-Library that is in use.
Allocating a context structure is the first step in any Client-Library application.
After allocating a context structure, a Client-Library application typically customizes the context by calling CSBCONFIG and/or CTBCONFIG, then sets up one or more connections within the context.
To deallocate a context structure, an application calls CSBCTXDROP.
Related functions:
