Allocates a connection handle.
%INCLUDE CTPUBLIC;
DCL 01 CONTEXT FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 CONNECTION FIXED BIN(31) INIT(0); CALL CTBCONAL (CONTEXT, RETCODE, CONNECTION);
(I) A context structure. The context structure is defined in the program call CSBCTXALLOC. The context structure corresponds to the IHANDLE in the Open ServerConnect Gateway-Library.
If this value is invalid or nonexistent, CTBCONALLOC fails.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(O) Handle for this connection. All subsequent Client-Library calls using this connection must use this same name in their CONNECTION argument. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
This is the same value used to define the connection to the Open ClientConnect Connection Table.
In case of error, CTBCONALLOC returns zeroes to this argument.
CTBCONALLOC returns one of the following values listed in Table 3-7.
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. The most common reason for a CTBCONALLOC failure is a lack of adequate memory. |
TDS_SOS (-257) |
Memory shortage. The mainframe subsystem was unable to allocate enough memory for the control block that CTBCONALLOC was trying to create. The operation failed. |
TDS_GWLIB_NO_STORAGE (-17) |
Could not get DSA for Gateway-Library. |
The following code fragment demonstrates the use of CTBCONALLOC. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------------*/
/* */
/* Subroutine to process input data */
/* */
/*------------------------------------------------------------------*/
PROCESS_INPUT: PROC ;
/*------------------------------------------------------------*/
/* allocate a connection to the server */
/*------------------------------------------------------------*/
CSL_CON_HANDLE = 0 ;
CALL CTBCONAL( CSL_CTX_HANDLE,
CSL_RC,
CSL_CON_HANDLE ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONALLOC failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* alter properties of the connection for user-id */
/*------------------------------------------------------------*/
CALL CTBCONPR( CSL_CON_HANDLE,
CSL_RC,
CS_SET,
CS_USERNAME,
PF_USER,
PF_USER_SIZE,
CS_FALSE,
OUTLEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONPROPS for user-id failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* alter properties of the connection for password */
/*------------------------------------------------------------*/
CALL CTBCONPR( CSL_CON_HANDLE,
CSL_RC,
CS_SET,
CS_PASSWORD,
PF_PWD,
PF_PWD_SIZE,
CS_FALSE,
OUTLEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONPROPS for password failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* alter properties of the connection for transaction */
/*------------------------------------------------------------*/
CALL CTBCONPR( CSL_CON_HANDLE,
CSL_RC,
CS_SET,
CS_TRANSACTION_NAME,
PF_TRAN,
PF_TRANL,
CS_FALSE,
OUTLEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONPROPS for transaction failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* alter properties of the connection for Network driver */
/*------------------------------------------------------------*/
SELECT;
WHEN (PF_NETDRV = ' ')
NETDRIVER = CS_LU62 ;
WHEN (PF_NETDRV = 'LU62' | PF_NETDRV = 'lu62')
NETDRIVER = CS_LU62 ;
WHEN (PF_NETDRV = 'IBMTCPIP' | PF_NETDRV = 'ibmtcpip')
NETDRIVER = CS_TCPIP ;
WHEN (PF_NETDRV = 'INTERLIN' | PF_NETDRV = 'interlin')
NETDRIVER = CS_INTERLINK ;
WHEN (PF_NETDRV = 'CPIC' | PF_NETDRV = 'cpic')
NETDRIVER = CS_NCPIC ;
OTHERWISE
DO;
MSGSTR = 'Invalid Network driver entered';
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END;
END;
CALL CTBCONPR( CSL_CON_HANDLE,
CSL_RC,
CS_SET,
CS_NET_DRIVER,
NETDRIVER,
CS_UNUSED,
CS_FALSE,
OUTLEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONPROPS for Network driver failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* setup retrieval of All Messages */
/*------------------------------------------------------------*/
CALL CTBDIAG( CSL_CON_HANDLE,
CSL_RC,
CS_UNUSED,
CS_INIT,
CS_ALLMSG_TYPE,
CS_UNUSED,
CS_UNUSED ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBDIAG CS_INIT failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* set the upper limit of number of messages */
/*------------------------------------------------------------*/
PF_MSGLIMIT = 5 ;
CALL CTBDIAG( CSL_CON_HANDLE,
CSL_RC,
CS_UNUSED,
CS_MSGLIMIT,
CS_ALLMSG_TYPE,
CS_UNUSED,
PF_MSGLIMIT ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBDIAG CS_MSGLIMIT failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* open connection to the server or CICS region */
/*------------------------------------------------------------*/
CALL CTBCONNE( CSL_CON_HANDLE,
CSL_RC,
PF_SERVER,
PF_SERVER_SIZE,
CS_FALSE ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONNECT failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* invokes SEND_COMMAND routine */
/*------------------------------------------------------------*/
IF NO_ERRORS_SW
THEN
CALL SEND_COMMAND ;
CTBCONALLOC allocates a connection handle to a Mainframe ClientConnect or another processing region (three-tier processing), or an Adaptive Server if using two-tier (gateway-less) processing.
Before calling CTBCONALLOC, an application must:
Call CSBCTXALLOC to allocate a context structure.
Call CTBINIT to initialize Client-Library.
Connecting to a server is a three-step process. To connect to a server, an application:
Calls CTBCONALLOC to obtain a connection handle.
Calls CTBCONPROPS to set the values of connection-specific properties, if desired.
Calls CTBCONNECT to create the connection and log in to the server.
All connections created within a context pick up default property values from the parent context. An application can override these default values by calling CTBCONPROPS to set property values at the connection level.
An application can have multiple connections to one or more servers at the same time.
For example, an application can simultaneously have two connections to the server “mars,” one connection to the server “venus,” and one connection to a separate transaction processing region named CICX3. The context property CS_MAX_CONNECT, set by CTBCONFIG, determines the maximum number of connections allowed per context.
Each server connection requires a separate connection handle.
In order to send requests to a server, one or more command handles must be allocated for a connection. CTBCMDALLOC allocates a command handle.
Related functions:
