Allocates a CS_CONTEXT structure.
CS_RETCODE cs_ctx_alloc(version, ctx_pointer) CS_INT version; CS_CONTEXT **ctx_pointer;
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 the Sybase library name change. |
The address of a pointer variable. cs_ctx_alloc sets *ctx_pointer to the address of a newly allocated CS_CONTEXT structure.
In case of error, cs_ctx_alloc sets *ctx_pointer to NULL.
cs_ctx_alloc 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. |
The most common reason for a cs_ctx_alloc failure is a misconfigured system environment. cs_ctx_alloc must read the locales file that specifies the default localization values for the allocated context. If CS-Library cannot find the locales file or if the locales file is misconfigured, cs_ctx_alloc fails.
When cs_ctx_alloc 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.
On most systems, the SYBASE environment variable or logical name specifies the location of the locales file. The Open Client and Open Server Configuration Guide for Microsoft Windows or Open Client and Open Server Configuration Guide for UNIX describes the environmental configuration required for CS-Library localization values.
Other common reasons for a cs_ctx_alloc failure include:
Memory is insufficient.
Localization files are missing.
The value of the LANG environment variable does not match an entry in the locales file.
On platforms that have a standard error device, cs_ctx_alloc prints
U.S. English error messages to the standard error device when CS-Library cannot find the locales file.
For Windows and other platforms that lack a standard error device,
U.S. English error messages are written to a text file called sybinit.err in
the application’s working directory.
/*
** ex_init()
*/
CS_RETCODE CS_PUBLIC
ex_init(context)
CS_CONTEXT* *context;
{
CS_RETCODE retcode;
CS_INT netio_type = CS_SYNC_IO;
/* Get a context handle to use */
retcode = cs_ctx_alloc(CS_VERSION_125, context);
if (retcode != CS_SUCCEED)
{
ex_error("ex_init: cs_ctx_alloc() failed");
return retcode;
}
/* Initialize Open Client */
...CODE DELETED.....
/* Install client and server message handlers */
...CODE DELETED.....
if (retcode != CS_SUCCEED)
{
ct_exit(*context, CS_FORCE_EXIT);
cs_ctx_drop(*context);
*context = NULL;
}
return retcode;
}
A CS_CONTEXT structure, also called a “context structure,” contains information that describes an application context. For example, a context structure contains default localization information and defines the version of CS-Library that is in use.
Allocating a context structure is the first step in any Client-Library or Server-Library application.
After allocating a CS_CONTEXT structure, a Client-Library application typically customizes the context by calling cs_config and/or ct_config to create one or more connections within the context. A Server-Library application can customize a context by calling cs_config and srv_props.
To deallocate a context structure, an application can call cs_ctx_drop.
cs_ctx_global also allocates a context structure. The 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.
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.
ct_con_alloc, ct_config, cs_ctx_drop, cs_ctx_global, cs_config
