using namespace std;
#include <stdio.h>
#define OTL_ORA7 // Compile OTL 3.1/OCI7
#include <otlv4.h> // include the OTL 4 header file
otl_connect db; // connect object
void insert()
// insert rows into table
{
otl_stream o(50, // buffer size
"insert into test_tab values(:f1<float>,:f2<char[31]>)",
// SQL statement
db // connect object
);
char tmp[32];
for(int i=1;i<=100;++i){
sprintf(tmp,"Name%d",i);
o<<(float)i<<tmp;
}
}
void select()
{
otl_stream i(50, // buffer size
"select * from test_tab where f1>=:f<int> and f1<=:f*2",
// SELECT statement
db // connect object
);
// create select stream
float f1;
char f2[31];
i<<8; // assigning :f = 8
// SELECT automatically executes when all input variables are
// assigned. First portion of output rows is fetched to the buffer
while(!i.eof()){ // while not end-of-data
i>>f1>>f2;
cout<<"f1="<<f1<<", f2="<<f2<<endl;
}
i<<4; // assigning :f = 4
// SELECT automatically executes when all input variables are
// assigned. First portion of output rows is fetched to the buffer
while(!i.eof()){ // while not end-of-data
i>>f1>>f2;
cout<<"f1="<<f1<<", f2="<<f2<<endl;
}
}
int main()
{
otl_connect::otl_initialize(); // initialize OCI environment
try{
db.rlogon("scott/tiger"); // connect to Oracle
otl_cursor::direct_exec
(
db,
"drop table test_tab",
otl_exception::disabled // disable OTL exceptions
); // drop table
otl_cursor::direct_exec
(
db,
"create table test_tab(f1 number, f2 varchar2(30))"
); // create table
insert(); // insert records into table
select(); // select records from table
}
catch(otl_exception& p){ // intercept OTL exceptions
cerr<<p.msg<<endl; // print out error message
cerr<<p.stm_text<<endl; // print out SQL that caused the error
cerr<<p.var_info<<endl; // print out the variable that caused the error
}
db.logoff(); // disconnect from Oracle
return 0;
}
]]>
Any SQL statement, PL/SQL block or a stored procedure call is characterized by its input / output [variables].
Example 1. A SELECT statement has scalar input variables that are used in the WHERE clause of the statement. The SELECT statement also defines output columns. Potentially, the output columns are vector parameters since the SELECT statement may return multiple rows.
Example 2. An INSERT statement writes data into a table, i.e. it has input parameters. Same is true for UPDATE statemements.
Example 3. A DELETE statement deletes rows from a table. Deletion criteria needs to be entered, thus the DELETE statement has input.
Example 4. A stored procedure may have input and/or output parameters. Usually, stored procedure parameters are scalars. There is a special case, though: stored procedure returning a referenced cursor (Oracle) or a result set (MS SQL Server or Sybase).
Example 5. An arbitrary PL/SQL block may have input or/and output parameters that may be either scalars or vectors.
Industrial strength database servers have bulk (or array) operations:
- bulk INSERT
- bulk UPDATE
- bulk DELETE
- bulk SELECT
Therefore, parameters in INSERT/UPDATE/DELETE statement may be vectors if the statement is performed in bulk.
The picture is clear: any interaction with SQL or its procedural extension can be treated as a black box with input and/or output. It does not matter what the black box does inside (according to the definition of a black box). What matters is the input wires that send signals into the box and the output wires that receive signals from the box:
Some of the wires may be both input and output.
Why not combine the concept of data streams and SQL? Instead of multiplying constructs and making database API's too convoluted, why not unify and simplify them? The OTL gives an answer to those questions and the answer is the otl_stream class.
Since a SQL statement may be done in bulk, the otl_stream is a buffered stream. Conceptually, the otl_stream has two separate buffers: input and output. The input buffer is comprised of all input variables put together. Respectively, the output buffer is comprised of all output variables put together.
C++ streams are usually manipulated via operator >> and operator <<. The stream reference is on the left of the operator symbol:
s>>variable; s<<variable;
The double arrow shows the direction in which data goes:
- >> -- from the stream into the data container (variable)
- << -- from the data container (variable) into the stream
OTL streams are similar to buffered C++ streams . A SQL statement or stored procedure call is opened as an ordinary buffered stream. The logic of the OTL stream operations remains the same as the C++ stream operations with the only exception -- the OTL stream has separate input and output buffers which may overlap.
The OTL stream has a flush function for flushing its input buffer when the buffer gets full and a collection of >> and << operators for reading and writing objects of different data types. The most important advantage of the OTL streams is their unified interface to SQL statements and stored procedure call of any kind. This means that the application developer needs to remember just a few syntactical constructs and function names which he already got familiar with when he started working with C++ streams.
Inside the OTL stream there is a small parser for parsing declarations of bind variables and their data types. There is no need to declare C/C++ host variables and bind them with placeholders by special bind function calls. All necessary buffers are created dynamically inside the stream. The stream just needs to be opened for reading and writing values.
The OTL stream interface requires use of the OTL exceptions. This means that potentially any OTL stream operation can throw an exception of the otl_exception type. In order to intercept the exception and prevent the program from aborting, wrap up the OTL stream code with the corresponding try & catch block.
The functioning of the otl_stream is pretty much automatic: when all of the input variables of the stream are defined (in other words, the input buffer is filled out), it triggers the block box inside the stream to execute. The output buffer gets filled out in the process of the execution of the black box. After the execution is finished, the output values can be read from the stream. If it is a SELECT statement and it returns more rows than the output buffer can hold, after the whole output buffer is read, then the stream automatically fetches the next bacth of rows into the output buffer.
]]>
OTL 4.0 was designed as a combination of a C++ template framework and OTL-adapters. The framework is a generic implementation of the concept of OTL streams. The OTL-adapters are thin wrappers around the database APIs and are used as class type parameters to be substituted into the template framework.
OTL 4.0 covers the functionality of a whole database API with just a handful of concrete classes: otl_stream, otl_connect, otl_exception, otl_long_string, and several template PL/SQL (Oracle) table container classes, generated from the template framework and the OTL-adapters.
The OTL code gets expanded into direct database API function calls, so it provides ultimate performance, reliability and thread safety in multi-processor environments as well as traditional batch programs. OTL 4.0, being a template library, is highly portable since it is self-sufficient and compact enough.
OTL 4.0 is ANSI C++ compliant (ANSI C++ typecasts, clean templatized code, etc.), tightly integrated with the Standard Template Library (STL) via so-called STL-compliant stream iterators, and natively supports the STL std::string's in otl_stream's.
The current version of the OTL supports Oracle 7 (natively via OCI7), Oracle 8 (natively via OCI8), Oracle 8i (natively via OCI8i), Oracle 9i (natively via OCI9i), Oracle 10g (natively via OCI10g), DB2 (natively via DB2 CLI), ODBC 3.x as well as ODBC 2.5 compliant data sources in MS Windows and Unix (e.g. Oracle, MS SQL Server, Sybase, Informix, MySQL, DB2, Interbase / Firebird, PostgreSQL, SQLite, SAP/DB, TimesTen, MS ACCESS, etc.). The list of supported database backends is constantly growing.
]]>