Chapter 3: Functions

CSBCTXALLOC

Description

Allocates a context structure.

Syntax

%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);

Parameters

VERSION

(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. This is the initial version of Client-Library.
CS_VERSION_50	Communicates with Adaptive Server release 10.0 and above.	RPCs.

RETCODE: (O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.

CONTEXT: (O) Variable where this newly-allocated context structure returns. This is the name used by CTBINIT when it initializes Client-Library.

Returns

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.

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.

Examples

Example 1

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.”

 /*------------------------------------------------------------------*/
 /* 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 ;

Usage

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.