Download O2DB Access User Manual

O2DBAccess
User Manual
C++ Interface
Release 5.0 - May 1998
In for m ation in t h is docu m en t is su bject t o ch an ge with ou t
n ot ice an d sh ou ld n ot be con str u ed as a com m it m en t by
O2 Tech n ology.
Th e soft war e descr ibed in th is docu m en t is deliver ed u n der a
licen se or n on disclosu r e agr eem en t.
Th e soft war e can on ly be u sed or copied in accor dan ce wit h t h e
ter m s of th e agr eem en t . It is again st t h e law t o copy t h is
soft war e on m agn et ic t ape, disk , or an y ot h er m ediu m for an y
pu r pose ot h er t h an t h e pu r ch aser ’s own u se.
Copyr igh t 1992-1998 O 2 Tech n ology.
All r igh t s r eser ved. No par t of t h is pu blicat ion can be
r epr odu ced, st or ed in a r et r ieval syst em or t r an sm it t ed in an y
for m or by an y m ean s, elect r on ic, m ech an ical, ph ot ocopy
with ou t pr ior wr itt en per m ission of O2 Tech n ology.
O2 , O 2 API, O 2 C, O2 DBAccess, O2 En gin e, O 2 Gr aph , O2 Kit ,
O2 Look , O2 St or e, O2 Tools, an d O2 Web ar e r egist er ed
tr adem ar k s of O2 Tech n ology.
SQL an d AIX ar e r egist er ed t r adem ar k s of In t er n at ion al
Bu sin ess Mach in es Cor por at ion .
Su n , Su n OS, an d SOLARIS ar e r egist er ed t r adem ar k s of Su n
Micr osystem s, In c.
X Win dow System is a r egist er ed tr adem ar k of t h e
Massach u set t s In st itu t e of Tech n ology.
Un ix is a r egist er ed t r adem ar k of Un ix Syst em Labor at or ies, In c.
HPUX is a r egist er ed t r adem ar k of H ewlet t -Pack ar d Com pan y.
BOSX is a r egist er ed t r adem ar k of Bu ll S.A.
IRIX is a r egist er ed t r adem ar k of Siem en s Nixdor f, A.G.
NeXTSt ep is a r egister ed t r adem ar k of t h e NeXT Com pu t er , In c.
Pu r ify, Qu an t ify ar e r egist er ed tr adem ar k s of Pu r e Soft war e In c.
Win dows is a r egist er ed t r adem ar k of Micr osoft Cor por ation .
All oth er com pan y or pr odu ct n am es qu ot ed ar e t r adem ar k s or
r egist er ed t r adem ar k s of t h eir r espect ive t r adem ar k h older s.
Who should read this manual
Th is m an u al descr ibes h ow t o u se O 2 D BAccess. Th is O 2 m odu le
en ables to con n ect O 2 applicat ion s t o r elation al databases on r em ot e
h ost s, an d t o im por t an d expor t dat a fr om an d t o su ch syst em s.
O 2 D BAccess pr ovides class libr ar ies (O2 C an d C++) for t h ese t ask s. Th e
m an u al also descr ibes h ow t o in vok e SQL st at em en t s fr om O2 . An
exam ple pr ogr am is pr esen t ed.
Oth er docu m en t s available ar e ou t lin ed, click below.
See O2 Documentation set.
T A B L E O F CON T E N T S
Th is m an u al is divided in t o t h e followin g ch apt er s:
• 1 - In t r odu ct ion
• 2 - Ut ilizat ion
• 3 - Classes
• 4 - Appen dices
O2 DBAccess User Man u al
5
TABLE OF CONTENTS
1
Introduction
9
1.1 System Overview......................................................................10
O2 Engine ....................................................................................12
O2 Store .......................................................................................13
O2DB Access ...............................................................................14
1.2 Manual Overview ......................................................................16
2
Programming Guide
17
2.1 The o2dbaccess Library ..........................................................18
Classes..........................................................................................18
2.2 Guidelines .................................................................................19
2.3 Accessing a Database .............................................................21
Host connection and database log in............................................21
Open Statement ............................................................................22
2.4 Preparing a Statement .............................................................23
Associating an SQL statement .....................................................23
Managing statements....................................................................23
Storing a query result set..............................................................24
2.5 Running a Statement ...............................................................25
2.6 Commit and Rollback...............................................................28
2.7 Ending a Session .....................................................................28
3
Class Library
29
3.1 o2db_O2DBAccess ..................................................................30
server_error ..................................................................................31
3.2 o2db_Connection .....................................................................32
connect .........................................................................................33
disconnect.....................................................................................34
logoff ............................................................................................35
logon.............................................................................................36
6
O2 DBAccess User M an u al
TABLE OF CONTENTS
3.3 o2db_Session .......................................................................... 38
close............................................................................................. 39
commit ......................................................................................... 40
open ............................................................................................. 41
rollback ........................................................................................ 43
3.4 o2db_Statement ....................................................................... 44
add_cursor_variable .................................................................... 45
add_input_variable ...................................................................... 46
associate....................................................................................... 48
operator >> .................................................................................. 50
operator << .................................................................................. 51
o2db_sql_execute ........................................................................ 53
4
Appendices
55
4.1 Example Application ............................................................... 56
Defining a C++ schema ............................................................... 57
Connecting to O2......................................................................... 58
Connecting to the Relational database server.............................. 59
Creating a table............................................................................ 61
Populating the table ..................................................................... 62
Displaying the table content ........................................................ 64
Querying the RDBMS ................................................................. 66
Building the application .............................................................. 68
4.2 Configuration File .................................................................... 69
4.3 Possible Errors ........................................................................ 71
INDEX
O2 DBAccess User Man u al
77
7
TABLE OF CONTENTS
8
O2 DBAccess User M an u al
11
I ntr oduction
Con gr at u lat ion s! You ar e n ow a u ser of O 2 D BAccess!
O2 DBAccess is t h e O2 m odu le t h at en ables you t o com m u n icat e an d
wor k wit h r elat ion al dat abases on r em ot e h osts
Th is ch apt er in t r odu ces t h e O2 syst em an d O2 DBAccess an d ou t lin es
it s var iou s feat u r es an d advan t ages. An over view of t h is User Man u al is
t h en given .
O2 DBAccess User Man u al
9
1
Introduction
1.1 System Overview
Th e syst em ar ch it ect u r e of O2 is illu st r at ed in Figu r e 1.1.
External
Interfaces
Development Tools
Standard
Dev. Tools
O2 Dev. Tools
OQL
Java
O2 C
C++
C
O2ODBC
O2Corba
Database Engine
O2Engine
O2Store
O2DB
Access
O2Web
Fi gu r e 1 .1 : O2 Sy st em Ar ch i t ect u r e
Th e O 2 system can be viewed as con sist in g of t h r ee com pon en t s. Th e
Database Engine pr ovides all t h e feat u r es of a D at abase syst em an d an
object -or ien t ed syst em . Th is en gin e is accessed wit h Development Tools ,
su ch as var iou s pr ogr am m in g lan gu ages, O 2 developm en t t ools an d an y
st an dar d developm en t tool. Nu m er ou s External Interfaces ar e pr ovided.
All en com passin g, O 2 is a ver sat ile, por t able, dist r ibu t ed, h igh per for m an ce dyn am ic object -or ien ted dat abase system .
Database En gin e:
10
• O2 St or e
Th e dat abase m an agem en t syst em pr ovides low level
facilit ies, t h r ou gh O2 Stor e API, t o access an d m an age a
dat abase: disk volu m es, files, r ecor ds, in dices an d
t r an sact ion s.
• O2 En gin e
Th e object dat abase en gin e pr ovides dir ect con t r ol of
sch em as, classes, object s an d t r an sact ion s, t h r ou gh
O2 En gin e API. It pr ovides fu ll t ext in dexin g an d sear ch
capabilit ies wit h O 2 Sear ch an d spat ial in dexin g an d
r et r ieval capabilit ies wit h O 2 Spat ial. It in clu des a
Not ificat ion m an ager for in for m in g oth er clien t s
con n ect ed t o t h e sam e O 2 ser ver t h at an even t h as
occu r r ed, a Ver sion m an ager for h an dlin g m u lt iple
object ver sion s an d a Replicat ion API for syn ch r on izin g
m u lt iple copies of an O2 system .
O2 DBAccess User Man u al
System Overview
Pr ogr am m in g Lan gu ages:
O 2 object s m ay be cr eat ed an d m an aged u sin g t h e followin g
pr ogr am m in g lan gu ages, u tilizin g all t h e featu r es available wit h O2
(per sist en ce, collection m an agem en t , t r an sact ion m an agem en t , OQL
qu er ies, et c.)
• C
O2 fu n ct ion s can be in vok ed by C pr ogr am s.
• C++
OD MG com plian t C++ bin din g.
• J ava
OD MG com plian t J ava bin din g.
• O2 C
A power fu l an d elegan t object-or ien t ed fou r t h
gen er at ion lan gu age specialized for easy developm en t
of object dat abase applicat ion s.
• OQL
OD MG st an dar d, easy-t o-u se SQL-lik e object qu er y
lan gu age wit h special feat u r es for dealin g wit h com plex
O2 object s an d m eth ods.
O 2 Developm en t Tools:
• O2 Gr aph
Cr eat e, m odify an d edit an y t ype of object gr aph .
• O2 Look
Design an d develop gr aph ical u ser in ter faces, pr ovides
in t er active m an ipu lation of com plex an d m u ltim edia
object s.
• O2 Kit
Libr ar y of pr edefin ed classes an d m et h ods for fast er
developm en t of u ser applicat ion s.
• O2 Tools
Com plet e gr aph ical pr ogr am m in g en vir on m en t t o
design an d develop O 2 dat abase applicat ion s.
St an dar d Developm en t Tools:
All stan dar d pr ogr am m in g lan gu ages can be u sed wit h st an dar d
en vir on m en t s (e.g. Visu al C++, Su n Spar cwor k s).
Exter n al In t er faces:
• O2 Cor ba
Cr eat e an O2 / Or bix ser ver t o access an O2 dat abase
wit h CORBA.
• O2 DBAccess
Con n ect O2 applicat ion s to r elation al dat abases on
r em ot e h ost s an d in vok e SQL st at em en ts.
• O2 OD BC
Con n ect r em ot e ODBC clien t applicat ion s t o O2
dat abases.
• O2 Web
Cr eat e an O2 Wor ld Wide Web ser ver t o access an O 2
dat abase th r ou gh t h e in t er n et n etwor k .
O2 DBAccess User Man u al
11
1
Introduction
O2 Engine
O 2 En gin e h as all t h e featu r es of a dat abase en gin e pr ovidin g
t r an spar en t m an agem en t of dat a per sisten ce, data sh ar in g an d dat a
r eliability, as well as all t h e feat u r es of an object -or ien t ed syst em
in clu din g t h e m an ipu lation of com plex object s with iden tit y, classes,
t ypes, m et h ods, m u lt iple in h er it an ce, over r idin g an d late bin din g of
m et h ods.
CLIENT
CLIENT
CLIENT
SERVER
DATABASE
Fi gu r e 1 .2 : Cl i en t /ser ver a r ch i t ect u r e
12
O2 DBAccess User Man u al
System Overview : O2 Store
O2 Store
Th e O2 St or e ph ysical st or age m an agem en t syst em offer s you th e
followin g feat u r es:
• Tr an sact ion al m an agem en t of per sist en t st r u ct u r es.
• Clien t/ ser ver ar ch it ect u r e.
• Rollback s an d cr ash r ecover y.
O 2 St or e h as t h e clien t / ser ver ar ch it ectu r e sh own in Figu r e 1.2. Th e
ser ver pr ocess pr ovides per sist en ce, disk m an agem en t , con cu r r en cy
con t r ol, dat a r ecover y, an d dat abase secu r it y.
Th e featu r es offer ed by O 2 En gin e an d O 2 St or e ar e sh own in Figu r e 1.3 .
O2Store
Schema Manager
Global Transaction
Manager
Object Manager
Global Log
Manager
Local Transaction
Manager
Page Buffer
Page Buffer
O2Store
Client Process
DB
Log
Server Process
Fi gu r e 1 .3 : Gl oba l a r ch i t ect u r e sh ow i n g O2 St or e l a y er
O2 DBAccess User Man u al
13
1
Introduction
O2DB Access
O2 DBAccess is a set of C++ classes t h at en ables O2 applicat ion s t o
com m u n icate an d wor k wit h r elation al dat abases on r em ote h ost s.
Th ese classes allow you t o car r y ou t t h e followin g action s fr om you r
applicat ion s:
• Con n ect t o a ser ver an d set u p a session on a r em ot e dat abase.
• Ru n an y SQL st at em en t in t h e SQL syn t ax of t h at dat abase.
• Fet ch dat a as r equ ir ed fr om t h e dat abase to t h e u ser applicat ion in t o
O 2 object s.
• Mir r or t h e com m it an d r ollback facilit ies of som e dat abases.
• Close t h e dat abase session an d t er m in at e th e con n ect ion to t h e h ost .
You can also r et r ieve er r or m essage t ext cor r espon din g to dat abase er r or
codes.
O2 DBAccess is based on t h e Sequ eLi n k pr ot ocol as sh own in
Figu r e 1.4. Th is is a soft war e pack age t h at en ables a clien t applicat ion
t o access sim u lt an eou sly differ en t r elat ion al dat abases r esidin g on
differ en t ser ver s th at ar e con n ect ed to on e or m or e types of local
n et wor k .
Sequ eLin k u n ifor m ly m an ages t h e differ en t n et wor k pr otocols an d t h e
h et er ogen eit y bet ween platfor m s1 . Wit h O2 DBAccess you can lin k to an y
platfor m cu r r en tly su ppor t ed by Sequ eLin k .
1. For in for m ation abou t all possible n et wor k -h ost -dat abase com bin ation s, call O2 Lin e.
14
O2 DBAccess User Man u al
System Overview : O2DB Access
CLIENT
SERVER
O2DBAccess
Relational
DBMS
Interface module
database
Client
Kernel
Server
Kernel
Interface module
network protocol
Interface module
network protocol
Standard Network Protocol
SequeLink
Fi gu r e 1 .4 : O2 DBAccess a n d Sequ eLi n k
O2 DBAccess User Man u al
15
1
Introduction
1.2 Manual Overview
Th is m an u al is divided u p in t o t h e followin g ch apt er s:
• Chapter 1 - Introduction
A sh or t in t r odu ct ion t o t h e O2 syst em , O2 En gin e, O2 St or e, an d
O2 DBAccess.
• Chapter 2- Programming Guide
Th is ch apt er descr ibes h ow t o u se O 2 D BAccess. It cover s accessin g a
dat abase, pr epar in g a st at em en t , fet ch in g dat a, com m it an d r ollback ,
an d r u n n in g t h e st at em en t .
• Chapter 3 - Class Library
Th is ch apt er details th e var iou s classes of t h e O2 DBAccess libr ar y:
o2db_O2DBAccess, o2db_Connection, o2db_Session, an d
o2db_Statement.
• Chapter 4 - Appendices
Th is ch apt er in clu des an exam ple pr ogr am . It gives possible er r or codes
an d t h e con figu r at ion file.
16
O2 DBAccess User Man u al
22
Progra m mi ng
G uide
Th is ch apt er det ails h ow t o u se O 2 D BAccess.
It is divided in t o t h e followin g ch apt er s:
• Th e o2dbaccess Libr ar y
• Gu idelin es
• Accessin g a Database
• Pr epar in g a St at em en t
• Ru n n in g a St at em en t
• Com m it an d Rollback
• En din g a Session
O2 DBAccess User Man u al
17
2
Programming Guide
2.1 The o2dbaccess Library
O2 DBAccess is in fact a st an dar d C++ libr ar y called o2dbaccess th at
you can u se in an y of you r C++ applicat ion .
Classes
Th e o2dbaccess libr ar y, sh own in Figu r e 2.1, pr ovides classes th at
en able you t o com m u n icat e an d wor k wit h th e r em ot e dat abase.
o2db_Connection
o2db_O2DBAccess
o2db_Session
o2db_Statement
Fi gu r e 2 .1 : o2 d ba ccess l i br a r y
Th e libr ar y classes ar e as follows:
• o2db_O2DBAccess
An o2db_O2DBAccess object defin es t h e com m on r esou r ces of
O 2 DBAccess classes. It con tain s on e fu n ct ion , server_error, wh ich
you u se to obt ain th e RDBMS-det ect ed er r or codes.
• o2db_Connection
o2db_Connection is a su bclass of o2db_O2DBAccess. An
o2db_Connection object defin es an d m ain t ain s a con n ection t o a
r em ote h ost .
• o2db_Session
o2db_Session is a su bclass of o2db_O2DBAccess. An o2db_Session
object defin es an d m ain t ain s a con n ect ion t o a dat abase ser ver . It
m an ages t h e tr an sact ion s of t h e session .
• o2db_Statement
o2db_Statement is a su bclass of o2db_O2DBAccess. An
o2db_Statement object defin es an access con t ext t o a dat abase an d
con tain s in for m at ion t h at is r equ ir ed t o r u n an SQL st at em en t .
18
O2 DBAccess User Man u al
Guidelines
2.2 Guidelines
To sen d an SQL st at em en t for pr ocessin g on r em ot e dat abase, you n eed
t o car r y ou t t h e followin g st eps:
1.
Set u p a con n ection t o th e h ost server m ach in e.
2.
Set u p a session on t h e dat abase by loggin g on .
3.
Open a st at em en t on t h e r em ot e database ser ver .
4.
Pr epar e t h e st at em en t t o be r u n . Th is m ean s pu tt in g in for m at ion
abou t t h e SQL qu er y you wan t to execu te in t h e statem en t an d t h e
C++ object s t h at will st or e t h e SQL r esu lt .
5.
Ru n t h e st at em en t .
6.
If in for m at ion h as been in ser t ed, u pdat ed or delet ed, m ak e t h e
ch an ges per m an en t , or u n do t h em .
7.
If you do n ot wan t t o r er u n t h e st at em en t , close it .
8.
Close t h e session by loggin g off th e dat abase.
9.
En d t h e con n ect ion by discon n ect in g fr om t h e h ost.
Each step cor r espon ds to a par t icu lar fu n ct ion . Table 2.1 sh ows t h ese
fu n ct ion s an d it s cor r espon din g st ep.
Th e class of t h e fu n ction is given befor e t h e fu n ct ion n am e.
Th ese fu n ction s con st it u t e t h e basic set of fu n ct ion s t h at you n eed t o
u se.
Table 2.1
Function set
Funct i ons
St ep
o2db_Connect::connection
Set u p a con n ect ion
o2db_Connection::logon
Set u p a session
o2db_Session::open
Open an access con t ext
O2 DBAccess User Man u al
19
2
Table 2.1
Programming Guide
Function set
Funct i ons
St ep
o2db_Statement::associate
o2db_Statement::add_cursor_variable
Pr epar e a st at em en t
o2db_Statement::add_input_variable
o2db_Statement::>>
o2db_Statement::<<
o2db_Statement::execute
Ru n a st at em en t
o2db_Session::commit
Mak e t h e ch an ges per m an en t
o2db_Session::rollback
Un do a tr an sact ion
o2db_Session::close
Close t h e con t ext
o2db_Connection::logoff
En d t h e session
o2db_Connection::disconnect
En d t h e con n ect ion
All t h ese var iou s st eps ar e detailed below.
For a fu ll descr iption of each specific fu n ct ion r efer t o Ch apt er 3.
20
O2 DBAccess User Man u al
Accessing a Database
2.3 Accessing a Database
You m u st fir st con n ect to t h e r em ot e h ost an d log on t o t h e dat abase.
Host connection and database log in
Wit h O 2 D BAccess, you do th is by cr eat in g a o2db_Connection object .
You m u st call t h e connect fu n ction on t h is object t o con n ect t o t h e
r em ot e h ost . You t h en call t h e logon fu n ction on t h is object t o log on to
t h e database an d begin a session . Th e logon fu n ct ion r et u r n s a poin ter
t o an o2db_Session object .
On ce con n ect ed an d logged on , you can r u n as m an y SQL stat em en t s as
you wan t .
For exam ple:
#include "o2db_o2db_access.h"
int create_session()
{
int code, status;
char *msg;
o2db_Connection connection;
o2db_Session *session;
status = connection.connect("oracle", "user", "pwd");
session = connection.logon("dbuser", "dbpasswd", &status);
if ( status == o2dbE_SERVER) {
msg = connection.server_error(&code);
cerr << "Error: " << code << "
msg: " << msg << endl;
} else if (status != O2DB_OK)
cerr << "An error occurs: " << status << endl;
...
}
Wh en you r t r an sact ion s wit h t h e dat abase ar e fin ish ed, you u se t h e
logoff an d disconnect fu n ct ion s t o r espectively en d t h e session an d
r em ot e h ost con n ect ion .
Refer to Sect ion 3.2 for a fu ll descr ipt ion of all th ese o2db_Connection
fu n ct ion s.
O2 DBAccess User Man u al
21
2
Programming Guide
Open Statement
On ce con n ect ed t o t h e r em ot e h ost an d logged on to t h e dat abase, you
m u st n ow open a st at em en t in wh ich you can r u n an SQL stat em en t .
You do t h is u sin g t h e open fu n ct ion fr om you r o2db_Session object
(r esu lt of t h e logon fu n ction ). Th e st at em en t con t ain s t h e st at em en t
itself an d an y addit ion al in for m at ion t h at m ay be n eeded t o r u n t h e
st at em en t. Th is fu n ction r et u r n s an object of class o2db_Statement.
A o2db_Statement object r em ain s open u n t il you explicit ly close it
u sin g t h e close fu n ct ion (of you r o2db_Session object ), or u n t il you
en d t h e dat abase session u sin g t h e logoff fu n ction . H owever , you do
n ot n eed t o close a st at em en t if you wan t to u se it for a differ en t
st at em en t. You sim ply r e-u se it .
For exam ple:
#include "o2db_o2db_access.h"
int open()
{
int code, status;
char *msg;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
status = connection.connect("oracle", "user", "pwd");
session = connection.logon( "dbuser", "dbpasswd",
&status);
statement = session->open(&status);
if (status == o2dbE_SERVER) {
msg = connection.server_error(&code);
cerr << "Error: " << code << "
msg: " << msg << endl;
} else if (status != O2DB_OK)
cerr << "An error occurs: " << status << endl;
...
}
o2db_Statement an d h ow t o m an age st at em en t s ar e fu lly explain ed in
Sect ion 2.4 below; Sect ion 3.3 gives a descr ipt ion of t h e open fu n ction .
Note
Th e statem en t is local t o t h e logon session in wh ich it is u sed an d t h e
n u m ber of st at em en t s you can open at t h e sam e t im e is r est r ict ed t o
100. However , you r ar ely n eed m or e t h an 15 an d t h e ext er n al database
or you r self can im pose a lower lim it.
22
O2 DBAccess User Man u al
Preparing a Statement : Associating an SQL
2.4 Preparing a Statement
Th e n ext st ep aft er accessin g t h e database is to pr epar e t h e SQL
st at em en t s you wan t t o r u n .
Associating an SQL statement
You m u st fir st ly defin e t h e SQL st at em en t you wan t to r u n u sin g t h e
associate fu n ct ion of t h e o2db_Statement class.
Th e associate fu n ction also sen ds th e statem en t t o t h e RDBM S
dat abase for validat ion . It is at t h is poin t t h at an y SQL syn t ax er r or s ar e
t r apped. If an y ar e fou n d, you can get t h e database er r or codes by
callin g t h e server_error fu n ct ion on t h e o2db_Statement object (see
Sect ion 3.1 for details of th is fu n ct ion an d Sect ion 4.3 for a list of
possible er r or s).
If t h e SQL st at em en t does n ot n eed a r esu lt object (i.e. it is n ot a select
st at em en t ) an d it con t ain s n o par am eter m ar k er s, O 2 D BAccess n eeds
n o m or e in for m at ion .
In t h is case, you can r u n you r st at em en t im m ediately u sin g t h e
o2db_sql_execute fu n ct ion . See Section 2.5 for m or e det ails.
In t h e oth er cases, i.e. if th e st at em en t is a sel ect st at em en t an d/ or if it
con t ain s par am et er m ar k er s, you m u st pr ovide O 2 DBAccess wit h m or e
in for m ation . Th is is explain ed in t h e r em ain der of t h is section .
Managing statements
Wh en you wan t t o r u n a select st at em en t or a st at em en t t h at con t ain s
par am eter m ar k er s or bot h , you n eed to pr ovide m or e in for m at ion
befor e t h e statem en t is r u n .
Th e in for m at ion n eeded in clu des t h e r esu lt object an d it s pr oject ion list ,
wh ich you st or e in t h e st at em en t u sin g t h e add_cursor_variable
fu n ct ion or t h e ’>>’ oper at or of t h e class o2db_Statement.
You also n eed t o st or e t h e in pu t par am et er s of t h e st at em en t u sin g th e
add_input_variable fu n ct ion or t h e ’<<’ oper at or of t h e class
o2db_Statement.
O2 DBAccess User Man u al
23
2
Programming Guide
You can m an age you r st at em en t s in t h e followin g th r ee differ en t ways:
1.
Use on e st at em en t for on e specific SQL statem en t an d close it as soon
as it h as been r u n .
2.
Open a st at em en t , u se it for on e SQL st at em en t , an d t h en r eu se it for
an ot h er SQL statem en t by sim ply associatin g it t o a n ew SQL
st at em en t.
You can to do t h is as m an y t im es as you wan t u n t il you wan t t o close
t h e st at em en t .
3.
Open a st at em en t for a par t icu lar SQL st at em en t t h at you wan t t o r u n
sever al t im es. You k eep t h e st at em en t open an d associat ed t o t h e
sam e SQL st at em en t u n t il you n o lon ger wish t o r er u n t h e st at em en t .
Wh ile t h e st at em en t is open , you can r er u n it wit h n ew valu es for an y
of it s par am et er s u sin g th e o2db_sql_execute fu n ct ion . Th e n ew
valu es of t h e par am et er s ar e given u sin g t h e add_input_variable
fu n ct ion (or t h e ’<<’ oper at or ).
Note
Re-associat in g a statem en t r eset s t h e par am et er list of th e st at em en t as
well as th e r esu lt in for m at ion .
Storing a query result set
Stor in g t h e r esu lt set of a qu er y fu n ct ion in volves t h e followin g st eps:
1.
You m u st fir stly defin e th e C++ classes wh er e you wan t t h e r et r ieved
dat a t o be st or ed.
2.
You m u st t h en give t h e r elevan t t r an sfer in for m ation . Th is m ean s
associat in g a par t of th e r esu lt set (i.e. t h e n am e of a colu m n ) t o a par t
of t h e C++ st or age class (i.e. t h e n am e of a C++ at tr ibu t e).
You do t h is by defin in g dat a bu ffer s u sin g t h e add_cursor_variable
fu n ct ion or th e ’>>’ oper at or of th e class o2db_Statement.
You can t h en r u n th e statem en t u sin g t h e o2db_sql_execute fu n ct ion .
See t h e exam ple in t h e n ext sect ion .
24
O2 DBAccess User Man u al
Running a Statement : Storing a query result set
2.5 Running a Statement
If t h e SQL st at em en t does n ot n eed a r esu lt object (i.e. it is n ot a select
st at em en t ), you can r u n it dir ect ly u sin g t h e o2db_sql_execute
fu n ct ion wit h on ly you r st atem en t as a par am et er .
If t h e st at em en t is a select st at em en t, you m u st pr ovide t h e r elevan t
t r an sfer in for m ation as det ailed in Section 2.4, an d t h en call t h e
o2db_sql_execute fu n ct ion wit h t h e statem en t an d t h e C++ object th at
will st or e t h e r esu lt of th e qu er y as par am eter s.
For exam ple, su ppose you set u p a sin gle con n ect ion , a sin gle session in
wh ich you wan t t o r u n t h r ee SQL st at em en ts: a CREATE st at em en t , an
INSERT st at em en t wit h par am et er s t h at you wan t t o r u n t wice, an d a
SELECT st at em en t ; you call t h e followin g sequ en ce of fu n ct ion s t o
pr ocess each step.
int test()
{
d_Set<d_Ref<Person> > the_persons("ThePersons");
d_Iterator<d_Ref<Person> > iter;
d_Ref<Person> person;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
int status, code;
status = connection.connect("oracle", "user", "passwd");
if (status != O2DB_OK)
return status;
session = connection.logon("oracleuser",
"oracleuserpasswd", &status);
if (status != O2DB_OK)
return status;
statement = session->open(&status);
if (status != O2DB_OK) return status;
// (1) A statement without parameters:
// ----------------------------------status = statement->associate("CREATE TABLE person \
(id_person SMALLINT null, \
name VARCHAR(16) null, \
firstname VARCHAR(16) null)");
if (status != O2DB_OK) return status;
O2 DBAccess User Man u al
25
2
Programming Guide
status = o2db_sql_execute(statement);
if (status != O2DB_OK)
return status;
// (2) A statement with 3 input parameters:
//----------------------------------------status = statement->associate( "INSERT INTO \
person(id_person, name,
firstname) \
VALUES (?, ?, ?)");
// First execution
*statement << 1 << "Doe" << "John";
status = o2db_sql_execute(statement);
if (status != O2DB_OK)
return status;
// Second execution with different parameters
*statement << 2 << "Smith" << "Paul";
status = o2db_sql_execute(statement);
if (status != O2DB_OK)
return status;
// (3) A statement returning a result
//-----------------------------------status = statement->associate("SELECT name, firstname \
FROM person");
// The class Person has at least 2 attributes:
// pname and pfirstname
*statement >> "pname" >> "pfirstname";
status = o2db_sql_execute(statement, the_persons);
if (status != O2DB_OK)
return status;
// Now the C++ set contains the selected information
iter = the_persons.create_iterator();
while (iter.next(person)) {
cout << "\t*** [ "
<< person -> pname << " "
<< person -> pfirstname << " ]" << endl;
}
26
O2 DBAccess User Man u al
Running a Statement : Storing a query result set
// Ending the session and disconnecting
status = session->close(statement);
if (status != O2DB_OK)
return status;
status = connection.logoff(session);
if (status != O2DB_OK)
return status;
connection.disconnect();
}
O2 DBAccess User Man u al
27
2
Programming Guide
2.6 Commit and Rollback
Th e commit an d rollback fu n ct ion s m ir r or a feat u r e of som e dat abases
in allowin g you to syst em at ically an d explicit ly m ak e per m an en t or
u n r oll a ser ies of r elat ed dat abase act ion s at st r at egic poin t s in a
session .
2.7 Ending a Session
Wh en all you r t r an sact ion s wit h t h e dat abase h ave been car r ied ou t , t h e
fu n ct ion s close, logoff an d disconnect close t h e st at em en t an d en d
t h e session an d con n ect ion r espect ively..
#include "o2db_o2db_access.h"
int end_session()
{
int status;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
...
statement = session->open(&status);
...
status = session->close(statement);
connection.logoff(session);
connection.disconnect();
return status;
}
28
O2 DBAccess User Man u al
33
C lass L ibrar y
CLASS SET AND THEIR MEM BER
FUNCTIONS
O2 DBAccess is a set of C++ classes th at en ables O 2 applicat ion s t o
com m u n icat e an d wor k wit h r elat ion al dat abases on r em ot e h osts.
Th is ch apt er det ails all t h ese classes an d t h eir r espect ive m em ber
fu n ct ion s.
It is divided in t o t h e followin g sect ion s:
• o2db_O2DBAccess - Th is is t h e su per class of all t h e ot h er classes of
t h e pack age.
• o2db_Con n ect ion - Th is class m an ages t h e con n ect ion t o a r em ot e
h ost.
• o2db_Session - Th is class m an ages t h e con n ect ion t o a database
ser ver .
• o2db_St at em en t - Th is class m an ages all t h e r esou r ces belon gin g t o
t o an SQL st at em en t .
O2 DBAccess User Man u al
29
3
Class Library
3.1 o2db_O2DBAccess
o2db_O2DBAccess is t h e su per class of t h e classes o2db_Connection,
o2db_Session, an d o2db_Statement. It m an ages com m on r esou r ces
an d own s t h e followin g pu blic m em ber fu n ction :
• server_error
30
O2 DBAccess User Man u al
o2db_O2DBAccess
server_error
Summary
Get s th e last er r or code fr om t h e dat abase ser ver .
Syntax
char* server_error(int *code);
Arguments
code
Description
Th is m em ber fu n ct ion is u sed by an O 2 D BAccess pr ogr am m er t o obt ain
ext r a in for m at ion abou t a dat abase ser ver r elat ed er r or . It can be
applied to an in stan ce of th e o2db_O2DBAccess class or on e of it s
su bclasses aft er an er r or of t ype o2dbE_SERVER occu r ed. Th e fu n ction
pu t s in t h e in t eger poin t ed by code t h e database ser ver er r or code
r aised by t h e failu r e. Th e str in g r etu r n ed by t h is fu n ction con t ain s a
t ext u al descr ipt ion of t h e er r or , wh en applicable.
A poin ter on an in t eger t h at in r et u r n will con t ain t h e
er r or code.
As t h is str in g is st or ed in a st at ic ar ea, it is on ly available u n t il t h e n ext
call t o server_error occu r s. Th is st r in g m u st n ot be fr eed by t h e u ser .
Returns
A st r in g wit h t h e t ext u al descr ipt ion of t h e er r or .
Example
#include "o2db_o2db_access.h"
int get_emp(o2db_Session *session)
{
int code, status;
char *msg;
o2db_Statement statement = session->open(&status);
status = statement->associate("SELECT * from emp");
if (status == o2dbE_SERVER) {
msg = statement->server_error(&code);
cerr << "error: " << code << " msg: " << msg << endl;
}
...
}
O2 DBAccess User Man u al
31
3
Class Library
3.2 o2db_Connection
An object of t h is class defin es an d m ain t ain s t h e con n ect ion t o a r em ot e
h ost. Th e in for m ation n eeded t o set u p a lin k bet ween t h e O 2
applicat ion an d t h e h ost syst em is fou n d in a con figu r at ion file. It is
m ade u p of a set of n et wor k an d h ost specific par am eter s. Refer t o
Sect ion 4.2 for a fu ll descr ipt ion of t h e con figu r at ion file.
Th is sect ion descr ibes t h e followin g m em ber fu n ct ion s of t h e
o2db_Connection class:
• connect
• disconnect
• logoff
• logon
32
O2 DBAccess User Man u al
o2db_Connection : connect
connect
Summary
Con n ect s t o a r em ote h ost .
Syntax
int connect(char *c_name,char *username,char *password);
Arguments
c_name
Th is is a st r in g con tain in g a valid en t r y in t h e
O2DBAccess con figu r at ion file (see Section 4.2).
username
Th is is a st r in g con tain in g th e u ser n am e on t h e r em ot e
h ost .
password
Th is is a st r in g con tain in g t h e passwor d of t h e u ser on
th e r em ot e h ost.
Description
Th is fu n ct ion set s u p a lin k bet ween th e wor k st at ion an d a r em ote
Sequ eL i n k ser ver .
Returns
O2DB_OK if th e con n ect ion su cceeded, or on e of t h e followin g er r or codes
if t h e con n ection failed:
• o2dbE_STILL_CONNECT
• o2dbE_RC_NOTFOUND
• o2dbE_FILE_NOTFOUND
• o2dbE_INVALID_RC
• o2dbE_UNKN_NETWORK
• o2dbE_OPEN_FILE
• o2dbE_SERVER
Example
#include "o2db_o2db_access.h"
int connect()
{
int code, status;
char *msg;
o2db_Connection connection;
status = connection.connect("oracle", "user", "pwd");
if ( status != O2DB_OK) {
cerr << "Connection error: " << status << endl;
}
...
}
O2 DBAccess User Man u al
33
3
Class Library
disconnect
Summary
Discon n ect s fr om a r em ote h ost .
Syntax
void disconnect(void);
Arguments
Non e.
Description
Th e disconnect m em ber fu n ct ion discon n ect s th e lin k bet ween t h e
applicat ion an d th e r em ot e Sequ eL i n k ser ver . All th e cu r r en t session s
an d st at em en t s ar e r eleased by th is fu n ct ion .
Returns
Not h in g
Example
#include "o2db_o2db_access.h"
int dbaccess()
{
int code, status;
char *msg;
o2db_Connection connection;
status = connection.connect("oracle", "user", "pwd");
...
connection.disconnect();
return status;
}
34
O2 DBAccess User Man u al
o2db_Connection : logoff
logoff
Summary
En ds a database ser ver session .
Syntax
int logoff(o2db_Session *session);
Arguments
session
Description
Th e logoff m em ber fu n ct ion en ds an exist in g session on a dat abase
ser ver . All t h e st at em en t s cr eat ed du r in g t h e session ar e destr oyed an d
t h e dat abase ser ver r esou r ces ar e r eleased. Th e poin t er s t o
o2db_Statement object s ar e n o lon ger valid aft er t h is call.
Returns
A st at u s code wh ose valu e is O2DB_OK if t h e oper at ion was su ccessfu ll,
or on e of th e followin g er r or codes if t h e oper ation failed:
A poin ter on t h e session t o close.
• o2dbE_NOT_CONNECT
• o2dbE_NOT_MEMBER
• o2dbE_SQLNK
• o2dbE_SERVER
Example
#include "o2db_o2db_access.h"
int dbaccess()
{
int code, status;
char *msg;
o2db_Connection connection;
o2db_Session *session;
status = connection.connect("oracle", "user", "pwd");
session = connection.logon( "dbuser", "dbpasswd",
&status);
...
status = connection.logoff(session);
if (status == o2dbE_SERVER) {
msg = connection.server_error(&code);
cerr << "error: " << code << "
msg: " << msg << endl;
} else if (status != O2DB_OK)
cerr << "An error occurs: " << status << endl;
...
connection.disconnect();
return status;
}
O2 DBAccess User Man u al
35
3
Class Library
logon
Summary
Logs on t o a dat abase ser ver .
Syntax
o2db_Session *logon( char *logon1,char *logon2,
int *retcode);
Arguments
logon1
A par am et er n eeded t o log on t o t h e dat abase ser ver .
logon2
A par am et er n eeded t o log on t o t h e dat abase ser ver .
retcode
A poin t er on an in t eger t h at will con tain an er r or code on
failu r e.
Description
Th e logon m em ber st ar t s a n ew session on t h e dat abase ser ver . Th e
logon1 an d logon2 par am et er s ar e database depen den t bu t u su ally
con t ain s a database u ser an d it s passwor d. For m or e in for m ation , r efer
t o t h e docu m en t at ion Using SequelLink w ith y our Database and Server .
Th e par am et er len gth m u st be less t h an 256 ch ar acter s.
retcode is a poin t er t o an in teger t h at will be set t o an er r or code in
case of failu r e. Th e possible er r or codes r et u r n ed in retcode ar e as
follows:
• o2dbE_NOT_CONNECT
• o2dbE_TOOLONG
• o2dbE_SQLNK
• o2dbE_SERVER
Returns
36
A poin ter to an object of t h e class o2db_Session, or NULL if th e login
failed.
O2 DBAccess User Man u al
o2db_Connection : logon
Example
#include "o2db_o2db_access.h"
int create_session()
{
int code, status;
char *msg;
o2db_Connection connection;
o2db_Session *session;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon("dbuser", "dbpasswd", &status);
if ( status == o2dbE_SERVER) {
msg = connection.server_error(&code);
cerr << "Error: " << code << "
msg: " << msg << endl;
} else if (status != O2DB_OK)
cerr << "An error occurs: " << status << endl;
...
connection.disconnect();
return status;
}
O2 DBAccess User Man u al
37
3
Class Library
3.3 o2db_Session
An object of t h e o2db_Session class is cr eat ed by t h e logon fu n ct ion of
t h e o2db_Connection class an d m an ages t h e con n ect ion t o a dat abase
ser ver .
Th is class h as t h e followin g m em ber fu n ct ion s:
• close
• commit
• open
• rollback
38
O2 DBAccess User Man u al
o2db_Session : close
close
Summary
Closes a st at em en t .
Syntax
int close(o2db_Statement *statement);
Arguments
statement
Description
Th is fu n ct ion closes an alr eady open ed st at em en t an d r eleases all
r esou r ces associat ed with t h is statem en t .
Returns
A st at u s code wh ose valu e is O2DB_OK if t h e oper at ion was su ccessfu l, or
on e of t h e followin g er r or codes if t h e oper ation failed:
A poin t er on a st at em en t r et u r n ed by t h e m em ber
fu n ction open.
• o2dbE_NOT_LOGON
• o2dbE_NOT_MEMBER
• o2dbE_SQLNK
• o2dbE_SERVER
Example
#include "o2db_o2db_access.h"
int dbaccess()
{
int code, status;
char *msg;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon( "dbuser", "dbpasswd",
&status);
...
statement = session->open(&status);
...
status = session->close(statement);
...
connection.disconnect();
return status;
}
O2 DBAccess User Man u al
39
3
Class Library
commit
Summary
Per for m s a com m it on t h e dat abase ser ver .
Syntax
int commit(void);
Arguments
Non e
Description
Th is fu n ct ion per for m s a com m it on t h e database ser ver , th u s validat in g
wh at h as been don e in th e cu r r en t session .
Returns
A st at u s code wh ose valu e is O2DB_OK if t h e oper ation was su ccessfu l, or
on e of th e followin g er r or codes if t h e oper ation failed:
• o2dbE_NOT_LOGON
• o2dbE_SQLNK
• o2dbE_SERVER
Example
#include "o2db_o2db_access.h"
int dbaccess()
{
int code, status;
char *msg;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon( "dbuser", "dbpasswd",
&status);
...
statement = session->open(&status);
...
status = session->commit();
...
status = session->close(statement);
...
connection.disconnect();
return status
}
40
O2 DBAccess User Man u al
o2db_Session : open
open
Summary
Cr eat es a n ew st at em en t .
Syntax
o2db_Statement *open(int *retcode);
Arguments
retcode
Description
Th is fu n ct ion open s a n ew st at em en t t h at will allow a pr ogr am m er t o
execu te SQL st at em en t s. A poin t er on t h e cr eat ed st at em en t is
r et u r n ed.
A poin ter on an in t eger t h at will con t ain an er r or code on
failu r e.
retcode is a poin t er on an in t eger t h at will be set t o an er r or code in
case of failu r e. Th e possible er r or codes r et u r n ed in retcode ar e as
follows:
• o2dbE_NOT_LOGON
• o2dbE_NO_MORE_STATEMENTS
• o2dbE_SQLNK
• o2dbE_SERVER
Returns
A poin ter on an object of t h e class o2db_Statement or NULL if t h e
oper at ion failed.
O2 DBAccess User Man u al
41
3
Class Library
Example
#include "o2db_o2db_access.h"
int dbaccess()
{
int code, status;
char *msg;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon( "dbuser", "dbpasswd",
&status);
...
statement = session->open(&status);
...
status = session->commit();
...
status = session->close(statement);
...
connection.disconnect();
return status;
}
42
O2 DBAccess User Man u al
o2db_Session : rollback
rollback
Summary
Per for m s a r ollback on t h e dat abase ser ver .
Syntax
int rollback(void);
Arguments
Non e.
Description
Th is fu n ct ion per for m s a r ollback on t h e dat abase ser ver , th u s
in validat in g wh at h as been don e in t h e cu r r en t session .
Returns
A st at u s code wh ose valu e is O2DB_OK if t h e oper at ion was su ccessfu l, or
on e of t h e followin g er r or codes if t h e oper ation failed:
• o2dbE_NOT_LOGON
• o2dbE_SQLNK
• o2dbE_SERVER
Example
#include "o2db_o2db_access.h"
int dbaccess()
{
int code, status;
char *msg;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon("dbuser", "dbpasswd", &status);
...
statement = session->open(&status);
...
status = session->rollback();
...
status = session->close(statement);
...
connection.disconnect();
return status;
}
O2 DBAccess User Man u al
43
3
Class Library
3.4 o2db_Statement
An object of t h e o2db_Statement class is cr eat ed by t h e open fu n ction
of t h e o2db_Session class an d m an ages all t h e r esou r ces r elat ed t o
SQL st at em en t s.
Th is class h as th e followin g m em ber fu n ct ion s:
• add_cursor_variable
• add_input_variable
• associate
• operator >>
• operator <<
An d t h e followin g fu n ct ion :
• o2db_sql_execute
44
O2 DBAccess User Man u al
o2db_Statement : add_cursor_variable
add_cursor_variable
Summary
Specifies a C++ at t r ibu t e n am e t o stor e an SQL r esu lt set colu m n .
Syntax
int add_cursor_variable(char *s);
Arguments
s
Description
Wh en a select st at em en t is per for m ed, t h e r esu lt set h as to be st or ed in
a C++ object or in a collection of C++ object s. Th is fu n ct ion m u st be
called on ce for each colu m n of t h e r esu lt set r etu r n ed by t h e SQL
statem en t , in or der t o specify in wh ich at t r ibu t e of a C++ object t h e
valu es of a colu m n will be pu t.
A st r in g r epr esen t in g a C++ at t r ibu te n am e.
Th e calls t o t h is fu n ct ion m u st be don e in t h e or der th e colu m n s of t h e
r esu lt set occu r in t h e SQL st at em en t .
Returns
O2DB_OK.
Example
#include "o2db_o2db_access.h"
int get_persons()
{
int code, status;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
d_Set<d_Ref<Person> > persons;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon("dbuser", "dbpasswd", &status);
...
statement = session->open(&status);
...
status = statement->associate("SELECT name,age FROM emp");
// asuming class Person {
//
char *name_att;
//
int age_att;
//
}
statement->add_cursor_variable("name_att");
statement->add_cursor_variable("age_att");
...
status = session->close(statement);
...
connection.disconnect();
return status;
}
O2 DBAccess User Man u al
45
3
Class Library
add_input_variable
Summary
Evalu ates an in pu t var iable of an SQL st at em en t .
Syntax
int
int
int
int
int
int
int
int
int
int
int
int
Arguments
xx
Description
Th is fu n ct ion is u sed by a pr ogr am m er wh o defin ed an SQL st at em en t
con t ain in g in pu t var iables. Th ese var iables ar e wr it t en u sin g '?' in t h e
SQL statem en t . It is n ecessar y to give a valu e for t h ese var iables befor e
r u n n in g t h e st at em en t .
add_input_variable(const char *s);
add_input_variable(char c);
add_input_variable(unsigned char uc);
add_input_variable(short s);
add_input_variable(unsigned short us);
add_input_variable(int i);
add_input_variable(unsigned int ui);
add_input_variable(long l);
add_input_variable(unsigned long ul);
add_input_variable(float f);
add_input_variable(double d);
add_input_variable(const d_Bits &s);
A C++ valu e t o assign to t h e in pu t var iable. xx can be an y
k in d of C++ t ype, accor din g t o t h e t ype expect ed by t h e
dat abase ser ver .
Th is fu n ct ion associat es a valu e of an y t ype wit h an in pu t var iable. Th e
t ype u sed m u st be con sist en t wit h t h e expect ed t ype in t h e dat abase
ser ver . Th is fu n ct ion m u st be called on ce for each in pu t var iable defin ed
in t h e st at em en t , in th e or der of th e ’?’ m ar k er s appear in g in t h e SQL
st at em en t .
Returns
A st at u s code wh ose valu e is O2DB_OK if t h e oper ation was su ccessfu l, or
on e of th e followin g er r or codes if t h e oper ation failed:
• o2dbE_NOT_OPEN
• o2dbE_NOSTMT
• o2dbE_INTERNAL
• o2dbE_NOT_SUPPORTED
• o2dbE_NILREF
• o2dbE_RANGE
• o2dbE_MISMATCH
• o2dbE_SQLNK
• o2dbE_SERVER
46
O2 DBAccess User Man u al
o2db_Statement : add_input_variable
Example
#include "o2db_o2db_access.h"
int get_persons()
{
int code, status;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
d_Set<d_Ref<Person> > persons;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon("dbuser", "dbpasswd", &status);
...
statement = session->open(&status);
...
status = statement->associate("SELECT name,age FROM emp
WHERE age<?");
...
statement->add_cursor_variable("name_att");
statement->add_cursor_variable("age_att");
statement->add_input_variable(20);
...
status = session->close(statement);
connection.disconnect();
return status;
}
O2 DBAccess User Man u al
47
3
Class Library
associate
Summary
Defin es an SQL st at em en t .
Syntax
int associate(char *stmt);
Arguments
stmt
Description
Th is fu n ct ion is u sed t o defin e an SQL st at em en t . It can be an y valid
SQL sen t en ce in wh ich in pu t var iables ar e r eplaced by qu est ion m ar k s
('?').
Th e t ext of t h e SQL st at em en t t h at will be execu t ed.
Th e act u al valu es for th e in pu t var iables ar e given u sin g t h e fu n ct ion
add_input_variable or t h e operator <<. Callin g associate on a
st at em en t in validat es all pr eviou s var iable defin it ion s for t h is st at em en t .
Returns
A st at u s code wh ose valu e is O2DB_OK if t h e oper ation was su ccessfu l, or
on e of th e followin g er r or codes if t h e oper ation failed:
• o2dbE_NOT_OPEN
• o2dbE_NOSTMT
• o2dbE_TOOLONG
• o2dbE_SQLNK
• o2dbE_SERVER
48
O2 DBAccess User Man u al
o2db_Statement : associate
Example
#include "o2db_o2db_access.h"
int get_persons()
{
int code, status;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
d_Set<d_Ref<Person> > persons;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon( "dbuser", "dbpasswd",
&status);
...
statement = session->open(&status);
...
status = statement->associate("SELECT name,age FROM emp
WHERE age<?");
...
status = session->close(statement);
...
connection.disconnect();
return status;
}
O2 DBAccess User Man u al
49
3
Class Library
operator >>
Summary
Adds a cu r sor var iable.
Syntax
o2db_Statement & operator >>( o2db_Statement &q ,
const char *s);
Arguments
q
A r efer en ce t o an object of t h e class o2db_Statement
t h at m an ages t h e SQL st at em en t for wh ich t h e var iable
is defin ed.
s
A st r in g r epr esen tin g a C++ at t r ibu te n am e.
Description
Th is oper at or act s in exact ly t h e sam e way as t h e m em ber fu n ct ion
add_cursor_variable. It is a m or e dir ect in t er face t o it .
Returns
A r efer en ce t o t h e st at em en t.
Example
int get_persons()
{
int code, status;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
d_Set<d_Ref<Person> > persons;
d_Iterator<d_Ref<Person> > iter;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon("dbuser", "dbpasswd", &status);
...
statement = session->open(&status);
...
status = statement->associate("SELECT name,age FROM emp
WHERE age<?");
*statement >> "name_att" >> "age_att";
statement->add_input_variable(20);
status = o2db_sql_execute(*statement, persons);
...
status = session->close(statement);
connection.disconnect();
iter = persons.create_iterator();
while (iter.next(p)) {
cout << "Name : " << p.name_att << endl;
cout << "Age : " << p.age_att << endl;
cout << endl;
}
return status;
}
50
O2 DBAccess User Man u al
o2db_Statement : operator <<
operator <<
Summary
Adds an in pu t var iable.
Syntax
o2db_Statement &operator << ( o2db_Statement &q,
const char *s);
o2db_Statement &operator << ( o2db_Statement &q, char c);
o2db_Statement &operator << ( o2db_Statement &q,
unsigned char uc);
o2db_Statement &operator << ( o2db_Statement &q, short s);
o2db_Statement &operator << ( o2db_Statement &q,
unsigned short us);
o2db_Statement &operator << ( o2db_Statement &q, int i);
o2db_Statement &operator << ( o2db_Statement &q,
unsigned int ui);
o2db_Statement &operator << ( o2db_Statement &q, long l);
o2db_Statement &operator << ( o2db_Statement &q,
unsigned long ul);
o2db_Statement &operator << ( o2db_Statement &q,
float f);
o2db_Statement &operator << ( o2db_Statement &q,
double d);
o2db_Statement &operator << ( o2db_Statement &q,
const d_Bits &s);
Arguments
q
A r efer en ce to an object of t h e class o2db_Statement
th at m an ages t h e SQL st at em en t for wh ich th e var iable
is defin ed.
xx
A C++ valu e t o associat e t o t h e in pu t var iable. xx can be
an y k in d of C++ t ype, accor din g t o t h e t ype expect ed by
th e dat abase ser ver .
Description
Th is oper at or acts in exact ly th e sam e way as t h e m em ber fu n ction
add_input_variable. It is a m or e dir ect in t er face t o it
Returns
A r efer en ce to t h e st at em en t .
O2 DBAccess User Man u al
51
3
Class Library
Example
int get_persons()
{
int code, status;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
d_Set<d_Ref<Person> > persons;
d_Iterator<d_Ref<Person> > iter;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon("dbuser", "dbpasswd", &status);
...
statement = session->open(&status);
...
statement->associate( "SELECT name,age FROM emp
WHERE age<?");
*statement >> "name_att" >> "age_att";
*statement << 20;
status = o2db_sql_execute(*statement, persons);
...
status = session->close(statement);
...
connection.disconnect();
iter = persons.create_iterator();
while (iter.next(p)) {
cout << "Name : " << p.name_att << endl;
cout << "Age : " << p.age_att << endl;
cout << endl;
}
return status;
52
O2 DBAccess User Man u al
o2db_Statement : o2db_sql_execute
o2db_sql_execute
Summary
Execu t es an SQL st at em en t .
Syntax
int o2db_sql_execute(o2db_Statement & q);
int o2db_sql_execute( o2db_Statement & q,
o2_col_root & coll);
int o2db_sql_execute(o2db_Statement & q, d_Ref<T> & o);
Arguments
q
A r efer en ce t o an object of t h e class o2db_Statement t h at
m an ages t h e SQL st at em en t t o be execu t ed.
coll
A r efer en ce to an y O 2 collect ion in wh ich t h e r esu lt of
th e st at em en t m u st in ser t ed.
o
A r efer en ce to an O2 object in wh ich th e r esu lt (for a
sin gle lin e r esu lt set ) m u st be pu t .
Description
Th is fu n ct ion execu tes a pr eviou sly defin ed SQL st at em en t . Th e fir st
fu n ct ion r et u r n s im m ediatly aft er t h e statem en t h as been r u n (u sed for
a st at em en t wit h ou t r esu lt ) an d t h e ot h er t wo fu n ct ion s pu t t h e r esu lt of
t h e st at em en t in to t h e t ar get object. Th e t ar get object can be a collect ion
of object wh en t h e pr ogr am m er expect s t o h ave a r esu lt set wit h
m u lt iple r ows or can be an object wh en t h e pr ogr am m er k n ows t h at th e
statem en t will r et u r n a sin gle r ow r esu lt set .
Returns
A st at u s code wh ose valu e is O2DB_OK if t h e oper at ion was su ccessfu l, or
on e of t h e followin g er r or codes if t h e oper ation failed:
• o2dbE_NOT_OPEN
• o2dbE_NOSTMT
• o2dbE_NOT_SELECT
• o2dbE_DEFINED
• o2dbE_MISMATCH
• o2dbE_NOT_SUPPORTED
• o2dbE_NOT_UNIQUE
• o2dbE_INVALID_NAME
• o2dbE_NOT_EXECUTED
• o2dbE_NILREF
• o2dbE_SQLNK
• o2dbE_SERVER
O2 DBAccess User Man u al
53
3
Class Library
Example
int get_persons()
{
int code, status;
o2db_Connection connection;
o2db_Session *session;
o2db_Statement *statement;
d_Set<d_Ref<Person> > persons;
d_Iterator<d_Ref<Person> > iter;
status = connection.connect("oracle", "user", "pwd");
...
session = connection.logon("dbuser", "dbpasswd", &status);
...
statement = session->open(&status);
...
statement->associate( "SELECT name,age FROM emp
WHERE age<?");
statement->add_cursor_variable("name_att");
statement->add_cursor_variable("age_att");
statement->add_input_variable(20);
status = o2db_sql_execute(*statement, persons);
...
status = session->close(statement);
connection.disconnect();
iter = persons.create_iterator();
while (iter.next(p)) {
cout << "Name : " << p.name_att << endl;
cout << "Age : " << p.age_att << endl;
cout << endl;
}
return status;
}
54
O2 DBAccess User Man u al
44
A ppe ndices
Th is ch apt er con t ain s t h e followin g appen dices:
• Exam ple Applicat ion
• Con figu r at ion File
• Possible Er r or s
O2 DBAccess User Man u al
55
4
Appendices
4.1 Example Application
Th is exam ple illu st r at es t h e var iou s st eps you m u st go t h r ou gh in or der
t o u se O2 DBAccess in side an ODMG C++ applicat ion .
Th is sect ion is divided u p in t o t h e followin g sect ion s:
• Defin in g a C++ sch em a
• Connecting to O2
• Con n ect in g to t h e Relation al dat abase ser ver
• Cr eatin g a table
• Popu lat in g t h e t able
• Displayin g t h e t able con t en t
• Qu er yin g t h e RDBMS
• Bu ildin g t h e applicat ion
56
O2 DBAccess User Man u al
Example Application : Defining a C++ schema
Defining a C++ schema
You m u st fir st defin e t h e C++ classes th at will be u sed t o r eceive t h e
r esu lt s of th e SQL statem en t s r u n in t h e applicat ion . In th is exam ple,
we defin e a class Person. Th e C++ classes defin ed h er e m u st be
im por t ed in O 2 as per sist en ce capable classes.
To be able t o st or e an SQL r esu lt set , you will n eed t o defin e collect ion s
for th ese classes.
#include "o2util_CC.hxx"
class Person {
public:
d_Short id_person;
char *name;
char *firstname;
int
age;
d_Char
employed;
d_Long
zip_code;
};
Note
You m ak e a C++ class per sist en ce capable u sin g o2im por t or a dir ective
in t h e o2makegen con figu r ation file (see t h e Sect ion "Bu ildin g t h e
applicat ion ").
O2 DBAccess User Man u al
57
4
Appendices
Connecting to O2
Th e m ain fu n ct ion of t h e applicat ion is an OD MG C++ fu n ction t h at
open s a session wit h t h e O2 ser ver , open s a dat abase, star t s an O2
t r an sact ion an d cr eat es a per sist en t r oot . It t h en calls t h e fu n ct ion
manage_sql, wh ich h an dles all t h e dbaccess par t an d fin ally com m it s
t h e O 2 t r an sact ion an d discon n ect s fr om t h e O2 ser ver .
main(int argc , char *argv[])
{
char *o2_home = getenv("O2HOME");
char *o2_system = getenv("O2SYSTEM");
char *o2_server = getenv("O2SERVER");
d_Session session;
d_Database database;
d_Transaction transaction;
if (! o2_home) {
cerr << "Cannot retrieve O2HOME" << endl;
exit(1);
}
if (! o2_system) {
cerr << "Cannot retrieve O2SYSTEM" << endl;
exit(1);
}
if (! o2_server) {
cerr << "Cannot retrieve O2SERVER" << endl;
exit(1);
}
if (session.begin(argc, argv, o2_system, o2_server, o2_home))
{
cerr << "Cannot connect to o2" << endl;
exit(1);
}
database.open("o2dbaccess_b");
transaction.begin();
database.create_persistent_root( "ThePersons",
"d_Set<d_Ref<Person> >");
manage_sql();
transaction.commit();
database.close();
session.end();
}
58
O2 DBAccess User Man u al
Example Application : Connecting to the Relational
Connecting to the Relational database server
Th is fu n ct ion is t h e en t r y poin t of t h e O2 DBAccess r elat ed code. It
establish es a con n ect ion with t h e r em ot e dat abase ser ver , open s a
dat abase, an d cr eat es a st at em en t .
At t h is poin t , t h e fu n ction s th at issu e t h e qu er ies ar e called, an d
fin ally, all t h e r esou r ces open ed on t h e r em ot e dat abase ser ver ar e
closed.
void manage_sql()
{
int retcode, svr_error;
char *msg;
o2db_Connection connection;
o2db_Session
*session;
o2db_Statement *statement;
// connection with the Sequelink server.
retcode = connection.connect( "oracle", "user",
"userpasswd");
if (retcode != O2DB_OK)
cerr << "Cannot open a connection with the
Sequelink server" << endl;
// open an session
session = connection.logon( "oracleuser",
"oracleuserpasswd",
&retcode);
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = connection.server_error(&svr_error);
cerr << "error: " << svr_error << " msg: " <<
msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
O2 DBAccess User Man u al
59
4
Appendices
// create a statement
statement = session->open(&retcode);
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = connection.server_error(&svr_error);
cerr << "error: " << svr_error << "
msg: "
<< msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
// call the queries
person_table_creation(statement);
person_table_initialization(statement);
person_table_display(statement);
retcode = connection.logoff(session);
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = connection.server_error(&svr_error);
cerr << "error: " << svr_error << "
msg: "
<< msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
retcode = connection.disconnect();
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = connection.server_error(&svr_error);
cerr << "error: " << svr_error << "
msg: "
<< msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
}
60
O2 DBAccess User Man u al
Example Application : Creating a table
Creating a table
Th is fu n ct ion cr eat es a n ew t able on t h e RDBMS. Th e SQL CREATE
st at em en t is associat ed t o t h e O 2 D BAccess st at em en t an d as th er e is n o
m or e in for m at ion t o give, t h e st at em en t is execu t ed.
void person_table_creation(o2db_Statement * statement)
{
int retcode, svr_error;
char *msg;
retcode = statement->associate("CREATE TABLE person \
( id_person SMALLINT null, \
name VARCHAR(16) null, \
firstname VARCHAR(16) null, \
age INTEGER null, \
employed INTEGER default 0, \
zip_code NUMERIC null)");
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = statement->server_error(&svr_error);
cerr << "error: " << svr_error << "
msg: " << msg
<< endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
retcode = o2db_sql_execute(*statement);
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = statement->server_error(&svr_error);
cerr << "error: " << svr_error << "
msg: " << msg
<< endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
}
O2 DBAccess User Man u al
61
4
Appendices
Populating the table
Th e followin g fu n ct ion popu lat es t h e pr eviou sly cr eat ed table.
Th e INSERT SQL st at em en t is associat ed t o th e O2 DBAccess st at em en t .
It con t ain s par am et er s m ar k er s (den ot ed wit h '?'), t h at m u st be bou n d
wit h t h e act u al valu es of t h e par am et er s.
In t h is exam ple, t h is is per for m ed u sin g th e '<<' oper at or . It cou ld also
h ave been per for m ed u sin g t h e add_input_variable m em ber fu n ct ion .
Th e person_data t able u sed in th e exam ple is n ot det ailed an d cou ld be
r eplaced by an y in pu t sou r ce.
Aft er t h e par am et er s ar e bou n d, t h e st at em en t is execu t ed. In t h is
exam ple, n ot e t h at t h e sam e associat ed statem en t is u sed sever al t im es
t o in ser t sever al r ows in t h e per son t able, each t im e wit h a n ew bin din g
of t h e act u al par am eter s.
void person_table_initialisation(o2db_Statement *
statement)
{
int retcode, svr_error;
char *msg;
retcode = statement->associate( "INSERT INTO \
person (id_person, \
name, \
firstname, \
age, \
employed, \
zip_code) \
VALUES (? , ? , ? , ? , ?, ?)");
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = statement->server_error(&svr_error);
cerr << "error: " << svr_error << "
msg: "
<< msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
62
O2 DBAccess User Man u al
Example Application : Populating the table
for (int i = 0 ;
*statement <<
*statement <<
*statement <<
*statement <<
*statement <<
*statement <<
i<NB_PERSON ; i++) {
person_data[i].id_person;
person_data[i].name;
person_data[i].firstname;
person_data[i].age;
person_data[i].employed;
person_data[i].zip_code;
retcode = o2db_sql_execute(*statement);
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = statement->server_error(&svr_error);
cerr << "error: " << svr_error
<< "
msg: " << msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
}
}
O2 DBAccess User Man u al
63
4
Appendices
Displaying the table content
Th is fu n ct ion sh ows h ow t o h an dle a SELECT SQL st at em en t . Th is k in d
of st at em en t r etu r n s a r esu lt set t h at n eeds t o be st or ed in C++ object s.
A collect ion of C++ objects of t h e per sist en ce capable class Person is
cr eat ed an d is given as par am et er t o t h e o2db_sql_execute fu n ct ion .
Aft er t h e st at em en t execu t ion , t h is collect ion will con t ain t h e r esu lt set
of t h e SQL qu er y. In t h is exam ple, t h e collect ion "Th ePer son s" is
per sist en t , bu t r esu lt s can be st or ed in t em por ar y collect ion s t oo.
Not e t h at n o cu r sor var iables ar e defin ed in t h is fu n ct ion t o specify t o
wh ich C++ at t r ibu t es t h e t able colu m n s ar e associat ed. In t h is case, all
t h e C++ at t r ibu t es of t h e class given t o t h e o2db_sql_execute fu n ct ion
ar e im plicit ly associat ed t o th e r esu lt set in t h e or der t h ey appear in t h e
C++ class defin it ion . You m u st ch eck th at t h e SQL qu er y r etu r n s a valid
dat a set for t h e given C++ object.
Aft er t h e st at em en t is execu t ed, an it er at or is cr eat ed on t h e collection
an d is u sed t o display each r et r ieved per son
64
O2 DBAccess User Man u al
Example Application
.
void person_table_display(o2db_Statement * statement)
{
int retcode, svr_error;
char *msg;
d_Set<d_Ref<Person> > the_persons("ThePersons");
d_Iterator<d_Ref<Person> > iter;
d_Ref<Person> person;
retcode = statement->associate( "SELECT * \
FROM person");
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = statement->server_error(&svr_error);
cerr << "error: " << svr_error << "
msg: "
<< msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
retcode = o2db_sql_execute(*statement, the_persons);
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = statement->server_error(&svr_error);
cerr << "error: " << svr_error
<< "
msg: " << msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
iter = the_persons.create_iterator();
while (iter.next(person)) {
cout << "\t*** [ "
<< person -> id_person << " "
<< person -> name << " "
<< person -> firstname << " "
<< person -> age << " "
<< person -> employed << " "
<< person -> zip_code << " ]" << endl;
}
}
O2 DBAccess User Man u al
65
4
Appendices
Querying the RDBMS
Th is qu er y is qu ite sim ilar to t h e pr eviou s on e except t h at cu r sor
var iables ar e explicit ly defin ed (becau se t h e n u m ber an d or der of
appear an ce of t h e at tr ibu t es of t h e given C++ class ar e n ot t h e sam e as
t h e colu m n s of t h e r esu lt set .
Th is exam ple also sh ows h ow t o com bin e in pu t var iables an d cu r sor
var iables in t h e sam e st at em en t . M or eover t h e r esu lt is n ow pu t in a
t em por ar y list .
Th e fu n ct ion fir st ly associat es t h e SQL st at em en t t o th e O2 DBAccess
st at em en t, gives t h e valu e '35' as t h e act u al par am et er for t h e m ar k er
u sed in t h e SQL st at em en t , an d defin es t h e cu r sor var iables.
In t h is case t h e colu m n "name" of t h e r esu lt set is associat ed t o t h e
at t r ibu t e "name" of th e C++ class (*statement >> "name") an d t h e
colu m n "firstname" of t h e r esu lt set is associated t o t h e at t r ibu t e
"firstname" of t h e C++ class (*statement >> ... >> "firstname").
Note
Even if it is t h e case in t h is fu n ction , t h e C++ at t r ibu te associat ed t o a
colu m n of t h e SQL r esu lt set does n ot n eed t o h ave th e sam e n am e as
t h e colu m n . For in stan ce, we cou ld h ave associat ed an att r ibu t e called
"person_name" t o t h e colu m n "name" of t h e r esu lt set
66
O2 DBAccess User Man u al
Example Application
void person_table_query(o2db_Statement * statement)
{
int retcode, svr_error;
char *msg;
d_List<d_Ref<Person> > young_people;
d_Iterator<d_Ref<Person> > iter;
d_Ref<Person> person;
retcode = statement->associate("SELECT name, firstname\
FROM person \
WHERE age < ? \
ORDER BY age");
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = statement->server_error(&svr_error);
cerr << "error: " << svr_error
<< "
msg: " << msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
// binds the input variable
*statement << 35;
// binds the cursor variables.
*statement >> "name" >> "firstname";
retcode = o2db_sql_execute(*statement, young_people);
if (retcode != O2DB_OK) {
if (retcode == o2dbE_SERVER) {
msg = statement->server_error(&svr_error);
cerr << "error: " << svr_error
<< "
msg: " << msg << endl;
} else cerr << "dbaccess error: " << retcode;
return;
}
iter = young_people.create_iterator();
while (iter.next(person)) {
cout << "\t*** [ "
<< person -> name << " "
<< person -> firstname << " ]" << endl;
}
}
O2 DBAccess User Man u al
67
4
Appendices
Building the application
You bu ild t h e applicat ion in exact ly th e sam e way as you bu ild a
classical OD MG C++ applicat ion .
To u se O2 DBAccess you ju st n eed to lin k -edit you r application wit h th e
O2 DBAccess libr ar y an d wit h th e Sequ eLin k clien t libr ar ies an d t o add a
dir ect ive t o look for Sequ eLin k clien t in clu de files.
Th e followin g code gives an o2makegen con figu r at ion file t h at can be
u sed t o cr eat e an application (see t h e "C++ Bi n d i n g Gu i d e M an u al ").
Note
Befor e u sin g a gen er at ed applicat ion , it is m an dat or y t o cr eat e an O 2
sch em a an d base u sin g t h e o2dsa pr ogr am .
O2System: $O2SYSTEM
O2Server: $O2SERVER
O2Schema: o2dbaccess_s
+UseConfirmClasses
O2Home: $O2HOME
ImpFiles: Person.hxx
[Person.hxx]ImpClasses: Person
ImpSet: Person
Sources: example.cc
ProgramLib: o2dbaccess SqlnkCor SqlnkNet SqlnkDef
ProgramLibDir: $O2HOME/thirdparty/SequeLink/lib/IRIX
Include: $O2HOME/thirdparty/SequeLink/include
ProgramName: example
ProgramObjs: example.o
.
68
O2 DBAccess User Man u al
Configuration File
4.2 Configuration File
Th e con figu r at ion file o2dbaccess.cf con tain s t h e in for m at ion n eeded
t o lin k u p you r O2 application an d a r em ote h ost , in th e for m of a set of
n et wor k an d h ost -specific par am eter s.
You can ch an ge t h e file n am e by specifyin g a n ew n am e an d it s pat h in
t h e en vir on m en t var iable O2DBACCESS. Th is var iable m u st con t ain t h e
fu ll pat h of t h e file.
In or der of pr ior it y, t h e file is fir st t ak en fr om th e wor k in g dir ector y,
t h en $HOME an d t h en t h e O 2 in st allat ion dir ect or y. It is an ASCII file
wh er e each lin e cor r espon ds t o a n am ed lin k descr ipt ion . It con tain s
on e en t r y for each n am ed lin k with com m en t s begin n in g wit h #. Th e lin e
for m at is:
c_name:network:host:port:service:lu_name:mode:max_statements:type_checking
Each field is descr ibed below.
c_name
Lin k n am e. Specify a lin k n am e each t im e you in vok e
t h e o2db_Connection::connect m em ber fu n ct ion .
network
Type of n et wor k pr otocol u sed. Possible valu es: TCP
(MacTCP on Macin t osh ), ADSP, APPC, D ECn et,
Net BIOS an d AppleTalk .
host
RDBMS r em ote h ost / n ode/ zon e n am e.
port
Por t on wh ich th e Sequ elin k ser ver is list en in g. Defau lt
is 2000. If you wan t t o u se t h e defau lt por t n u m ber ,
u se a ’*’.
service
Sequ eLin k (dat abase) ser vice n am e t h at you wan t t o
con n ect t o. You can fin d t h is n am e in t h e ser ver m ap
file on t h e r em ot e h ost . See Sequ eLin k m an u al.
lu_name
Ph ysical LU Nam e in APPC n et wor k pr ot ocol (opt ion al).
If it is n ot applicable, u se a ’*’.
mode
APPC m ode in APPC n et wor k pr ot ocol (opt ion al). If it is
n ot applicable, u se a ’*’.
max_statements In teger (fr om 0 to 100) specifyin g m axim u m n u m ber of
st at em en t s t h at can be open ed at t h e sam e t im e du r in g
a session . If 0, th e defau lt valu e (15) is u sed.
type_checking Boolean specifyin g wh et h er t o en able (true) or disable
(false) type ch eck in g in t h e
o2db_Statement::add_cursor_variable an d
o2db_Statement::add_input_variable m em ber
fu n ct ion s. Defau lt valu e is false.
O2 DBAccess User Man u al
69
4
Appendices
Warning !
Th e t ype ch eck in g is n ot su p por t ed for al l RDBM S. An exam ple
con figu r ation file is as follows:
supra on salome:TCP:salome:LSPSUPRA2:*:*:15:false
db2 on sgphl1:DECnet:sgphl1:MVSDB2:*:*:0:true
oracle:TCP:o2tech:oracle_services:*:*:0:false
70
O2 DBAccess User Man u al
Possible Errors : Building the application
4.3 Possible Errors
Each m em ber fu n ct ion r et u r n s an in t er n al er r or code.
Th is sect ion descr ibes th ese er r or codes. You can obtain
RD BM S-det ect ed er r or codes u sin g th e server_error m em ber
fu n ct ion . See Sect ion 3.1 for a descr ipt ion of t h is m em ber fu n ct ion .
• -1001
Code:
o2dbE_SERVER (-1001)
Call:
All.
Cau se:
RDBMS-detect ed er r or h as occu r r ed.
Act ion :
Con su lt er r or code an d m essage t ext callin g t h e
o2db_O2DBAccess::server_error m em ber fu n ct ion .
• -2001
Code:
o2dbE_SQLNK (-2001)
Call:
All.
Cau se:
A Sequ eLin k er r or h as occu r r ed. Sh ou ld u su ally on ly be
issu ed on a o2db_Connection::connect m em ber
fu n ct ion call.
Act ion :
Ch eck t h e lin k par am et er s, u ser n am e an d passwor d. Th e
con n ect failu r e r eason is in <network>srv.log file on t h e
r em ot e h ost .
• -3001
Code:
o2dbE_STILL_CONNECT (-3001)
Call:
o2db_Connection::connect
Cau se:
You ar e st ill con n ect ed t o a h ost .
Act ion :
Th e o2db_Connection::connect m em ber fu n ct ion was
called bu t n ot t h e o2db_Connection::disconnect
m em ber fu n ct ion .
• -3002
Code:
o2dbE_NOT_CONNECT (-3002)
Call:
o2db_Connection::logon, o2db_Connection::logoff
Cau se:
Not con n ect ed.
Act ion :
Ch eck com plet ion of t h e pr eviou s connect m em ber
fu n ct ion call.
O2 DBAccess User Man u al
71
4
Appendices
• -3003
Code:
o2dbE_NOT_MEMBER (-3003)
Call:
o2db_Connection::logoff, o2db_Session::close
Cau se:
Th e Session / St at em en t object h as n ot been cr eat ed by t h e
r eceiver .
Act ion :
Ch eck th e m em ber fu n ction call syn t ax.
• -3004
Code:
o2dbE_NOT_LOGON (-3004)
Call:
o2db_Session::open, o2db_Session::close,
o2db_Session::commit, o2db_Session::rollback
Cau se:
Not logged on .
Act ion :
Ch eck com plet ion of t h e pr eviou s
o2db_Connection::logon m em ber fu n ct ion call.
• -3005
Code:
o2dbE_TOOLONG (-3005)
Call:
o2db_Connection::logon, o2db_Statement::associate
Cau se:
Th e par am et er s ar e t oo lon g.
Act ion :
D ecr ease par am et er len gt h .
• -3006
Code:
o2dbE_NOT_OPEN (-3006)
Call:
o2db_Statement::associate,
o2db_Statement::add_input_variable,
o2db_sql_execute
Cau se:
Th e st at em en t h as n ot been open ed.
Act ion :
Ch eck t h e com pletion of t h e pr eviou s
o2db_Session::open m em ber fu n ct ion call.
• -3008
Code:
o2dbE_NOSTMT (-3008)
Call:
o2db_Statement::associate,
o2db_Statement::add_input_variable,
o2db_sql_execute
Cau se:
Th e SQL st at em en t is em pt y.
Act ion :
72
Ch eck th e m em ber fu n ction call syn t ax.
O2 DBAccess User Man u al
Possible Errors : Building the application
• -3009
Code:
o2dbE_FILE_NOTFOUND (-3009)
Call:
o2db_Connection::connect
Cau se:
Th e con figu r at ion file was n ot fou n d.
Act ion :
Ch eck t h at t h e con figu r at ion file exist s.
• -3010
Code:
o2dbE_RC_NOTFOUND (-3010)
Call:
o2db_Connection::connect
Cau se:
No descr ipt ion of t h e lin k par am et er s for t h is lin k n am e.
Act ion :
Ch eck con figu r at ion file con t en t s an d th e m em ber fu n ct ion
call syn t ax.
• -3011
Code:
o2dbE_INVALID_RC (-3011)
Call:
o2db_Connection::connect
Cau se:
In valid lin e in t h e con figu r at ion file.
Act ion :
Ch eck t h e con figu r at ion file con t en t s.
• -3012
Code:
o2dbE_UNKN_NETWORK (-3012)
Call:
o2db_Connection::connect
Cau se:
Un k n own n etwor k pr ot ocol.
Act ion :
Ch eck con figu r at ion file con t en t s.
• -3013
Code:
o2dbE_OPEN_FILE (-3013)
Call:
o2db_Connection::connect
Cau se:
Th e con figu r at ion file can n ot be open ed.
Act ion :
Ch eck t h at t h e con figu r at ion file exist s an d ch eck it s
access r igh t s.
O2 DBAccess User Man u al
73
4
Appendices
• -3014
Code:
o2dbE_NOT_SELECT (-3014)
Call:
o2db_sql_execute
Cau se:
Th e SQL st at em en t is n ot a select st at em en t .
Act ion :
Ch eck t h e syn t ax of t h e SQL st at em en t.
• -3015
Code:
o2dbE_RANGE (-3015)
Call:
o2db_Statement::add_input_variable
Cau se:
Th e or der n u m ber is ou t of r an ge.
Act ion :
Ch eck t h e or der n u m ber .
• -3016
Code:
o2dbE_DEFINED (-3016)
Call:
o2db_sql_execute
Cau se:
Th e par am et er or t h e r esu lt object is yet defin ed.
Act ion :
Ch eck t h e or der n u m ber .
• -3017
Code:
o2dbE_MISMATCH (-3017)
Call:
o2db_Statement::add_input_variable,
o2db_sql_execute
Cau se:
Type ch eck in g failed.
Act ion :
Ch eck t h e r esu lt or par am et er t ype.
• -3018
74
Code:
o2dbE_NOT_SUPPORTED (-3018)
Call:
o2db_Statement::add_input_variable,
o2db_sql_execute
Cau se:
On e of t h e atom ic t ypes u sed is n ot su ppor ted in th e
cu r r en t ver sion of O2 DBAccess.
Act ion :
Ch eck t h e t ype of r esu lt object .
O2 DBAccess User Man u al
Possible Errors : Building the application
• -3021
Code:
o2dbE_INVALID_NAME (-3021)
Call:
o2db_sql_execute
Cau se:
On e of t h e n am es is n ot an att r ibu t e n am e.
Act ion :
Ch eck t h e list of att r ibu t e n am es.
• -3022
Code:
o2dbE_NOT_EXECUTED (-3022)
Call:
o2db_sql_execute
Cau se:
Th e stat em en t h as n ot been execu ted.
Act ion :
Ch eck t h e com plet ion of t h e pr eviou s o2db_sql_execute
m em ber fu n ct ion call.
• -3023
Code:
o2dbE_NO_MORE_STATEMENTS (-3023)
Call:
o2db_Statement::open
Cau se:
An at t em pt was m ade t o exceed th e m axim u m n u m ber
open statem en t s allowed.
Act ion :
Close som e statem en t s.
• -3024
Code:
o2dbE_NILREF (-3024)
Call:
o2db_Statement::add_input_variable,
o2db_sql_execute
Cau se:
Th e r esu lt object or a par am et er is nil.
Act ion :
Ch eck t h e m em ber fu n ct ion call syn t ax.
• -3025
Code:
o2dbE_NOMEM (-3025)
Call:
All.
Cau se:
Not en ou gh m em or y.
Act ion :
Close som e statem en t s.
O2 DBAccess User Man u al
75
4
Appendices
• -4001
Code:
o2dbE_INTERNAL (-4001)
Call:
All.
Cau se:
In t er n al er r or . It sh ou ld n ot n or m ally be issu ed.
Act ion :
Con t act you r local t ech n ical su ppor t.
• -5001
76
Code:
o2dbW_NOT_UNIQUE (-5001)
Call:
o2db_sql_execute
Cau se:
Th is a war n in g. Th er e is m or e t h an on e r ow t o fet ch
wh er eas t h e r esu lt t ype is n ot a collect ion .
Act ion :
Noth in g. On ly t h e fir st r ow h as been fet ch ed.
O2 DBAccess User Man u al
IN DEX
O2 DBAccess User Man u al
77
INDEX
A
D
add_cu r sor _var iable
Function 23–24, 45
Data
Access 21
add_in pu t _var iable
Function 23–24, 46
Database
Access 21–22
Log off 21
Log on 21
Applicat ion
Bu ildin g 68
Exam ple 56–68
Ar ch itect u r e
Clien t / ser ver 13
O2 10
associat e
Function 23, 48
C
discon n ect
Function 21, 28, 34
E
En vir on m en t var iable 69
Er r or codes 23, 71–76
Exam ple application 56–68
C 11
C++
In t er face 11
F
C++ Sch em a
Defin it ion 57
c_name 69
Class 18
o2db_Connection 21, 32
o2db_O2DBAccess 30
o2db_Session 21, 38
o2db_Statement 44
File
Con figu r at ion 69
Clien t / ser ver ar ch it ect u r e 13
close
Function 22, 39
com m it
Function 28, 40
Con figu r at ion
File 68, 69
con n ect
Function 21, 33
78
O2 DBAccess User Man u al
INDEX
Fu n ct ion 19
add_cursor_variable 23–24, 45
add_input_variable 23–24, 46
associate 23, 48
close 22, 39
commit 28, 40
connect 21, 33
disconnect 21, 28, 34
logoff 21, 28, 35
logon 21, 36
o2db_sql_execute 25, 53
open 22, 41
operator << 51
operator >> 50
rollback 28, 43
server_error 31
L
Libr ar y
Defin it ion 18
logoff
Function 21, 28, 35
logon
Function 21
lu_name 69
M
H
H ost
Con n ection 21, 58
Discon n ect 21, 28
Man agin g st at em en t s 23
max_statements 69
mode 69
host 69
N
I
network 69
In t er n al er r or codes 71
O
J
O2
Ar ch it ect u r e 10
J ava 11
O2 C 11
O2 Cor ba 11
O2 DBAccess User Man u al
79
INDEX
o2db_Con n ect ion
Class 18, 32
Creation 21
Functions 21, 32–37
o2db_O2DBAccess
Class 18, 30
Functions 31
o2db_Session
Class 18, 21–22, 38
Functions 38–43
R
RDBM S
Qu er yin g 66
r ollback
Function 28, 43
o2db_sql_execu te
Function 25, 53
o2db_St at em en t
Class 18, 22, 44
Functions 44–54
O2DBACCESS 69
O 2 DBAccess 11
o2dbaccess
Schema 18
o2dbaccess.cf 69
O 2 En gin e 10
O 2 Gr aph 11
O 2 Kit 11
O 2 Look 11
O 2 OD BC 11
O 2 Stor e 10
Over view 13
O 2 Tools 11
O 2 Web 11
open
Function 22, 41
oper ator <<
Function 51
S
ser ver _er r or
Error codes 71
Function 23, 31
service 69
Session
Close 22, 28
Open 22
Statem en t
Close 22
Man agem en t 23
Maxim u m n u m ber 22
Open 22
Pr epar at ion 23
Ru n n in g 25
Syst em
Ar ch it ect u r e 10
oper ator >>
Function 50
OQL 11
P
port 69
80
T
Table
Cr eat in g 61
Displayin g con t en t 64
Popu lat in g 62
type_checking 69
O2 DBAccess User Man u al