Allocates a connection handle.
CS_RETCODE cs_con_alloc(context, connection); CS_CONTEXT *context; CS_CONNECTION **connection;
(I) A context structure. The context structure is defined in the program call cs_ctx_alloc. The context structure corresponds to the IHANDLE structure in the Open ServerConnect Gateway-Library.
If this value is invalid or nonexistent, ct_con_alloc fails.
(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, ct_con_alloc returns zeroes to this argument.
ct_con_alloc returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. The most common reason for a ct_con_alloc 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 ct_con_alloc 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 ct_con_alloc. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
/************************************************************************/
/* */
/* Subroutine to process input data */
/* */
/************************************************************************/
void proces_input ()
{
CS_INT rc;
CS_INT *outlen;
CS_INT buf_len;
CS_INT msglimit;
CS_INT netdriver;
/*------------------------------------------------------------*/
/* Allocate a connection to the server */
/*------------------------------------------------------------*/
rc = ct_con_alloc (context, &maxconnect);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CONALLOC failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Alter properties of the connection for user-id */
/*------------------------------------------------------------*/
buf_len = user_size;
rc = ct_con_props (connection, (long)CS_SET,
(long)CS_USERNAME, username,
buf_len, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CON_PROPS for user-id failed",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Alter properties of the connection for password */
/*------------------------------------------------------------*/
buf_len = pwd_size;
rc = ct_con_props (connection, (long)CS_SET,
(long)CS_PASSWORD, pwd, buf_len, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CON_PROPS for password failed",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Alter properties of the connection for transaction */
/*------------------------------------------------------------*/
buf_len = tran_size;
rc = ct_con_props (connection, (long)CS_SET,
(long)CS_TRANSACTION_NAME,
tran, buf_len, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CON_PROPS for transaction failed",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Alter properties of the connection for network driver */
/*------------------------------------------------------------*/
netdriver = 9999; /* default value for non-regconized
driver name */
/* if no netdriver entered, default is LU62 */
if (strncmp(driver," ",9) == 0 ??
strncmp(driver,"LU62",4) == 0)
netdriver = CS_LU62;
else if (strncmp(driver,"INTERLINK",8) == 0)
netdriver = CS_INTERLINK;
else if (strncmp(driver,"IBMTCPIP",8) == 0)
netdriver = CS_TCPIP;
else if (strncmp(driver,"CPIC",4) == 0)
netdriver = CS_NCPIC;
rc = ct_con_props (connection, (long)CS_SET,
(long)CS_NET_DRIVER, (long) netdriver,
CS_UNUSED, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CON_PROPS for network driver failed",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Setup retrieval of All Messages */
/*------------------------------------------------------------*/
rc = ct_diag (connection, CS_INIT,
CS_UNUSED, CS_UNUSED, CS_NULL);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_DIAG CS_INIT failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Set the upper limit of number of messages */
/*------------------------------------------------------------*/
msglimit = 5 ;
rc = ct_diag (connection, CS_MSGLIMIT, CS_ALLMSG_TYPE,
CS_UNUSED, &msglimit);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_DIAG CS_MSGLIMIT failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Open connection to the server or CICS region */
/*------------------------------------------------------------*/
rc = ct_connect (connection, servname, server_size);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CONNECT failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Invokes SEND_COMMAND routine */
/*------------------------------------------------------------*/
if (no_errors_sw)
send_command ();
ct_con_alloc allocates a connection handle to a Mainframe ClientConnect or another processing region (three-tier processing), or an Adaptive Server Enterprise if using two-tier (gateway-less) processing.
Before calling ct_con_alloc, an application must:
Call ct_ctx_alloc to allocate a context structure.
Call ct_init to initialize Client-Library.
Connecting to a server is a three-step process. To connect to a server, an application:
Calls ct_con_alloc to obtain a connection handle.
Calls ct_con_props to set the values of connection-specific properties, if desired.
Calls ct_connect to create the connection and log into 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 ct_con_props 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 CICS region named CICX3. The context property CS_MAX_CONNECT, set by ct_config, 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. ct_cmd_alloc allocates a command handle.
Related functions
