ct_con_props

Description

Set or retrieve connection structure properties.

Syntax

CS_RETCODE ct_con_props(connection, action, property,
                buffer, buflen, outlen)
 
 CS_CONNECTION    *connection;
 CS_INT                       action;
 CS_INT                       property;
 CS_VOID                    *buffer;
 CS_INT                       buflen;
 CS_INT                        *outlen;

Parameters

connection: A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

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	Resets the property to its default value.
CS_SUPPORTED	Checks whether a distributed-service driver supports the property. Use only with properties that affect the behavior of a directory or security driver. See “Checking whether a property is supported”.

property: The symbolic name of the property whose value is being set or retrieved. Table 3-12 lists the properties that can be set with ct_con_props. “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.

buflen

Generally, buflen is the length, in bytes, of *buffer.

If *buffer is a fixed-length or symbolic value, pass buflen as CS_UNUSED.

outlen

A pointer to an integer variable.

outlen is not used if a property value is being set and should be passed as NULL.

If a property value is being retrieved and outlen is supplied, ct_con_props 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_con_props returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Examples

Example 1

/*

         ** EstablishConnection()

**

         ** Purpose:

         ** This routine establishes a connection to the server

         ** identified in example.h and sets the CS_USER,

         ** CS_PASSWORD, and CS_APPNAME properties for the

         ** connection.

**

         ** NOTE: The user name, password, and server are defined

         ** in the example header file.

*/

        CS_STATIC CS_RETCODE

         EstablishConnection(context, connection)

         CS_CONTEXT      *context;

         CS_CONNECTION   *connection;

             CS_INT      len;

             CS_RETCODE  retcode;

             CS_BOOL     bool;

            /* Allocate a connection structure */

             ...CODE DELETED.....

/*

             ** If a user name is defined in example.h, set the

             ** CS_USERNAME property.

*/

             if (retcode == CS_SUCCEED && Ex_username != NULL)

                 if ((retcode = ct_con_props(*connection, CS_SET,

                     CS_USERNAME, Ex_username, CS_NULLTERM, NULL))

                     != CS_SUCCEED)

                     ex_error("ct_con_props(username) failed");

/*

             ** If a password is defined in example.h, set the

             ** CS_PASSWORD property.

*/

             if (retcode == CS_SUCCEED && Ex_password != NULL)

                 if ((retcode = ct_con_props(*connection, CS_SET,

                     CS_PASSWORD, Ex_password, CS_NULLTERM, NULL))

                     != CS_SUCCEED)

                     ex_error("ct_con_props(passwd) failed");

            /* Set the CS_APPNAME property */

             ...CODE DELETED.....

            /* Enable the bulk login property */

             if (retcode == CS_SUCCEED)

                 bool = CS_TRUE;

                 retcode = ct_con_props(*connection, CS_SET,

                     CS_BULK_LOGIN, &bool, CS_UNUSED, NULL);

                 if (retcode != CS_SUCCEED)

                      ex_error("ct_con_props(bulk_login) failed");

            /* Open a server connection */

             ...CODE DELETED.....

This code excerpt is from the blktxt.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.

Connection properties define aspects of Client-Library behavior at the connection level. To determine whether a property is supported, an application can call ct_con_props on an established connection. The call must use the CS_SUPPORTED action parameter and must use the buffer parameter as the address of a CS_BOOL variable.
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.

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.
All command structures allocated for a connection pick up default property values from the parent connection. An application can override these default values by calling ct_cmd_props to set property values at the command structure level.

If an application changes connection property values after allocating command structures for the connection, the existing command structures will not pick up the new property values. New command structures allocated for the connection will use the new property values as defaults.
Some connection properties only take effect if they are set before an application calls ct_connect to establish the connection. These are indicated the “Notes” column in Table 3-12.
See “Properties” for more information.

An application can use ct_con_props to set or retrieve the following properties:

