An application needs to call Open ClientConnect functions to allocate, use, and deallocate most handles, but does not need to access them directly.
Client-Library uses handles at three levels. Each handle defines and manages a particular environment. Each type of handle can have certain properties, described below.
Most Client-Library functions include a handle argument.
An application must allocate these handles before using them as
arguments.
The following handles are used with Client-Library:
Context handle. A context handle defines a particular application, context, or operating environment. The context handle is defined in the program call CSBCTXALLOC.
An application can have only one context.
A context handle corresponds to the IHANDLE structure in the Open ServerConnect Gateway-Library.
The context handle can have the following properties listed in Table 2-10.
Property |
Set By |
|---|---|
CS_EXTRA_INF |
CSBCONFIG |
CS_LOGIN_TIMEOUT |
CTBCONFIG |
CS_MAX_CONNECT |
CTBCONFIG |
CS_NETIO |
CTBCONFIG |
CS_NOINTERRUPT |
CTBCONFIG |
CS_TEXTLIMIT |
CTBCONFIG |
CS_TIMEOUT |
CTBCONFIG |
CS_VERSION |
CSBCONFIG |
Connection handle.
This is the handle for an individual client/server connection. The connection handle is defined in the program’s CTBCONALLOC call. If parallel sessions are used, there must be one connection handle for each session. An application can have up to 25 connections.
Open ClientConnect uses a Connection Router program to define connections. Each connection handle corresponds to a connection defined with the Connection Router. For details about the Connection Router, see the Mainframe Connect Client Option Installation and Administration Guide.
A connection handle can have the following properties listed in Table 2-11.
Property |
Set by |
|---|---|
CS_APPNAME |
CTBCONPROPS |
CS_CHARSETCNV |
CTBCONPROPS |
CS_COMMBLOCK |
CTBCONPROPS |
CS_EXTRA_INF |
CTBCONPROPS |
CS_HOSTNAME |
CTBCONPROPS |
CS_LOC_PROP |
CTBCONPROPS |
CS_LOGIN_STATUS |
CTBCONPROPS |
CS_NET_DRIVER |
CTBCONPROPS |
CS_NETIO |
CTBCONPROPS |
CS_NOINTERRUPT |
CTBCONPROPS |
CS_PACKETSIZE |
CTBCONPROPS |
CS_PASSWORD |
CTBCONPROPS |
CS_TDS_VERSION |
CTBCONPROPS |
CS_TEXTLIMIT |
CTBCONPROPS |
CS_TRANSACTION_NAME |
CTBCONPROPS |
CS_USERNAME |
CTBCONPROPS |
Command handle.
A command handle defines a command space, which is used to send commands to a server over a connection and process the results. A command handle is defined in the program call CTBCMDALLOC. Each command handle is associated with a particular connection. There can be any number of command handles associated with a connection.
A command handle and its associated connection handle correspond to the TDPROC handle in the Open ServerConnect Gateway-Library.
A command handle can have the CS_USERDATA property.
Table 2-12 lists the routines that allocate, use, and deallocate handles.
Structure |
Allocated and used by |
|---|---|
CONTEXT |
CSBCTXALLOC, CTBCONFIG, CSBCONFIG, CSBCTXDROP |
CONNECTION |
CTBCONALLOC, CTBCONPROPS, CTBCONDROP |
COMMAND |
CTBCMDALLOC, CTBCMDPROPS, CTBCMDDROP |
