Set or retrieve context properties.
CS_RETCODE ct_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:
Value of action |
Result |
|---|---|
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 Client-Library default value. |
CS_SUPPORTED |
Checks whether a distributed-service driver supports the property. Use only with properties that affect the behavior of a security or directory driver. See “Checking whether a property is supported”. |
The symbolic name of the property whose value is being set or retrieved. Table 3-13 lists the Client-Library context properties. “Properties” lists all Client-Library properties.
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 ct_config will place the requested information.
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 value, symbolic value, or function, pass buflen as CS_UNUSED.
A pointer to an integer variable.
If a property value is being set, outlen is not used and should be passed as NULL.
If a property value is being retrieved and outlen is supplied, ct_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.
ct_config returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully |
CS_FAIL |
The routine failed |
/* Set the input/output type to asynchronous */
CS_INT propvalue;
if (retcode == CS_SUCCEED)
{
propvalue = CS_ASYNC_IO;
retcode = ct_config(*context, CS_SET, CS_NETIO,
(CS_VOID *)&propvalue, CS_UNUSED, NULL);
if (retcode != CS_SUCCEED)
{
ex_error("ex_init: ct_config(netio) failed");
}
}
This code excerpt is based on code in the exutils.c sample program.
For information about action, buffer, buflen, and outlen, see Chapter 2, “Understanding Structures, Constants, and Conventions,” in the Open Client Client-Library/C Programmer's Guide.
Context properties define aspects of Client-Library behavior at the context level.
ct_config takes precedence over the libtcl*.cfg file for all connections established within the CS_CONTEXT
ct_config controls connection properties and the use of external files that configure context. See “Using the runtime configuration file”.
All connections created within a context pick up default property values from the parent context. An application can override these default values by calling ct_con_props to set property values at the connection level.
If an application changes context property values after allocating connections for the context, existing connections will not pick up the new property values. New connections allocated within the context will use the new property values as defaults.
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-specific context properties. Properties set through cs_config affect only CS-Library.
ct_config sets and retrieves the values of Client-Library-specific context properties. Properties set through ct_config affect only Client-Library.
srv_props sets and retrieves the values of Server-Library-specific context properties. Properties set through srv_props affect only Server-Library.
See “Properties” for more information.
An application can use ct_config to set or retrieve the following properties:
Property |
Meaning |
*buffer value |
Level |
Notes |
|---|---|---|---|---|
CS_ANSI_BINDS |
Whether to use ANSI-style binds. |
CS_TRUE or CS_FALSE. |
Context, connection |
|
CS_DISABLE_POLL |
Whether to disable polling. If polling is disabled, ct_poll does not report asynchronous operation completions. |
CS_TRUE or CS_FALSE. |
Context, connection |
Useful in layered asynchronous applications. |
CS_DS_RAND_ OFFSET |
Enables or disables random offset in connection lists. |
CS_TRUE or CS_FALSE.The default is CS_FALSE. |
Context, connection |
Determined when the network address list is retrieved from the directory service. |
CS_EXPOSE_FMTS |
Whether to expose results of type CS_ROWFMT_RESULT and CS_COMPUTEFMT_ RESULT. |
CS_TRUE or CS_FALSE. |
Context, connection |
Takes effect only if set before connection is established. |
CS_EXTERNAL_ CONFIG |
Whether ct_connect reads an external configuration file to set properties and options for the connection to be opened. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection. |
Requires initialization with CS_VERSION_110 or later. |
CS_EXTRA_INF |
Whether to return the extra information that’s required when processing Client-Library messages inline using SQLCA, SQLCODE, and SQLSTATE structures. |
CS_TRUE or CS_FALSE. |
Context, connection |
|
CS_HIDDEN_KEYS |
Whether to expose hidden keys. |
CS_TRUE or CS_FALSE. |
Context, connection, command |
|
CS_IFILE |
The path and name of the interfaces file. |
A character string. |
Context |
|
CS_LOGIN_ TIMEOUT |
The login timeout value. |
An integer value. |
Context |
|
CS_MAX_CONNECT |
The maximum number of connections for this context. |
An integer value. |
Context |
|
CS_MEM_POOL |
A memory pool that Client-Library will use to satisfy interrupt-level memory requirements. |
If action is CS_SET, *buffer is a pool of bytes. If action is CS_GET, *buffer is set to the address of a pool of bytes. |
Context |
Useful in asynchronous applications. Cannot be set or cleared when context has connections. |
CS_NETIO |
Whether network I/O is synchronous, fully asynchronous, or deferred asynchronous. |
CS_SYNC_IO, CS_ASYNC_IO, or CS_DEFER_IO. |
Context, connection |
Cannot be set for a context with open connections. |
CS_NO_TRUNCATE |
Whether Client-Library should truncate or sequence messages that are longer than CS_MAX_MSG. |
CS_TRUE, which means sequence or CS_FALSE, which means truncate. |
Context |
|
CS_NOAPI_CHK |
Whether Client-Library performs argument and state checking when the application calls a Client-Library routine. |
CS_TRUE or CS_FALSE. The default is CS_FALSE, which means that Client-Library performs API checking. |
Context |
|
CS_NOINTERRUPT |
Whether the application can be interrupted by certain callback events. |
CS_TRUE or CS_FALSE. |
Context |
Affects completion events only, not notification events. |
CS_PARTIAL_TEXT |
Indicates whether or not the client application should perform a partial update. |
CS_TRUE or CS_FALSE.The default is CS_FALSE. |
Context, connection |
This property must be set before a connection to the server is established. If the server does not support partial updates, this property will be reset to CS_FALSE. |
CS_PROP_EXTENDEDFAILOVER |
Enables or disables server-provided failover targets. |
CS_TRUE or CS_FALSE.The default is CS_TRUE. |
Context, connection |
Login property. |
CS_PROP_ MIGRATABLE |
Enables or disables connection migration. |
CS_TRUE or CS_FALSE. The default is CS_TRUE. |
Context, connection |
Login property. |
CS_PROP_REDIRECT |
Enables or disables login redirection support. |
CS_TRUE or CS_FALSE.The default is CS_TRUE. |
Context, connection |
Login property. |
CS_PROP_SSL_ PROTOVERSION |
The version of supported SSL/TLS protocols. |
CS_INT |
Context, connection |
Must be one of the following values:
|
CS_PROP_SSL_ CIPHER |
Comma-separated list of CipherSuite names. |
CS_CHAR |
Context, connection |
|
CS_PROP_SSL_ LOCALID |
Property used to specify the path to the Local ID (certificates) file. |
Character string |
Context, connection |
A structure containing a file name and a password used to decrypt the information in the file. |
CS_PROP_SSL_CA |
Specify the path to the file containing trusted CA certificates. |
CS_CHAR |
Context, connection |
|
CS_SEC_ CHANBIND |
Whether the connection’s security mechanism will perform channel binding. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ CONFIDENTIALITY |
Whether data encryption service will be performed on the connection. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ CREDENTIALS |
Used by gateway applications to forward a delegated user credential. |
A CS_VOID * pointer. |
Context, connection |
Cannot be read. Requires a supporting network security mechanism. |
CS_SEC_ CREDTIMEOUT |
Whether the user’s credentials have expired. |
A CS_INT. See Table 2-32 for possible values and their meanings. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ DATAORIGIN |
Whether the connection’s security mechanism will perform data origin verification. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ DELEGATION |
Whether to allow the server to connect to a second server with the user’s delegated credentials. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ DETECTREPLAY |
Whether the connection’s security mechanism will detect replayed transmissions. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ DETECTSEQ |
Whether the connection’s security mechanism will detect transmissions that arrive out of sequence. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ INTEGRITY |
Whether the connection’s security mechanism will perform data integrity checking. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ MECHANISM |
The name of the network security mechanism that performs security services for the connection. |
A string value. The default depends on security driver configuration. |
Context, connection |
|
CS_SEC_ MUTUALAUTH |
Whether the server is required to authenticate itself to the client. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ NETWORKAUTH |
Whether the connection’s security mechanism will perform network-based user authentication. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection |
Requires a supporting network security mechanism. |
CS_SEC_ SESSTIMEOUT |
Whether the connection’s security session has expired. |
A CS_INT. See Table 2-32 for possible values and their meanings. |
Context, connection |
Requires a supporting network security mechanism. |
CS_TEXTLIMIT |
The largest text or image value to be returned on this connection. |
An integer value. |
Context, connection |
|
CS_TIMEOUT |
The timeout value. |
An integer value. |
Context |
|
CS_USER_ALLOC |
A user-defined memory allocation routine. |
If action is CS_SET, *buffer is the user-defined function to install. If action is CS_GET, *buffer is set to the address of the user-defined function that is currently installed. |
Context |
Useful in asynchronous application. |
CS_USER_FREE |
A user-defined memory free routine. |
If action is CS_SET, *buffer is the user-defined function to install. If action is CS_GET, *buffer is set to the address of the user-defined function that is currently installed. |
Context |
Useful in asynchronous applications. |
CS_VER_STRING |
Client-Library’s true version string. |
A character string. |
Context |
Retrieve only. |
CS_VERSION |
The version of Client-Library in use by this context. |
A symbolic version level. |
Context |
Retrieve only. |
cs_config, ct_cmd_props, ct_capability, ct_con_props, ct_connect, ct_init, “Properties”
