Set or retrieve CS-Library properties.
CS_RETCODE cs_config(context, action, property,
buffer, buflen, outlen)
CS_CONTEXT *context;
CS_INT action;
CS_INT property;
CS_VOID *buffer;
CS_INT buflen;
CS_INT *outlen;
A pointer to a CS_CONTEXT structure.
One of the following symbolic values:
action |
cs_config |
|---|---|
CS_SET |
Sets the value of the property. |
CS_GET |
Retrieves the value of the property. |
CS_CLEAR |
Clears the value of the property by resetting it to its default value. |
The property whose value is being set or retrieved, according to the following table:
Value of property |
Controls |
Action |
*buffer is |
|---|---|---|---|
CS_APPNAME |
The name the application calls itself. |
Set, retrieve, or clear. |
A CS_CHAR string. The default is NULL. |
CS_CONFIG_FILE |
The name and path of the Open Client and Open Server runtime configuration file. Meaningful only when external configuration has been enabled by setting CS_EXTERNAL_CONFIG. |
Set, retrieve, or clear. |
A CS_CHAR string. The default is NULL, which means a platform-specific default is used. See “Runtime configuration file property” for more information. |
CS_DEFAULT_ IFILE |
The name and path to an alternate default interfaces file. |
Set, retrieve, or clear. |
A CS_CHAR string to the new interfaces file. |
CS_EXTERNAL_ CONFIG |
Whether or not the Client-Library routine ct_init reads an external configuration file to set default property values. |
Set, retrieve, or clear. |
CS_TRUE or CS_FALSE. The default, CS_TRUE, is dependent on whether the external configuration file exists. See “External configuration property” for more information. |
CS_EXTRA_INF |
Whether or not to return the extra information that is required when processing messages inline using a SQLCA, SQLCODE, or SQLSTATE structure. |
Set, retrieve, or clear. |
CS_TRUE or CS_FALSE. CS_FALSE is the default. |
CS_LIBTCL_CFG |
The name and path to an alternate libtcl.cfg file. |
Set, retrieve, or clear. |
A CS_CHAR string to the new libtcl.cfg configuration file. |
CS_LOC_PROP |
A CS_LOCALE structure that defines localization information for this context. |
Set, retrieve, or clear. |
A CS_LOCALE structure previously allocated by the application. |
CS_MESSAGE_CB |
The CS-Library message callback routine, which is an application-provided handler for CS-Library error and informational messages. |
Set, retrieve, or clear. |
If action is CS_SET, *buffer is the message callback routine. If action is CS_GET, *buffer is set to the address of the message callback routine that is currently installed. The default is NULL, which means no handler is installed. |
CS_NOAPI_CHK |
Whether or not CS-Library validates function arguments when library functions are called. |
Set, retrieve, or clear. |
CS_TRUE or CS_FALSE. CS_FALSE, the default, indicates that argument checking is performed. |
CS_SYBASE_ HOME |
The location of an alternate Sybase home directory. |
Set, retrieve, or clear. |
A CS_CHAR string to the new Sybase home directory. |
CS_USERDATA |
User-allocated data. |
Set, retrieve, or clear. |
User-allocated data. A default is not applicable. |
CS_VERSION |
The version of CS-Library. |
Retrieve only. |
A symbolic code indicating the library version:
|
If a property value is being set, buffer points to the value to use in setting the property.
If a property value is being retrieved, buffer points to the space in which cs_config will place the value of the property.
If a property value is being cleared, pass buffer as NULL and buflen as CS_UNUSED.
Generally, buflen is the length, in bytes, of *buffer.
If a property value is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.
If *buffer is a fixed-length or symbolic value, pass buflen as CS_UNUSED.
A pointer to an integer variable.
outlen is not used if a property value is being set.
If a property value is being retrieved, cs_config sets *outlen to the length, in bytes, of the requested information.
If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.
outlen can be passed as NULL if the application is setting a property value or does not require the output length of a retrieved value.
cs_config returns:
Returns |
Indicates |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
There are three kinds of context properties:
Context properties specific to CS-Library
Context properties specific to Client-Library
Context properties specific to Server-Library
cs_config sets and retrieves the values of CS-Library context properties. With the exception of CS_LOC_PROP, properties set using cs_config affect only CS-Library.
ct_config sets and retrieves the values of Client-Library-specific context properties. Properties set using ct_config affect only Client-Library.
srv_props sets and retrieves the values of Server-Library-specific context properties. Properties set using srv_props affect only Server-Library.
See the “Properties” topics page in the Open Client Client-Library/C Reference Manual for information about Client-Library properties.
CS_APPNAME specifies the name that the application calls itself.
cs_config sets the application name for a CS_CONTEXT structure. In a Client-Library application, allocated connections inherit the application name from their parent CS_CONTEXT structure.
The application name specifies a section name in the Open Client and Open Server runtime configuration file. See “Runtime configuration file property” for more information.
CS_APPNAME cannot be set, retrieved, or cleared unless the CS_CONTEXT structure was allocated with CS_VERSION_110 or later.
CS_CONFIG_FILE specifies the name and path to the Open Client and Open Server runtime configuration file.
The default value is NULL, which means that the platform-specific default file will be used:
On UNIX platforms, the default file is $SYBASE/$SYBASE_OCS/config/ocs.cfg, where $SYBASE is the path to the Sybase installation directory; this path is specified as the value of the SYBASE environment variable.
On Windows platforms, the default file is %SYBASE%\%SYBASE_OCS%\ini\ocs.cfg, where %SYBASE% is the path to the Sybase installation directory; this path is specified as the value of the SYBASE environment variable.
The default value may be overridden by the environment
variable, SYBOCS_CFG.
Setting the SYBOCS_CFG environment variable overrides the CS_EXTERNAL_CONFIG default. Note that this only affects applications which do not set the value of CSCONFIG_FILE via cs_config.
If the default external-configuration file exists, Client-Library reads configuration settings from it unless the application explicitly sets the CS_EXTERNAL_CONFIG property to CS_FALSE. See “External configuration property”.
CS_CONFIG_FILE cannot be set, retrieved, or cleared unless the CS_CONTEXT structure was allocated with CS_VERSION_110 or later.
CS_EXTERNAL_CONFIG controls whether the Client-Library routine ct_init will read the Open Client and Open Server runtime configuration file to set default Client-Library property values for the CS_CONTEXT structure.
The name of the Open Client and Open Server runtime configuration file is specified with the CS_CONFIG_FILE property. See “Runtime configuration file property”.
The default for CS_EXTERNAL_CONFIG, CS_TRUE, depends on whether the default external-configuration file exists (see “Runtime configuration file property”). If the external-configuration file exists, then CS_EXTERNAL_CONFIG defaults to CS_TRUE. Otherwise, CS_EXTERNAL_CONFIG defaults to CS_FALSE.
Configuration information is read from the section of the file labeled:
[appname]
where appname is the value of the CS_APPNAME property. (See “Application name property”.) If the application has not set the CS_APPNAME property, the configuration reads the section labeled:
[DEFAULT]
The “Using the Open Client and Open Server Runtime Configuration File” topics page in the Open Client Client-Library/C Reference Manual describes the syntax and keywords for configuration file entries.
CS_EXTERNAL_CONFIG cannot be set, retrieved, or cleared unless the CS_CONTEXT structure is allocated with CS_VERSION_110 or later. (See cs_ctx_alloc for more information.)
CS_EXTRA_INF determines whether or not CS-Library returns the extra information that is required to fill in a SQLCA, SQLCODE, or SQLSTATE structure.
If an application is not retrieving messages into a SQLCA, SQLCODE, or SQLSTATE structure, the extra information is returned as ordinary CS-Library messages.
The CS_LOC_PROP property defines a CS_LOCALE structure that contains localization information for a context. Localization information includes a language, character set, datetime, money, and numeric formats, and a collating sequence.
CS_LOC_PROP affects both CS-Library and Client-Library, because a new connection picks up default localization information from its parent context.
If an application does not call cs_config to define localization information for a context, the context uses default localization information that it picks up from the operating system environment when it is allocated. If localization information is not available in the operating system environment, the context uses platform-specific default localization values.
The cs_loc_alloc routine allocates a CS_LOCALE structure.
The CS_MESSAGE_CB property consists of a pointer to a user-supplied CS-Library message callback routine. The application uses this property to install a handler for error or informational messages from CS-Library.
The default value is NULL, meaning that no handler is installed.
An application function can be installed as a handler for CS-Library errors.
Once the handler is installed, CS-Library calls the handler when an error or exception occurs in a CS-Library routine.
For a description and an example of coding a CS-Library error handler, see “Defining a CS-Library message callback”.
The following code fragment demonstrates how a handler function is installed for CS-Library errors:
/*
** Install the function cslib_err_handler as the
** handler for CS-Library errors.
*/
if (cs_config(context, CS_SET, CS_MESSAGE_CB,
(CS_VOID *)cslib_err_handler,
CS_UNUSED, NULL)
!= CS_SUCCEED)
{
/* Release the context structure. */
(void)cs_ctx_drop(context);
fprintf(stdout,
"Can't install CS-Lib error handler.\
Exiting.\n");
exit(1);
}
Client-Library applications that call CS-Library routines besides cs_ctx_alloc and cs_ctx_drop need dedicated CS-Library error handling. Applications should either install a CS-Library error handler or handle CS-Library errors inline with cs_diag.
CS-Library error messages
are not sent to the Client-Library error handler.
Callback error handlers for Client-Library and CS-Library are installed differently:
An application installs Client-Library callback routines by calling ct_callback.
An application installs a CS-Library message callback routine by calling cs_config to set the value of the CS_MESSAGE_CB property.
Aside from this difference, the CS-Library message callback is similar to the Client-Library client message callback. For general information on callback routines, see the “Callbacks” topics page in the Open Client Client-Library/C Reference Manual.
The CS_NOAPI_CHK property determines whether or not CS-Library validates function arguments when a library function is called.
If the value of CS_NOAPI_CHK is CS_FALSE (the default), then CS-Library checks arguments when API functions are called. Setting CS_NOAPI_CHK to CS_TRUE disables API checking.
For argument checking, CS-Library validates the parameters passed with each function call. Pointers to CS-Library hidden structures such as CS_LOCALE are checked. Field values in structures are also checked for illegal combinations. If CS-Library finds invalid arguments and API checking is enabled, CS-Library generates error messages and the function fails. These messages can be trapped and displayed with a CS-Library callback error handler.
If the value of CS_NOAPI_CHK is CS_TRUE, arguments are not validated before they are used. If the application passes invalid arguments to CS-Library, the application will not work right, resulting in memory corruption, memory access violations (UNIX “core dumps”), or incorrect results. No error messages are generated to warn the application of the condition. Do not disable API argument checking until the application has been completely debugged with API checking enabled.
WARNING! Do not set CS_NOAPI_CHK to CS_TRUE unless your application has been completely debugged with the default setting (CS_FALSE).
The CS_USERDATA property defines user-allocated data. This property allows an application to associate user data with a particular context structure.
CS-Library copies the user data into internal data space. An application can then call cs_config at a later time to retrieve the data.
If you do not include a string’s null terminator when calculating its length during the input stage, a call to cs_config (CS_GET) will return only the string (minus its null terminator). For example, if you input a 2-byte string with a null terminator, and specify the string’s length as 2 bytes, cs_config (CS_GET) will return only the string. If, on the other hand, you input a 2-byte string with a null terminator and specify the string’s length as 3 bytes, cs_config (CS_GET) will return the string and its null terminator.
Although Client-Library also has a CS_USERDATA property, the Client-Library CS_USERDATA is set only at the connection and command levels.
The CS_SYBASE_HOME property specifies the name and path to an alternate Sybase home directory and overrides the environment variable $SYBASE (%SYBASE% for Windows).
CS_SYBASE_HOME must be set before allocating a CS-Library context because the allocation of a context requires a valid Sybase home directory from which it will be set up. This means that CS_SYBASE_HOME must be set before calling cs_ctx_alloc() or cs_ctx_global(). cs_config() must be invoked with a NULL context to set CS_SYBASE_HOME. For example:
ret = cs_config(NULL, CS_SET, CS_SYBASE_HOME, "/work/NewSybase", CS_NULLTERM, NULL);
You can also use the -y option of the isql and bcp utilities to specify an alternate Sybase home directory.
The CS_LIBTCL_CFG property specifies the name and path to an alternate libtcl.cfg file. As in the CS_SYBASE_HOME property, CS_LIBTCL_CFG is set by cs_config() using a NULL context and must be set before a CS-Library context is allocated. For example:
ret = cs_config(NULL, CS_SET, CS_LIBTCL_CFG, "/work/Sybase/OCS-15_0/config/libtcl.cfg", CS_NULLTERM, NULL);
The CS_DEFAULT_IFILE property specifies the name of an alternate interfaces file and its path. Unlike the CT-Library property CS_IFILE, CS_DEFAULT_IFILE does not override the use of alternate directory services that have already been specified in the libtcl.cfg file. The primary purpose of CS_DEFAULT_IFILE is to set a new default location for the interfaces file, in case the interfaces file is being used as the directory service.
A CS-Library context must be allocated before calling cs_config() and it must be passed in cs_config() while setting the CS_DEFAULT_IFILE property. For example:
ret = cs_config(ctx, CS_SET, CS_DEFAULT_IFILE, "/work/NewSybase/interfaces", CS_NULLTERM, NULL);
The CS_VERSION property represents the version of CS-Library behavior that an application has requested using cs_ctx_alloc.
An application can only retrieve the value of CS_VERSION.
Possible values for CS_VERSION include the following:
CS_VERSION_100 indicates version 10.0 behavior
CS_VERSION_110 indicates version 11.1 behavior
CS_VERSION_120 indicates version 12.0 behavior
CS_VERSION_125 indicates version 12.5 behavior
CS_VERSION_150 indicates version 15.0 behavior.
cs_ctx_alloc, ct_con_props, ct_config, ct_init
