# The eXtremeSQL ODBC API

> This topic describes the eXtremeSQL ODBC Driver implementation and how to use the ODBC driver to connect to existing eXtremeDB databases. (Please use the following links for details on configuring the ODBC DSN on Windows systems or on Unix-Linux systems.)

> The objective of the ODBC Driver is to allow ODBC client applications to gain access to a standard eXtremeSQL application. It is not intended, and it is not possible, to create a stand-alone ODBC application. eXtremeSQL interfaces with on-disk and in-memory databases; the database dictionary that describes the structure of the database is encoded in the application by virtue of linking the `mcocomp`-generated C file. Further, eXtremeDB in-memory databases don’t exist until they are created by the application, unlike on-disk databases that persist across executions of the application and which store the database dictionary with the on-disk database files.

> The eXtremeSQL ODBC Driver can be used to connect to an eXtremeDB database in two distinct ways:

> - connect to a local database (an on-disk or in-memory database created on the same machine by a standard eXtremeDB or eXtremeSQL application), or
> - connect to a remote database (on-disk or in-memory) through the eXtremeSQL remote server.

> In the first case, the driver acts as a thin client that serializes SQL queries and deserializes the results via a TCP connection to the eXtremeSQL server application; the server can be the xSQL utility or any application using the eXtremeSQL APIs.

> In the second case, the ODBC driver connects to a remote database if the `DSN=` string in the ODBC configuration file specifies a TCP address. Or the ODBC driver can open a database locally in shared memory. In this case the process that loads the ODBC driver in its memory space gains direct access to the database in shared memory. (Note that in this case, if the application crashes or terminates inside an open transaction, it can cause database corruption.)

> Whether the database is accessed locally or remotely is determined by the `DSN=` string in the ODBC configuration file. If the `DSN`string has a TCP address semantic like `192.168.1.1:5000` or `localhost:5000` (where the `:port_number` portion indicates the communication port) then the ODBC driver acts as a remote SQL client and tries to connect to the specified address. When the `DSN` string specifies just a name with no port specification (`:port_number`), the ODBC driver tries to connect to a local database in shared memory with the specified name.

> The xSQL utility can be invoked as a ready-to-use eXtremeSQL remote server which interfaces with a database created in shared memory by another application (the main application). Thus xSQL can act as a medium between any in-memory database placed in shared memory and the eXtremeSQL ODBC Driver on the client side. To provide a connection from the ODBC Driver to a persistent (on-disk) remote database, an eXtremeSQL remote server needs to be embedded into the main application. (Note that the `sql-12-interactive` source code in the SDK samples demonstrates how to setup and run an eXtremeSQL remote server with interactive user interface.)

> The diagram below illustrates how the ODBC driver interfaces with an application that opens an in-memory database in shared memory:

The diagram below illustrates how the ODBC driver interfaces with a remote in-memory database opened by xSQL: