ct_connect_string

Description

Connects to a server by specifying a connection string. This function provides the same functionality as ct_connect(). It also provides a mechanism to set certain attributes at connection time.

Syntax

CS_RETCODE ct_connect_string(connection, connection_string, length)
CS_CONNECTION    *connection;
CS_CHAR                  *connection_string;
CS_INT                       length;

Parameters

connection: 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.

connection_string: A string containing attribute names and values.

length: The length, in bytes, of *connection_string. If *connection_string is null-terminated, pass length as CS_NULLTERM. If connection_string is NULL, pass length as 0 or CS_UNUSED.

Returns

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”.

The connection string is a semicolon-separated string of name=value parts:

Name – a case-insensitive value that can be delimited by an equal sign (=) or semicolon (;). An attribute can have multiple synonyms. For example, server and servername refer to the same attribute.
Equals sign (=) – indicates the start of the value to be assigned to the Name. If there is no equals sign, the Name is assumed to be of Boolean type with a value of true.
Value – a string that is terminated by a semicolon (;). Use a backslash (\) if a semicolon or another back slash is present in the value. Values can be of type boolean, integer, or string. Valid values for Boolean types are true, false, on, off, 1, and 0.

If a boolean name is present without a value, the Boolean type must be set to true.

Examples

Example 1

ct_connect_string(conn, "Username=me; Password=mypassword; Servername=ASE", CS_NULLTERM);

Usage

**Table 3-14: Valid Attribute Names and Values**
Name	Description	Value
ANSINull	Determines whether evaluation of NULL-valued operands in SQL equality (=) or inequality (!=) comparisons is ANSI-compliant. If the value is true, Adaptive Server enforces the ANSI behavior that = NULL and is NULL are not equivalent. In standard Transact-SQL®, = NULL and is NULL are considered to be equivalent. This option affects <> NULL and is not NULL behavior in a similar fashion.	Boolean value. The default is false.
BulkLogin	Determines whether a connection is enabled to perform a bulk-copy operation.	Boolean value. The default is false.
ChainXacts	If true, Adaptive Server uses chained transaction behavior, that is, each server command is considered to be a distinct transaction. Adaptive Server implicitly executes a begin transaction before any of these statements: delete, fetch, insert, open, select, and update. You must still explicitly end or roll back the transaction. If false, an application must specify explicit begin transaction statements paired with commit or rollback statements.	Boolean value. The default is false.
Charset	Specifies the charset to be used on this connection.	String value.
Confidentiality	Whether data encryption service is performed on the connection.	Boolean value. The default is false.
CredentialDelegation	Determines whether to allow the server to connect to a second server with the user’s delegated credentials.	Boolean value. The default is false.
DetectReplay	Determines whether the connection’s security mechanism detects replayed transmissions.	Boolean value. The default is false.
DetectOutOfSequence	Determines whether the connection’s security mechanism detects transmissions that arrive out of sequence.	Boolean value. The default is false.
Integrity	Determines whether the connection’s security mechanism performs data integrity checking.	Boolean value. The default is false.
Interfaces	The path and name of the interfaces file.	String value.
Keytab	The name and path to the file from which a connection’s security mechanism reads the security key to go with the username value.	String value. The default is NULL, that is, the user must have established credentials before connecting.
Locale	Determines which language and character set to use for messages, datatype conversions, and datetime formats.	String value.
Language	Determines which language set to use for messages, datatype conversions, and datetime formats.	String value.
LoginTimeout	Specifies the login timeout value.	Integer value.
MaxConnect	Specifies the maximum number of simultaneously open connections that a context may have.	Integer value. Default value is 25. Negative and zero values are not allowed.
MutualAuthentication	Determines whether the server is required to authenticate itself to the client.	Boolean value. The default is false.
NetworkAuthentication	Determines whether the connection’s security mechanism performs network-based user authentication.	Boolean value. The default is false.
PacketSize	Specifies the TDS packet size.	Integer value.
Password	Specifies the password used to log in to the server.	String value.
PasswordEncryption	Determines whether the connection uses asymmetrical password encryption.	Boolean value. The default is false.
SecurityMechanism	Specifies the name of the network security mechanism that performs security services for the connection.	String value. The default value depends on security driver configuration.
Server Servername	Specifies the name of the server to which you are connected.	String value.
ServerPrincipalName	Specifies the network security principal name for the server to which a connection is opened.	String value. The default is NULL, which means that the connection assumes the server principal name is the same as its ServerName value.
TDS_Keepalive	Determines whether to use the KEEPALIVE option.	Boolean value. The default is true.
Timeout	Specifies the connection timeout value.	Integer value.
UID User Username	Specifies the name used to log in to the server.	String value.