ct_config

Description

Set or retrieve context properties.

Syntax

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;

Parameters

context

A pointer to a CS_CONTEXT structure.

action

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”.

property

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.

buffer

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.

buflen

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.

outlen

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.

Returns

ct_config returns the following values:

Examples

Example 1

        /* 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 example program.

Usage

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:

  Table 3-13: Client-Library context structure 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_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_PROP_SSL_ PROTOVERSION	The version of supported SSL/TLS protocols.	CS_INT	Context, connection	Must be one of the following values. CS_SSLVER_20 CS_SSLVER_30 CS_SSLVER_TLS1
  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_ CONFIDEN TIALITY	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-31 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-31 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.

See also

cs_config, ct_cmd_props, ct_capability, ct_con_props, ct_connect, ct_init, “Properties”

---

Copyright © 2003. Sybase Inc. All rights reserved.

View this book as PDF