Connects to a server.
CS_RETCODE ct_connect(connection, servername,
servername_len);
CS_CONNECTION *connection;
CS_CHAR *servername;
CS_INT servername_len
(I) Handle for this SNA connection. This connection handle must be allocated with ct_con_alloc. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
(I) Name of the connected server. For clients running SNA, this is the name by which the server is known to the Open ClientConnect Server Path Definition Table. For clients running TCP/IP without a gateway, this is the actual name of the Adaptive Server Enterprise in the LAN interfaces file.
You must assign a value to this argument. If a server name is not specified, ct_connect fails.
(I) Length, in bytes, of servername.
ct_connect returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. |
TDS-CRTABLE-UNAVAILABLE (-31) |
The connection router table cannot be loaded. |
The following code fragment demonstrates the use of ct_connect. 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, &connection);
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_connect establishes a connection between a mainframe transaction processing region and a remote server. Information about the connection is stored in a connection handle, which uniquely identifies the connection.
The remote server can be another transaction processing region or server (Adaptive Server Enterprise, Open Server, and so on). For clients running SNA, the name in the Server Path Definition Table is the name of the remote region or server. For clients running TCP/IP, SYGWHOST (server name and IP address) is used in conjunction with either the MVS-side information file for the specific drive or the CICS partner table.
When it establishes a connection, ct_connect sets up communication with the server, forwards login information, and communicates any connection-specific property information to the server.
Because creating a connection involves sending login information, an application must define login parameters (server user ID and password) before calling ct_connect. An application calls ct_con_props to define login parameters.
The maximum number of open connections per context is determined by the CS_MAX_CONNECT property (set by ct_config). The default maximum is 25 connections.
An attempt to establish a connection can fail in two ways (assuming that the system is correctly configured):
If the specified server machine (the machine on which the server resides) is running correctly and the network is running correctly, but no server is listening on the specified port, the specified server machine signals the client, through a network error, that the connection cannot be formed. Regardless of the login time-out value, the connection fails.
If the machine on which the server resides is down, the server does not respond. Because “no response” is not considered to be an error, the network does not signal the client that an error occurred. However, if a login time-out period is set, a time-out error occurs when the client fails to receive a response within the set period.
To close a connection, an application calls ct_close.
Related functions
Related topics
Related documentation
Mainframe Connect Client Option Installation and Administration Guide
