Home How To Online Documentation Support Download Order

 

 

 
SACommand
SAConnection
SAException
SAField
SAParam
SAString
SADateTime
SANumeric
SAInterval
Enums and Typedefs

  

Usage

Class Members

Examples

SAConnection::Connect

void Connect( const SAString &sDBString , const SAString &sUserID , const SAString &sPassword ,
                            SAClient_t eSAClient = SA_Client_NotSpecified, saConnectionHandler_t fHandler = NULL );  throw (SAException);

Opens the connection to a data source. 

Parameters

sDBString.    Name of database this connection will connect to (see Server specific notes).

sUserID.    A string containing a user name to use when establishing the connection (see Server specific notes).

sPassword.    A string containing a password to use when establishing the connection.

eSAClient.    Optional. One of the following values from SAClient_t enum:

  • SA_Client_NotSpecified     Used by default. Client is not specified.
  • SA_Oracle_Client    Oracle client.
  • SA_SQLServer_Client    SQL Server client.
  • SA_InterBase_Client    InterBase client.
  • SA_SQLBase_Client    SQLBase client.
  • SA_ODBC_Client    ODBC client.
  • SA_DB2_Client    DB2 client.
  • SA_Informix_Client    Informix client.
  • SA_Sybase_Client    Sybase client.
  • SA_MySQL_Client    MySQL client.
  • SA_PostgreSQL_Client    PostgreSQL client.
  • SA_SQLite_Client    SQLite client.

fHandler. Optional. Allow to define connection process callback function defined as:

        typedef void (SQLAPI_CALLBACK *saConnectionHandler_t)(SAConnection &con, SAConnectionHandlerType_t eHandlerType);

Remarks

Using the Connect method on a SAConnection object establishes the physical connection to a data source. After this method successfully completes, the connection is live and you can issue commands against it and process the results.

If you use the default value of eSAClient parameter, you should call setClient method before using Connect.

To check whether a connection established use isConnected method. To check whether a connection is brocken or not use isAlive method.

Server specific notes

Oracle

sDBString - the database name as it is specified in TNSNAMES.ORA file.

If sUserID parameter is empty, SQLAPI++ Library requests Oracle external authentication.

The SQLAPI++ Library requires OCI version 7.3 or higher. The Library tries to connect to Oracle using OCI8 first. If it fails it tries to connect using OCI7.

SQL Server

sDBString - one of the following formats:

  • "" or "@" - empty string or '@' character, connects to a default database on a local server.
  • <database name> or @ <database name> - connects to a database with the specified name on your local server.
  • <server name>@ - connects to a default database on the specified server.
  • <server name>@<database name> - connects to a database with the specified name on the specified server.

To connect to a named instance of SQL Server  use <server name\instance name> instead of <server name>.

The latest SQL Server OLEDB API also supports the next "><server name> forms:

  • TCP/IP: tcp:<servername>[\<instancename>],<port> or tcp:<IPAddress>[\<instancename>],<port>
  • Named Pipes: np:\\<computer_name>\pipe\<pipename> or np:\\<IPAddress>\pipe\<pipename> (for a named instance, the default pipe name is \\<computer_name>\pipe\MSSQL$<instance_name>\sql\query)
  • Shared Memory: lpc:<servername>[\instancename]
  • VIA: via:<servername> [\instancename],<nic number>:<port>

If sUserID parameter is empty, SQLAPI++ Library requests a secure, or trusted, connection to SQL Server.

Using OLE DB
Starting from version 3.3.1 SQLAPI++ Library uses OLE DB as the default API when working with SQL Server. The SQLAPI++ Library requires SQL Server OLE DB version 2.5 or higher.

Using DB-Library
Starting from version 3.3.1 SQLAPI++ Library uses OLE DB as the default API when working with SQL Server. If you want to use DB-Library, you should set "UseAPI" connection option before specifying SQL Server client or connecting to database. The SQLAPI++ Library requires DB-Library version 6.x or higher.
Sybase

sDBString - one of the following formats:

  • "" or "@" - empty string or '@' character, connects to a default database on a default server.
  • <database name> or @ <database name> - connects to a database with the specified name on your default server.
  • <server name>@ - connects to a default database on the specified server.
  • <server name>@<database name> - connects to a database with the specified name on the specified server.

The SQLAPI++ Library requires Open Client version 10.0 or higher.

DB2

sDBString - any valid DB2 connection string.

The SQLAPI++ Library requires DB2 CLI version 6.x or higher.

Informix

sDBString - any valid Informix connection string.

The SQLAPI++ Library requires Informix CLI version 2.x or higher.

InterBase

sDBString:

  • For local InterBase databases, this can be a file name.
  • To connect to an InterBase database on a remote server using TCP/IP the syntax is <server name>:<filename>.
  • To connect to an InterBase database on a remote server using NetBEUI, the syntax is \\ <server name>\<filename>.
  • To connect to an InterBase database on a remote server using SPX, the syntax is <server name>@<filename>.

The SQLAPI++ Library requires client API version 5.x or higher.

SQLBase

sDBString - the database name as it is specified in SQL.INI file.

The SQLAPI++ Library requires CAPI version 6.x or higher.

MySQL

sDBString - One of the following formats:

  • "" or "@" - empty string or '@' character, connects to a local server.
  • <database name> or @ <database name>- connects to a database with the specified name on local server.
  • <server name>@- connects to the specified server.
  • <server name>@<database name> - connects to a database with the specified name on the specified server.

<server name> in its turn can have the following formats:

  • hostname[:port] 
  • pathname of the Unix socket that is used to connect to the server 

The SQLAPI++ Library requires MySQL C API version 3.23.x or higher.

PostgreSQL

sDBString - One of the following formats:

  • "" or "@" - empty string or '@' character, connects to a local server.
  • <database name> or @ <database name>- connects to a database with the specified name on local server.
  • <server name>@- connects to the specified server.
  • <server name>@<database name> - connects to a database with the specified name on the specified server.

The SQLAPI++ Library requires libpq version 7.1.x or higher.

ODBC

sDBString - any valid ODBC connection string.

The SQLAPI++ Library requires ODBC version 3.x or higher.

SQLite

 sDBString - any valid path to the SQLite database file. sUserID and sPassword parameters aren't used.

The SQLAPI++ Library requires SQLite version 3.x or higher.

See also

isConnected, Disconnect, setClient, setOption

SAClient_t

Error handling

Problems and Questions

If you haven't found the answer to your questions or have some problems on using the Library, please, send e-mail to howto@sqlapi.com.