cs_ctx_global

Description

Allocates or returns a CS_CONTEXT structure.

Syntax

CS_RETCODE cs_ctx_global(version, ctx_pointer)
 
 CS_INT             version;
 CS_CONTEXT   **ctx_pointer;

Parameters

version: One of the following symbolic values, to indicate the intended version of CS-Library behavior:

Value of version

Indicates

Features supported

CS_VERSION_100

10.0 behavior

Initial version.

CS_VERSION_110

11.1 behavior

Unicode character set support.

Use of external configuration files to control Client-Library property settings.

CS_VERSION_120

12.0 behavior

All above features.

CS_VERSION_125

12.5 behavior

unichar support, wide data and columns, SSL.

CS_VERSION_150

15.0 behavior

BCP partitions, BCP computed columns, large identifiers, Unilib, ASE default packet size, scrollable cursors, and clusters support. Also support for unitext, xml, bigint, usmallint, uint, and ubigint datatypes. Note Sybase library name change.

If an application has already allocated a CS_CONTEXT structure, version must match the version previously requested.

Value of version	Indicates	Features supported
CS_VERSION_100	10.0 behavior	Initial version.
CS_VERSION_110	11.1 behavior	Unicode character set support. Use of external configuration files to control Client-Library property settings.
CS_VERSION_120	12.0 behavior	All above features.
CS_VERSION_125	12.5 behavior	unichar support, wide data and columns, SSL.
CS_VERSION_150	15.0 behavior	BCP partitions, BCP computed columns, large identifiers, Unilib, ASE default packet size, scrollable cursors, and clusters support. Also support for unitext, xml, bigint, usmallint, uint, and ubigint datatypes. Note Sybase library name change.

ctx_pointer: The address of a pointer variable. cs_ctx_global sets *ctx_pointer to the address of a new or previously allocated CS_CONTEXT structure.

In case of error, cs_ctx_global sets *ctx_pointer to NULL.

Returns

cs_ctx_global returns:

Returns	Indicates
CS_SUCCEED	The routine completed successfully.
CS_MEM_ERROR	The routine failed because it could not allocate sufficient memory.
CS_FAIL	The routine failed for other reasons.

Common reasons for a cs_ctx_global failure include:

A lack of available memory
A version value that does not match a previously requested version

When cs_ctx_global returns CS_FAIL an extended error message is sent to standard error (SDTERR) and to the sybinit.err file that is created in the current working directory.

The first cs_ctx_global call to execute in an application can fail due to configuration problems. See “Returns” under cs_ctx_alloc in this chapter for more information.

Usage

cs_ctx_alloc also allocates a context structure. The only difference between cs_ctx_alloc and cs_ctx_global is that cs_ctx_alloc allocates a new context structure each time it is called, while cs_ctx_global allocates a new context structure only once, the first time it is called. On subsequent calls, cs_ctx_global simply returns a pointer to the existing context structure.
cs_ctx_global is of use in applications that need to access a single context structure from multiple independent modules.
To allow the use of sigwait in signal handling for multithreaded applications, both cs_ctx_alloc and cs_ctx_global will block signals the first time they are executed for a multi-threaded application. All these signals are blocked except for one dedicated thread, which is controlled by the Open Client/Open Server libraries. This thread will block the signal when a corresponding signal handler is installed using the ct_callback or srv_signal routines. A separate thread is subsequently spawned to invoke sigwait for this signal and to execute the appropriate user-provided signal handler function when the signal is received. For information on how to override this behavior and allow your application to handle thread signals itself, see the Chapter 2, “Client-Library Topics“ in the Open Client Client-Library/C Reference Manual.
For more information on context structures, see cs_ctx_alloc in this chapter.