O2 ODMG Database System Tutorial

 
O2 ODMG
Database System
    Tutorial

    Release 5.0 - April 1998
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 .

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                          5
TABLE 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 ial
TABLE 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                                                                    7
TABLE 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                                                    9
1       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 ial
Object 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 ial
Benefits 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                                                    13
1   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 ial
Example 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                                                  15
1           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 ial
Example 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                                                   17
1   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 ial
Setup

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                                                        19
1   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 ial
Setup

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                                             23
2   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 ial
C++ 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                  25
2      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 ial
Store 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 ial
Change 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                                                  29
2    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 ial
Change 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                                                    31
2      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 ial
Connect 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                                                    33
2      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 ial
Create 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                                                       35
2      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 ial
Modify 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                                      37
2      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 ial
Create 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                                                   39
2   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 ial
Build 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                                                  41
2       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 ial
Replace 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                                                        43
2   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 ial
Replace 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;i
2   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 ial
Replace 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                                                      47
2   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 ial
Build 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                                                        49
2   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 ial
You can also read
Next slide ... Cancel