O2 ODMG Database System Tutorial
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
O2 ODMG
Database System
Tutorial
Release 5.0 - April 1998In for m at ion in t h is docu m en t is su bject t o ch an ge wit h ou t n ot ice an d sh ou ld n ot be con st r u ed as a com m it m en t by O2 Tech n ology. Th e soft war e descr ibed in t h 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 t er m s of t h e agr eem en t . It is again st th e law t o copy t h is softwar e t o m agn et ic t ape, disk , or an y oth 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 ts 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 ted in an y for m or by an y m ean s, elect r on ic, m ech an ical, ph ot ocopy wit h ou t pr ior wr it t en per m ission of O2 Tech n ology. O 2 , O2 En gin e API, O2 C, O 2 DBAccess, O 2 En gin e, O2 Gr aph , O 2 Kit , O2 Look , O2 St or e, O 2 Tools, an d O 2 Web ar e r egist er ed t r adem ar k s of O2 Tech n ology. SQL an d AIX ar e r egist er ed tr 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 M icr osyst em s, In c. X Win dow Syst em is a r egister ed t r adem ar k of t h e Massach u set ts In stit u t e of Tech n ology. Un ix is a r egist er ed tr adem ar k of Un ix Syst em Labor at or ies, In c. H PUX is a r egist er ed t r adem ar k of Hewlet 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 egist er ed t r adem ar k of t h e NeXT Com pu ter , In c. Pu r ify, Qu an t ify ar e r egist er ed t r 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 M icr osoft Cor por at ion . All ot h er com pan y or pr odu ct n am es qu ot ed ar e t r adem ar k s or r egister ed t r adem ar k s of t h eir r espect ive t r adem ar k h older s. In for m at ion in t h is docu m en t is su bject t o ch an ge wit h ou t n ot ice an d sh ou ld n ot be con st r u ed as a com m it m en t by O2 Tech n ology. Th e soft war e descr ibed in t h is docu m en t is deliver ed u n der a licen se or n on disclosu r e agr eem en t.
Who should use this tutorial
Th is t u t or ial is for pr ogr am m er s wh o wish t o wr ite or adapt C++
applicat ion s t o r u n wit h O2 .
It pr esen t s an exam ple applicat ion an d descr ibes t h e st eps r equ ir ed t o por t
t h is applicat ion t o O2 . A pr ior k n owledge of C++ is assu m ed.
It also pr esen t s t h e object qu er y lan gu age (OQL) wh ich can be u sed for
st an d-alon e qu er ies or em bed qu er ies in a C++ pr ogr am .
Th e followin g m an u als give fu r t h er det ails on t h e topics cover ed in t h is
t u t or ial:
ODMG C++ Binding Guide
ODMG C++ Binding Reference Manual
OQL User Manual
O2 System Administration Guide
O2 System Administration Reference Manual
Oth er docu m en t s available ar e ou t lin ed, click below.
See O2 Documentation set.TABLE OF CON TENTS
Th is t u t or ial con t ain s t h e followin g sect ion s:
1 - In t r odu ction
2 - Por t in g a C++ applicat ion
3 - OQL
O2 ODMG Dat abase System Tu t or ial 5TABLE OF CONTENTS
1 Introduction 9
1.1 Introduction to O2 ....................................................................10
Architecture..................................................................................10
1.2 Object Database Management Group (ODMG)...................... 11
The O2 ODMG C++ Binding ......................................................12
1.3 Benefits of porting to O2 .........................................................13
1.4 Example application.................................................................15
Relevant files................................................................................17
1.5 Setup .........................................................................................19
2 Porting a C++ Application 23
2.1 Store C++ objects in an O2 database .....................................26
2.2 Change C++ pointers to persistent pointers .........................28
2.3 Include files...............................................................................32
2.4 Connect to the database..........................................................33
2.5 Run a transaction .....................................................................34
2.6 Create names............................................................................35
2.7 Modify source code..................................................................36
2.8 Create persistent objects ........................................................38
2.9 Build and Run the Application ................................................41
2.10 Replace arrays by collection classes.....................................42
2.11 Build and Run the Application ................................................49
3 OQL 51
3.1 The O2 ODMG Object Query Language .................................52
Interactive ad hoc queries ............................................................52
Accessing data..............................................................................53
6 O2 ODM G D at abase Syst em Tu t or ialTABLE OF CONTENTS
Selecting data............................................................................... 53
Manipulating complex values...................................................... 54
Manipulating polymorphic collections........................................ 54
Composing operators................................................................... 55
3.2 Embedding OQL in C++ .......................................................... 56
3.3 Build and Run the Application ............................................... 58
O2 ODMG Database Syst em Tu t or ial 7TABLE OF CONTENTS 8 O2 ODM G D at abase Syst em Tu t or ial
11 I ntr oduction
In t r odu ct ion t o t h e ben efit s of O2 .
Th is ch apt er br iefly in tr odu ces t h e O2 system an d t h e ben efit s of por t in g
a C++ applicat ion to O2. It con t ain s t h e followin g section s:
• Introduction to O2
• Object D at abase M an agem en t Gr ou p (OD MG)
• Benefits of porting to O2
• Exam ple applicat ion
• Set u p
O2 OD MG Dat abase Syst em Tu tor ial 91 Introduction
1.1 Introduction to O2
Th e O 2 ODM G dat abase syst em is a fu lly OD MG com plian t syst em ,
offer in g a power fu l dat abase en gin e, a C++ pr ogr am m in g in t er face an d
an OQL qu er y in t er face. Th e O2 ODMG dat abase syst em offer s a dat a
m odel fu lly com patible wit h t h e C++ t ype syst em . It pr ovides
t r an spar en t m u lt i-u ser access t o a dat abase an d in clu des a com plet e
em bedded qu er y lan gu age for associat ive access t o dat a.
Th e O 2 system h as been design ed to su ppor t lar ge dat abases wit h a
lar ge n u m ber of u ser s.
O 2 is a t otally open syst em t h at in t egr at es easily wit h ot h er soft war e.
Th e open ar ch it ect u r e of O2 pr ovides con n ect ion s t o r elat ion al dat abase
en gin es, GUI t ools, t h e Wor ld Wide Web, pr ogr am m in g lan gu ages an d
CASE an d m et h odology tools.
O 2 is lan gu age an d com piler in depen den t . To pr ovide m axim u m
flexibilit y you can access t h e sam e dat abase wit h an y of t h e su ppor ted
pr ogr am m in g lan gu ages su ch as C, C++, J ava, Eiffel, Lisp, Objective C
an d O2 C wh ich is a fou r t h gen er at ion object lan gu age.
O 2 applicat ion s can be developed u sin g th e stan dar d pr ogr am m in g
en vir on m en t s available or u sin g O2 Tools. With O 2 , you can u se
st an dar d object -or ien t ed m et h odologies an d associat ed tools (Tr am is,
LOV, Object eer in g, ROSE, et c.).
Architecture
Th e O 2 Syst em su ppor ts a clien t ser ver ar ch itect u r e. Th e clien t an d
ser ver ar e separ at e pr ocesses wh ich com m u n icat e over a n et wor k . Th er e
is u su ally a sin gle ser ver pr ocess wh ich com m u n icat es wit h m u lt iple
clien t s.
Th e ser ver (o2server) is r espon sible for r eadin g an d wr it in g dat a t o
per m an en t st or age, m an agin g con cu r r en t access to t h e dat a fr om
m u lt iple clien ts, back in g u p t h e database an d r ecover in g t h e dat abase
aft er a cr ash .
Th e clien t pr ocess is a u ser application pr ogr am . For t h e pu r poses of
t h is tu t or ial t h e clien t is an exam ple C++ applicat ion . In t h e C++ sam ple
applicat ion t h e com m u n ication wit h t h e ser ver is t r an spar en t t o t h e C++
developer . Th e C++ applicat ion au t om atically com m u n icat es wit h t h e
o2server t h r ou gh t h e O2 C++ r u n tim e libr ar y.
10 O 2 ODM G D at abase Syst em Tu t or ialObject Database Management Group (ODMG) 1.2 Object Database Management Group (ODMG) Th e Object Dat abase Man agem en t Gr ou p (ODMG) is m ade u p of th e leadin g Object D at abase ven dor s plu s a lar ge n u m ber of com pan ies t h at ar e in t er est ed in an ODBM S st an dar d. Th e ODM G h as pr odu ced a st an dar d for object dat abases. Th e OD MG St an dar d is an in t er oper abilit y st an dar d wh ich allows applicat ion s wr it ten t o t h e st an dar d t o r u n on an y com plian t syst em . Th is st an dar d con t ain s five cat egor ies: - Object M odel - Object D efin it ion Lan gu age (ODL) - Object Qu er y Lan gu age (OQL) - C++ Lan gu age Bin din g - J ava Lan gu age Bin din g Th e ODM G Object m odel is an ext en sion of t h e OM G object m odel. Th e object m odel su ppor t s t h e n ot ion s of class, objects wit h at t r ibu t es an d m et h ods, in h er it an ce, an d specialization . Th e exten sion s to t h e OMG object m odel in clu de su ppor t for r elat ion sh ips between object s, su ppor t for collect ion classes an d a set of base classes for dat e, tim e an d ch ar act er str in gs. Th e ODM G-93 st an dar d also allows for explicit n am es for an object or collection . Fr om a n am e, an applicat ion can dir ect ly r et r ieve th e n am ed object an d oper ate on it or n avigat e t o ot h er objects followin g r elat ion sh ip lin k s. A n am e in t h e sch em a plays t h e r ole of a var iable in a pr ogr am . Nam es ar e en tr y poin t s to th e dat abase. Fr om t h ese en tr y poin t s, ot h er object s can be r each ed t h r ou gh associative qu er ies or n avigat ion . Th e O2 OD MG Dat abase is fu lly com patible wit h t h e OD MG object m odel, object qu er y lan gu age (OQL) an d C++ bin din g. O2 ODMG Dat abase System Tu tor ial 11
1 Introduction
The O2 ODMG C++ Binding
Th e ODMG C++ lan gu age bin din g is design ed t o br in g t r an spar en t
per sist en ce t o C++ applicat ion s. Per sist en ce is t h e abilit y for an object t o
ou t live t h e pr ocess wh ich cr eat ed it . Tr an spar en cy applies t o bot h t h e
t ype syst em an d t h e pr ogr am m in g lan gu age. Fr om t h e C++ developer ’s
per spect ive t h er e is a sin gle u n ified t ype syst em acr oss t h e
pr ogr am m in g lan gu age an d t h e dat abase. Th er efor e an y C++ class can
be stor ed in t h e database. Th e dat abase m an ipu lat ion lan gu age is C++
so th er e is n o n eed for a separ at e database pr ogr am m in g lan gu age t o
access an d m an ipu lat e data.
Th e ODMG C++ bin din g con sist s of st an dar d C++ code. Th er e ar e n o
n ew lan gu age con st r u ct s u sed for t h e bin din g. Th e bin din g m ak es u se
of C++ t em plat es t o pr ovide per sisten ce. Sin ce t h e code is st an dar d C++
code t h er e is n ot a special pr e-com piler for t h e sou r ce code, so you can
con tin u e t o u se an y of you r exist in g C++ t ools as well as adopt n ew tools
in th e fu t u r e.
12 O 2 ODM G D at abase Syst em Tu t or ialBenefits of porting to O2
1.3 Benefits of porting to O2
A sh or t ban k in g applicat ion is pr ovided for t h e pu r poses of th is t u t or ial.
It is an au tom at ed teller m ach in e (ATM ) applicat ion . Th e applicat ion
allows u ser s t o login t o t h eir accou n t s t o m ak e deposits or wit h dr awals
an d t o ch eck t h e balan ce of an accou n t or r eview r ecen t t r an sact ion s.
Th e ch an ges r equ ir ed to por t t h e application t o O2 in volve less t h an
10% of t h e code an d t h ou gh on ly a sm all por t ion of code is m odified t h e
applicat ion gain s su bst an t ially in t er m s of fu n ct ion alit y. It gain s in
t er m s of du r abilit y, con cu r r en cy, scalability an d accessibilit y t h r ou gh
OQL.
Th e or igin al ver sion of t h e sou r ce code r eads cu st om er data at st ar t u p
an d wr it es in for m at ion back wh en t h e pr ogr am en ds. If t h e pr ogr am
fails all m odification s m ade will be lost . Th e possibilit y of losin g dat a is
u n accept able. Th e O2 System pr otect s dat a by en su r in g t h at all ch an ges
com m it t ed to t h e dat abase ar e in deed wr it t en t o th e dat abase an d t h at
if a cr ash occu r s t h e dat a is safe fr om cor r u pt ion .
Th e O2 System allows for con cu r r en t access t o dat a. Wit h con cu r r en t
access it is possible t o h ave m u lt iple pr ocesses accessin g t h e dat abase
at th e sam e t im e. For exam ple you cou ld h ave sever al ATM m ach in es
accessin g th e sam e dat abase. Th e dat abase con t r ols t h e access t o t h e
dat a en su r in g t h at ever y clien t h as a con sist en t view of th e dat a.
On e of t h e m ost im por tan t im pr ovem en ts t o t h e sam ple applicat ion will
be t o m ak e t h e application m or e scalable. Th e or igin al applicat ion is
lim it ed in t h e am ou n t of dat a it can st or e t o m ach in e m em or y. By u sin g
t h e O2 dat abase t h e applicat ion is n o lon ger lim it ed in t h is way. Th er e is
n o pr act ical lim it t o th e size of an O2 dat abase.
Th e addit ion of ODMG collect ion classes an d OQL qu er ies r edu ces th e
ph ysical lim itation s of t h e applicat ion . ODM G collection classes pr ovide
flexible collect ion s wh ich can gr ow as dat a expan ds an d t h ey ar e t igh tly
lin k ed t o t h e dat abase en gin e t o pr ovide efficien t cach in g of lar ge
collection s. By r eu sin g t h e OD MG collect ion classes you will also r edu ce
t h e am ou n t of code t h at you n eed t o develop an d m ain t ain .
Th e OQL qu er y lan gu age is an opt im ized qu er y lan gu age. All qu er ies will
be au tom at ically opt im ized t o im pr ove t h e per for m an ce of you r
applicat ion . Th e OQL qu er y lan gu age is a declar at ive qu er y lan gu age so
t h e ph ysical st r u ct u r e of t h e dat a can be ch an ged wit h ou t h avin g to
ch an ge th e qu er y. Th is allows an adm in ist r at or to add in dexes to lar ge
collection s wit h ou t h avin g t o m odify or r ecom pile t h e applicat ion .
O2 ODMG Dat abase System Tu tor ial 131 Introduction
Th e O2 System can r eplace exist in g code th at im plem en ts dat abase t ype
feat u r es t h u s r edu cin g th e am ou n t of code t o be m ain t ain ed. For n ew
developm en t s t h e O2 Syst em r edu ces t h e am ou n t of code r equ ir ed. For
t h e sam ple applicat ion we can r em ove t h e code for t h e
initializeAccounts an d updateAccounts m eth ods. By r em ovin g th e
code wh ich becom es u seless th r ou gh por tin g we r edu ce t h e size of t h e
applicat ion by 200 lin es or 25%.
On e of t h e k ey featu r es of t h e O 2 ODMG C++ Bin din g is t h at it does n ot
ext en d t h e C++ lan gu age t o add special dat abase k eywor ds. Th e bin din g
u ses st an dar d C++ con cept s su ch as t em plates an d in h er it an ce t o
pr ovide con n ect ion t o t h e dat abase. Th e u se of st an dar d C++ does n ot
for ce developer s t o ch an ge t h e m et h ods or t ools t h ey u se t o develop
code. An y t ool t h at can wor k wit h stan dar d C++ can be u sed wit h t h e O 2
ODMG C++ Bin din g. Th ese in clu de fr on t en d case t ools wh ich gen er at e
C++ code, edit or s, debu gger s, m em or y m an agem en t t ools an d t h ir d
par t y class libr ar ies.
Th is t u t or ial is in ten ded t o pr ovide a qu ick in t r odu ct ion t o t h e O2
ODMG C++ In ter face an d t h e OQL qu er y lan gu age. Th er e ar e m an y
im por t an t feat u r es of t h e O 2 Syst em t h at wer e n ot cover ed in t h is
t u t or ial. Th ese in clu de dat abase feat u r es su ch as t r an sact ion types.
sch em a u pdat es, war m an d cold r ecover y, an d su ppor t for con t in u ou s
oper at ion .
An ot h er obviou s advan t age is O2 Tech n ology’s com m it m en t t o in du st r y
st an dar ds. Usin g a syst em t h at com plies wit h in du st r y st an dar ds
en su r es t h e in ter oper abilit y bet ween you r applicat ion an d ot h er t ools
an d does n ot lock you r sou r ce code t o a specific ven dor .
14 O 2 ODM G D at abase Syst em Tu t or ialExample application
1.4 Example application
In t h is t u t or ial we ar e goin g t o be wor k in g wit h a C++ ban k in g
applicat ion wh er e cu st om er s u se au tom at ic t eller m ach in es (ATM) t o
ch eck t h eir accou n ts or car r y ou t sim ple ban k in g t r an sact ion s. Th is is
n ot a pr odu ct ion applicat ion , bu t a sim ple pr ogr am u sed for exam ple
pu r poses on ly. Th e application u ses a sim ple t er m in al in ter face to
com m u n icat e with cu st om er s.
Befor e bein g por ted t o O2 , t h e applicat ion u ses st an dar d oper at in g
syst em files t o st or e in for m at ion abou t cu st om er s an d accou n t s. Wh en
t h e ATM applicat ion is star t ed in for m at ion abou t exist in g accou n t s is
r ead fr om a file an d wh en t h e applicat ion st ops in for m at ion is wr it t en
back t o th e file. Th e class com posit ion is sh own in figu r e 1.
O2 ODMG Dat abase System Tu tor ial 151 Introduction
Terminal ATM
displayLogin cash_balance
displaySelectEvent total_deposits
displayBalance term
displaySelectAccount account_list
displayMessage location
displayPerson lookupAccount
displayEvent dispenseCash
getString printReceipt
getNumber initializeAccounts
getAmount run
Account Address
number Street
balance Person city
description firstName state
owners middleName zip_code
events_completed lastName
lookupOwner personal_id
newOwner accounts
insertEvent address Event
getNumber showDeposits machine
getBalance showWithdraws message
title showEvents amount
deposit execute
withdraw show
Attributes
one to one
Methods Figure 1. one to many
16 O 2 ODM G D at abase Syst em Tu t or ialExample application
Th e in h er itan ce h ier ar ch y of t h e even t classes is sh own in figu r e 2.
Event
depositEvent withdrawEvent balanceEvent
Figure 2.
Relevant files
Th e applicat ion sou r ce code is st or ed in var iou s files:
main.cxx - con t ain s t h e m ain pr ogr am .
atm.hxx an d atm.cxx - con t ain t h e defin it ion of t h e ATM class an d
m et h od defin it ion s.
account.hxx an d account.cxx - con t ain t h e defin it ion s of t h e Addr ess,
Per son an d Accou n t classes an d m et h od defin ition s.
event.hxx an d event.cxx - con t ain t h e defin it ion s of t h e Even t ,
deposit Even t , wit h dr awEven t an d balan ceEven t classes an d t h eir
m et h od defin it ion s.
terminal.hxx an d terminal.cxx - con t ain t h e Ter m in al class
defin ition an d m eth od defin it ion s.
MakefileUnix.original or MakefileNt.original -con t ain th e
m ak efile for com pilin g t h e or igin al ver sion of t h e applicat ion .
Th e m ain r ou t in e of t h e pr ogr am cr eat es t h e ATM, Per son an d Accou n t
object s, fr om dat a in a file an d t h en passes con t r ol t o t h e ATM ::r u n
m et h od. Th e data file is locat ed in dat a/ accou n t s.
Fin ally, README files descr ibe t h e st ep by st ep pr ocess t o r u n t h e
t u t or ial. Please h ave a look at t h em .
O2 ODMG Dat abase System Tu tor ial 171 Introduction
Th e ATM::r u n m et h od con t r ols t h e in t er act ion bet ween cu st om er s an d
accou n t s. Th e m et h od fir st displays a login pr om pt t o t h e u ser . Th e
login pr ocess pr odu ces an accou n t n u m ber an d a per son al iden t ificat ion
n u m ber (PIN). Th e ATM:look u pAccou n t m eth od is t h en u sed t o fin d an
accou n t cor r espon din g t o th e accou n t n u m ber . Th en t h e
Accou n t ::look u pOwn er m et h od is u sed t o look u p a Per son based on t h e
PIN. Th e t er m in al t h en displays a list of action s t h at t h e cu st om er can
t ak e.
Th e act ion s ar e r epr esen t ed as even t object s wh ich r epr esen t t h e
in t er face between cu stom er s an d t h eir accou n t s. Even t object s ar e
saved in t h e dat abase t o m ain t ain an accou n t h ist or y. Even t object s ar e
t h e on ly n ew object s cr eat ed in t h e database wh ile th e ATM:Ru n m et h od
is r u n n in g. Th e ot h er object s in th e database ar e on ly m odified wh en t h e
ATM is r u n n in g, for in st an ce t h e Accou n t object is u pdat ed t o r eflect
an y ch an ge in t h e balan ce of t h e accou n t an d also t o add even t s t o t h e
even t h ist or y.
18 O 2 ODM G D at abase Syst em Tu t or ialSetup
1.5 Setup
It is assu m ed t h at t h e O2 soft war e is in st alled. If t h is is n ot t h e case,
r efer t o t h e O2 In st allat ion sh eet for fu r t h er det ails.
Th e O2 system m u st be set u p befor e you can begin por t in g t h e exam ple
applicat ion .
Set an en vir on m en t var iable called O2HOME specifyin g t h e dir ector y path
wh er e t h e O2 soft war e is in st alled.
Position you r self at O2HOME:
> cd $O2HOME
Add th e O2HOME/bin dir ect or y t o th e path in each wor k in g win dow:
> set path = ($O2HOME/bin $path)
In or der t o r u n t h e O 2 Syst em you n eed to h ave a .O2KEYS licen se file
for th e m ach in e you ar e r u n n in g on . Th e .O2KEYS file sh ou ld be st or ed
in th e O2 in st allat ion dir ect or y.
Th e o2server pr ogr am calls t h e O2 dat abase ser ver . Each o2server
r u n s a sin gle n am ed syst em . Th e logical defin it ion for each syst em is
given in t h e .o2serverrc file locat ed in t h e O2HOME dir ect or y. Th e
.o2serverrc file con t ain s t h e syst em n am e, n am e of t h e ser ver
m ach in e, t h e locat ion of t h e catalog, log an d sh adow dir ect or y. For
m or e in for m at ion abou t th e .o2serverrc file r efer t o t h e O2 System
Adm in ist r at ion Gu ide. Fr om th e O2HOME dir ect or y u se t h e followin g
com m an ds t o cr eat e a .o2serverrc file for t h e tu tor ial.
> mkdir o2vol
Edit t h e .o2ser ver r c file an d add th e followin g lin es:
demo.server =
demo.cataldir = $O2HOME/o2vol
demo.logdir = $O2HOME/o2vol
demo.shadowdir = $O2HOME/o2vol
wh er e is h e n am e of t h e m ach in e wh er e th e O2 ser ver will
run.
Th e defau lt syst em n am e an d ser ver n am e can be specified by
th e en vir on m en t var aible O2OPTIONS. Use th e followin g
com m an ds t o set O2OPTIONS:
O2 ODMG Dat abase System Tu tor ial 191 Introduction
On Un ix,
(in sh) set O2OPTIONS "-system demo -server
; export O2SYSTEM
(in csh) setenv O2OPTIONS "-system demo -server
"
On Win dows NT, u se th e Environment tab of t h e syst em pr oper t ies
pan el to set t h e O2OPTIONS var iable.
Th e O2OPTIONS en vir on m en t var iable is u sed by all O 2 u t ilit ies
pr ogr am s.
You m u st in it ialize a syst em befor e you can r u n a dat abase ser ver . Th e
in it ializat ion pr ocess cr eat es t h e files u sed by th e dat abase ser ver . To
in it ialize th e system u se th e followin g com m an d.
> o2dba_init -system demo -server
Now st ar t t h e dat abase ser ver for t h e system with t h e followin g
com m an d:
> o2server -system demo
Each syst em can con t ain m u lt iple sch em as an d bases. A schema is a
collect ion of class defin ition s. A base is a collect ion of in st an ces of
classes. Sch em as allow for t h e r eu se of code by let t in g you or gan ize a
gr ou p of classes t h at wor k t oget h er in t o a sin gle sch em a. For in st an ce,
you cou ld cr eat e a cu st om er sch em a t h at cou ld con t ain sever al classes
to deal with cu st om er s. Th en an y ot h er applicat ion th at n eeded to deal
with cu st om er s h as on ly t o im por t th e r elevan t classes fr om t h e
cu st om er sch em a.
You m u st cr eat e t h e schema an d base for t h e t u t or ial. Th is can be don e
fr om a C++ pr ogr am or in t er act ively u sin g t h e O2 adm in ist r at ion tools.
We will cr eat e th e schema an d base in t er actively. Fir st st ar t t h e O2
adm in ist r at ion t ool.
> o2dsa_shell
Now cr eat e t h e sch em a an d base. Com m an ds ar e con fir m ed by t ypin g a
n ew lin e followed by ctr l D.
schema bankSchema;
base bankBase;
quit;
^D
20 O 2 ODM G D at abase Syst em Tu t or ialSetup Now copy t h e t u t or ial sou r ce code t o a wor k in g dir ect or y. To com plet e t h e tu t or ial you will n eed appr oxim at ely t en m egabyt es of disk space in t h e wor k in g dir ect or y. To copy t h e sou r ce code t o a dir ect or y called working_directory execu t e t h e followin g: On Un ix, > cd $O2HOME/samples/o2cplusplus/odmg_tutorial/ > cp -r * working_directory On Win dows NT, sim ply m ak e a copy/paste oper at ion t o t h e folder u sin g t h e NT Explor er . Th e dir ect or y called wor k in g_dir ect or y m u st alr eady exist . Now m ove t o t h e wor k in g dir ect or y On Un ix, > cd working_directory/original On Win dows NT, > cd working_directory\original You ar e n ow r eady t o por t t h e exam ple applicat ion t o O 2 . O2 ODMG Dat abase System Tu tor ial 21
1 Introduction 22 O 2 ODM G D at abase Syst em Tu t or ial
22 P orting a C++
A p p l i ca ti o n
Th is ch apt er descr ibes h ow to por t an exam ple C++ applicat ion t o O2 .
It con tain s th e followin g sect ion s:
• St or e C++ object s in an O2 dat abase: im por t in g class defin it ion s t o O 2
• Ch an ge C++ poin t er s t o per sist en t poin t er s
• In clu de files
• Con n ect t o t h e database
• Ru n a t r an sact ion
• Cr eat e n am es
• M odify sou r ce code
• Cr eat e per sisten t object s
• Replace ar r ays by collect ion classes
O2 OD MG Dat abase Syst em Tu tor ial 232 Porting a C++ Application
Th e exam ple application wor k s in it s cu r r en t st at e. Befor e pr oceedin g
we su ggest you br owse t h r ou gh t h e files t o fam iliar ize you r self wit h t h e
applicat ion , th en com pile, lin k an d execu te it . To com pile an d lin k t h e
applicat ion en t er th e followin g com m an d:
On Un ix
> make -f MakefileUnix.original
On Win dows NT
> nmake -F MakefileNt.original
On ce it h as been com piled r u n t h e pr ogr am t h r ou gh t h e followin g
com m an ds:
Star t t h e applicat ion
> bank
En ter t h e Accou n t n u m ber 11111 at t h e pr om pt an d pr ess en t er . Th e
followin g will be displayed.
Welcome to the Bank of O2
Enter Account Number, 0 to exit
> 11111
At th e per son al ID pr om pt en ter t h e n u m ber 9999 an d pr ess en t er .
Enter Personal ID Number, 0 to exit
> 9999
You ar e n ow logged in t o t h e syst em so you can car r y ou t t r an sact ion s
wit h t h e accou n t s available.
Now exit t h e pr ogr am .
We will n ow go t h r ou gh t h e st eps n ecessar y t o por t t h e existin g
applicat ion t o th e O2 Syst em . Figu r e 3 sh ows th e im por t , com pile an d
lin k st eps t h at ar e n ecessar y t o gen er at e an O2 C++ dat abase
applicat ion .
24 O 2 ODM G D at abase Syst em Tu t or ialC++ Class
Definitions
o2import
Generated Application
C++ Code C++ Code
C++ Compiler
O2 Object
Database Runtime Code
Library
Linker
Executable
Application
O2 Runtime
Library
Figure 3.
O2 ODMG Dat abase System Tu tor ial 252 Porting a C++ Application
2.1 Store C++ objects in an O2 database
To st or e a C++ object in an O2 database, t h e dat abase n eeds in for m ation
on t h e st r u ct u r e of t h e object . You can su pply th is in for m at ion by
im por t in g C++ class defin it ion s. Th e im por t pr ocess par ses class
defin it ion s to gen er at e m et a in for m at ion for t h e dat abase an d it
en h an ces t h e exist in g class defin it ion s t o add per sist en ce. An en h an ced
class defin it ion is a su bclass of a r oot per sist en t class (o2 _r oot ) an d
sever al m et h ods ar e gen er ated for t h e class wh ich m an age in t er action
wit h t h e dat abase.
On ce t h e class h as been im por t ed in t o O2 , in stan ces of t h e class can be
st or ed in t h e database or can con t in u e t o be u sed as n or m al t r an sien t
C++ object s. Su ch classes ar e k n own as per sist en t capable classes.
Th e o2cpp_import tool im por t s class defin it ion s in t o O 2 . To sim plify th e
pr ocess of im por t in g m u ltiple classes in t o O2 a u t ilit y is pr ovided. Th is is
o2makegen an d it gen er ates a M ak efile t o im por t all you r classes. Th e
gen er at ed Mak efile can be u sed dir ect ly or can be in t egr at ed in t o you r
exist in g m ak e pr ocess.
Th e o2makegen pr ogr am t ak es a con figu r at ion file as in pu t . Th e
con figu r at ion file for t h is tu t or ial is alr eady wr it ten . Th e file is
bank.config. Th is con figu r at ion file in clu des com m en ts wh ich descr ibe
t h e syn t ax. You sh ou ld r eview th is file t o bet ter u n der st an d th e
in for m at ion n eeded t o im por t classes in t o O2 .
Th e files im por ted m u st be com pilable in C++ or self-con t ain ed. H eader
files ar e u su ally par sed du r in g t h e com pilat ion of a sou r ce file. Th e
sou r ce file m ay pr ovide con t ext in for m at ion t h at is n eeded t o par se t h e
h eader file. Com m an d lin e opt ion s m ay also pr ovide vit al in for m at ion .
Most h eader files ar e self con t ain ed, h owever .
Som e h eader files do r equ ir e addition al con t ext in for m at ion t o be
im por t ed in t o O 2 . Th e m ost com m on addit ion al in for m ation n eeded is
ot h er class defin it ion s. Th e best way t o solve t h is is to or der t h e im por t
pr ocess so t h at an y class defin it ion n eeded by a class h as alr eady been
im por t ed.
Som et im es a closed cir cle of poin t er s can exist in class defin it ion s, for
exam ple:
class A { B *pointer };
class B { A *pointer };
To br eak t h is cycle you can u se t h e ImpForwardClasses opt ion with
o2makegen t o declar e classes wh ich ar e n eeded t o par se a file, bu t
wh ich h ave n ot yet been defin ed.
26 O 2 ODM G D at abase Syst em Tu t or ialStore C++ objects in an O2 database On ce im por t ed, t h e en h an ced per sist en t capable class defin it ion s m u st be u sed in st ead of t h e or igin al t r an sien t class defin ition s. You can eit h er h ave t h e o2cpp_import over wr it e t h e or igin al ver sion of th e h eader file or wr it e it t o an ot h er file. In t h is exam ple we do n ot over wr it e t h e h eader files. Th e lin e "[FILENAM E]Im pOu t pu t Dir : ou t pu t " in bank.config specifies t h at th e gen er at ed files sh ou ld be st or ed in t h e output dir ect or y. To gen er ate t h e Mak efile for t h e applicat ion execu t e t h e followin g com m an d: > o2makegen bank.config O2 ODMG Dat abase System Tu tor ial 27
2 Porting a C++ Application
2.2 Change C++ pointers to persistent pointers
For each class T im por t ed in t o O 2 an an cillar y class d_Ref is
available. An in stan ce of t h e d_Ref class is called a per sist en t poin t er .
Th e per sist en t poin t er is t h en u sed t o r efer en ce an in stan ce of a
per sist en t capable class. Per sist en t poin t er s ar e m an ipu lat ed in t h e
sam e way as st an dar d C++ poin t er s. Per sist en t poin t er s m ain tain a
r elat ion sh ip bet ween two object s per m an en t ly in t h e dat abase.
Stan dar d C++ poin t er s r efer t o an addr ess wh ich is valid on ly wh ile a
pr ogr am is execu t in g.
Befor e im por t in g class defin ition s in to O2 you m u st ch an ge st an dar d
C++ poin t er s in per sist en t capable classes to per sisten t poin t er s. For
in st an ce in t h e exam ple applicat ion t h e Per son class h as a poin t er t o an
addr ess object .
class Person {
...
Address *address;
...
};
So t h at t h e dat abase can m ain t ain t h e r elat ion sh ip bet ween t h e Per son
an d t h e Addr ess you n eed t o ch an ge t h e poin t er t o a per sist en t poin t er .
class Person {
...
d_Ref address;
...
};
Th e per sist en t poin t er m ech an ism offer s a n u m ber of advan t ages t o t h e
C++ pr ogr am m er . Per sist en t poin t er s ch eck r efer en t ial in tegr it y so you r
dat a is safe fr om cor r u pt ion by dan glin g poin ter s. A per sist en t poin t er
can addr ess m or e dat a t h an th e st an dar d 32 bit C++ poin t er so you r
dat abase can be scaled t o a lar ger size.
o2cpp_import h elps you by au t om at ically m odifyin g t h e class defin ition
t o u se per sist en t poin t er s in st ead of st an dar d C++ poin t er s. If an
at t r ibu t e is a poin t er t o an ot h er k n own per sist en t class th e poin t er will
au tom at ically be ch an ged t o a per sist en t poin ter . Th e m et h od
sign at u r es m ay also con t ain r efer en ces t o per sist en t capable classes.
However , m et h od sign at u r es m ay or m ay n ot n eed t o be ch an ged
depen din g on wh et h er or n ot t h e dat a r efer en ced is per sist en t . For t h is
r eason m et h od sign at u r es ar e n ot m odified by o2cpp_import an d it is
left t o you t o decide if m eth od sign atu r es sh ou ld be ch an ged.
In t h e accou n t .h xx file you on ly n eed t o ch an ge t wo m et h od sign at u r es
of t h e Accou n t class. Th e Per son an d Addr ess class can be im por t ed
wit h ou t ch an ge. You m u st m ak e t h e ch an ges ou tlin ed below t o t h e
Accou n t class.
28 O 2 ODM G D at abase Syst em Tu t or ialChange C++ pointers to persistent pointers
Wh en m ak in g ch an ges you can delet e lin es or con ver t t h em t o
com m en t s. Bot h t h e or igin al ver sion an d th e m odified ver sion ar e in t h e
file. Th e m odified ver sion is in com m en t s. You n eed on ly r em ove th e
com m en t s an d delete t h e or igin al ver sion or con ver t it t o com m en t s. Th e
best way t o fin d t h e lin es t h at n eed t o be ch an ged is t o sear ch for t h e
class n am e or m et h od n am e wh er e t h e ch an ge tak es place. Th e lin e "/ /
ODMG Per sist en t Ver sion " sh ou ld r em ain in com m en ts.
• account.hxx file
In t h e Accou n t class defin it ion in t h e accou n t .h xx file delet e or
com m en t ou t th e followin g lin es:
// Original Version
Person *lookupOwner(int pin_number) const;
void newOwner(Person *NewOwner);
void insertEvent(Event* event);
an d add or u n -com m en t th e followin g lin es in t h eir place:
// ODMG Persistent Version
d_Ref lookupOwner(int pin_number) const;
void newOwner(d_Ref &NewOwner);
void insertEvent(const d_Ref &event);
You m u st also ch an ge t h e cor r espon din g sign at u r e of th e m et h od
defin ition .
• account.cxx file
In t h e file accou n t .cxx delet e or com m en t ou t t h e followin g lin e:
// Original Version
Person * Account::lookupOwner(int pin_number) const {
an d add or u n -com m en t t h e followin g lin e in it s place:
// ODMG Persistent Version
d_Ref Account::lookupOwner(int pin_number)
const{
In t h e file accou n t .cxx delet e or com m en t ou t t h e followin g lin e:
// Original Version
void Account::newOwner(Person *NewOwner) {
an d add or u n -com m en t t h e followin g lin e in it s place:
// ODMG Persistent Version
void Account::newOwner(d_Ref &NewOwner) {
O2 ODMG Dat abase System Tu tor ial 292 Porting a C++ Application
In t h e file accou n t .cxx delet e or com m en t ou t t h e followin g lin e:
// Original Version
void Account::insertEvent(Event* event) {
an d add or u n -com m en t t h e followin g lin e in it s place:
// ODMG Persistent Version
void Account::insertEvent(const d_Ref &event) {
• atm.hxx file
In t h e file at m .h xx again you on ly n eed t o ch an ge t h e m et h od
sign at u r es. Mak e t h e ch an ges ou t lin ed below t o at m .h xx.
In t h e ATM class defin it ion in t h e file at m .h xx delet e or com m en t ou t t h e
followin g lin es:
// Original Version
Account *newAccount(int account_number, ...);
Account *lookupAccount(int account_number) const;
an d add or u n -com m en t t h e followin g lin es in t h eir place:
// ODMG Persistent Version
d_Ref newAccount(int account_number, ...);
d_Ref lookupAccount(int account_number) const;
Again ch an ge t h e cor r espon din g sign at u r es in t h e m et h od defin it ion s.
• atm.cxx file
In t h e file at m .cxx delet e or com m en t ou t th e followin g lin e:
// Original Version
Account * ATM::lookupAccount(int account_number) const
an d add or u n -com m en t t h e followin g lin e in it s place
// ODMG Persistent Version
d_RefATM::lookupAccount(int
account_number)const
In file atm .cxx delet e or com m en t ou t t h e followin g lin e:
// Original Version
Account * ATM::newAccount(int account_number, ...) {
an d add or u n -com m en t t h e followin g lin e in it s place
// ODMG Persistent Version
d_Ref ATM::newAccount(int account_number,
...);
30 O 2 ODM G D at abase Syst em Tu t or ialChange C++ pointers to persistent pointers
• terminal.hxx file
In file ter m in al.h xx in t h e class Ter m in al delet e or com m en t ou t t h e
followin g lin es:
// Original Version
Account *displaySelectAccount(const Person* customer)
const;
void displayPerson(const Person *customer) const;
an d add or u n -com m en t t h e followin g lin e in th eir place
// ODMG Persistent Version
d_Ref displaySelectAccount(const d_Ref
&customer) const;
void displayPerson(const d_Ref &customer)
const;
On ce again ch an ge t h e cor r espon din g m et h od defin it ion s.
• terminal.cxx file
In file ter m in al.cxx delet e or com m en t ou t t h e followin g lin e:
// Orignal Version
Account* Terminal::displaySelectAccount(const Person*
customer) const{
an d add or u n -com m en t t h e followin g lin e in it s place
// ODMG Persistent Version
d_Ref Terminal::displaySelectAccount(const
d_Ref& customer) const {
In file ter m in al.cxx delet e or com m en t ou t t h e followin g lin e:
// Original Version
void Terminal::displayPerson(const Person *customer)
const {
an d add or u n -com m en t t h e followin g lin e in it s place
// ODMG Persistent Version
void Terminal::displayPerson(const d_Ref&
customer) const{
O2 ODMG Dat abase System Tu tor ial 312 Porting a C++ Application
2.3 Include files
You m u st add t h e followin g in clu de files t o t h e applicat ion . Th ese
in clu de files con t ain t h e object s, classes an d fu n ct ion s wh ich pr ovide
t h e in t er face bet ween t h e applicat ion an d t h e database.
Th e atm .h xx file is in clu ded by ever y sou r ce file so we will add t h e
in clu de lin es t o t h at file.
• atm.hxx file
In t h e file at m .h xx add or u n -com m en t t h e followin g lin es
// ODMG Persistent Version
// Contains d_Session, d_Database and d_Transaction
classes
#include “o2lib_CC.hxx
// Contains templates for d_Ref, d_Set, d_List, ...
#include “o2template_CC.hxx”
// Contains OQL interface
#include “OQL_CC.hxx”
32 O 2 ODM G D at abase Syst em Tu t or ialConnect to the database
2.4 Connect to the database
Th e ODM G C++ bin din g con t ain s a set of classes for database
m an agem en t. Th e d_Session class set s u p com m u n icat ion s between a
C++ applicat ion an d a dat abase ser ver . Th e d_D at abase class is u sed t o
cr eat e, dest r oy, open an d close a dat abase. Th e d_Dat abase class can
also be u sed t o cr eat e an d dest r oy n am es in t h e dat abase as well as
associat in g C++ var iables t o n am es. Th e d_Tr an sact ion class star t s an d
en ds t r an sact ion s wit h t h e dat abase. You n eed to add in st an ces of all of
t h ese classes t o th e exam ple applicat ion .
Th e d_Session class h as a begin m et h od t o est ablish com m u n ication
wit h t h e dat abase ser ver . Th e followin g lin e in t h e sou r ce code sh ows
t h e call t o begin :
session.set_default_env();
if (session.begin(argc,argv)) {
Th e par am et er s passed t o begin ar e t h e ar gc an d ar gv par am et er s
passed t o t h e m ain r ou t in e. Th e set _defau lt _en v m et h od sets t h e O2
Syst em n am e, t h e n am e of t h e m ach in e t h at t h e O2 Ser ver is r u n n in g
on an d t h e locat ion of th e O2 soft war e.
Th e d_Session class also h as an en d m et h od. Th is m eth od closes t h e
con n ection wit h th e dat abase. Th e followin g lin e fr om t h e sou r ce code
sh ows t h e call to en d:
session.end();
Aft er con n ect in g t o t h e dat abase ser ver t h e applicat ion m u st specify
wh ich dat abase t o open . Th e followin g lin e sh ows t h e call n eed t o open
t h e ban k Base dat abase.
database_g->open("bankBase");
It is possible t o open an d close m u lt iple dat abases in a sin gle session .
Th e followin g lin e sh ow th e call n eeded t o close t h e dat abase
database_g->close();
O2 ODMG Dat abase System Tu tor ial 332 Porting a C++ Application
2.5 Run a transaction
In or der t o m odify dat a in t h e database you n eed to be in a t r an sact ion .
Th e t r an sact ion m ech an ism pr ot ect s an applicat ion again st failu r e an d
en su r es t h at dat a is con sist en t in a m u lt i-u ser en vir on m en t .
In side a t r an sact ion , O2 pr ovides an isolat ion pr oper t y by lock in g t h e
objects. Con sequ en t ly, in cer tain cir cu m st an ces a t r an sact ion wait s
u n t il an oth er t r an sact ion com m its.
To m in im ize t h e wait t im e, we declar e a t r an sact ion on ly in t h e m et h ods
th at m odify t h e dat a.
• account.cxx file
In th e m et h od Accou n t ::deposit add or u n -com m en t t h e followin g lin es:
d_Transaction transaction;
transaction.begin();
...
transaction.validate();
In th e m et h od Accou n t ::wit h dr aw add or u n -com m en t t h e followin g
lin es:
d_Transaction transaction;
transaction.begin();
...
transaction.validate();
• atm.cxx file
In th e m et h od ATM::in it ializeAccou n t s() add or u n -com m en t t h e
followin g lin es:
d_Transaction transaction;
transaction.begin();
...
transaction.validate();
34 O 2 ODM G D at abase Syst em Tu t or ialCreate names
2.6 Create names
You will n eed t o cr eat e n am es in th e dat abase. A n am e is t h e en t r y poin t
for t h e application to th e database. You can cr eat e a sin gle n am e for t h e
ATM object , ATM_MACH INE an d th en access all per sist en t dat a by
t r aver sin g fr om t h e n am ed ATM object . Sin ce t h e n am e n eeds t o be
cr eat ed on ly on ce you can cr eat e it du r in g in it ializat ion . Th e
set_object _n am e m et h od of t h e d_Database class is u sed t o cr eate t h e
n am e. Th e followin g lin e sh ows t h e call n eeded t o cr eat e t h e
ATM _MACHINE n am e
database_g-> set_object_name(atm_machine,
"ATM_MACHINE");
On ce t h e n am e is cr eat ed you access t h e n am e t h r ou gh a per sist en t
poin t er . You can associat e a per sist en t poin t er wit h a n am ed object by
t r an sm it t in g t h e n am e as an ar gu m en t t o t h e con str u ct or . For exam ple:
d_Ref machine("ATM_MACHINE");
Th e r elat ion sh ip can also be est ablish ed by u sin g t h e
d_Dat base::look u p_object m et h od. We will u se t h e look u p_object
m et h od for t h e ATM applicat ion sin ce th e per sist en t poin t er is declar ed
befor e t h e n am e h as been cr eat ed. Th e followin g lin e sh ows t h e call
n eeded t o look u p th e n am e ATM_MACH INE
atm_machine->lookup_object("ATM_MACHINE");
O2 ODMG Dat abase System Tu tor ial 352 Porting a C++ Application
2.7 Modify source code
We n eed t o cr eat e an in st an ce of d_D at abase in global scope so t h at we
can cr eate n ew object s in t h e database in an y fu n ct ion or m et h od.
Near lin e 80 in m ain .cxx add or u n -com m en t th e followin g global
declar at ion .
• main.cxx file
In t h e file m ain .cxx n ear lin e 80 add or u n -com m en t t h e followin g global
declar at ion .
d_Database* database_g = new d_Database;
We also n eed t o add a declar at ion so t h at ot h er files can access t h e
global var iable. We will add th e declar at ion t o t h e file at m .h xx sin ce it is
in clu ded by ever y sou r ce file.
• atm.hxx file
In file atm .h xx add or u n -com m en t t h e followin g lin es:
// ODMG Persistent Version
// Global database pointer for creating objects in the
database
extern d_Database* database_g;
You can t h en add th e code t o est ablish a con n ect ion with t h e dat abase,
open t h e ban k Base dat abase, st ar t t h e t r an sact ion , cr eat e th e n am es in
t h e dat abase, en d th e t r an sact ion , close t h e ban k Base an d fin ally close
t h e con n ect ion wit h t h e dat abase.
In t h e class ATM add or u n -com m en t t h e followin g lin e:
void d_activate {term = new Terminal;}
You m u st in itialize t h e t em por ar y at tr ibu t e t er m wh en t h e per sist en t
object of t h e class ATM is r ead fr om t h e dat abase for th e fir st t im e.
• main.cxx file
In t h e file m ain .cxx delete or com m en t ou t t h e followin g lin es:
// Original Version
ATM* atm_machine;
atm_machine->initializeAccounts();
atm_machine = new ATM;
atm_machine->run();
an d add or u n -com m en t t h e followin g lin es in t h eir place, n ot e t h at t h e
com m en ted ou t por t ion begin s wit h "/ * BEGIN PERSISENT VERSION"
36 O 2 ODM G D at abase Syst em Tu t or ialModify source code
an d en ds wit h "END PERSISTENT VERSION */ " in st ead of th e "/ / "
com m en t s:
// ODMG Persistent Version
/* BEGIN PERSISTENT VERSION */
d_Session session;
d_Transaction transaction;
// ODMG Persistent Version
d_Ref atm_machine;
session.set_default_env();
if (session.begin(argc,argv)) {
cerrinitializeAccounts();
} else {
database_g->open("bankBase");
atm_machine =
database_g->lookup_object("ATM_MACHINE");
}
if (! atm_machine) {
cerr close();
session.end();
/* END PERSISTENT VERSION */
Now you ar e r eady t o cr eat e object s in t h e dat abase.
O2 ODMG Dat abase System Tu tor ial 372 Porting a C++ Application
2.8 Create persistent objects
In t h e OD MG bin din g, per sist en ce is specified at object cr eat ion tim e. If
you wan t t o cr eat e a per sist en t object you t r an sm it a d_Database
poin t er t o t h e n ew oper at or of t h e object . Sin ce all per sist en t dat a is
accessed fr om n am es, each n ewly cr eated per sist en t object sh ou ld be
at t ain able fr om a n am e. An object can be associat ed dir ect ly wit h a
n am e or an object can be in dir ect ly att ain able fr om a n am e th r ou gh
per sist en t poin t er s.
Th e allocat ion st at em en ts in t h e exam ple applicat ion m u st be m odified
t o cr eat e per sist en t object s in st ead of t r an sien t on es. Som e local
var iable declar ation s wh ich ar e poin t er s t o per sist en t object s n eed t o be
ch an ged t o per sist en t poin ter s. Th is en su r es th at per sist en t object s ar e
k ept in t h e C++ cach e. Th e dat abase will swap per sist en t object s ou t of
t h e cach e t h at ar e n o lon ger poin t ed t o by a per sisten t poin t er .
• account.cxx file
In file accou n t .cxx in t h e m et h od Accou n t ::deposit delet e or com m en t
ou t t h e followin g lin es:
// Original Version
depositEvent* event = new depositEvent(machine_g);
an d add or u n -com m en t t h e followin g lin es in t h eir place
// ODMG Persistent Version
d_Ref event = new(database_g)
depositEvent(machine_g);
In file accou n t .cxx in t h e m et h od Accou n t ::wit h dr aw delet e or com m en t
ou t t h e followin g lin es:
// Original Version
withdrawEvent* event = new withdrawEvent(machine_g);
an d add or u n -com m en t t h e followin g lin es in t h eir place
d_Ref event = new(database_g)
withdrawEvent(machine_g);
38 O 2 ODM G D at abase Syst em Tu t or ialCreate persistent objects
• atm.cxx file
In file at m .cxx in t h e m et h od ATM::r u n delet e or com m en t ou t t h e
followin g lin es:
// Original Version
Account * current_account;
Person * current_customer
an d add or u n -com m en t t h e followin g lin es in t h eir place
// ODMG Persistent Version
d_Ref current_account;
d_Ref current_customer;
In file at m .cxx in t h e con st r u ct or ATM ::ATM () delet e or com m en t ou t t h e
followin g lin es:
// Original Version
location = new Address("3600_BAYSHORE","PALO
ALTO","CA","94043");
an d add or u n -com m en t t h e followin g lin es in t h eir place
// ODMG Persistent Version
location = new(database_g) Address("3600_BAYSHORE",
"PALO_ALTO", "CA", "94303");
In file at m .cxx in t h e m et h od ATM ::look u pAccou n t (in t accou n t _n u m ber )
delet e or com m en t ou t t h e followin g lin es:
// Original Version
Account *target_account = (Account*) NULL;
an d add or u n -com m en t t h e followin g lin es in t h eir place
// ODMG Persistent Version
d_Ref target_account = (Account*)NULL;
In file at m .cxx in t h e m et h od ATM:in it ializeAccou n t s() delet e or
com m en t ou t th e followin g lin es:
// Original Version
Person* current_person;
...
Account* new_account = new Account;
inFile >> * new_account;
...
// Original Version
current_person = new Person;
inFile >> * current_person;
O2 ODMG Dat abase System Tu tor ial 392 Porting a C++ Application
an d add or u n -com m en t t h e followin g lin es in t h eir place
// ODMG Persistent Version
d_Ref current_person;
...
d_Ref new_account = new(database_g) Account;
inFile >> * (new_account.ptr());
...
// ODMG Persistent Version
current_person = new(database_g) Person;
inFile >> * (current_person.ptr());
In file atm .cxx in t h e m et h od ATM:n ewAccou n t(in t accou n t_n u m ber , ...)
delet e or com m en t ou t t h e followin g lin es:
// Original Version
Account* new_account = new Account(account_number,
description, balance);
an d add or u n -com m en t t h e followin g lin es in t h eir place
// ODMG Persistent Version
d_Ref new_account = new(database_g) Account
(account_number, description, balance);
Sin ce t h e ATM object is n am ed an d all per sist en t object s ar e associat ed
wit h t h e ATM by per sist en t poin t er s n o addition al n am es n eed t o be
cr eat ed.
J u st as wit h a typical C++ pr ogr am you can explicit ly delete object s
fr om th e dat abase wh en t h ey ar e n o lon ger n eeded. However , O2
pr ovides a gar bage fu n ct ion t o deal wit h dat a t h at is n ot delet ed by t h e
applicat ion .
In file accou n t .cxx in t h e oper at or >> (ifst r eam & , Per son & ) delet e or
com m en t ou t t h e followin g lin es:
p.address = new Address;
ifs >> *p.address
...
Account* current_account;
an d add or u n -com m en t t h e followin g lin es in t h eir place
p.address = new(database_g) Address;
ifs >> *(p.address.ptr());
...
d_Ref current_account;
40 O 2 ODM G D at abase Syst em Tu t or ialBuild and Run the Application
2.9 Build and Run the Application
Th e sam ple applicat ion is n ow por t ed t o th e O2 Syst em .
To com pile, lin k an d r u n t h e applicat ion en t er th e followin g com m an d:
On Un ix,
> make clean
> make
On Win dows NT,
> nmake clean
> nmake
If n ecessar y, cor r ect an y t ypin g er r or s you m igh t h ave m ade t h at cau se
syn t ax er r or s an d r epeat t h e m ak e.
On ce it h as been com piled an d lin k ed r u n t h e pr ogr am t h r ou gh t h e
followin g com m an ds:
St ar t t h e applicat ion
> bank -initialize
En t er t h e Accou n t n u m ber 11111 at t h e pr om pt an d pr ess en t er . Th e
followin g will be displayed.
Welcome to the Bank of O2
Enter Account Number, 0 to exit
> 11111
At t h e per son al ID pr om pt en t er t h e n u m ber 9999 an d pr ess en t er .
Enter PIN Number
> 9999
You ar e n ow logged in to t h e syst em so you can car r y ou t tr an sact ion s
wit h t h e accou n t s available.
Now exit t h e pr ogr am
O2 ODMG Dat abase System Tu tor ial 412 Porting a C++ Application
2.10 Replace arrays by collection classes
ODMG-93 in t r odu ces pr edefin ed gen er ic collect ion classes. An O2
OD MG dat abase su ppor ts all ODM G collect ion classes. Th e collect ion s
su ppor t ed ar e:
d_Set - u n or der ed collect ion of elem en t s wit h n o du plicat es.
d_Bag - u n or der ed collect ion of elem en t s t h at allows for du plicat es.
d_List - an or der ed collection of elem en t s t h at allows for du plicates.
d_Var r ay - a on e dim en sion al ar r ay of var yin g len gt h .
Collection classes u se st an dar d C++ t em plat e classes t o pr ovide su ppor t
for elem en ts of an ar bit r ar y type. Th ese classes h ave m et h ods for
var iou s oper ation s, su ch as in ser t , delet e, appen d, u n ion , in t er sect ion ,
et c. Th er e is also an it er at or t em plat e class for defin in g iter ator s for an y
t ype of collect ion . Th e it er at or s ar e u sed t o scan a collect ion sequ en tially
r et u r n in g each m at ch in g elem en t fr om t h e collect ion .
Th e u se of collect ion classes in C++ pr ogr am s m ak es t h e pr ogr am s m or e
scalable. Ou r exam ple applicat ion u ses ar r ays t o st or e collect ion s. Th e
size of t h e ar r ays is set at t h e t im e t h e applicat ion is com piled. Th e
OD MG C++ collect ion classes ar e n ot of a fixed size an d can expan d as
t h e applicat ion evolves.
Collection classes ar e t igh t ly cou pled to t h e O 2 dat abase t o pr ovide
t r an spar en t cach in g of lar ge collect ion s. Wh en an applicat ion accesses a
lar ge ODM G collect ion on ly a por t ion of t h e collect ion is br ou gh t in t o
applicat ion m em or y. As t h e applicat ion tr aver ses t h e collect ion t h e r est
of t h e collect ion is br ou gh t in . Accessin g data in collect ion s can be
speeded u p by cr eat in g in dexes on a collect ion .
You can n ow r eplace t h e ar r ays in t h e exam ple application wit h
collect ion classes. Th e ATM class con t ain s t h e list of accou n ts. Th is is
k n own as t h e accou n t s_list . Th e list of accou n t s is im plem en t ed u sin g a
st an dar d C++ ar r ay. Sin ce t h er e is n o r equ ir em en t t o m ain t ain an y
or der in g on t h e list of accou n t s we will u se a d_Set t o r eplace t h e ar r ay.
Fir st we n eed t o m odify t h e declar at ion of t h e accou n t list .
• atm.hxx file
In t h e ATM class declar at ion in t h e file at m .h xx com m en t ou t or delete
t h e followin g lin es:
// Original Version
Account *accounts_list[MAX_ACCOUNTS];
an d add or u n -com m en t t h e followin g lin es in t h eir place:
42 O 2 ODM G D at abase Syst em Tu t or ialReplace arrays by collection classes
// ODMG Collection Class Replacement
d_Set< d_Ref > accounts_list;
Not e t h e u se of a space bet ween > > to differ en t iate bet ween a n ested
t em plat e an d t h e sh ift oper ator .
Now m odify t h e code wh er e t h e accou n t s_list is bein g u sed. On ly t h e
look u pAccou n t m et h od accesses t h e accou n t s_list . Rem ove t h e
in it ializat ion code th at is n o lon ger n eeded t h en r eplace t h e for loop
u sed in t h e m et h od wit h t h e u se of an iter ator . Fir st cr eat e t h e it er at or
fr om t h e accou n ts_list collect ion an d t h en t r aver se th e collect ion u sin g
t h e it er at or .
• atm.cxx file
In t h e con st r u ct or ATM::ATM in t h e file atm .cxx delet e or com m en t ou t
t h e followin g lin es:
// Original Version
//for(int i=0;igetNumber() == account_number)
{
target_account = accounts_list[i];
} break;
}
an d add or u n -com m en t t h e followin g lin es in t h eir place:
// ODMG Collection Class Replacement
d_Ref search_account;
d_Iterator< d_Ref > iterator =
accounts_list.create_iterator();
while ( iterator.next(search_account) ) {
if (search_account->getNumber() ==
account_number)
target_account = search_account;
} break;
O2 ODMG Dat abase System Tu tor ial 432 Porting a C++ Application
M odify t h e accou n t cr eat ion r ou t in e t o appen d t h e n ew accou n t on t o t h e
list by m ak in g t h e followin g m odificat ion .
In t h e m et h od ATM::in itializeAccou n t s in th e file at m .cxx delet e or
com m en t ou t t h e followin g lin es:
// Original Version
int i = 0;
while (accounts_list[i] != NULL)
i++;
accounts_list[i] = new_account;
an d add or u n -com m en t t h e followin g lin es in t h eir place:
// ODMG Collection Class Version
accounts_list.insert_element( new_account );
In t h e m et h od ATM::n ewAccou n t in t h e file at m .cxx delet e or com m en t
ou t t h e followin g lin es:
// Original Version
int i = 0;
while (accounts_list[i] != NULL)
i++;
accounts_list[i] = new_account;
an d add or u n -com m en t t h e followin g lin es in t h eir place:
// ODMG Collection Class Version
accounts_list.insert_element( new_account );
Replace t h e ar r ay of poin t er s t o even t s in t h e Accou n t class t o u se an
OD MG collect ion class. Th e or der of t h e even ts is sign ifican t so u se a
d_List t o m ain t ain t h e or der . Collect ion classes su ppor t polym or ph ism
t h r ou gh class h ier ar ch y t h er efor e t h e d_List m ay
con tain elem en t s of t h e su bclasses of Even t , n am ely deposit Even t an d
wit h dr awEven t . Replace t h e ar r ay of Per son by a r elation sh ip of t ype
d_Set t o m ain t ain r efer en t ial in t egr it y wit h Per son an d
ch an ge it s in ver se lin k , accou n t s in t h e Per son class, to a r elation sh ip of
t h e t ype d_List . M ak e th e followin g ch an ges t o t h e
declar at ion of t h e even ts_com plet ed, own er s in t h e Accou n t class an d
accou n t s in t h e Per son class.
44 O 2 ODM G D at abase Syst em Tu t or ialReplace arrays by collection classes
• account.hxx file
In t h e accou n t class declar ation in t h e file accou n t .h xx delet e or
com m en t ou t th e followin g lin es:
// Original Version
Person* owners[CUSTOMERS_PER_ACCOUNT];
...
Event *events_completed[MAX_EVENTS];
Add or u n -com m en t th e followin g lin es in th eir place:
// ODMG Collection Class Replacement
d_Set owners inverse accounts;
...
d_List< d_Ref > events_completed;
In t h e Per son class declar at ion delet e or com m en t ou t th e followin g
lin es:
// Original Version
Account* accounts[ACCOUNTS_PER_CUST]
Add or u n -com m en t t h e followin g lin es in t h eir place:
// ODMG Collection Class Replacement
d_List accounts inverse owners
You also n eed t o ch an ge th e way t h e even t s_com plet ed an d t h e own er s
ar e u sed. St op th e even t s_com plet ed an d own er s bein g in it ialized t o
NULL in bot h t h e Accou n t con st r u ct or s an d add t h e in itializer for th e
r elat ion sh ip.
• account.cxx file
In t h e con st r u ct or Accou n t ::Accou n t in t h e file accou n t .cxx delet e or
com m en t ou t th e followin g lin es
// Original Version
int i;
for (i=0;i2 Porting a C++ Application
for (i=0;ipersonal_id ==
pin_number) {
return owners[j];
46 O 2 ODM G D at abase Syst em Tu t or ialReplace arrays by collection classes
an d u n -com m en t or add t h e followin g lin es:
d_Ref search_person;
d_Iterator< d_Ref > iterator =
owners.create_iterator();
while ( iterator.next(search_person) ) {
if (search_person->personal_id == pin_number) {
return search_person;
}
}
In t h e m et h od Accou n t ::n ewOwn er in t h e file accou n t .cxx r em ove or
com m en t ou t th e followin g lin es:
// Original Version
int i = 0;
while (owners[i]) i++;
owners[i] = NewOwner;
an d u n -com m en t or add t h e followin g lin es:
// ODMG Collection Class Version
owners.insert_element(NewOwner);
In t h e con st r u ct or Per son ::Per son () in t h e file accou n t.cxx r em ove or
com m en t ou t th e followin g lin es:
// Original Version
Person::Person() {
for (int i = 0; inewOwner(&p);
an d u n -com m en t or add t h e followin g lin es:
// ODMG Collection Class Version
p.accounts.insert_element (current_account);
O2 ODMG Dat abase System Tu tor ial 472 Porting a C++ Application
In t h e m et h od Ter m in al::displaySelect Accou n t in t h e file t er m in al.cxx
r em ove or com m en t ou t th e followin g lin es:
// Original Version
while (i < ACCOUNTS_PER_CUST && customer->accounts[i])
{
an d u n -com m en t or add t h e followin g lin es:
// ODMG Collection Class Version
int nb = customer->accounts.cardinality();
while (i < nb && customer-accounts[i]) {
48 O 2 ODM G D at abase Syst em Tu t or ialBuild and Run the Application
2.11 Build and Run the Application
Now you h ave por t ed t h e au t om at ed t eller m ach in e applicat ion t o u se
ODMG collect ion classes. Th e n ext st ep is t o com pile an d lin k th e
m odified applicat ion .
Ru n t h e followin g com m an d t o com pile an d lin k t h e applicat ion :
On Un ix,
> make
On Win dows NT,
> nmake
If n ecessar y, cor r ect an y t ypin g er r or s you m igh t h ave m ade t h at cau se
syn t ax er r or s an d r epeat t h e m ak e.
Now r u n t h e application , u sin g t h e in it ialize option t o r er ead t h e dat a
fr om t h e files. You n eed t o r ein it ialize t h e dat abase becau se you
m odified t h e sch em a wh en you added th e collect ion classes.
> bank -initialize
En t er t h e Accou n t n u m ber 11111 at t h e pr om pt an d pr ess en t er . Th e
followin g will be displayed.
Welcome to the Bank of O2
Enter Account Number, 0 to exit
> 11111
At t h e per son al ID pr om pt en t er t h e n u m ber 9999 an d pr ess en t er .
Enter PIN Number
> 9999
You ar e n ow logged in to t h e syst em so you can car r y ou t tr an sact ion s
wit h t h e accou n t s available.
To exit t h e pr ogr am en t er 0 at t h e accou n t n u m ber pr om pt .
O2 ODMG Dat abase System Tu tor ial 492 Porting a C++ Application 50 O 2 ODM G D at abase Syst em Tu t or ial
33 OQL Th is ch apt er descr ibes OQL. It con tain s th e followin g sect ion s: • Th e O2 OD MG Object Qu er y Lan gu age • Em beddin g OQL in C++ • Bu ild an d Ru n t h e Applicat ion O2 OD MG Dat abase Syst em Tu tor ial 51
3 OQL
3.1 The O2 ODMG Object Query Language
OD MG-93 in t r odu ces an object qu er y lan gu age (OQL). OQL is an SQL-
st yle lan gu age t h at allows for easy access t o object s. Sim ilar in u se t o
SQL, OQL is an essen t ial t ool for developin g dat abase applicat ion s.
• Query optimization
Th e syst em opt im izes you r qu er ies. Tr ied an d t est ed opt im izat ion
t ech n iqu es ar e u sed t o evalu at e an OQL qu er y. For exam ple, OQL u ses
appr opr iat e in dexes to r edu ce t h e am ou n t of data t o be filter ed. It
fact or izes com m on su b-expr ession s, discover s wh ich expr ession s can be
com pu t ed on ce ou t side an it er at ion , an d m ak es select ion s befor e
st ar t in g an in n er it er at ion .
• Logical and physical independence
OQL differ s fr om st an dar d pr ogr am m in g lan gu ages in t h at t h e execu t ion
of an OQL qu er y can be im pr oved dr am at ically wit h ou t m odifyin g t h e
qu er y it self. Th is is don e by declar in g n ew ph ysical dat a st r u ct u r es or
n ew in dexin g or clu st er in g st r at egies. Th is r edu ces r espon se t im e.
Th is sor t of m odificat ion in a pu r ely im per at ive lan gu age lik e C++
r equ ir es t h at an algor it h m be com pletely r ewr itt en , as it m ak es u se of
ph ysical st r u ct u r es.
Interactive ad hoc queries
A dat abase u ser can n ot be ask ed t o wr it e, com pile, lin k , edit an d debu g
a C++ pr ogr am to m ak e sim ple qu er ies. OQL can be u sed dir ect ly as a
st an d-alon e qu er y in t er pr et er . Its syn t ax is sim ple an d flexible. For
som eon e fam iliar with SQL, OQL can be lear n ed in a sh or t t im e.
Som e exam ples ar e given t o dem on st r at e th e m ost u sefu l feat u r es of
OQL. You can execu t e t h em as ad h oc qu er ies with o2dsa. Fir st st ar t th e
o2dsa in t er pr et er :
> o2dsa_shell
Now set th e base an d pu t th e in t er pr et er in to qu er y m ode
set base bankBase
^D
query
^D
52 O 2 ODM G D at abase Syst em Tu t or ialYou can also read
