Properties define aspects of Open ClientConnect behavior.
Login properties are used when logging into a server. Login properties include CS_USERNAME, CS_PASSWORD, CS_PACKETSIZE, and CS_NET_DRIVER (used with dynamic network drivers).
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. These types of properties are called negotiated properties.
CS_NET_DRIVER is used to switch communication protocols. The supported protocols vary depending on the operating environment. TCP/IP and CPIC are supported in CICS, IMS and MVS. SNA (LU 6.2) is only supported in CICS and IMS.
An application calls CTBCONFIG, CTBCONPROPS, and CTBCMDPROPS to set and retrieve properties at the context, connection, and command structure levels, respectively. An application calls CTBCONFIG to set and retrieve most context properties; it calls CSBCONFIG 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 CSBCONFIG, CTBCONFIG, CTBCONPROPS, or CTBCMDPROPS 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. |
CTBCONPROPS |
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. |
CTBCONPROPS |
Retrieve only, after the connection is established. |
CS_COMMBLOCK |
A pointer to a communication sessions block (EIB). |
A pointer value. The default is NULL. |
CTBCONPROPS |
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. |
CSBCONFIG, CTBCONFIG, CTBCONPROPS |
|
CS_HOSTNAME |
The host (server) machine name. |
A character string. The default is NULL. |
CTBCONPROPS |
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. |
CTBCONPROPS |
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. |
CTBCONPROPS |
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. |
CTBCONFIG |
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). |
CTBCONFIG |
|
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 |
CTBCONPROPS |
|
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. |
CTBCONFIG, CTBCONPROPS |
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. |
CTBCONFIG, CTBCONPROPS |
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. |
CTBCONPROPS |
Negotiated login property. Takes effect only if set before the connection is established. |
CS_PASSWORD |
The password used to log in to the server. |
A character string. The default is NULL. |
CTBCONPROPS |
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_VERSIONdefaults to the value of CS_VERSION. |
CTBCONPROPS |
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. |
CTBCONFIG, CTBCONPROPS |
|
CS_TIMEOUT |
The timeout value. |
An integer value. The default is CS_NO_LIMIT. |
CTBCONFIG |
Not supported under CICS. CICS waits for ever. |
CS_TRANSACTION_ NAME |
A transaction name. |
A string value. The default is NULL. |
CTBCONPROPS |
|
CS_USERDATA |
User-allocated data. |
User-allocated data. |
CTBCONPROPS, CTBCMDPROPS |
These are pointers to data that allow the customer to tie in to the data. |
CS_USERNAME |
The name used to log in to the server. |
A character string. The default is NULL. |
CTBCONPROPS |
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 CTBINIT call. |
CSBCONFIG, CTBCONFIG |
