ct_init

Description

Initialize Client-Library for an application context.

Syntax

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

Parameters

context

A pointer to a CS_CONTEXT structure. An application must have previously allocated this context structure by calling the CS-Library routine cs_ctx_alloc.

context identifies the Client-Library context being initialized.

version

The version of Client-Library behavior that the application expects. Table 3-44 lists the symbolic values for version:

**Table 3-44: Values for ct_init version parameter**
Value of version	Meaning	Features supported
CS_VERSION_100	10.0 behavior.	Cursors, registered procedures, remote procedure calls. This is the initial version of Client-Library.
CS_VERSION_110	11.0 behavior.	All 10.0 features plus these new version 11.1 features: Network-based directory and security services. External configuration of properties, options, and capabilities.
CS_VERSION_120	12.0 behavior	All previous features plus: High-availability failover Native thread support for Digital UNIX platforms Bulk-row inserts A new property for enabling/disabling sort-merge joins
CS_VERSION_125	12.5 behavior	Added features for version 12.5 include: LDAP security features SSL security features Unichar-16 for 2-byte character support support for wide columns and wide tables.

Returns

ct_init returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_MEM_ERROR	The routine failed due to a memory allocation error.
CS_FAIL	The routine failed for other reasons.

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

When ct_init returns CS_FAIL due to a Net-Library error, extended error information is sent to standard error (STDERR) and to the sybinit.err file that is created in the current working directory.

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

Configuring context properties externally

Client-Library reads the Open Client/Server configuration file to get default context property values if the application requests external configuration by calling cs_config to set the CS_CONFIG_FILE context property before calling ct_init.
External configuration can eliminate several ct_config calls in an application. Also, if an application is coded to request external configuration, it allows the application’s runtime property settings to be changed without recompiling. For more information on this feature, see “Using the runtime configuration file”.