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. |
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/Server Configuration Guide 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.
ct_con_alloc, ct_config, cs_ctx_drop, cs_ctx_global, cs_config
