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
CS_VERSION_125	12.5 behavior

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

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.
For more information on context structures, see cs_ctx_alloc in this chapter.