ct_init

Description

Initialize Client-Library for an application context.

Syntax

CS_RETCODE ct_init(context, version)
 
 CS_CONTEXT    *context;
 CS_INT                version;

Parameters

Returns

ct_init returns the following values:

ct_init returns CS_FAIL if Client-Library cannot provide version-level behavior.

A ct_init failure does not typically make *context unusable. Instead of dropping the context structure, an application can try calling ct_init again with the same context pointer.

Examples

Example 1

       /*

        ** ex_init() -- Allocate and initialize a CS_CONTEXT

        **    structure.

        **

        ** EX_CTLIB_VERSION is defined in the examples header file 

        ** as CS_VERSION_110.

        */

        CS_RETCODE CS_PUBLIC

         ex_init(context)

         CS_CONTEXT  **context;

         {

             CS_RETCODE   retcode;

            /* Get a context handle to use */

             retcode = cs_ctx_alloc(EX_CTLIB_VERSION, context);

                  ... error checking code deleted ...

            /* Initialize Open Client */

             retcode = ct_init(*context, EX_CTLIB_VERSION);

             if (retcode != CS_SUCCEED)

             {

                 ex_error("ex_init: ct_init() failed");

                 cs_ctx_drop(*context);

                 *context = NULL;

                 return retcode;

             }

            /* Install client and server message handlers */

             ... ct_callback calls deleted .....

            /* Call ct_config to set context properties */

             ... ct_config calls deleted ...

            /* Exit from Client-Library */

             retcode = ct_exit(context, CS_UNUSED);

             if (retcode != CS_SUCCEED)

             {

                 ct_exit(*context, CS_FORCE_EXIT);

                 cs_ctx_drop(*context);

                 *context = NULL;

             }

            return retcode;

         }

This code excerpt is from the exutils.c sample program.

Usage

• ct_init sets up internal control structures and defines the version of Client-Library behavior that the application expects.

• ct_init must be the first Client-Library routine called in a Client-Library application context. Other Client-Library routines will fail if they are called before ct_init.

  A Client-Library application can call CS-Library routines before calling ct_init (and, in fact, must call the CS-Library routine cs_ctx_alloc before calling ct_init).

• If ct_init returns CS_SUCCEED, Client-Library will provide the requested behavior, regardless of the actual version of Client-Library in use. If Client-Library cannot provide the requested behavior, ct_init returns CS_FAIL. Generally speaking, higher-level versions of Client-Library can provide lower-level behavior, but lower-level versions cannot provide higher-level behavior.

• Because an application calls ct_init before it sets up error handling, an application must check ct_init’s return code to detect failure.

• It is not an error for an application to call ct_init multiple times for the same context. If this occurs, only the first call has any effect. Client-Library provides this functionality because some applications cannot guarantee which of several modules will execute first. In such a case, each module needs to contain a call to ct_init.

• version is the version of Client-Library behavior that the application expects. version determines the value of the context’s CS_VERSION property. Connections allocated within a context use default CS_TDS_VERSION values based on their parent context’s CS_VERSION level.