Connect to a server.
CS_RETCODE ct_connect(connection, server_name,
snamelen)
CS_CONNECTION *connection;
CS_CHAR *server_name;
CS_INT snamelen;
A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.
Use ct_con_alloc to allocate a CS_CONNECTION structure, and ct_con_props to initialize that structure with login parameters.
A pointer to the name of the server to connect to. *server_name is the name of the server’s entry in the connection’s directory source. ct_connect looks up *server_name in the connection’s directory source to determine how to connect to that server. A connection’s directory source is specified with the CS_DS_PROVIDER property. See “Directory service provider”. This can be either the Sybase interfaces file or a network-based directory service.
server_name must use the naming syntax recognized by the connection’s directory provider. Most network-based directory providers allow a base directory path (DIT base) to be specified with the CS_DS_DITBASE connection property. If server_name is a partially qualified name, the directory provider combines it with the DIT base to form a fully qualified name.
If server_name is NULL, ct_connect uses a platform-specific default for the server name. On platforms that support environment variables or logical names, this is the value of the DSQUERY environment variable or logical name. On these platforms, if DSQUERY has not been set, ct_connect looks for a server with the name SYBASE.
The length, in bytes, of *server_name. If *server_name is null-terminated, pass snamelen as CS_NULLTERM. If server_name is NULL, pass snamelen as 0 or CS_UNUSED.
ct_connect returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
CS_PENDING |
Asynchronous network I/O is in effect. See “Asynchronous programming”. |
CS_BUSY |
An asynchronous operation is already pending for this connection. See “Asynchronous programming”. |
Common reason for a ct_connect failure include:
Unable to allocate sufficient memory.
The maximum number of connections is already established. Use ct_config to increase the maximum number of connections allowed per context.
Unable to open socket.
Server name not found in interfaces file.
Unknown host machine name.
Adaptive Server is unavailable or does not exist.
Login incorrect.
Cannot open interfaces file or a directory service session.
Cannot load requested directory driver.
When ct_connect returns CS_FAIL, it generates a Client-Library error number that indicates the error.
If ct_connect is
called in the entry functions of a DLL,
a deadlock may arise. This system creates OS threads
and tries to synchronize them using system utilities. This synchronization
conflicts with the operating system’s serialization process.
/* ex_connect() */
CS_RETCODE CS_PUBLIC
ex_connect(context, connection, appname,username, password,
server)
CS_CONTEXT context;
CS_CONNECTION *connection;
CS_CHAR *appname;
CS_CHAR *username;
CS_CHAR *password;
CS_CHAR *server;
{
CS_INT len;
CS_RETCODE retcode;
/* Allocate a connection structure */
...CODE DELETED.....
/* Set properties for new connection */
...CODE DELETED.....
/* Open the connection */
if (retcode == CS_SUCCEED)
{
len = (server == NULL) ? 0 : CS_NULLTERM;
retcode = ct_connect(*connection, server, len);
if (retcode != CS_SUCCEED)
{
ex_error("ct_connect failed");
}
}
if (retcode != CS_SUCCEED)
{
ct_con_drop(*connection);
*connection = NULL;
}
return retcode;
}
This code excerpt is from the exutils.c sample program.
Information about the connection is stored in a CS_CONNECTION structure, which uniquely identifies the connection. In the process of establishing a connection, ct_connect sets up communication with the network, logs into the server, and communicates any connection-specific property information to the server.
Because creating a connection involves logging into a server, an application must define login parameters (such as a server user name and password) before calling ct_connect. An application can call ct_con_props to define login parameters.
A connection can be either synchronous or asynchronous. The Client-Library property CS_NETIO determines whether a connection is synchronous or asynchronous.
For more information about asynchronous connections, see “Asynchronous programming”.
The maximum number of open connections per context is determined by the CS_MAX_CONNECT property (set by ct_config). If not explicitly set, the maximum number of connections defaults to a platform-specific value. For information about platform-specific property values, see the Open Client and Open Server Programmer's Supplement for Microsoft Windows or Open Client and Open Server Programmer's Supplement for UNIX.
When a connection attempt is made between a client and a server, there are two ways in which the process can fail (assuming that the system is correctly configured):
The machine that the server is supposed to be on is running correctly and the network is running correctly.
In this case, if no server is listening on the specified port, the machine that the server is supposed to be on will inform the client, through a network error, that the connection cannot be formed. Regardless of the login timeout value, the connection will fail.
The machine that the server is on is down.
In this case, the machine that the server is supposed to be on will not respond. Because “no response” is not considered to be an error, the network will not inform the client that an error has occurred. However, if a login timeout period has been set, a timeout error will occur when the client fails to receive a response within the set period.
The CS_LOGIN_TIMEOUT property specifies a login timeout period. See “Login timeout”.
To close a connection, an application calls ct_close.
Client-Library requires a directory source that contains the network addresses associated with a given server name. The directory source can be either the Sybase interfaces file or a network-based directory service.
The directory source used by ct_connect depends on the setting of the CS_DS_PROVIDER connection property. See “Directory service provider” for a description of the CS_DS_PROVIDER property.
For information on network-based directory services, see “Directory services” and “Server directory object”.
More than one address can be associated with a server name. ct_connect begins a login dialog at the first address where a server responds.
The CS_RETRY_COUNT property controls how many times ct_connect retries each server address.
The CS_LOOP_DELAY property controls how long ct_connect waits before retrying the sequence again.
See “Retry count” and “Loop delay” for descriptions of these properties.
ct_connect optionally reads the Open Client and Open Server runtime configuration file to set connection properties, server options, and debugging options for the connection. This feature allows a programmer to externalize settings rather than hard-coding calls to ct_con_props, ct_options, and ct_debug.
By default, ct_connect does not read the configuration file. The application must set the CS_EXTERNAL_CONFIG property to enable external configuration. For more information on this feature, see “Using the runtime configuration file”.
ct_close, ct_con_alloc, ct_con_drop, ct_con_props, ct_remote_pwd, “Directory services”, “Interfaces file”, “Properties”, “Server directory object”
