Properties define aspects of Open ClientConnect behavior.
Login properties are used when logging into a server.
These include CS_USERNAME, CS_PASSWORD, CS_PACKETSIZE and CS_NET_DRIVER (used with dynamic network drivers).
Negotiated properties are used by servers when a property value must be changed.
That is, a server can change the values of some login properties during the login process. For example, if an application sets CS_PACKETSIZE to 2048 bytes and then logs into a server that cannot support this packet size, the server overwrites 2048 with a packet size it can support.
An application calls ct_config, ct_con_props, and ct_cmd_props to set and retrieve properties at the context, connection, and command structure levels, respectively. An application calls ct_config to set and retrieve most context properties; it calls cs_config to set and retrieve global context properties.
When a context structure is allocated, its property values default to standard values.
When a connection structure is allocated, it picks up default property values from its parent context. For example, if CS_TEXTLIMIT is set to 16,000 at the context level, then any connection created within this context has a default text limit value of 16,000. Likewise, when a command structure is allocated, it picks up default property values from its parent connection.
An application can override a default property value by calling cs_config, ct_config, ct_con_props, or ct_cmd_props to change the value of the property.
Most property values can be either set or retrieved by an application, but some properties are retrieve only.
Table 2-8 lists the Open ClientConnect properties.
Property |
Meaning |
Values |
Function set by |
Notes |
---|---|---|---|---|
CS_APPNAME |
The application name used when logging into the server. |
A character string. The default is NULL. |
ct_con_props |
Login property. Takes effect only if set before the connection is established. |
CS_CHARSETCNV |
The conversion indicator. It indicates whether or not character set conversion is taking place. |
CS_TRUE or CS_FALSE. A default is not applicable. |
ct_con_props |
Retrieve only, after the connection is established. |
CS_COMMBLOCK |
A pointer to a communication sessions block (EIB). |
A pointer value. The default is NULL. |
ct_con_props |
Takes effect only if set before the connection is established. |
CS_EXTRA_INF |
The extra information indicator. It specifies whether or not to return the extra information that is required when processing messages in-line using a SQLCA or SQLCODE. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
cs_config, ct_con_props |
|
CS_HOSTNAME |
The host (server) machine name. |
A character string. The default is NULL. |
ct_con_props |
Login property. Takes effect only if set before the connection is established. |
CS_LOC_PROP |
A pointer to a CS_LOCALE structure that defines localization information. |
A pointer value. A connection picks up a default CS_LOC_PROP from its parent context. |
ct_con_props |
Login property. |
CS_LOGIN_STATUS |
The connection status indicator. It indicates whether or not the connection is open. |
CS_TRUE or CS_FALSE. A default is not applicable. |
ct_con_props |
Retrieve only. |
CS_LOGIN_TIMEOUT |
The login timeout value. |
An integer value. The default is 60 seconds. A value of CS_NO_LIMIT represents an infinite timeout period. |
ct_config |
Open ClientConnect ignores this property. This is the same value as the CICS RTIMEOUT. |
CS_MAX_CONNECT |
The maximum number of connections for this context. |
An integer value. The default varies by platform. On mainframes, the default is 25 (an unlimited number of connections can be defined for a context). |
ct_config |
|
CS_NET_DRIVER |
The type of network driver in use. |
CS_LU62, CS_TCPIP, CS_INTERLINK, or CS_NCPIC. Defaults for: CICS – CS_LU62 IMS – CS_LU62 MVS – CS_NCPIC |
ct_con_props |
|
CS_NETIO |
The sync/async indicator. It indicates whether network I/O is synchronous or asynchronous. |
CS_SYNC_IO or CS_ASYNC_IO. The default is CS_SYNC_IO. |
ct_config, ct_con_props |
With Open ServerConnect this value is always CS_SYNC_IO. |
CS_NOINTERRUPT |
The interrupt indicator. It indicates whether or not the application can be interrupted. |
CS_TRUE or CS_FALSE. The default is CS_FALSE, which means the application can be interrupted. |
ct_config, ct_con_props |
N/A for CICS. This property is included for compatibility with other Open Client libraries. |
CS_PACKETSIZE |
The TDS packet size. |
An integer value. The default varies by platform. On UNIX and MVS platforms, the default is 512 bytes. |
ct_con_props |
Negotiated login property. Takes effect only if set before the connection is established. |
CS_PASSWORD |
The password used to log into the server. |
A character string. The default is NULL. |
ct_con_props |
Login property. Takes effect only if set before the connection is established. |
CS_TDS_VERSION |
The version of the TDS protocol that the connection is using. |
A symbolic version level. CS_TDS_VERSION defaults to the value of CS_VERSION. |
ct_con_props |
Negotiated login property. Takes effect only if set before the connection is established. |
CS_TEXTLIMIT |
The largest text or image value to be returned on this connection. |
An integer value. The default is CS_NO_LIMIT. |
ct_config, ct_con_props |
|
CS_TIMEOUT |
The timeout value. |
An integer value. The default is CS_NO_LIMIT. |
ct_config |
Not supported under CICS. CICS waits forever. |
CS_TRANSACTION_ NAME |
A transaction name. |
A string value. The default is NULL. |
ct_con_props |
|
CS_USERDATA |
User–allocated data. |
User–allocated data. |
ct_con_props, ct_cmd_props |
These are pointers to data that allow the customer to tie into the data. |
CS_USERNAME |
The name used to log into the server. |
A character string. The default is NULL. |
ct_con_props |
Login property. Takes effect only if set before the connection is established. |
CS_VERSION |
The version of Client-Library used by this context. |
CS_VERSION gets its value from a context ct_init call. |
cs_config, ct_config |