**Table 3-12: Connection 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_APPNAME	The application name used when logging into the server.	A character string	Context, connection. To set at the context level, call cs_config.	Login property. Cannot be set after connection is established.
CS_ASYNC_ NOTIFS	Whether a connection will receive registered procedure notifications asynchronously.	CS_TRUE or CS_FALSE.	Connection.
CS_BULK_LOGIN	Whether a connection is enabled to perform bulk copy “in” operation.	CS_TRUE or CS_FALSE.	Connection.	Login property. Cannot be set after connection is established.
CS_CHARSETCNV	Whether character set conversion is taking place.	CS_TRUE or CS_FALSE.	Connection.	Retrieve only, after connection is established.
CS_COMMBLOCK	A pointer to a communication sessions block. This property is specific to IBM370 systems and is ignored on all other platforms.	A pointer value.	Connection.	Cannot be set after connection is established.
CS_CON_KEEP ALIVE	Whether to use the KEEPALIVE option.	CS_TRUE (default) or CS_FALSE	Context or connection	Some Net-Library protocol drivers do not support this property. After completing a connection on such a protocol driver, calling ct_con_props with CS_GET or CS_SET returns CS_FAIL.
CS_CON_STATUS	The connection’s status.	A CS_INT-sized bit-mask.	Connection.	Retrieve only.
CS_CON_TCP_ NODELAY	Whether to use the TCP_NODELAY option.	CS_TRUE (default) or CS_FALSE	Context or connection	Some Net-Library protocol drivers do not support this property. After completing a connection on such a protocol driver, calling ct_con_props with CS_GET or CS_SET returns CS_FAIL.
CS_CONFIG_ BY_SERVERNAME	Whether ct_connect uses its server_name parameter or the value of the CS_APPNAME property as the section name to read external configuration data from.	CS_TRUE or CS_FALSE. The default is CS_FALSE, which means that CS_APPNAME is used.	Connection.	Requires initialization with CS_VERSION_110 or later.
CS_CONFIG_FILE	The name and path of the Open Client/Server runtime configuration file. See “Using the runtime configuration file” for more information.	A character string. The default is NULL, which means a platform-specific default is used.	Connection.	Requires initialization with CS_VERSION_110 or later.
CS_DIAG_TIMEOUT	When inline error handling is in effect, whether Client-Library should fail or retry on timeout errors.	CS_TRUE or CS_FALSE.	Connection.
CS_DISABLE_POLL	Whether to disable polling. If polling is disabled, ct_poll does not report asynchronous operation completions. Registered procedure notification will still be reported.	CS_TRUE or CS_FALSE.	Context, connection.	Useful in layered asynchronous applications.
CS_DS_COPY	Whether the directory service is allowed to satisfy an applications request with cached copies of directory entries.	CS_TRUE or CS_FALSE. The default is CS_TRUE, which allows cache use.	Connection.	Not supported by all directory providers.
CS_DS_DITBASE	Fully qualified name of directory node where directory searches begin.	A character string. The default is directory-provider specific.	Connection.	Not supported by all directory providers.
CS_DS_EXPAND ALIAS	Whether the directory service expands directory alias entries.	CS_TRUE or CS_FALSE. The default is CS_TRUE, which allows alias expansion.	Connection.	Not supported by all directory providers.
CS_DS_FAILOVER	Whether to allow failover to the interfaces file when a directory service driver can not be initialized.	CS_TRUE or CS_FALSE The default is CS_TRUE.	Connection.
CS_DS_PASSWORD	Password to go with the directory user ID specified as CS_DS_PRINCIPAL.	A character string. The default is NULL.	Connection.	Not supported by all directory providers.
CS_DS_PRINCIPAL	A directory user ID for use of the directory service to go with the password specified as CS_DS_PASSWORD.	A character string. The default is NULL.	Connection.	Not supported by all directory providers.
CS_DS_PROVIDER	The name of the directory provider for the connection.	A character string. The default depends on directory driver configuration.	Connection.
CS_DS_SEARCH	Restricts the depth of a directory search.	A CS_INT sized symbolic value. For a list of possible values, see “Directory service search depth”.	Connection.	Not supported by all directory providers.
CS_DS_SIZELIMIT	Restricts the number of directory entries that can be returned by a search started with ct_ds_lookup.	A CS_INT value greater than or equal to 0. A value of 0 indicates there is no size limit.	Connection.
CS_DS_TIMELIMIT	Sets an absolute time limit, in seconds, for completion of directory searches.	A CS_INT value greater than or equal to 0. A value of 0 indicates there is no time limit.	Connection.	Not supported by all directory providers.
CS_EED_CMD	A pointer to a command structure containing extended error data.	A pointer value.	Connection.	Retrieve only.
CS_ENDPOINT	The file descriptor for a connection.	An integer value, or -1 if the platform does not support CS_END POINT	Connection.	Retrieve only, after connection is established.
CS_EXPOSE_FMTS	Whether to expose results of type CS_ROWFMT_RESULT and CS_COMPUTEFMT_ RESULT.	CS_TRUE or CS_FALSE.	Context, connection.	Cannot be set after 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_HOSTNAME	The host name of the client machine.	A character string.	Connection.	Login property. Cannot be set after connection is established.
CS_LOC_PROP	A CS_LOCALE structure that defines localization information.	A CS_LOCALE structure previously allocated by the application.	Connection.	Login property. Cannot be set after connection is established.
CS_LOGIN_STATUS	Whether the connection is open.	CS_TRUE or CS_FALSE.	Connection.	Retrieve only.
CS_LOOP_DELAY	The delay, in seconds, that ct_connect waits before retrying the sequence of addresses associated with a server name.	A CS_INT >= 0. The default is 0.	Connection.	CS_RETRY_ COUNT specifies the number of times to retry.
CS_NETIO	Whether network I/O is synchronous, fully asynchronous, or deferred-asynchronous	CS_SYNC_IO, CS_ASYNC_IO, CS_DEFER_IO.	Context, connection.	Asynchronous connections are either fully or deferred asynchronous, to match their parent context.
CS_ NOCHARSETCNV_ REQD	Whether the server performs character set conversion if the server’s character set is different from the client’s.	CS_TRUE or CS_FALSE.	Connection.	Cannot be set after connection is established.
CS_NOTIF_CMD	A pointer to a command structure containing registered procedure notification parameters.	A pointer value.	Connection.	Retrieve only.
CS_PACKETSIZE	The TDS packet size.	An integer value.	Connection.	Negotiated login property. Cannot be set after connection is established.
CS_PARENT_ HANDLE	The address of the connection structure’s parent context.	Set to an address.	Connection, command.	Retrieve only.
CS_PASSWORD	The password used to log in to the server.	A character string.	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_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_RETRY_COUNT	The number of times to retry a connection to a server’s address.	A CS_INT >= 0. The default is 0.	Connection.	Affects only the establishment of a login dialog. Failed logins are not retried.
CS_SEC_ APPDEFINED	Whether the connection will use application-defined challenge/response security handshaking.	CS_TRUE or CS_FALSE.	Connection.	Cannot be set after connection is established.
CS_SEC_ CHALLENGE	Whether the connection will use Sybase-defined challenge/response security handshaking.	CS_TRUE or CS_FALSE.	Connection.	Cannot be set after connection is established.
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.	Cannot be set after connection is established. 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.	Cannot be set after connection is established. 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. Cannot be set after connection is established. 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.	Cannot be set after connection is established. 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.	Cannot be set after connection is established. 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.	Cannot be set after connection is established. 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.	Cannot be set after connection is established. 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.	Cannot be set after connection is established. Requires a supporting network security mechanism.
CS_SEC_ ENCRYPTION	Whether the connection will use encrypted password security handshaking.	CS_TRUE or CS_FALSE.	Connection.	Cannot be set after connection is established.
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.	Cannot be set after connection is established. Requires a supporting network security mechanism.
CS_SEC_ KEYTAB	The name and path to the file from which a connection’s security mechanism reads the security key to go with the CS_USERNAME property.	A character string. The default is NULL, which means the user must have established credentials before the application calls ct_connect.	Connection.	Cannot be set after connection is established. 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.	Cannot be set after connection is established.
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.	Cannot be set after connection is established. Requires a supporting network security mechanism.
CS_SEC_ NEGOTIATE	Whether the connection will use trusted-user security handshaking.	CS_TRUE or CS_FALSE.	Connection.	Cannot be set after connection is established.
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.	Cannot be set after connection is established. Requires a supporting network security mechanism and a preexisting credential that matches CS_USERNAME.
CS_SEC_ SERVERPRINCIPAL	The network security principal name for the server to which a connection will be opened.	A string value. The default is NULL, which means that ct_connect assumes the server principal name is the same as its server_name parameter.	Connection.	Cannot be set after connection is established. Meaningful only for connections that use network-based user authentication.
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.	Cannot be set after connection is established. Requires a supporting network security mechanism.
CS_SERVERADDR	The address of the server to which you are connected to.	The format “hostname portnumber [filter], where filter is optional.	Connection	Using this property causes ctlib to bypass the host name of the server and the port number of the interfaces.
CS_SERVERNAME	The name of the server to which you are connected.	A string value.	Connection.	Retrieve only, after connection is established.
CS_TDS_VERSION	The version of the TDS protocol that the connection is using.	A symbolic version level.	Connection.	Negotiated login property. Cannot be set after connection is established.
CS_TEXTLIMIT	The largest text or image value to be returned on this connection.	An integer value.	Context, connection.
CS_TRANSACTION_NAME	A transaction name to be used over a connection to Open Server for CICS.	A string value.	Connection.
CS_USERDATA	User-allocated data.	User-allocated data.	Connection, command.
CS_USERNAME	The name used to log in to the server.	A character string.	Connection.	Login property. Cannot be set after connection is established.
CS_VALIDATE_CB	A client-library routine, registered through ct_callback	An integer value	Connection, command