AdsConnect60

Advantage Client Engine

  This is the first topic This is the last topic  

Connects to the given server or to a database in an Advantage Data Dictionary.

Syntax

UNSIGNED32 AdsConnect60( UNSIGNED8 *pucConnectPath,

UNSIGNED16 usServerTypes,

UNSIGNED8 *pucUserName,

UNSIGNED8 *pucPassword,

UNSIGNED32 ulOptions,

ADSHANDLE *phConnect );

Parameters

pucConnectPath (I)

Full file path of the data dictionary file, server name, or drive letter to which to connect. If the application uses a server name as the parameter, it must include the share name for Windows, path from the root for Linux, or volume name for Novell NetWare as well. For example, use "\\server\share", "\\server\path_from_root", or "\\server\volume". Linux users can also connect to the local machine using a direct path such as "/mydata". All Advantage clients and servers consider either slash type (forward or backslash) to be a path delimiter, this means you could also use a connection path with forward slashes, such as "//server/volume". Linux users should also reference the REPLACE_UNC_SERVER section in the ads.ini documentation.

usServerTypes (I)

Enumeration of server types to allow client connections. Options are ADS_REMOTE_SERVER, ADS_AIS_SERVER, and ADS_LOCAL_SERVER. The default is ADS_REMOTE_SERVER logically ORed with ADS_AIS_SERVER.

pucUserName (I)

Optional user name to verify in the data dictionary. The user name and password is validated against information stored in the data dictionary. If this parameter is not NULL, the pucConnectPath must specify an Advantage Data Dictionary. Otherwise, an error will be returned.

pucPassword (I)

Optional password for the user.

ulOptions (I)

Options for connecting to Advantage servers. Allowed values are ADS_DEFAULT, ADS_INC_USERCOUNT, ADS_STORED_PROC_CONN, ADS_COMPRESS_ALWAYS, ADS_COMPRESS_NEVER, and ADS_COMPRESS_INTERNET. The values can be ORed together. See Remarks for more information on the options.

phConnect (O)

The handle of the connection is returned if it the connection is made successfully.

Special Return Codes

AE_NO_DRIVE_CONNECTION

An Advantage server could not be located for the indicated path.

AE_INVALID_PASSWORD

Either the user is unknown in the database or an incorrect password is entered for the user.

7077

The Advantage Database Server cannot open the specified data dictionary.

7078

Authentication error.

7085

Invalid UNC server name. The server name used in the connection path could not be resolved. If using local server verify the name exists in the ads.ini file and that the application is using the correct ads.ini file. If using remote server you should not get this error. Contact your Advantage Technical Services representative.

Remarks

AdsConnect60 connects to the Advantage Database Server on the given server. The pucConnectPath parameter can be a full file path to an Advantage Data Dictionary file, a drive letter, or any valid path (standard name resolution will be performed). Only those server types that are specified in usServerType parameter will be considered when attempting to connect. If the usServerType is 0, this call obeys the default server types that may have been set by calling AdsSetServerType. The function returns a connection handle if it succeeds. The connection handle can be used in subsequent calls to AdsOpenTable, AdsCreateTable, and transaction processing functions.

If the pucConnectPath parameter specifies a path to an Advantage Data Dictionary file, the returned connection handle is a database connection handle. A database connection handle can be used in all functions where a connection handle is required. In addition, a database connection provides access to additional functionality provided by the Advantage Data Dictionary. Specifically, a database connection handle is required to open ADT tables that are part of the database defined in the data dictionary. See Advantage Data Dictionary for more information.

If the pucConnectPath parameter does not specify a path to an Advantage Data Dictionary file, the returned connection handle is a free connection handle.

The pucUserName and pucPassword parameters are optional. They are used by the Advantage Server to authenticate the user when attempting to obtain a database connection. If the pucUserName parameter is provided, the pucConnectPath must specify a path to an Advantage Data Dictionary file. However, the user name and password are not required when making a database connection. The database specified by the pucConnectPath can be set up to allow anonymous user connections (see AdsDDSetDatabaseProperty for information). In such a case, using no user name and no password is a valid combination to obtain a database connection. If the database specified by the pucConnectPath is set up to require users to log in, a valid combination of user name and password must be supplied to obtain a database connection.

The ulOptions parameter specifies options used when making the connection. The following values can be ORed together in the ulOptions parameter.

ADS_DEFAULT

If no options are needed, this constant (0) can be used.

ADS_INC_USERCOUNT

If this option is passed, the user count on the Advantage Database Server will be incremented, even if the current PC is already connected to the Advantage server. Without this option, if the same PC connects to Advantage more than one time they are counted as a single user and only the connection count is incremented.

In general, this property was added to allow an Advantage middleware type of application to increment the Advantage Database Server user count for each remote client workstation indirectly accessing the Advantage Database Server. This provides an easy way for Advantage middleware applications to abide by the Advantage Database Server license agreement as related to remote client workstations taking up a "user" toward the maximum number of licensed users.

ADS_STORED_PROC_CONN

Used to NOT increase the user count on the server. All stored procedure developers should use this option when making connections from stored procedures. If the application is not a stored procedure, then this has no effect.

ADS_COMPRESS_ALWAYS

If this option is specified, then all data communications between the client and server will be compressed unless compression is specifically turned off at the server. See Communications Compression. This option is ignored for ADS_LOCAL_SERVER connections.

ADS_COMPRESS_NEVER

If this option is specified, then compression will not be used for communications between the client and server. This option is ignored for ADS_LOCAL_SERVER connections.

ADS_COMPRESS_INTERNET

If this option is specified, then all data communications for ADS_AIS_SERVER connections will be compressed unless compression is specifically turned off at the server. See Communications Compression. This option is ignored for ADS_LOCAL_SERVER connections.

ADS_UDP_IP_CONNECTION

If this option is specified, then the client will communicate with the server using UPD/IP.

ADS_IPX_CONNECTION

If this option is specified, then the client will communicate with the server using IPX.

ADS_TCP_IP_CONNECTION

If this option is specified, then the client will communicate with the server using TCP/IP.

Note that if none of the ADS_COMPRESS options are specified, the COMPRESSION setting in the ADS.INI file will be used if available.

Connection paths to the Advantage Database Server can also include a port number if the Advantage Database Server configuration specifies the port number. The form of the connection string can be either of the following (using forward or backward slashes):

//servername:port/path

//ip_addr:port/path

In the first format (//servername:port), the client will attempt a DNS lookup for the host to find the IP address and then will use the given port to attempt communication with the Advantage Database Server. In the second format, the client simply uses the given IP address and port to attempt to communicate with the Advantage Database Server. The following are syntactically correct connection paths using port numbers:

//theserver:31237/adsdata/testing

//theserver.mydomain.com:31237/adsdata/testing

//1.2.3.4:31237/adsdata/testing

Example

Making a data dictionary bound connection and opening the "Customer Information" table in the database.

AdsConnect60( "n:\\MyData\\myData.ADD", ADS_REMOTE_SERVER, NULL, NULL, ADS_DEFAULT, &hConn );

AdsOpenTable( hConn, "Customer Information", NULL, ADS_DEFAULT, ADS_ANSI, ADS_DEFAULT,

ADS_DEFAULT, ADS_DEFAULT, &hTable );

See Also

AdsOpenTable

AdsDisconnect

AdsSetServerType

AdsDDCreate

AdsDDAddTable

AdsDDSetDatabaseProperty

AdsDDGetTableProperty

AdsDDGetFieldProperty

AdsIsConnectionAlive