4 Overview
4.1 Interfaces
The interface of the Erlang ODBC application divided into four parts:
- Functions for starting and stopping ODBC servers.
- The Basic API which are easy_to-use functions for database access with some control. A basic API function has a corresponding SQL function defined by the ODBC standard.
- The Utility API which supplies a few easy-to-use functions for database access with little control over details. A utility API function is a collection of some SQL functions.
- Depricated functions are only with for compatibility reason. Some of them do nothing and some are replaced by a function from Basic or Utility API.
An ODBC serving process can be compared to an Erlang port. It allows you to make function calls, from Erlang, to an ODBC Driver (or in reality a Driver Manager, which talks to a Driver). The Driver communicates with the database, which it is built for. The serving process also plays the role of a server and will be referred to as the server in this text.
When you start ODBC you get a new server, which handles requests by passing them on to an ODBC Driver. Requests are handled sequentially and the server cannot be connected to more than one database at any time.
An ODBC server can only be started on a named node with a cookie (start Erlang with one of the -name
<nodename>
or -sname<nodename>
options and possibly with the -setcookie<cookie>
option).The server links to the process that starts it (the client). Should the client terminate, the server terminates too. The server is dedicated to the client process just like an Erlang port, but there are two important differences: an ODBC server accepts requests from any process (ports accept messages from the connected process only), and it does not send messages spontaneously (or deliver them from the ODBC Driver) -- the ODBC server is passive.
4.1.1 Utility API
Using the Utility API is easy. Follow the steps below:
- Start the server by calling
start_link/[2, 3]
.
- Connect to the database with one of
erl_connect/[2, 3, 4, 5]
- Submit SQL statements to the database by calling
erl_executeStmt/[2, 3]
.
- Disconnect by calling
erl_disconnect/[1, 2]
. At this point it is possible to connect to another database by callingerl_connect/[2, 3, 4, 5]
again.
- The server process dies when
stop/[1, 2]
is called.
4.1.2 Basic API
To be able to make full use of the Basic API it is necessary to be familiar with the ODBC standard. Here is a typical way to use it for a SELECT statement though:
- Connect to the database:
sqlConnect/[4, 5]
.
- Execute an SQL statement:
sqlExecDirect/[2, 3]
- Check if the statement generated a result set (or table), which SELECT statements do:
sqlNumResultCols/[1, 2]
returns a value greater than zero.
- Describe the returned column of the table:
sql_describe_col/[4, 5]
.
- Create reference for the returned column:
columnRef/0
.
- Bind the reference to the column:
sqlBindCol/[3, 4]
.
- Repeat steps 4 through 6 for each desired column (not necessarily all columns in the table).
- Get the data for the columns:
sqlFetch/[1, 2]
.
- Get the data for a column:
getData/[2, 3]
.
- Repeat step 9 for all selected columns.
- Repeat steps 8 through 10 until all rows in the table have been retrieved.
- Close the cursor on the statement:
sqlCloseCursor/[1, 2]
.
- Start over with step 2 to execute a new statement.
- Disconnect from the database:
sqlDisConnect/[1, 2]
.
You may use the Basic API and the Utility API intermittently, but remember that certain operations performed in the Basic API (like setting different attributes defined by the ODBC standard) may affect the behaviour of the Utility API.
4.1.3 Choice of API
When to use which API? The Utility API can be used when none of the following is true:
- It is necessary to set an attribute. This can only be done through the Basic API. You may however use the Basic API just for setting attributes, and the Utility API for all other tasks.
- The table resulting from a SELECT statement is very big. In this case using the Utility API would consume a huge amount of memory, since the whole table is returned in one chunk. You can get around this problem by using the Basic API by retrieving fewer rows at a time.