Download O2 DBAccess User Manual (O2C Interface)

O2DBAccess
User Manual
O2C 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
O2Engine .....................................................................................12
O2 Store .......................................................................................13
O2DB Access ...............................................................................14
1.2 Manual Overview ......................................................................16
2
Utilization
17
2.1 The o2dbaccess schema .........................................................18
Classes..........................................................................................18
Importing the schema...................................................................19
2.2 Guidelines .................................................................................20
2.3 Accessing a database..............................................................22
Host connection and database log in............................................22
Open Context ...............................................................................23
2.4 Preparing a statement..............................................................24
Linking statement and context .....................................................24
Managing contexts .......................................................................24
Transferring data ..........................................................................25
2.5 Run statement and fetching data............................................29
2.6 Commit and rollback................................................................30
2.7 Ending a session......................................................................31
3
Classes
33
3.1 O2DBAccess.............................................................................34
server_error method .....................................................................35
3.2 Connection................................................................................36
connect method ............................................................................37
disconnect method........................................................................38
logon method................................................................................39
6
O2 DBAccess User M an u al
TABLE OF CONTENTS
logoff method .............................................................................. 40
3.3 Session ..................................................................................... 41
close method................................................................................ 42
commit method............................................................................ 43
open method ................................................................................ 44
rollback method ........................................................................... 45
sqlquery method .......................................................................... 46
3.4 Context ..................................................................................... 47
associate method.......................................................................... 48
define_bind method ..................................................................... 49
define_projection method ............................................................ 50
exec method................................................................................. 51
fetch method ................................................................................ 52
4
Appendices
53
4.1 Example Application ............................................................... 54
Define the schema ....................................................................... 55
Host connection and database log on .......................................... 56
Open a context ............................................................................. 57
Prepare the statement................................................................... 58
Run the statement ........................................................................ 59
Fetch the data............................................................................... 60
Close the context ......................................................................... 61
Close database session and end host connection......................... 61
4.2 Configuration File .................................................................... 62
4.3 Possible Errors ........................................................................ 63
INDEX
O2 DBAccess User Man u al
69
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
O2Engine
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 ity.
Th e feat u r es offer ed by O 2 En gin e an d O2 St or e ar e sh own in Figu r e 1.3
below.
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 O2 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 s.
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 for 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- Utilization
Th is ch apt er descr ibes h ow t o u se O 2 D BAccess: 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 - Classes
Th is ch apt er details all t h e var iou s classes an d m et h ods of t h e
O2 DBAccess sch em a: o2DBAccess, Connection, Session, an d
Context.
• 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
U ti l i zat i o n
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:
• The o2dbaccess schema
• Gu idelin es
• Accessin g a dat abase
• Pr epar in g a st at em en t
• Ru n st at em en t an d fet ch in g dat a
• Com m it an d r ollback
• En din g a session
O2 DBAccess User Man u al
17
2
Utilization
2.1 The o2dbaccess schema
O2 DBAccess is in fact a st an dar d O 2 sch em a called o2dbaccess th at
you can u se in an y of you r u ser -defin ed sch em as.
Classes
Th e o2dbaccess sch em a, sh own in Figu r e 2.1, h as classes t h at en able
you to com m u n icat e an d wor k wit h t h e r em ote dat abase.
Par am et er
Con n ect ion
Object
O2D BAccess
Session
Con text
Fi gu r e 2 .1 : o2 d ba ccess sch em a
Th e sch em a classes ar e as follows:
• o2DBAccess
An o2DBAccess object defin es t h e com m on r esou r ces of O2 DBAccess
classes. It con tain s on e m et h od, server_error, wh ich you u se t o
obt ain th e RDBMS-det ect ed er r or codes.
• Connection
Connection is a su bclass of o2dbaccess. A Connection object defin es
an d m ain t ain s a con n ect ion t o a r em ot e h ost .
• Session
Session is a su bclass of o2dbaccess. A Session object defin es an d
m ain t ain s a con n ect ion to a database ser ver . It m an ages t h e
t r an sact ion s of th e session .
• Context
Context is a su bclass of o2dbaccess. A Context object defin es an
access con t ext t o a dat abase an d con t ain 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.
• Parameter
An y classes u sed for t h e r esu lt object an d par am et er s m u st be a
su bclass of t h e Parameter class.
18
O2 DBAccess User Man u al
The o2dbaccess schema
Importing the schema
Im por t t h e o2dbaccess sch em a u sin g th e O2 import com m an d:
import schema o2dbaccess class Parameter, Connection,
Session, Context;
Th is import com m an d gives you access t o an y o2dbaccess classes.
If you ar e u sin g O2 Tools, you see t h e class h ier ar ch y sh own in Figu r e
2.2.
Par am et er
Con n ect ion
Object
Session
Con text
Fi gu r e 2 .2 : I m p or t ed O2 DBAccess cl a sses
You can also im por t t h e O2DBAccess class if you ar e goin g t o u se
gen er ic er r or m essages.
Par am et er
Con n ect ion
Object
Session
Con text
O2DBAccess
Fi gu r e 2 .3 : I m p or t O2 DBAccess cl a ss
Note
For fu ller det ails of t h ese classe an d t h eir m eth ods, r efer t o Ch apt er 3.
O2 DBAccess User Man u al
19
2
Utilization
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 ect ion t o t h 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 an access con t ext for t h e st at em en t .
4.
Pr epar e t h e st at em en t t o be r u n . Th is m ean s pu t t in g in for m at ion
abou t t h e st at em en t in t h e con t ext .
5.
Ru n t h e st at em en t .
6.
If t h e st at em en t is a select st at em en t, fetch t h e dat a fr om t h e dat abase
t o you r applicat ion in t o an O2 object .
7.
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 th em .
8.
If you do n ot wan t t o r er u n t h e st at em en t, close t h e con t ext .
9.
Close t h e session by loggin g off t h e dat abase.
10. En d t h e con n ect ion by discon n ectin g fr om th e h ost .
20
O2 DBAccess User Man u al
Guidelines
Each step cor r espon ds to a par t icu lar m et h od. Table 2.1 sh ows t h ese
m et h ods an d it s cor r espon din g st ep.
Th e class of t h e m eth od is given aft er th e m eth od n am e.
Th ese m eth ods con st it u t e t h e basic set of m et h ods t h at you n eed to u se.
Table 2.1
Method set
Met h ods
St ep
connect@Connection
Set u p a con n ect ion
logon@Connection
Set u p a session
open@Session
Open an access con t ext
associate@Context
define_projection@Context
Pr epar e a st at em en t
define_bind@Context
exec@Context
Ru n a st at em en t
fetch@Context
Fet ch dat a fr om t h e dat abase
commit@Session
Mak e t h e ch an ges per m an en t
rollback@Session
Un do a tr an sact ion
close@Session
Close t h e con t ext
logoff@Connection
En d t h e session
disconnect@Connection
En d t h e con n ect ion
All t h ese var iou s st eps ar e detailed below.
For a descr ipt ion of each specific m et h od r efer t o Ch apter 3.
Note
St eps 3 to 8 can be r edu ced u sin g t h e m et h od sqlqu er y of t h e class
Session . See Sect ion 3.3 for m or e det ails.
O2 DBAccess User Man u al
21
2
Utilization
2.3 Accessing a database
You m u st fir st con n ect t o t h e r em ote h ost an d log on t o t h e dat abase.
Host connection and database log in
With O 2 D BAccess, you do th is by cr eat in g a Connection object . You
m u st call th e connect m et h od on t h is object to con n ect to t h e r em ot e
h ost. You t h en call th e logon m et h od on t h is object t o log on to t h e
dat abase an d begin a session . Th e logon m et h od r et u r n s a Session
object .
On ce con n ect ed an d logged on , you can r u n as m an y SQL st at em en ts as
you wan t .
For exam ple:
run body {
o2 Connection host = new Connection;
Cr eat e t h e object
o2 Session session;
Con n ect ion t o t h e h ost defin ed by where
host->connect ("where", "username", "password");
Log on t h e dat abase defin ed by db name
session = host->logon ("db name", "db username/password").session;
/* Some transactions */
host->logoff (session);
host->disconnect;
En d session
Discon n ect fr om t h e h ost
};
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 th e
logoff an d disconnect m et h ods to r espect ively en d t h e session an d
r em ote h ost con n ect ion .
Refer t o Sect ion 3.2 for a fu ll descr iption of all t h ese Connection
m et h ods.
22
O2 DBAccess User Man u al
Accessing a database : Open Context
Open Context
On ce con n ect ed to t h e r em ot e h ost an d logged on t o t h e database, you
m u st n ow open a con t ex t for each SQL st at em en t you wan t t o r u n . You
do t h is u sin g t h e open m et h od fr om you r Session object (r esu lt of t h e
logon m et h od). Th e con t ext con t ain s t h e st at em en t it self an d an y
addition 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
m et h od r et u r n s an object of class Context.
A Context object r em ain s open u n t il you explicit ly close it u sin g t h e
close m et h od (of you r Session object), or u n t il you en d t h e dat abase
session u sin g t h e logoff m eth od. However , you do n ot n eed to close a
con t ext in or der t o u se it for a differ en t st atem en t . You sim ply r e-u se it .
For exam ple:
run body {
o2 Connection host = new Connection;
o2 Session
session;
o2 Context
context1, context2;
host->connect ("where", "username", "password");
session = host->logon ("db name", "db username/password").session;
context1 = session->open.context;
/* statements */
session->close(context1);
context2 = session->open.context;
/* statements */
session->close(context2);
host->logoff(session);
host->disconnect;
};
Con t ext s an d h ow t o m an age con t ext s ar e explain ed fu lly in Sect ion 2.4
below an d Sect ion 3.3 gives a descr ipt ion of t h e open m et h od.
Note
Th e con t ext 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 con text s you can open at t h e sam e tim 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 dat abase or
you r self can im pose a lower lim it .
O2 DBAccess User Man u al
23
2
Utilization
2.4 Preparing a statement
Th e n ext st ep aft er accessin g t h e dat abase is to pr epar e t h e SQL
st at em en ts you wan t t o r u n .
Linking statement and context
You m u st fir st ly lin k th e statem en t t o it s con text u sin g t h e associate
m et h od of t h e Context class.
Th is m et h od associates t h e st at em en t t o t h e open ed con t ext in or der t o
pass in for m at ion abou t t h e st at em en t t o th e dat abase ser ver .
Th e in for m at ion in t h e con t ext can be u sed for a t ype ch eck in g on t h e
clien t side.
Th e associate also sen ds t h e st at em en t t o th e RDBMS dat abase for
validat ion . It is at t h is poin t t h at an y SQL syn tax 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 m et h od on t h e Context object (see Sect ion 3.1 for det ails
of t h is m et h od an d Sect ion 4.3 for a list of possible er r or s).
Fin ally, t h e associate m et h od st or es t h e st at em en t in t h e con t ext.
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 et er m ar k er s, O 2 D BAccess n eeds
n o m or e in for m at ion .
You can t h er efor e im m ediat ely r u n you r st at em en t u sin g th e exec
m et h od. See Sect ion 2.5 for m or e det ails.
However , if t h e st at em en t a sel ect st at em en t an d/ or it con tain s
par am et er m ar k er s, you m u st pr ovide O 2 D BAccess wit h m or e
in for m at ion . Th is is explain ed in t h e r em ain der of th is sect ion .
Managing contexts
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 et er m ar k er s or bot h , you n eed t o pr ovide m or e in for m at ion
befor e th e stat em 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 con t ext u sin g t h e define_projection m et h od of
t h e class Context.
You also n eed to st or e an y par am et er s in t h e con t ext u sin g th e
define_bind m et h od.
24
O2 DBAccess User Man u al
Preparing a statement : Transferring data
You can m an age you r con t ext s in t h r ee differ en t ways:
1.
Use on e con t ext for on e specific SQL stat em en t an d close t h e con t ext
as soon as t h e st atem en t h as been r u n .
2.
Open a con t ext, u se it for on e st at em en t , an d t h en r eu se for an ot h er
st at em en t by sim ply associat in g it t o t h e n ew st atem en t .
You can t o do t h is as m an y tim es as you wan t u n t il you wan t t o close
th e con t ext .
3.
Open a con t ext for a par t icu lar statem en t t h at you wan t t o r u n sever al
t im es. You k eep th e con t ext open an d associat ed t o t h e st at em en t
u n t il you n o lon g wish t o r er u n t h e st at em en t .
Wh ile t h e con t ext is open , you can r er u n t h e st at em en t wit h n ew
valu es for an y of it s par am eter s u sin g t h e exec an d fetch m eth ods.
However , you can n ot r edefin e an y objects u sin g t h e
define_projection or define_bind m eth ods.
Note
Re-associat in g a con t ext fr ees all defin es.
Transferring data
Th e tr an sfer of data bet ween t h e applicat ion an d t h e dat abase in volves
t h e followin g st eps:
1.
You m u st fir st ly defin e t h e classes of object s wh er e you wan t th e dat a
t o be bu f f er ed . Th ese classes m u st be su bclasses of t h e Parameter
class.
2.
You m u st t h en give th e r elevan t t r an sfer in for m at ion . Th is in clu des
t h e objects in wh ich th e dat a is t o be bu ffer ed an d wh et h er th ese
object s defin e a par am eter or t h e r esu lt object.
You do t h is by defin in g dat a bu ffer s u sin g t h e define_projection
an d define_bind m et h ods descr ibed above. Th ese m et h ods st or e t h e
tr an sfer in for m at ion in t h e con t ext .
You can th en r u n t h e st at em en t u sin g t h e exec m et h od If you ar e
t r an sfer r in g dat a fr om t h e dat abase, you m u st fet ch it fr om t h e
dat abase t o t h e design at ed r esu lt object u sin g t h e fetch m et h od.
Th is sect ion n ow descr ibes t h ese st eps in m or e det ail.
O2 DBAccess User Man u al
25
2
Utilization
• Data buffers
Th e dat a bu ffer s ar e O2 object s, t h e classes of wh ich ar e u ser -defin ed
an d m u st be in h er it ed fr om t h e Parameter class.
Defin e t h e class type as follows k n owin g t h at you can ch oose an y
collect ion t ypes:
• For a par am eter , t h e class type m u st be at om i c an d m at ch t h e scalar
t ype of th e associat ed par am et er m ar k er in t h e SQL st at em en t .
• Th e r esu lt of a select statem en t is a r el at i on . A r elat ion is a collect ion
of t u ples wh ose att r ibu t es h ave scalar t ypes. If t h e r elation h as on ly
on e at t r ibu t e, you can u se a collect ion of atom s.
If you wan t t o fet ch dat a r ow by r ow or if t h e r elat ion h as on ly on e r ow,
you can om it t h e collect ion an d u se a tu ple (or an atom for a on e
at t r ibu t e r elat ion ).
Note
You can en capsu lat e collect ion elem en t s an d t u ple at t r ibu tes.
• Defining buffers
You give t h e n ecessar y in for m at ion abou t t h e r esu lt object an d t h e
par am et er s u sin g t h e define_projection an d define_bind m et h ods.
Th e define_projection m et h od h as a pr oject ion m ech an ism wit h
wh ich you can defin e t h e r esu lt object .
You can declar e a t u ple t ype wit h m or e at t r ibu tes, in a differ en t or der
an d with differ en t n am es t h an in th e r elat ion . To do t h is, you m u st give
a lin k bet ween t h e t u ple at t r ibu tes an d t h e r elat ion at t r ibu t es.
Th is lin k is called th e p r oj ect i on l i st an d is m ade u p of a list of
at t r ibu t e n am es wh er e th e it h m em ber of th e list obt ain s t h e valu e of t h e
ith at t r ibu t e of t h e r elat ion .
Th e ot h er t u ple at t r ibu tes get t h eir defau lt O 2 valu es.
For exam ple, if you wan t to obt ain dat a fr om t h e r elat ion :
Relation [A: integer, B: char(1), C: float, D: char(30)]
26
O2 DBAccess User Man u al
Preparing a statement : Transferring data
You t h en wan t t o st or e th e r esu lt in an object of t h e Employees class,
wh ich is defin ed as follows:
class Employees inherit Parameter type
list (tuple (name: string,
code: integer,
entry_date: Date,
Im por t ed fr om o2kit
dept_id: char,
salary: real))
end;
On ce con n ect ed, logged on an d a con t ext is open ed, you m u st cr eat e a
n ew Employees object :
o2 Employees result_object = new Employees;
Associate you r st at em en t t o t h e open ed con t ext .
context->associate("SELECT A, B, C, D FROM Relation");
D efin e th e r esu lt object u sin g t h e define_projection m eth od (t h e
entry_date att r ibu t e is n ot be valu ed):
context->define_projection(result_object,
list("code", "dept_id",
"salary", "name"));
The define_bind m et h od declar es an object th at will con t ain t h e valu e
of a var iable u sed in t h e SQL st at em en t . A secon d par am et er defin es t h e
position of t h is var iable in t h e SQL st at em en t .
Note
Wit h ORACLE, t h e var iable m ar k er s m u st be called: ":1", ":2", etc.
For exam ple, you wan t to u pdat e t h e C at tr ibu t e wh er e t h e B at t r ibu te is
’C’ an d ’T’ in t h e followin g r elat ion :
Relation[A: integer, B: char(1), C: float, D: char(30)]
For t h is, you defin e t h e Char class as follows.
class Char inherit Parameter public type char end;
On ce con n ect ed, logged on an d a con t ext is open ed, you m u st cr eat e a
n ew Char object .
o2 Char parameter = new Char;
O2 DBAccess User Man u al
27
2
Utilization
Associat e you r statem en t to t h e open ed con t ext.
context->associate("UPDATE Relation SET C=C * 1.1 WHERE B=?");
Defin e t h e r esu lt object u sin g t h e define_bind m et h od.
context->define_bind(parameter, 1);
Fix t h e par am et er valu e an d r u n t h e st at em en t .
*parameter = ’C’;
context->exec;
You can r er u n t h e st at em en t with an ot h er valu e.
*parameter = ’T’;
context->exec;
28
O2 DBAccess User Man u al
Run statement and fetching data
2.5 Run statement and fetching data
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, you can r u n you r
st at em en t u sin g th e exec m et h od.
If t h e st at em en t is a select an d/ or it con t ain s par am et er m ar k er s, you
m u st pr ovide t h e r elevan t t r an sfer in for m at ion as det ailed above in
Sect ion 2.4, an d t h en t r an sfer t h e dat a u sin g t h e fetch m et h od.
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 cr eat e statem en t , an
in ser t st at em en t con t ain in g t h r ee par am et er s, wh ich you wan t 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
m et h ods in or der to pr ocess each st ep.
run body {
o2 Connection host = new Connection;
o2 Session
session;
o2 Context
context1, context2, context3;
host->connect ("where", "username", "password");
session = host->logon ("db name",
"db username/password").session;
context1 = session->open.context;
context1->associate ("CREATE...");
context1->exec;
session->close (context1);
context2 = session->open.context;
context2->associate ("INSERT...?...?...?...");
context2->define_bind (...);
context2->define_bind (...);
context2->define_bind (...);
context2->exec;
...
context2->exec;
session->commit;
session->close (context2);
context3->associate ("SELECT...");
context3->define_projection (...);
context3->exec;
...
context3->fetch (...);
session->close (context3);
host->logoff (session);
host->disconnect;
};
O2 DBAccess User Man u al
29
2
Utilization
2.6 Commit and rollback
Th e commit an d rollback m et h ods 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 .
30
O2 DBAccess User Man u al
Ending a session : Transferring data
2.7 Ending a session
Wh en all you r t r an sact ion s wit h t h e dat abase ar e com plet e, t h e
m et h ods logoff an d disconnect en d t h e session an d con n ection
r espect ively, close t h e con t ext , et c.
run body {
o2 Connection host = new Connection;
o2 Session
session;
o2 Context
context1, context2;
host->connect ("where", "username", "password");
session = host->logon ("db name",
"db username/password").session;
context1 = session->open.context;
/* statements */
session->close(context1);
context2 = session->open.context;
/* statements */
session->close(context2);
host->logoff(session);
host->disconnect;
};
O2 DBAccess User Man u al
31
2
32
Utilization
O2 DBAccess User Man u al
33
C lasses
CLASS SET AND THEIR METHODS
O2 DBAccess is a set of O 2 classes t h at en ables O2 application s to
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 et h ods.
It is divided in t o t h e followin g sect ion s:
• O2DBAccess
• Con n ection
• Session
• Con t ext
O2 DBAccess User Man u al
33
3
Classes
3.1 O2DBAccess
An o2dbaccess object defin es th e com m on r esou r ces of O 2 D BAccess
classes.
It con t ain s on e m et h od, th e server_error m et h od with wh ich you can
obt ain th e RDBMS-det ect ed er r or codes.
34
O2 DBAccess User Man u al
O2DBAccess
server_error method
Summary
Gives t h e RD BM S-det ect ed er r or code.
Syntax
receiver->server_error
Arguments
Non e.
Description
You u se t h is m et h od t o obt ain RDBMS-det ect ed er r or codes.
Returns
Th e code an d it s descr ipt ion . Th e type of th e r et u r n ed valu e is as
follows:
tuple (code: integer, msg: string)
Th e code att r ibu t e con t ain s t h e RDBMS-det ect ed er r or code an d t h e
msg at t r ibu t e con t ain s it s t ext u al descr ipt ion .
Example
#include "o2dbaccess.h"
o2 Context context;
o2 integer status;
o2 tuple(code: integer, msg: string) error;
...
status = context->associate("SELECT * FROM emp");
if (status != O2DB_OK) {
if ( status == o2dbE_SERVER ) {
error = host->server_error;
printf("Server Error (%d): %s\n", error.code, error.msg);
...
O2 DBAccess User Man u al
35
3
Classes
3.2 Connection
A Connection object defin es an d m ain tain s a con n ect ion t o a r em ot e
h ost.
Th e in for m at ion n eeded t o set u p a lin k between t h e O 2 application an d
t h e h ost syst em is fou n d in a con f i gu r at i on f i l e. It is m ade u p of a set of
n et wor k an d h ost-specific par am et er s.
Refer t o Sect ion 4.2 for a fu ll descr iption of t h e con figu r at ion file.
Th is sect ion n ow descr ibes t h e m et h ods associated t o t h e Connection
class:
• connect method
• disconnect method
• logon method
• logoff method
36
O2 DBAccess User Man u al
Connection : connect method
connect method
Summary
Con n ect s t o a r em ote h ost .
Syntax
receiver->connect (c_name, username, password)
Arguments
c_name
is a st r in g t h at defin es t h e lin k par am eter s u sed in t h e
con figu r at ion file.
username
is a st r in g specifyin g t h e h ost u ser n am e.
password
is a st r in g specifyin g t h e h ost u ser passwor d.
Description
Th e connect m et h od set s u p a lin k bet ween th e wor k st at ion an d a
r em ot e Sequ eL i n k ser ver .
Returns
0 if t h e con n ect ion is su ccessfu l or an er r or code if n ot .
Example
o2 Connection host = new Connection;
o2 integer status;
...
supra_server:TCP:salome:LSPSUPRA2:::15:false
Th is is t h e cor r espon din g r esou r ce lin e in t h e con figu r ation file.
status = host->connect("supra_server", "scott", "TIGER");
if (status != 0) {
printf("error in connection (%d)\n",status);
return;
}
O2 DBAccess User Man u al
37
3
Classes
disconnect method
Summary
Discon n ect s t h e r em ot e h ost .
Syntax
receiver->disconnect
Arguments
Non e
Description
Th e disconnect m et h od discon n ect s t h e lin k bet ween th e wor k station
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 of th is
con n ect ion ar e closed.
Returns
Not h in g
Example
o2 Connection host = new Connection;
o2 integer status;
...
supra_server:TCP:salome:LSPSUPRA2:::15:false
Th is is th e cor r espon din g r esou r ce lin e in t h e con figu r at ion file.
status = host->connect("supra_server", "scott", "TIGER");
if (status != 0) {
printf("error in connection (%d)\n",status);
return;
}
...
host->disconnect;
38
O2 DBAccess User Man u al
Connection : logon method
logon method
Logs on t o t h e dat abase.
Summary
Syntax
receiver->logon (logon1, logon2)
Arguments
logon1,logon2
ar e st r in gs t h at specify t h e par am eter s r equ ir ed in
or der to log on to t h e dat abase you ar e u sin g.
Refer t o t h e docu m en t at ion "Usi n g Sequ eL i n k wi t h y ou r Dat abase an d
Ser v er " for t h e specific logon par am eter s n eeded for t h e dat abase you
wan t t o u se. Th e par am eter len gt h m u st be less t h an 256 ch ar act er s.
Description
Th e logon m et h od passes bot h t h e logon1 an d logon2 par am et er s t o
t h e dat abase ser ver . It t h en st ar t s a n ew session by cr eatin g m an object
of class Session.
Returns
An object defin in g a lin k wit h t h e dat abase, or an er r or code if
som et h in g goes wr on g.
Th e t ype of r et u r n ed valu e is:
tuple (retcode: integer, session: Session)
Example
o2 Connection host = new Connection;
o2 tuple (retcode : integer, session : Session) status;
o2 Session session;
...
log on SUPRA Ser ver
status = host->logon("O2SCDEMO",
"connect o2tech identified by beaut");
if (status.retcode != 0) {
printf("error in log on (%d)\n", status.retcode);
return;
}
session = status.session;
...
O2 DBAccess User Man u al
39
3
Classes
logoff method
Summary
En ds a logon session
Syntax
receiver->logoff (session)
Arguments
session
Description
Th e logoff m et h od en ds a specified logon session an d r eleases all it s
r esou r ces. All con t ext s cr eated du r in g t h e session ar e closed.
is a Session object th at r epr esen t s t h e session t o close.
Not e t h at t h e r eceiver object of t h e logoff m et h od m u st be th e sam e as
t h e r eceiver object of t h e logon m et h od t h at or igin ally cr eat ed th e
Session object .
0 if su ccessfu lly logged off or an er r or code if n ot.
Returns
Example
o2 Connection host = new Connection;
o2 integer status;
o2 Session session;
...
status = host->logoff(session);
if (status != 0) {
printf("error in log off (%d)\n", status);
return;
}
40
O2 DBAccess User Man u al
Session : logoff method
3.3 Session
A Session object defin es an d m ain t ain s t h e con n ect ion t o a database
ser ver .
Th e Session class h as t h e followin g m et h ods:
• close method
• commit method
• open method
• rollback method
• sqlquery method
O2 DBAccess User Man u al
41
3
Classes
close method
Summary
Closes a con text .
Syntax
receiver->close (context)
Arguments
context
Description
Th e close m et h od closes a con text an d r eleases all it s r esou r ces.
is a Context object t h at r epr esen t s t h e con t ext to close.
Th e con t ext m u st h ave been cr eat ed by th e r eceiver .
Not e t h at t h e r eceiver object of t h e close m et h od m u st be th e sam e as
t h e r eceiver object of t h e open m et h od t h at or igin ally cr eat ed th e
Context object .
0 if t h e m et h od is su ccessfu l or an er r or code if n ot .
Returns
Example
o2 Session session;
o2 Context
context;
o2 integer status;
o2 tuple (retcode : integer, context : Context) open_status;
...
open_status = session->open;
if (open_status.retcode != 0) {
printf("error in open (%d)\n", open_status.retcode);
return;
}
context = open_status.context;
...
status = session->close(context);
...
42
O2 DBAccess User Man u al
Session : commit method
commit method
Summary
Com m it s m odificat ion s.
Syntax
receiver->commit
Arguments
Non e
Description
Th e commit m et h od com m it s wh at h as been don e in t h e session sin ce
last com m it or st ar t of t h e session .
Returns
0 if t h e m et h od is su ccessfu l or an er r or code if n ot .
Example
o2 Connection host = new Connection;
o2 Session session;
o2 integer status;
o2 tuple (retcode : integer, session : Session) log_status;
...
log on SUPRA Ser ver
log_status = host->logon("O2SCDEMO",
"connect o2tech identified by beaut");
if (log_status.retcode != 0) {
printf("error in log on (%d)\n", log_status.retcode);
return;
}
session = log_status.session;
...
status = session->commit;
...
O2 DBAccess User Man u al
43
3
Classes
open method
Summary
Cr eat es a n ew con t ext .
Syntax
receiver->open
Arguments
Non e.
Description
Th e open m et h od cr eat es a n ew access con t ext for t h e r eceiver by
cr eatin g an object of class Context.
Returns
An object defin in g th e n ew con t ext , or an er r or code if som et h in g wen t
wr on g.
Th e t ype of r et u r n ed valu e is:
tuple (retcode: integer, context: Context)
Example
o2 Session session;
o2 Context
context;
o2 integer status;
o2 tuple (retcode : integer, context : Context) open_status;
...
open_status = session->open;
if (open_status.retcode != 0) {
printf("error in open (%d)\n", open_status.retcode);
return;
}
context = open_status.context;
...
44
O2 DBAccess User Man u al
Session : rollback method
rollback method
Summary
Rever ses all m odificat ion s sin ce last com m it .
Syntax
receiver->rollback
Arguments
Non e.
Description
Th e rollback m eth od r ollback s an y m odificat ion s you h ave car r ied ou t
in t h is session sin ce last com m it .
Returns
0 if t h e m et h od is su ccessfu l or an er r or code if n ot .
Example
o2 Connection host = new Connection;
o2 Session session;
o2 integer status;
o2 tuple (retcode : integer, session : Session) log_status;
...
log on SUPRA Ser ver
log_status = host->logon("O2SCDEMO",
"connect o2tech identified by beaut");
if (log_status.retcode != 0) {
printf("error in log on (%d)\n", log_status.retcode);
return;
}
session = log_status.session;
...
status = session->rollback;
...
O2 DBAccess User Man u al
45
3
Classes
sqlquery method
Summary
Ru n s a statem en t an d fet ch es t h e r esu lt if r equ ir ed.
Syntax
receiver->sqlquery (result, stmt, params, projection)
Arguments
result
is a Parameter object specifyin g wh er e t h e qu er y r esu lt
is st or ed, or n il if n ot r equ ir ed.
stmt
is a st r in g of less th an 4096 ch ar act er s r epr esen tin g t h e
SQL st at em en t t o be r u n .
params
is a list of Parameter objects specifyin g t h e qu er y
par am eter s.
projection
is a list of st r in g specifyin g t h e pr oject ion at t r ibu t es. By
defau lt (projection = list()), t h e qu er y r esu lt fu lly
m atch es t h e O2 class t ype.
Description
Th is m et h od r u n s a st at em en t an d can fetch t h e r esu lt. On ly pr oject ion
at t r ibu tes ar e valu ed (ot h er s get t h eir O 2 defau lt valu es). By defau lt
(projection = list()), t h e r esu lt tot ally m at ch es t h e O2 class t ype.
Returns
An in t eger of t h e n u m ber of fet ch ed r ows if su ccessfu l: O if t h er e is n o
m or e data t o fet ch or a n egat ive n u m ber r epr esen t in g an er r or code.
Example
class Employees inherit Parameter type
list(tuple(name: string, department: integer, salary: real)) end;
class Integer inherit Parameter public type integer end;
class String inherit Parameter public type string end;
run body {
...
o2 Session session;
o2 integer status;
o2 string stmt = "SELECT ename, esalary FROM emp\
WHERE deptno = ? and job = ?";
o2 Employees res = new Employees;
o2 Integer dept = new Integer;
o2 String job = new String;
...
*dept = 80;
*job = "tailor";
status = session->sqlquery(res, stmt, list(dept,job),
list("name", "salary"));
...
res->display;
...
}
46
O2 DBAccess User Man u al
Context : sqlquery method
3.4 Context
A Context object defin es an access con t ext t o a dat abase an d con tain s
in for m ation t h at is r equ ir ed t o execu t e an SQL st at em en t.
Th e Context class h as t h e followin g m et h ods:
• associate method
• define_bind method
• define_projection method
• exec method
• fetch method
O2 DBAccess User Man u al
47
3
Classes
associate method
Summary
Associat es a statem en t wit h an open ed con text .
Syntax
receiver->associate (stmt)
Arguments
stmt
Description
Th e associate m et h od associat es an SQL st at em en t t o t h e con t ext
r eceiver . You can r eu se a con t ext for a n ew qu er y bu t t h e pr eviou s
associat ion is t h en lost .
Returns
0 if t h e m et h od is su ccessfu l or an er r or code if n ot .
is a st r in g of less th an 4096 ch ar act er s r epr esen tin g t h e
SQL st at em en t t o execu t e.
Example
o2
o2
o2
o2
Session session;
Context context;
integer status;
tuple (retcode : integer,
context : Context) open_status;
o2 string stmt = "SELECT ename, esalary\
FROM emp WHERE deptno = 80";
...
open_status = session->open;
if (open_status.retcode != 0) {
printf("error in open (%d)\n", open_status.retcode);
return;
}
context = open_status.context;
status = context->associate(stmt);
...
48
O2 DBAccess User Man u al
Context : define_bind method
define_bind method
Summary
St or es t h e par am et er s in t h e con t ext .
Syntax
receiver->define_bind (param, order)
Arguments
param
order
is a Parameter object t h at will con t ain t h e valu e
cor r espon din g t o a var iable u sed in t h e SQL st at em en t.
is an in t eger specifyin g t h e posit ion of t h is var iable in
th e SQL statem en t . Nu m ber in g begin s at 1.
Description
Th e define_bind m et h od declar es a Parameter object t h at con tain s
t h e cu r r en t valu e cor r espon din g t o a var iable u sed in t h e SQL
statem en t . Th e secon d par am et er defin es t h e posit ion of t h is var iable in
t h e SQL st at em en t . If you u se ORACLE, you m u st call t h e m ar k er
":n", wh er e n is t h e position of t h e var iable in t h e st at em en t .
Returns
0 if t h e m et h od is su ccessfu l or an er r or code if n ot .
Example
class Employees inherit Parameter type
list(tuple(name: string, department: integer, salary: real)) end;
class Integer inherit Parameter public type integer end;
class String inherit Parameter public type string end;
run body {
...
o2 Context context;
o2 integer status;
o2 string stmt = "SELECT ename, esalary FROM emp\
WHERE deptno = ? and job = ?";
o2 Employees res = new Employees;
o2 Integer dept = new Integer;
o2 String job = new String;
...
status = context->associate(stmt);
status = context->define_projection(res, list("name", "salary"));
...
status = context->define_bind(job, 2);
status = context->define_bind(dept, 1);
...
}
O2 DBAccess User Man u al
49
3
Classes
define_projection method
Summary
St or es t h e r esu lt object in th e con t ext .
Syntax
receiver->define_projection (result, projection)
Arguments
result
projection
is a Parameter object specifyin g wh er e t h e r esu lt of t h e
qu er y will be st or ed. Th e par am eter m u st be n ot n il.
is a list of st r in gs specifyin g t h e pr oject ion at t r ibu t es. By
defau lt (projection=list()), t h e qu er y r esu lt m at ch es
t h e O2 class t ype.
Description
Th e define_projection m et h od st or es t h e r esu lt object in t h e con t ext .
Th e qu er y r esu lt is assign ed t o th e valu e of th e r esu lt object . On ly
pr oject ion att r ibu t es ar e valu ed (ot h er s get t h eir O2 defau lt valu es). By
defau lt (projection=list()), t h e qu er y r esu lt m atch es t h e O 2 class
t ype.
Returns
0 if t h e m et h od is su ccessfu l or an er r or code if n ot .
Example
class Employees inherit Parameter type
list(tuple(name: string, department: integer, salary: real))
end;
run body {
...
o2 Session session;
o2 Context context;
o2 integer status;
o2 tuple (retcode : integer, context : Context) open_status;
o2 string stmt = "SELECT ename, esalary\
FROM emp WHERE deptno = 80";
o2 Employees res = new Employees;
...
open_status = session->open;
if (open_status.retcode != 0) {
printf("error in open (%d)\n", open_status.retcode);
return;
}
context = open_status.context;
status = context->associate(stmt);
...
50
O2 DBAccess User Man u al
Context : exec method
exec method
Summary
Ru n s th e qu er y.
Syntax
receiver->exec
Arguments
Non e
Description
Th e exec m et h od bin ds th e cu r r en t valu es defin ed as in pu t t o th e SQL
statem en t an d r u n s t h e qu er y.
Returns
0 if t h e m et h od is su ccessfu l or an er r or code if n ot .
Example
class Employees type
list(tuple(name: string, department: integer, salary: real))
end;
class Integer public type integer end;
class String public type string end;
run body {
...
o2 Context context;
o2 integer status;
o2 string stmt = "SELECT ename, esalary FROM emp
WHERE deptno = ? and job = ?";
o2 Employees res = new Employees;
o2 Integer dept = new Integer;
o2 String job = new String;
...
status = context->associate(stmt);
status = context->define_projection(res,
list("name", "salary"));
...
status = context->define_bind(job, 2);
status = context->define_bind(dept, 1);
...
/* now we can run the query */
*dept = 80;
*job = "tailor";
status = context->exec;
...
}
O2 DBAccess User Man u al
51
3
Classes
fetch method
Summary
Fet ch es th e r esu lt s.
Syntax
receiver->fetch (row_count)
Arguments
row_count
Description
Th e fetch m et h od fet ch es t h e r esu lt s in t o t h e r esu lt object .
Returns
An in t eger of t h e n u m ber of r ows th at wer e act u ally fetch ed. Wh en n o
m or e r ows can be fet ch ed, it r et u r n s 0. If t h e fet ch is u n su ccessfu l, it
r et u r n s an er r or code (a n egat ive n u m ber ). Wit h o2dbW_NOT_UNIQUE,
on ly t h e fir st r ow is st or ed in t h e r esu lt object .
is an in t eger . Th e m axim u m n u m ber of r ows t o fet ch .
You can specify 0 (O2DB_ALL) in or der t o fet ch as m an y
r ows as possible.
Example
class Employees inherit Parameter type
list(tuple(name: string, department: integer, salary: real)) end;
class Integer inherit Parameter public type integer end;
class String inherit Parameter public type string end;
run body {
#include "o2dbaccess.h"
...
o2 Context context;
o2 integer status;
o2 string stmt = "SELECT ename, esalary\
FROM emp WHERE deptno = ? and job = ?";
o2 Employees res = new Employees;
o2 Integer dept = new Integer;
o2 String job = new String;
...
status = context->associate(stmt);
status = context->define_projection(res, list("name", "salary"));
...
status = context->define_bind(dept, 1);
status = context->define_bind(job, 2);
...
/* now you can run the query */
*dept = 80;
*job = "tailor";
status = context->exec;
status = context->fetch(O2DB_ALL);
res->display;
...
*job = "grocer";
status = context->exec;
status = context->fetch(10);
res->display;
...
}
52
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
53
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 or der t o sen d an SQL st at em en t for pr ocessin g on
a r em ot e dat abase.
Th is sect ion en ables you t o follow all t h ese var iou s st eps an d is divided
u p in to t h e followin g section s:
• Defin e t h e sch em a
• Host con n ect ion an d dat abase log on
• Open a con t ext
• Pr epar e th e statem en t
• Ru n th e statem en t
• Close t h e con text
• Fet ch t h e dat a
• Close dat abase session an d en d h ost con n ection
Note
Com m it or r ollback an y ch an ges m ade - th e commit an d rollback
m et h ods depen d on t h e dat abase you ar e u sin g ar e t h er efor e n ot
illu st r at ed in t h is exam ple.
54
O2 DBAccess User Man u al
Example Application : Define the schema
Define the schema
You begin by im por t in g th e o2dbaccess sch em a.
You t h en m u st defin e all t h e var iou s classes (Employees, Integer an d
String) in wh ich t h e r esu lt of you r SQL st atem en t an d t h e qu er y
par am eter s ar e st or ed.
import schema o2dbaccess class Parameter, Connection,
Session, Context;
class Employees inherit Parameter type
list (tuple (name: string,
department: integer,
salary: real))
end;
class Integer inherit Parameter public type integer end;
class String inherit Parameter public type string end;
O2 DBAccess User Man u al
55
4
Appendices
Host connection and database log on
To con n ect t o t h e h ost an d log on to t h e dat abase, you m u st cr eat e a
Connection object .
You m u st t h en call t h e connect an d logon m eth ods on t h is object .
run body {
o2 Connection host = new Connection;
o2 Session sess;
o2 Context
ctxt;
o2 tuple (retcode: integer, sess: Session) log_status;
o2 tuple (retcode: integer, ctxt: Context) open_status;
o2 integer status;
o2 string stmt = "SELECT ename, esalary\
FROM emp\
WHERE deptno = ? and job = ?";
o2 Employees res = new Employees;
o2 Integer dept = new Integer;
o2 String job = new String;
status = host->connect("supra_server", "scott", "TIGER");
if (status != 0) {
printf("error in connection (%d)\n", status);
return;
log on SUPRA Ser ver
}
log_status = host->logon("O2SCDEMO",
"connect o2tech identified by beaut");
if (log_status.retcode != 0) {
printf("error in log on (%d)\n", log_status.retcode);
host->disconnect;
return;
}
Refer t o Sect ion 2.3 an d Sect ion 3.2 for m or e det ails.
56
O2 DBAccess User Man u al
Example Application : Open a context
Open a context
You open a con t ext for each statem en t u sin g t h e open m et h od of t h e
Session object .
Th is object con tain s th e stat em en t an d oth er in for m at ion n eeded for
r u n n in g t h e statem en t .
sess = log_status.sess;
open_status = sess->open;
if (open_status.retcode != 0) {
printf("error in open (%d)\n", open_status.retcode);
host->disconnect;
Close all session s an d discon n ect
return;
}
Refer to Sect ion 2.3 an d Sect ion 3.3 for fu r t h er det ails.
O2 DBAccess User Man u al
57
4
Appendices
Prepare the statement
You m u st associat e a st at em en t by fir st ly associat in g it wit h t h e open ed
con text u sin g t h e associate m eth od.
Th e st at em en t is a select st at em en t an d h as par am et er s. You m u st
t h er efor e defin e an d st or e in t h e con t ext, t h e r esu lt object an d it s
pr oject ion list u sin g t h e define_projection m eth od in con n ect ion
wit h t h e class Employees. You defin e an d st or e t h e par am et er s u sin g
t h e define_bind m et h od in con n ect ion wit h t h e classes Integer an d
String.
ctxt = open_status.ctxt;
status = ctxt->associate(stmt);
if (status != 0) {
printf("error in associate (%d)\n", status);
host->disconnect;
return;
}
status = ctxt->define_projection(res, list("name", "salary"));
if (status != 0) {
printf("error in define_projection (%d)\n", status);
host->disconnect;
return;
}
status = ctxt->define_bind(job, 2);
if (status != 0) {
printf("error in define_bind(2) (%d)\n", status);
host->disconnect;
return;
}
status = ctxt->define_bind(dept, 1);
if (status != 0) {
printf("error in define_bind(1) (%d)\n", status);
host->disconnect;
return;
}
Refer t o Sect ion 2.4 an d Sect ion 3.4 for fu ll det ails.
58
O2 DBAccess User Man u al
Example Application : Run the statement
Run the statement
All t h e r elevan t in for m at ion h as been given .
You can n ow r u n th e statem en t u sin g t h e exec m eth od.
*dept = 80;
*job
= "tailor";
status = ctxt->exec;
if (status != 0) {
printf("error in exec(1) (%d)\n", status);
host->disconnect;
return;
}
Refer to Sect ion 2.5 an d Sect ion 3.4 for fu r t h er details of th is m et h od.
O2 DBAccess User Man u al
59
4
Appendices
Fetch the data
As t h e st at em en t is a select st at em en t , you can t r an sfer data fr om
dat abase t o you r application in t o an O 2 object u sin g th e fetch m et h od.
status = ctxt->fetch(O2DB_ALL);
if (status < 0) {
printf("error in fetch(1) (%d)\n", status);
host->disconnect;
return;
}
else
printf("%d fetched rows\n", status);
res->display;
*job
= "grocer";
status = ctxt->exec;
if (status != 0) {
printf("error in exec(2) (%d)\n", status);
host->disconnect;
return;
}
status = ctxt->fetch(10);
if (status < 0) {
printf("error in fetch(2) (%d)\n", status);
host->disconnect;
return;
}
else
printf("%d fetched rows\n", status);
res->display;
Refer t o Sect ion 2.5 an d Sect ion 3.4 for m or e det ails.
60
O2 DBAccess User Man u al
Example Application : Close the context
Close the context
As t h e st at em en t is n ot r e-r u n , you can n ow close t h e con t ext u sin g t h e
close m et h od of t h e Session object.
status = sess->close(ctxt);
if (status != 0) {
printf("error in close (%d)\n", status);
host->disconnect;
return;
}
Refer to Sect ion 2.7 an d Sect ion 3.3.
Close database session and end host connection
All t h e you r t r an sact ion s wit h dat abase ar e fin ish ed. Th e m et h od
logoff en ds t h e session an d t h e m et h od disconnect en ds t h e
con n ection wt h t h e h ost .
status = host->logoff(sess);
if (status != 0) {
printf("error in log off (%d)\n", status);
host->disconnect;
return;
}
host->disconnect;
}
Refer to Sect ion 2.7 an d Sect ion 3.2 for m or e det ails.
O2 DBAccess User Man u al
61
4
Appendices
4.2 Configuration File
Th e con figu r at ion file o2dbaccess.cf con t ain 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 ot e h ost, in t h e for m of a set of
n et wor k an d h ost-specific par am et er 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 tain 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 t h e wor k in g dir ect or y,
t h en $HOME an d t h en t h e O2 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 t ain s
on e en t r y for each n am ed lin k wit h com m en t s begin n in g with #. Th e lin e
for m at is:
c_name:network:host:service:lu_name:mode:max_contexts: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 connect m et h od.
network
Type of n et wor k pr otocol u sed. Possible valu es: TCP
(MacTCP on Macin t osh ), ADSP, APPC, DECn et ,
NetBIOS an d AppleTalk .
host
RDBMS r em ot e h ost / n ode/ zon e n am e.
service
Sequ eLin k (database) ser vice n am e t h at you wan t t o
con n ect to. You can fin d t h is n am e in t h e ser ver m ap
file on th 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).
mode
APPC m ode in APPC n etwor k pr ot ocol (opt ion al).
max_contexts
In t eger (fr om 0 t o 100) specifyin g m axim u m n u m ber of
con text 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, t h 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 define_projection an d
define_bind m et h ods. Defau lt valu e is false.
Warning !
Th e t ype ch eck in g is n ot su p p or t ed f or al l RDBM S, call O 2 Lin e for m or e
det ails. An exam ple con figu r at ion 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::::
62
O2 DBAccess User Man u al
Possible Errors
4.3 Possible Errors
Each m et h od 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 RDBMSdet ect ed er r or codes u sin g t h e server_error m et h od. See Sect ion 3.1
for a descr ipt ion of t h is m eth od.
• -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
server_error m et h od.
• -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 connect m et h od call.
Act ion :
Ch eck t h e lin k par am at 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:
Connection@connect
Cau se:
You ar e st ill con n ect ed t o a h ost .
Act ion :
Th e connect m et h od was called bu t n ot t h e disconnect
m et h od.
• -3002
Code:
o2dbE_NOT_CONNECT (-3002)
Call:
Connection@logon, 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 et h od call.
O2 DBAccess User Man u al
63
4
Appendices
• -3003
Code:
Call:
o2dbE_NOT_MEMBER (-3003)
Connection@logoff, Session@close
Cau se:
Act ion :
Th e Session / Con t ext object h as n ot been cr eat ed by t h e
r eceiver .
Ch eck th e m eth od call syn t ax.
• -3004
Code:
o2dbE_NOT_LOGON (-3004)
Call:
Session@open, Session@close, Session@commit,
Session@rollback, Session@sqlquery
Cau se:
Not logged on .
Act ion :
Ch eck com plet ion of t h e pr eviou s logon m eth od call.
• -3005
Code:
o2dbE_TOOLONG (-3005)
Call:
Connection@logon, Context@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:
Context@associate, Context@define_projection,
Context@define_bind, Context@exec, Context@fetch
Cau se:
Th e con t ext h as n ot been open ed.
Act ion :
Ch eck t h e com pletion of t h e pr eviou s open m et h od call.
• -3008
Code:
o2dbE_NOSTMT (-3008)
Call:
Context@associate, Session@sqlquery
Cau se:
Th e SQL st at em en t is em pt y.
Act ion :
64
Ch eck th e m eth od call syn t ax.
O2 DBAccess User Man u al
Possible Errors
• -3009
Code:
o2dbE_FILE_NOTFOUND (-3009)
Call:
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:
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 et h od call
syn t ax.
• -3011
Code:
o2dbE_INVALID_RC (-3011)
Call:
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:
Call:
o2dbE_UNKN_NETWORK (-3012)
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:
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
65
4
Appendices
• -3014
Code:
o2dbE_NOT_SELECT (-3014)
Call:
Context@define_projection, Context@fetch,
Session@sqlquery
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:
Context@define_bind
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:
Context@define_projection, Context@define_bind
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:
Context@define_projection, Context@define_bind,
Session@sqlquery
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
66
Code:
o2dbE_NOT_SUPPORTED (-3018)
Call:
Context@define_projection, Context@define_bind,
Session@sqlquery
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
• -3021
Code:
o2dbE_INVALID_NAME (-3021)
Call:
Context@define_projection, Session@sqlquery
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:
Call:
o2dbE_NOT_EXECUTED (-3022)
Context@fetch
Cau se:
Th e stat em en t h asn ’t been execu t ed.
Act ion :
Ch eck t h e com plet ion of t h e pr eviou s exec m et h od call.
• -3023
Code:
o2dbE_NO_MORE_CONTEXTS (-3023)
Call:
Context@open, Session@sqlquery
Cau se:
An at t em pt was m ade t o exceed th e m axim u m n u m ber
open con t ext s allowed.
Act ion :
Close som e con t ext s.
• -3024
Code:
o2dbE_NILREF (-3024)
Call:
Context@define_projection, Context@define_bind,
Context@exec, Context@fetch, Session@sqlquery
Cau se:
Th e r esu lt object or a par am et er is nil.
Act ion :
Ch eck t h e m et h od 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 con t ext s.
O2 DBAccess User Man u al
67
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 O2 Lin e.
• -5001
68
Code:
o2dbW_NOT_UNIQUE (-5001)
Call:
Context@fetch, Session@sqlquery
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
69
INDEX
com m it
Method 30, 43, 54
A
Con figu r at ion
File 62
Applicat ion
Exam ple 54–61
In for m at ion tr an sfer 25
Ar ch itect u r e
Clien t / ser ver 13
O2 10
associat e
Example 58
Method 24, 48
Con n ection
Class 18, 36
Creation 22, 56
Import 55
Methods 22, 36–40
Con t ext
Class 18, 23, 47
Close 23, 61
Import 55
Lin k t o st at em en t 24
Man agem en t 24
Maxim u m n u m ber 23
Methods 47
Open 23, 57
B
Bu ffer s
Data 26
Defin it ion 26
D
C
Data
Access 22
Bu ffer s 26
Fet ch in g 29, 60
Tr an sfer 25
C 11
C++
In t er face 11
Database
Access 22–23
In for m at ion t r an sfer 25
Log off 22, 61
Log on 22, 56
c_name 62
Class 18
Connection 22, 36
Context 47
O2DBAccess 34
Session 22, 41
Clien t / ser ver ar ch it ect u r e 13
close
Example 61
Method 23, 42
70
con n ect
Example 56
Method 22, 37
defin e_bin d
Example 58
Method 24–27, 49
defin e_pr oject ion
Example 58
Method 24–26, 50
O2 DBAccess User Man u al
INDEX
discon n ect
Example 61
Method 22, 31, 38
E
I
import schema 55
In t er n al er r or codes 63
En vir on m en t var iable 62
Er r or codes 24, 63–68
Exam ple applicat ion 54–61
exec
Example 59
Method 29, 51
J
J ava 11
F
L
fet ch
Example 60
Method 29, 52
logoff
Example 61
Method 22, 31, 40
File
Con figu r at ion 62
logon
Example 56
Method 22, 39
lu_name 62
H
M
H ost
Con n ection 22, 56
Discon n ect 22, 31, 61
host 62
Man agin g con t ext s 24
max_contexts 62
O2 DBAccess User Man u al
71
INDEX
M et h od 21
associate 24, 48
close 23, 42
commit 30, 43
connect 22, 37
define_bind 24–27, 49
define_projection 24–26, 50
disconnect 22, 31, 38
exec 29, 51
fetch 29, 52
logoff 22, 31, 40
logon 22, 39
open 23, 44
rollback 30, 45
server_error 35
sqlquery 46
O2 Gr aph 11
O2 Kit 11
O2 Look 11
O2 OD BC 11
O2 Stor e 10
Over view 13
mode 62
P
N
O2 Tools 11
O2 Web 11
open
Example 57
Method 23, 44
OQL 11
network 62
Par am et er
Buffers 26
Class 18, 26
Import 55
Subclass 55
O
R
O2
Ar ch it ectu r e 10
O 2 C 11
O 2 Cor ba 11
O2DBACCESS 62
O2D BAccess
Class 18, 34
Methods 35
r ollback
Method 30, 45, 54
S
O 2 DBAccess 11
o2dbaccess
Schema 18, 55
Sch em a
Defin it ion 18, 55
o2dbaccess.cf 62
O 2 En gin e 10, 12
72
O2 DBAccess User Man u al
INDEX
ser ver _er r or
Error codes 63
Method 24, 35
service 62
Session
Class 18, 22–23, 41
Close 23, 31, 61
Example 57, 61
Import 55
Methods 41
Open 23, 57
sqlqu er y
Method 46
St at em en t
Lin k t o con t ext 24
Pr epar at ion 24, 58
Ru n n in g 29, 59
Syst em
Ar ch it ectu r e 10
T
Tr an sfer r in g dat a 25
type_checking 62
O2 DBAccess User Man u al
73
INDEX
74
O2 DBAccess User Man u al