| |
Home |
![[Table of Contents]](/dwicons/b_toc.gif)
|
Open Client Client-Library/C Reference Manual |
![[-]](/dwicons/i_colpse.gif)
| Chapter 3 Routines |
|
| ct_con_props |
|
| 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.
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:
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_STATUS | The connection's status. | A CS_INT-sized bit-mask. | Connection. | Retrieve only. |
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_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-29 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-29 for possible values and their meanings. | Context, connection. | Cannot be set after connection is established. Requires a supporting network security mechanism. |
CS_SERVERNAME | The name of the server to which this connection is 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 via ct_callback | An interger value | Connection, command |
|
|