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 CPI-C are supported in CICS, IMS and MVS. SNA (LU6.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-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 into 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-VERSION defaults 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 into the data. |
CS-USERNAME |
The name used to log into 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 |
