CSBCTXALLOC

Description

Allocates a context structure.

Syntax

COPY CTPUBLIC.

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

CALL ‘CSBCTXAL' USING 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.

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 “Return value,” 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 the use of CSBCTXALLOC. 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

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.