A typical database session would consist of the following operations:
| • | Initialize the library (SQLOP_INIT_LIB): This is where you identify the ASQL connector to use, based on the target database engine/interface, and load the connector and client library. |
| • | Initialize the connection structure (SQLOP_INIT_CONN): This returns you a handle (in the cmdhdr structure) which is required for all other operations relating to the connection. Note that you could have multiple connections to different databases, in which case you would only need to initialize the library once (assuming the databases all supported the same connector), but you would need to use a separate SQLOP_INIT_CONN to initialize each connection (and then keep the handles separate, probably by allocating separate cmdhdr structures for each connection). |
| • | Optionally set connection option flags (SQLOP_SET_CONNATR) which will affect the connection, such as time-outs, auto-reconnection, caching, etc. Note: some ODBC connection options must be set after connecting to the database. |
| • | Connect to the database (SQLOP_CONNECT): This is where you actually establish the connection and authenticate yourself. It is somewhat analogous to a traditional file-open, except that a database may consist of many tables (each one of which is roughly analogous to a file). Once the database connection is established, there is no need to do anything special to “open” a table, other than reference it in a query statement. |
| • | [ODBC] Optionally set statement attributes (SQLOP_SET_STMATR) which affect the operation of the subsequent statements such as cursor attributes, row-set size, concurrency, etc. |
| • | Issue query and other SQL statements (SQLOP_QUERY) to manipulate the database. |
| • | Retrieve results: For query statements that return result sets (e.g. SELECT), you may retrieve information describing the columns returned using SQLOP_FETCH_COLUMNS. In order to retrieve data, you must use a separate SQLOP_FETCH_ROW call for each row. When finished processing the result set, use SQLOP_FREE_RESULT to release the resources associated with the result set. If you need to start a new query in the middle of processing the results from the previous query, set the reshdl field of the cmdhdr to 1,2,… etc. to keep the result sets straight. |
| • | Disconnect (SQLOP_DISCONNECT) from the database. |
| • | Close the library (SQLOP_CLOSE_LIB). |
