Download C Interface to O2 User Manual

C Interface to O2
User Manual
Release 5.0 - May 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 t h e law t o copy th is softwar e t o m agn et ic t ape, disk , or
an y ot h er m ediu m for an y pu r pose ot h er t h an t h e pu r ch aser ’s own u se.
Copyr igh t 1992-1998 O 2 Tech n ology.
All r igh 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 t ed in an y for m or by an y m ean s, elect r on ic,
m ech an ical, ph ot ocopy with ou t pr ior wr itt en per m ission of O2 Tech n ology.
O 2 , O2 En gin e API, O2 C, O2 DBAccess, O 2 En gin e, O2 Gr aph , O 2 Kit , O 2 Look ,
O 2 Stor 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.
Who should read this manual
Th is m an u al pr esen t s t h e basic con cept s of t h e C in t er face t o O2 an d
descr ibes h ow to lin k ext er n al C applicat ion s t o O 2 . It det ails th e
m an agem en t of object h an dles, it er at or fu n ct ion s, an d h ow t o u se
O2 Look an d OQL wit h C. Th e in t er face wit h O 2 C is also descr ibed,
in clu din g m et h od an d fu n ct ion calls an d object h an dle con ver sion s t o
O2 C var iables. A com plet e pr ogr am m in g exam ple is pr esen t ed.
Ot h er docu m en t s available ar e ou tlin ed, click below.
See O2 Documentation set.
TABLE OF CONTENTS
Th is m an u al is divided in t o t h e followin g ch apt er s:
• 1 - In t r odu ct ion
• 2 - Ru n t im e Libr ar y
• 3 - Exam ple C applicat ion
C In t er face t o O 2 User M an u al
5
TABLE OF CONTENTS
1
Introduction
9
1.1 System overview ......................................................................10
Integrated modules .......................................................................12
1.2 Features and advantages ........................................................13
1.3 Introducing the C interface to O2 ...........................................14
C Application structure ................................................................15
1.4 Manual overview.......................................................................17
2
Runtime Library
19
2.1 Database Connection...............................................................20
Starting an O2 session..................................................................20
Setting a base ...............................................................................22
2.2 Transaction Management ........................................................23
Defining transactions ...................................................................23
Read-only transactions .................................................................23
Update transactions ......................................................................24
2.3 Using OQL in C.........................................................................26
o2query.........................................................................................26
Method and function call .............................................................28
2.4 Handle management ................................................................31
Manipulating functions ................................................................31
Iterator functions ..........................................................................33
Handle conversion........................................................................34
2.5 Running an application............................................................37
Example .......................................................................................37
2.6 Garbage Collection ..................................................................38
Example .......................................................................................38
2.7 Leaving the database...............................................................39
6
C In t er face t o O2 User M an u al
TABLE OF CONTENTS
3
An Example C Application
41
3.1 Introduction.............................................................................. 42
3.2 Define the class Person in file Person.h ............................. 43
The class Person .......................................................................... 44
Writing and reading a person from C .......................................... 44
Implementing O2C read and write methods................................ 45
Creating O2 objects from C......................................................... 47
The Person_new C function ........................................................ 47
Implementing Person_new in O2C ............................................. 47
3.3 The application code ............................................................... 49
The C header file Person.h .......................................................... 49
The O2C schema ......................................................................... 49
3.4 Class Implementation in Person.c ....................................... 52
3.5 The application in the main.c file ........................................... 55
Main program .............................................................................. 56
3.6 Compiling your application .................................................... 58
The Makefile ............................................................................... 58
Makefiles and Platforms.............................................................. 58
INDEX
C In t er face t o O2 User M an u al
61
7
TABLE OF CONTENTS
8
C In t er face t o O2 User M an u al
1
I ntr oduction
1
GENERAL OVERVIEW OF TH E
C INTERFACE TO O2
Con gr at u lat ion s! You ar e n ow a u ser of t h e C in t er face to O2!
You will fin d t h at developin g O2 applicat ion s in C h as sever al k ey
advan t ages: data per sist en ce, con for m an ce t o C stan dar ds, r eu se of
exist in g C applicat ion s, ext en ded C pr ogr am m in g an d open n ess t o all
O2 t ools in clu din g t h e OQL qu er y lan gu age an d O2 Look gr aph ical
in t er face gen er ator .
Th is ch apt er in t r odu ces t h e O2 in t er face t o C.
Th e ch apt er is divided in t o t h e followin g sect ion s:
• Syst em over view
• Feat u r es an d advan t ages
• In t r odu cin g t h e C in t er face t o O2
• M an u al over view
C In t er face t o O 2 User Man u al
9
1
Introduction
1.1 System overview
Th e syst em ar ch it ect u r e of O2 is illu st r at ed in Figu r e 1.1.
External
Interfaces
Development Tools
Standard
Dev. Tools
O2 Dev. Tools
OQL
C
O2 C
C++
Java
Database Engine
O2Engine
O2Store
O2ODBC
O2Corba
O2DB
Access
O2Web
Fi gu r e 1 .1 : O2 Sy st em Ar ch i t ect u r e
Th e O 2 system can be viewed as con sist in g of t h r ee com pon en t s. Th e
Database Engine pr ovides all t h e feat u r es of a D at abase syst em an d an
object -or ien t ed syst em . Th is en gin e is accessed wit h Development Tools ,
su ch as var iou s pr ogr am m in g lan gu ages, O 2 developm en t t ools an d an y
st an dar d developm en t tool. Nu m er ou s External Interfaces ar e pr ovided.
All en com passin g, O 2 is a ver sat ile, por t able, dist r ibu t ed,
h igh -per for m an ce dyn am ic object -or ien t ed dat abase syst em .
Database En gin e:
10
• O2 St or e
Th e dat abase m an agem en t syst em pr ovides low level
facilit ies, t h r ou gh O2 Stor e API, t o access an d m an age a
dat abase: disk volu m es, files, r ecor ds, in dices an d
t r an sact ion s.
• O2 En gin e
Th e object dat abase en gin e pr ovides dir ect con t r ol of
sch em as, classes, object s an d t r an sact ion s, t h r ou gh
O2 En gin e API. It pr ovides fu ll t ext in dexin g an d sear ch
capabilit ies wit h O 2 Sear ch an d spat ial in dexin g an d
r et r ieval capabilit ies wit h O 2 Spat ial. It in clu des a
Not ificat ion m an ager for in for m in g oth er clien t s
con n ect ed t o t h e sam e O 2 ser ver t h at an even t h as
occu r r ed, a Ver sion m an ager for h an dlin g m u lt iple
object ver sion s an d a Replicat ion API for syn ch r on izin g
m u lt iple copies of an O2 system .
C In ter face to O2 User Man u al
System overview
Pr ogr am m in g Lan gu ages:
O 2 object s m ay be cr eat ed an d m an aged u sin g t h e followin g
pr ogr am m in g lan gu ages, u tilizin g all t h e featu r es available wit h O2
(per sist en ce, collection m an agem en t , t r an sact ion m an agem en t , OQL
qu er ies, et c.)
• C
O2 fu n ct ion s can be in vok ed by C pr ogr am s.
• C++
OD MG com plian t C++ bin din g.
• J ava
OD MG com plian t J ava bin din g.
• O2 C
A power fu l an d elegan t object-or ien t ed fou r t h
gen er at ion lan gu age specialized for easy developm en t
of object dat abase applicat ion s.
• OQL
OD MG st an dar d, easy-t o-u se SQL-lik e object qu er y
lan gu age wit h special feat u r es for dealin g wit h com plex
O2 object s an d m eth ods.
O 2 Developm en t Tools:
• O2 Gr aph
Cr eat e, m odify an d edit an y t ype of object gr aph .
• O2 Look
Design an d develop gr aph ical u ser in ter faces, pr ovides
in t er active m an ipu lation of com plex an d m u ltim edia
object s.
• O2 Kit
Libr ar y of pr edefin ed classes an d m et h ods for fast er
developm en t of u ser applicat ion s.
• O2 Tools
Com plet e gr aph ical pr ogr am m in g en vir on m en t t o
design an d develop O 2 dat abase applicat ion s.
St an dar d Developm en t Tools:
All stan dar d pr ogr am m in g lan gu ages can be u sed wit h st an dar d
en vir on m en t s (e.g. Visu al C++, Su n Spar cwor k s).
Exter n al In t er faces:
• O2 Cor ba
Cr eat e an O2 / Or bix ser ver t o access an O2 dat abase
wit h CORBA.
• O2 DBAccess Con n ect O2 applicat ion s to r elation al dat abases on
r em ot e h ost s an d in vok e SQL st at em en ts.
• O2 OD BC
Con n ect r em ot e ODBC clien t applicat ion s t o O2
dat abases.
• O2 Web
Cr eat e an O2 Wor ld Wide Web ser ver t o access an O 2
dat abase th r ou gh t h e in t er n et n etwor k .
C In t er face t o O 2 User Man u al
11
1
Introduction
Integrated modules
If you ch oose t o u se t h e C in t er face to O 2, you see t h at C in h er it s all t h e
advan t ages of th e O2 syst em dat abase en gin e O2En gin e:
• Object s in C applicat ion s ar e m an ipu lat ed in t h e sam e way as
st an dar d C object s.
• An y exist in g C application can be m ade per sist en t aft er ver y m in or
m odificat ion .
• O2 en su r es dat abase con sist en cy, r efer en t ial in t egr it y an d
au t om atically m an ages th e dyn am ic m em or y of O2
objects. It also pr ovides facilit ies for cr eat in g an d
m an ipu lat in g O 2 an d C collect ion s.
• You u se t h e com plem en t ar y t ools OQL an d O2Look : database qu er y,
com plex valu e cr eat ion an d in itializat ion , object
br owsin g an d object edit in g.
12
C In ter face to O2 User Man u al
Features and advantages
1.2 Features and advantages
D evelopin g O2 applicat ion s in C h as sever al k ey ben efit s: dat a
per sist en ce, con for m an ce t o C st an dar ds, r eu se of exist in g C
applicat ion s, ext en ded C pr ogr am m in g an d open n ess t o all O 2 t ools
in clu din g t h e OQL qu er y lan gu age an d O 2 Look gr aph ical in t er face
gen er at or .
C in h er it s all t h e advan t ages of t h e O2 syst em database en gin e
O 2 En gin e.
• Per sist en ce
Th e data in C applicat ion s can be m ade per sist en t wit h fu n ct ion s for
cr eat in g, r eadin g an d wr it in g object s. You r C applicat ion s can be m ade
t o h ave per sist en t st r u ct s after ver y m in or m odificat ion . Per sisten t r oot s
ar e defin ed dyn am ically in C.
Per sist en ce of dat a is ach ieved t h r ou gh t h e declar at ion of per sist en t
r oot s t o th e applicat ion . Edit an d display facilit ies for C dat a ar e
gen er at ed au t om atically.
• Code r eu se
Exist in g C applicat ion s ar e easily ext en ded an d t h eir object s m ade
per sist en t . Code r eu se by im por t in g classes fr om differ en t sch em as.•
D at abase con sisten cy is m ain t ain ed
• Im pr oved an d ext en ded C
O 2 h as libr ar ies for cr eat in g an d m an ipu latin g O2 an d C collect ion s.
Gen er ic libr ar ies for easily cr eat in g an d m an ipu lat in g O 2 collect ion s
wit h r eu se of exist in g libr ar ies wit h ou t r ecom pilation OQL an d O2 Look
can be in t egr at ed an d applied t o C object s. Pr im it ives for dat abase
t r an saction m an agem en t ar e available fr om C application s
Pr ogr am m in g O2 in C feat u r es in clu de User -pr ogr am m ed t r an saction
com m it an d abor t. Stan dar d C com piler . A C pr ogr am m er n eeds n o
pr eviou s k n owledge of O 2 t o st ar t developin g applicat ion s im m ediat ely.
• In t egr at ed t ools
You can tak e advan tage of com plem en t ar y tools: dat abase qu er y,
com plex valu e cr eat ion an d in it ializat ion , object br owsin g an d object
edit in g. Com plem en t ar y t ools can be in t egr at ed wit h t h e C in t er face,
su ch as dat abase qu er y, com plex valu e cr eat ion an d in it ialization as
well as object br owsin g an d edit in g fr om C.
C In t er face t o O 2 User Man u al
13
1
Introduction
1.3 Introducing the C interface to O2
As O 2C is a su per set of C, you will fin d t h at t h e object -or ien t ed 4th
gen er at ion lan gu age O2C in it self h as all t h e feat u r es you n eed.
H owever , you can n ot u se t h e O2C application m odel if, for exam ple, you r
applicat ion n eeds a m ain pr ogr am wr it t en in plain C.
Th is m an u al explain s h ow t o wr it e C pr ogr am s wh ich can u se t h e O2
dat abase in or der t o st or e an d r et r ieve C dat a. A a C pr ogr am m er , you
will fin d pr ogr am m in g an applicat ion u sin g t h e O2 dat abase ver y easy.
Fi gu r e 1 .2 : Th e C i n t er f a ce t o O2
14
C In ter face to O2 User Man u al
Introducing the C interface to O2
C Application structure
An applicat ion is a C execu t able wh ich at som e m om en t con n ect s it self
t o O2, open s a dat abase an d th en r u n s u n der t h e con t r ol of t h e O 2
t r an saction m an ager .
It th en u ses OQL t o qu er y t h e dat abase an d t o call u p O 2C fu n ct ion s
an d m et h ods in or der t o m an ipu lat e h an dles (O 2 objects or valu es).
• Dat abase con n ect ion
A C applicat ion com m u n icates wit h O2 via var iou s fu n ction s defin ed in
an O 2 l i br ar y .
Th e C applicat ion st ar t s u p an O 2 session u sin g t h e o2_link_init
fu n ct ion an d defin es a dat abase con t ext again st wh ich t h e application
r u n s u sin g t h e o2_link_set_base fu n ct ion .
• Tr an sact ion s
It can t h en st ar t u p a t r an sact i on u sin g t h e o2_link_transaction
fu n ct ion , an d can en d th e t r an sact ion by com m it t in g t h e t r an sact ion
u sin g t h e o2_link_commit fu n ct ion , validat in g th e t r an sact ion u sin g
t h e o2_link_validate fu n ction or abor tin g t h e tr an sact ion u sin g t h e
o2_link_abort fu n ct ion .
An applicat ion is u su ally m ade u p of m an y t r an saction s. each on e
r eflect in g a par t icu lar u t ilizat ion of th e dat abase: cr eatin g object s,
qu er yin g in for m at ion , u pdat in g object s, addin g n ew in for m at ion ,
delet in g in for m at ion , et c.
By defau lt , an applicat ion r u n s in a r ead-on l y t r an sact ion . Th is is a
t r an saction wh er e n o u pdat es on per sist en t data ar e allowed.
• Usin g OQL in C
In side a t r an saction , t h e object qu er y lan gu age OQL is u sed so t h at
you r C applicat ion can u se an O 2 dat abase in or der t o:
• qu er y an O2 collection .
• call an O2C fu n ct ion
• call an O2C m et h od
• Han dles
For a C applicat ion , an O2 object or an O 2 valu e is a h an d l e.
You r C pr ogr am m an ipu lat es t h ese O2 object s an d valu es by callin g O 2C
fu n ct ion s or m et h ods, an d passin g an d r eceivin g t h e object s an d valu es
as par am et er s.
C In t er face t o O 2 User Man u al
15
1
Introduction
You can car r y ou t th e followin g oper at ion s on h an dles:
• assign a valu e t o an ot h er valu e
• assign an object t o an ot h er object
• assign a valu e t o a n am ed valu e
• assign an object t o a n am ed object
• it er at e on a collect ion .
You can also car r y ou t h an dle con ver sion . In side an O2C fu n ct ion body
or m et h od body, you can con ver t a h an dle in t o an o2 var iable or
con ver sely, con ver t an o2 var iable in t o a h an dle. You do th is by u sin g
t h e O 2C fu n ct ion c_assign.
• Ru n n in g th e application
You can st ar t an O2C applicat ion fr om a C pr ogr am u sin g t h e fu n ction
o2_run_application.
• Leavin g an O2 session
You en d t h e session an d leave t h e database u sin g t h e fu n ct ion
o2_link_end.
16
C In ter face to O2 User Man u al
Manual overview
1.4 Manual overview
Th is m an u al is divided u p in t o t h e followin g ch apt er s:
• Chapter 1 - Introduction
Th is ch apt er in t r odu ces t h e C in ter face to O2, ou t lin es t h e O2 system
an d gives all t h e feat u r es an d advan t ages th e in t er face h as t o offer . It
t h en goes on t o in t r odu ce t h e st r u ct u r e of a C applicat ion in O2ou t lin in g
su ch con cept s as dat abase con n ect ion , tr an sact ion m an agem en t , u sin g
OQL t o qu er y t h e dat abase an d t o call O 2 fu n ct ion s an d m et h ods in
or der t o m an ipu late O 2 object s an d valu es, h an dles (O 2 object s an d
valu es), r u n n in g t h e applicat ion an d leavin g an O2 session .
• Chapter 2 - Runtime Library
Th is ch apt er gives all t h e r u n tim e libr ar y fu n ct ion s you n eed t o u se t h e
C in t er face t o O2 an d is divided u p in t o t h e followin g sect ion s:
• Dat abase con n ect ion
• Tr an sact ion m an agem en t
• Usin g OQL in C
• Han dle m an agem en t
• Ru n n in g t h e application
• Leavin g t h e dat abase
• Chapter 3 - Example application
Th is ch apt er gives a com plet e exam ple of h ow t o u se th e C in t er face t o
O 2, sh owin g h ow t o m ak e str u ct u r es per sist en t , h ow t o cr eat e data as
well as stor e an d r et r ieve t h ese st r u ct u r es t o an d fr om a dat abase.
C In t er face t o O2 User M an u al
17
1
18
Introduction
C In ter face to O2 User Man u al
2
2
R untime L ibra ry
Th is ch apt er gives t h e r u n tim e libr ar y fu n ct ion s you n eed t o u se t h e C
in t er face t o O2 .
Th e ch apt er is divided in t o t h e followin g sect ion s:
• D at abase Con n ect ion
• Tr an sact ion Man agem en t
• Usin g OQL in C
• H an dle m an agem en t
• Ru n n in g an applicat ion
• Gar bage Collect ion
• Leavin g t h e dat abase
Note
Please r efer t o t h e O2 C an d OQL m an u als for m or e det ails on h ow t o u se
t h ese lan gu ages.
C In ter face to O2 User Man u al
19
2
Runtime Library
2.1 Database Connection
To bu ild t h e fin al O2 / C applicat ion , t h e C in t er face h as a r u n tim e
libr ar y th r ou gh wh ich t h e con n ect ion between O2 an d C is car r ied ou t .
You r C pr ogr am com m u n icates wit h O2 by in vok in g t h e fu n ct ion s
defin ed in t h e followin g libr ar ies:
an d libo2linkcuse.a t o u se O 2 Look in side O2 C
m et h ods an d fu n ct ion s,
• libo2lklink.a
• libo2link.a an d libo2linkcuse.a - t h ese do n ot in clu de O 2 Look .
Th e ext er n al applicat ion m u st be lin k ed t o t h e O 2 libr ar y, sit u at ed in th e
lib su bdir ect or y of t h e O2 in st allat ion dir ect or y.
If t h e applicat ion u ses O2 Look , it m u st be lin k ed t o M OTIF (1.2) an d
st an dar d X libr ar ies.
Th is sect ion is divided u p in t o t h e followin g sect ion s:
• St ar t in g an O2 session
• Set tin g a base
Starting an O2 session
To u se O2 in a C pr ogr am , t h e applicat ion pr ogr am m u st st ar t an O 2
session wh ich in it ializes t h e con n ect ion t o t h e ser ver .
To do t h is you r applicat ion u ses t h e O2 libr ar y fu n ct ion :
int o2_link_init (argc, argv[], sinit, mode)
int argc; char *argv[]; O2_sinit *sinit; int mode;
Th e o2_link_init fu n ct ion set s u p a wor k in g con n ect ion bet ween t h e
ext er n al C pr ogr am an d th e specified O 2 syst em n am e an d is m u ch lik e
st ar t in g u p an O 2 session u n der Un ix, by in vok in g t h e o2 execu table
pr ogr am .
Th e fu n ct ion passes th e argc an d argv par am eter s as com m an d lin e
ar gu m en t s t o t h e o2 execu t able. Th e argc an d argv par am et er s ar e t h e
n u m ber an d list of com m an d lin e ar gu m en t s wit h wh ich t h e exter n al C
applicat ion was lau n ch ed.
20
C In ter face to O2 User Man u al
Database Connection
An y valid O2 com m an d lin e opt ion s can be u sed wh en lau n ch in g a C
applicat ion .
Th e sinit par am et er is a poin t er t o an in stan ce of th e followin g
st r u ct u r e:
typedef struct {
char *sysdir;
char *sysname;
char *svname;
char *swapdir;
char **libpath;
char **libname;
An O2 installation directory
An O2 named system
Machine where o2server is running
Special swap directory
Paths to search for libraries
Library names to search for
} O2_sinit;
Th e defin it ion of t h is st r u ct u r e is given in t h e h eader file o2_c.h.
All t h e var iou s m em ber s of t h e st r u ct u r e ar e descr ibed below.
Th e fir st fou r m em ber s of t h e st r u ct u r e iden t ify wh ich O2 syst em to u se,
an d t h e last t wo on ly ser vin g t h ose applicat ion s n eedin g dyn am ic r u n t im e lin k in g t o on e or m or e libr ar ies of C fu n ction s:
• sysdir:
Th is is th e absolu te pat h of an O2 in st allat ion dir ect or y, con t ain in g t h e systems file an d t h e bin su bdir ector y h oldin g t h e
O 2 execu t ables. Th is m u st n ot be n u ll.
• sysname:
Th e n am e of t h e O2 dat abase syst em wor k in g wit h th e C applicat ion . Th is m u st be defin ed in th e systems file in dicated by
sysdir an d m u st n ot be n u ll.
• svname:
Th e n am e of a m ach in e on t h e local n et wor k on wh ich t h e
o2server pr ocess is r u n n in g. If n u ll, o2_link_init look s for
t h e ser ver specificat ion in t h e systems file in t h e O 2 in st allat ion
dir ect or y.
• swapdir:
Th e absolu t e pat h of a dir ect or y for special swap files. If n u ll,
t h e defau lt locat ion (O2 in st allat ion dir ector y swap su bdir ect or y) is u sed.
• libpath:
C In ter face to O2 User Man u al
21
2
Runtime Library
A n u ll t er m in at ed ar r ay of absolu t e pat h s wh ich ar e sear ch ed,
for libr ar ies du r in g a dyn am ic loadin g pr ocedu r e for C fu n ct ion s. Th is is sim ilar t o t h e -L opt ion of th e o2 execu t able. It is
im por t an t t o C pr ogr am s t h at in vok e dyn am ically-lin k ed m odu les fr om u ser -specified libr ar ies; ot h er wise t h is can be n u ll.
• libname:
A n u ll t er m in at ed ar r ay of libr ar y n am es wh ich ar e each
sear ch ed, for dyn am ically-loaded fu n ct ion s called by t h e applicat ion . Th is is sim ilar t o t h e -l opt ion of t h e o2 execu t able. It is
im por t an t t o C pr ogr am s t h at in vok e dyn am ically-lin k ed m odu les fr om u ser -specified libr ar ies; ot h er wise t h is can be n u ll.
Fin ally, th e mode par am et er 1 is an in t eger wh ich deter m in es wh et h er or
n ot t h e ext er n al applicat ion u ses t h e O2 Look gr aph ic u ser in t er face.
Zer o in dicates t h at th e application u ses O2 Look ; 1 in dicat es t h at t h e
applicat ion is alph an u m er ic.
Th e o2_link_init fu n ct ion r et u r n s zer o if th e lin k t o O2 was
su ccessfu lly est ablish ed or an er r or code if n ot .
Setting a base
Th e C pr ogr am th en sets t h e dat abase wit h wh ich it wan ts t o wor k by
u sin g t h e followin g O 2 fu n ction :
int o2_link_set_base (base_name) char *base_name;
Th is is t h e sam e as t h e O2 sch em a com m an d set base.
Th e o2_link_set_base fu n ct ion iden t ifies t h e O 2 base wit h wh ich t h e
ext er n al pr ogr am wan t s t o wor k .
A base wit h t h e specified n am e m u st alr eady exist wit h in th e n am ed
dat abase system specified in t h e o2_link_init fu n ct ion above.
Th e fu n ction r et u r n s zer o if t h e base in dicat ed is fou n d or an er r or code
if n ot .
1.
22
Only meaningful with the graphical version of O2
C In ter face to O2 User Man u al
Transaction Management
2.2 Transaction Management
Th is sect ion descr ibes all t h e var iou s r u n t im e libr ar y fu n ct ion s you
n eed t o wor k wit h tr an sact ion s.
Th is sect ion is divided as follows:
• Defin in g t r an sact ion s
• Read-on ly t r an sact ion s
• Updat e t r an sact ion s
Defining transactions
You star t u p a n ew t r an sact ion u sin g t h e followin g fu n ct ion :
void o2_link_transaction()
By defau lt , a C applicat ion r u n s as a pr ogr am , i.e. it is allowed t o r ead
p er si st en t d at a bu t n ot t o u pdat e it . In or der t o u pdat e, t h e applicat ion
m u st st ar t a t r an sact ion .
Read-only transactions
Th e call t o t h e o2_link_transaction is n ot obligator y is you on ly wan t
t o r ead dat a becau se by defau lt , an applicat ion r u n s in a r ead -on l y
t r an saction .
Th is is a t r an sact ion wh er e n o u pdat es on per sist en t dat a ar e allowed
an d n o lock s ar e set by t h e syst em .
Aft er a tr an sact ion en ds, th e applicat ion is au t om at ically r eset in to a
r ead-on ly t r an sact ion . Su ch a r ead-on ly tr an sact ion is u sefu l becau se it
does n ot con flict with oth er t r an sact ion s.
It can r ead an y object s or collect ion s, an d it can cr eat e an y tem por ar y
O 2 objects or collection s as com plex as n eeded.
Th e r ead-on ly t r an saction is th er efor e ideally su it ed t o t h at par t of you r
applicat ion wh er e an in t er act ive dialogu e wit h th e en d-u ser occu r s, or
wh er e som e com plex calcu lat ion is n ecessar y after r eadin g st able dat a.
C In ter face to O2 User Man u al
23
2
Runtime Library
Th is par t of an application is u su ally followed by a st an dar d t r an sact ion
wh ich m an ages t h e cr eat ion an d u pdatin g of per sist en t dat a.
Note
When you start a transaction using o2_link_transaction, O2 ensures that the
objects you access are always up-to-date, i.e. with the latest committed value.
Moreover, the transaction protects you from concurrent updates and guarantees that the
data you read will not change during the transaction. Inside the transaction, you simply
must check that the assumptions made in the read-only phase, if any, still hand.
Update transactions
• Link
An u pdat e t r an saction begin s wit h t h e fu n ction :
void o2_link_transaction()
Th is leaves r ead-on ly m ode. Con sisten cy is gu ar an t eed by O 2 wh ich
au tom at ically r er eads t h e var iables wh ich h ave been r ead du r in g r eadon ly m ode.
• Commit
Th e followin g t r an sact ion en ds t h e cu r r en t tr an sact ion on t h e cu r r en t
dat abase:
void o2_link_commit()
o2_link_commit u pdat es t h e dat abase, r eleases all lock s, fr ees all
m em or y allocat ed at r u n t im e an d t h en star t s a r ead-on ly t r an sact ion .
All ch an ges m ade t o t h e database du r in g t h e pr esen t t r an sact ion ar e
wr it t en to disk an d a n ew t r an sact ion is in it iated. Aft er a com m it, all
h an dles h eld by a C applicat ion ar e n o lon ger valid an d t h ey m u st be
r ecom pu t ed st ar t in g fr om per sist en t r oot s.
• Validate
Th e validat e fu n ct ion is as follows:
void o2_link_validate()
24
C In ter face to O2 User Man u al
Transaction Management
Th is fu n ct ion is t h e sam e as o2_link_commit except t h at it does n ot
fr ee th e m em or y allocated by O2 t o r u n t h is t r an sact ion . Aft er a
validat e, all h an dles h eld by a C applicat ion ar e st ill valid.
• Abort
Th e abor t fu n ct ion is as follows:
void o2_link_abort()
Th is fu n ct ion also en ds th e cu r r en t dat abase tr an sact ion . An y ch an ges
m ade t o t h e dat abase du r in g t h e pr esen t t r an sact ion ar e aban don ed
an d a n ew t r an sact ion is in it iat ed. Aft er an abor t , all h an dles h eld by a
C applicat ion ar e n o lon ger valid an d t h ey m u st be r ecom pu t ed star t in g
fr om per sist en t r oot s.
C In ter face to O2 User Man u al
25
2
Runtime Library
2.3 Using OQL in C
Th is sect ion n ow descr ibes h ow t o call OQL fr om a C pr ogr am u sin g th is
fu n ct ion , pass C par am et er s to it an d get t h e r esu lt of th e qu er y.
It th en descr ibes h ow t o call an O2 m eth od or fu n ct ion fr om OQL in
or der t o u se t h e O2 dat abase.
o2query
Th e C in t er face t o O2 h as a set of fu n ct ion s, each wit h a n am e begin n in g
wit h o2query wh ich ar e t h e in t er face bet ween C applicat ion s an d OQL.
Th e fir st ar gu m en t is a poin t er t o t h e r esu lt r et u r n ed by t h e qu er y.
Th e fu n ct ion r et u r n s a zer o u n less t h er e is a syn t ax er r or in t h e qu er y
specified in querytext.
Th e n am e an d syn opsis of t h e fu n ct ion depen ds on t h e t ype of t h e
expect ed r esu lt :
• object or value
If t h e qu er y r esu lt is an object or valu e (t u ple, (u n iqu e) set, list ).
int o2query (void** handle_address,
char *querytext [, qvariable]...)
• integer
If t h e qu er y r esu lt is an in teger :
int o2query_integer (int *i,
char *querytext [, qvariable]...)
• real
If t h e qu er y r esu lt is a r eal n u m ber :
int o2query_real (double *d,
char *querytext [, qvariable]...)
• character or boolean
If t h e qu er y r esu lt is a ch ar acter or boolean :
int o2query_char (char *c,
char *querytext [, qvariable]...)
26
C In ter face to O2 User Man u al
Using OQL in C
• string
If t h e r esu lt of t h e qu er y is a st r in g:
int o2query_string (char **s,
char *querytext [, qvariable]...)
o2query_string dyn am ically allocat es a C ar r ay for t h e qu er y r esu lt
an d it is you , t h e u ser wh o fr ees t h is char* wh en it is n o lon ger u sed.
Th e ot h er two ar gu m en t s of t h e o2query fu n ct ion ar e:
• querytext
A st r in g, con t ain in g t h e t ext of t h e qu er y, an d can in clu de r efer en ces t o
O 2 sch em a n am es bu t n ot t o local pr ogr am var iables.
Th e st r in g can , h owever , con t ain r efer en ces t o qu er y var iables (defin ed
by su bsequ en t q_variable par am et er s, descr ibed below), in th e for m
of $1 for t h e fir st var iable, $2 for t h e secon d, et c.; an d th ese qu er y
var iables r efer t o local pr ogr am var iables. See t h e exam ples below.
• q_variable
An expr ession r epr esen t in g a valu e t o be su bst itu ted for th e $n
r efer en ces in t h e querytext ar gu m en t .
Th er e m u st be as m an y of t h ese q_variable ar gu m en t s as t h er e ar e
dist in ct $n r efer en ces.
Each qu er y var iable iden t ifies th e t ype as well as th e valu e of a $n
r efer en ce an d m u st t h er efor e t ak e on e of t h e followin g for m s:
• o2_integer (int), for a C in t eger var iable
• o2_real (double), for a C float in g-poin t n u m ber var iable
• o2_char (char), for a C ch ar acter var iable
• o2_string (char *), for a C st r in g var iable
• o2_handle (x), wh er e x is a h an dle st an din g for an O 2 object or an
O2 com plex valu e (t u ple, list , set , u n iqu e set)
• Example queries
To fin d t h e valu e of t h e age at t r ibu t e of n am ed object Father:
int i;
o2query_integer (&i, "Father.age");
C In ter face to O2 User Man u al
27
2
Runtime Library
To filt er t h e n am ed list valu e Employees an d select on ly t h ose
em ployees bet ween t h e ages of min an d max:
typedef void* o2_list_Person;
o2_list_Person s = 0;
int min, max;
...
o2query (&s, "select e
from e in Employees
where e.age < $2 and e.age > $1",
o2_integer(max), o2_integer(min));
To test if Mister M. belon gs t o t h is set of em ployees:
char is_here;
char M_name[10];
...
o2query_char (&is_here, "exists p in $1: p.name
= $2",
o2_handle(s), o2_string(M_name));
Th e o2query fu n ction is also u sed t o in it ialize C var iables wh ich ar e
in st an ces of collect ion s.
Th is is pr obably t h e best way t o in it ialize su ch var iables.
You can wr it e for in st an ce:
typedef void* o2_list_integer;
o2_list_integer L = 0;
o2query (&L, "list (1, 4, 9, 16, 25)");
Method and function call
An O 2 C m et h od or fu n ct ion is easily called u sin g OQL.
28
C In ter face to O2 User Man u al
Using OQL in C
For exam ple, t o call t h e m eth od display on a h an dle h an d t h en call
t h e fu n ct ion stats, you u se t h e followin g OQL qu er ies:
void* Void = 0;
int rc;
double max;
o2query(&Void,
"$1->display",
o2_handle(h));
o2query_integer(&rc,
"stats($1, $2)",
o2_handle(h),
o2_real(max));
Fr om O2 C, wh en a m et h od or fu n ct ion is called, it r eceives h an d l e
par am eter s as n or m al O2 C par am et er s, pr ovided t h eir types m at ch t h e
cor r espon din g O2 C par am et er s.
For exam ple, t h e O2 C fu n ct ion stats is declar ed as:
class Vector type list(real) end;
function stats(v: Vector, upper_bound: real): integer;
At callin g tim e, if t h e h an dle h is n ot an object of class Vector (or on e of
it s su bclasses) a type error except ion is r aised.
Lik ewise an object or a valu e r et u r n ed by an O 2 C m et h od or fu n ction is
r eceived as a h an dle by C.
For exam ple, you h ave a C h an dle r epr esen t in g a list of in t eger s an d you
wan t to call an O2 C fu n ct ion wh ich adds an in t eger t o t h is list an d
r et u r n s t h e n ew in ser t ed list .
C In ter face to O2 User Man u al
29
2
Runtime Library
function insert (l: list(integer),
e: integer): list(integer);
function body insert{
l += list(e);
return l;
}
You call t h e fu n ct ion fr om C as follows:
void * vector;
...
o2query(&vector,
"insert($1, 100)",
o2_handle(vector));
30
C In ter face to O2 User Man u al
Handle management
2.4 Handle management
A h an dl e r epr esen ts an O 2 object or an O2 valu e in side an applicat ion
wr itt en in C.
Manipulating functions
Th e followin g C fu n ct ion s allow you t o m an ipu lat e h an dles. To u se th ese
fu n ct ion s, a C pr ogr am m u st in clu de th e file h eader : o2_c.h.
Th e o2_assign_handle fu n ction assign s t h e sou r ce h an dle t o t h e
t ar get h an dle:
void o2_assign_handle (target_handle_address,
source_handle)
void** target_handle_address; void* source_handle}
Befor e assign m en t , it au t om at ically de-r efer en ces t h e h an dle con t ain ed
in t h e tar get var iable, if on e exist s, an d con sequ en t ly, at t h e t im e of call,
t h e tar get h an dle m u st be set t o 0 or else m u st con t ain a valid h an dle.
M or eover , if t h e t ar get h an dle is n ot 0 befor e assign m en t , it m u st
con t ain a h an dle of t h e sam e k in d as t h e on e con t ain ed in t h e sou r ce
h an dle, i.e. if sou r ce con t ain s a valu e, t ar get m u st be a valu e an d if
sou r ce is an object , t ar get m u st also be an object .
Not e t h at a h an dle is fr eed explicit ly an d set t o 0 by t h e
o2_unref_handle fu n ct ion below.
If t h e above con dit ion s ar e n ot sat isfied, t h e assign m en t fails an d t h e
applicat ion cr ash es possibly wit h t h e m essage “In t er n al in con sist en cy
in th e Com plex Object Man ager ” followed by an au t om at ic abor t .
For exam ple, t o get a h an dle of a n am ed collect ion people in to a
var iable called people an d assign it t o an ot h er var iable, called
copy_people.
#include "o2_c.h"
typedef void* o2_set_Person;
o2_set_Person people = 0, copy_people = 0;
o2query(&people, "people");
o2_assign_handle(&copy_people, people);
C In ter face to O2 User Man u al
31
2
Runtime Library
Th e fu n ct ion :
void o2_assign_name (name, source_handle) char* name;
void* source_handle
u pdates t h e n am ed object (or valu e) iden t ified by name wit h th e object
(or valu e) fou n d in source_handle. Th e n am e m u st be defin ed in t h e
cu r r en t base.
For exam ple
void* node = 0;
compute_root(&node);
o2_assign_name("Graph_root", node);
Th e o2_unref_handle is a m acr o wh ich fr ees t h e h an dle passed as
par am et er an d set s t h is h an dle t o 0:
void o2_unref_handle (handle)
Th e par am et er m u st con tain a valid h an dle or else 0. Ot h er wise t h e
applicat ion wou ld cr ash som ewh er e.
Th is m acr o m u st be called as soon as a h an dle var iable is n o lon ger
u sed by th e applicat ion , an d allows t h e O 2 syst em t o r elease an d
gar bage objects an d valu es wh ich ar e n o lon ger r each able.
Keepin g r efer en ces t o u n u sed object s or valu es can slow per for m an ce.
For exam ple
void* temp = 0;
o2query(&temp, "people"); /* temp stands for a set value */
...
/* to reuse temp and assign to it a new value of a new
type (list(string)), you must free it before assignment */
o2_unref_handle(temp);
o2query(&temp, "list('blue', 'white', 'red')");
o2query(&temp, "list("'yellow')"); /* same type */
/* cannot assign temp with an OBJECT without freeing it
before: */
o2_unref_handle(temp);
o2_assign_handle(&temp, node);
32
C In ter face to O2 User Man u al
Handle management
Iterator functions
Th ese fu n ct ion s en able you t o it er at e on a col l ect i on (object or valu e)
an d u se a type defin it ion o2_iterator.
Th e fu n ct ion o2_iterator_open in itializes a scan passed as par am et er :
o2_iterator o2_iterator_open (collection_handle)
Th is fu n ct ion r et u r n s o2_iterator wh ich m u st be passed to t h e next
an d close m acr os below.
Th e fu n ct ion :
int o2_iterator_next (iterator, element_address)
int o2_iterator_next_string (iterator,
char_array_address)
get s t h e n ext elem en t fr om t h e collect ion for wh ich t h e it er at or h as been
open ed. If th e scan is exh au st ed, it r et u r n s 0, or r et u r n s 1 if n ot .
Th e n ext elem en t is t h e addr ess passed as secon d par am et er an d m u st
be t h e addr ess of:
• a char, for collect ion s of boolean s or ch ar s
• an int, for collect ion s of in t eger s
• a double, for collect ion s of r eals
• a handle, for collect ion s of com plex valu es or collection s of object s.
Th e h an dle is set t o 0 befor e or is valid an d con sist en t , as wit h
o2_assign_handle.
Th e fu n ct ion o2_iterator_next_string get s th e n ext elem en t fr om a
collection of O2 st r in gs or bit s an d pu ts t h e st r in g in t o a C ar r ay.
Th is ar r ay is defin ed by th e secon d par am et er wh ich is of type char *
an d, wh ich is allocat ed by t h e applicat ion befor e callin g t h is fu n ct ion
an d m u st be big en ou gh t o h old t h e st r in g.
Th e fu n ct ion o2_iterator_close ter m in at es t h e scan :
o2_iterator_close (iterator)
C In ter face to O2 User Man u al
33
2
Runtime Library
For exam ple for collect ion of object s:
o2_set_Person s = 0;
o2_Person p = 0;
o2_iterator it;
Person val;
o2query(&s, "people");
it = o2_iterator_open(s);
while(o2_iterator_next(it, &p)){
Person_read(&val, p);
print(val);
}
o2_unref_handle(p); /* release reference "p" to the
last collection element */
o2_iterator_close(it);
For collect ion of st r in gs:
char element[20];
void* flag = 0;
o2_iterator it;
o2query(&flag, "list('blue', 'white', 'red')");
it = o2_iterator_open(flag);
while(o2_iterator_next_string(it, element)){
printf("%s\n", element);
}
o2_iterator_close(it);
Handle conversion
Som et im es you h ave to con ver t a C h an dle in t o an O2 C var iable or
con ver sely, pu t O2 C data in t o C types.
For exam ple, a C pr ogr am wan t s t o pass a C str u ct or a C ar r ay,
con tain in g h an dles, t o an O 2 C fu n ct ion (or m et h od).
34
C In ter face to O2 User Man u al
Handle management
To in ter pr et t h ese h an dles, O2 C tr an sfor m s it t o n or m al O 2 C t yped dat a.
Con ver sely, an O2 C fu n ct ion (or m eth od) m ay n eed t o pu t O2 C dat a in t o
a C str u ct or a C ar r ay t o deliver it t o a callin g C pr ogr am . c_assign
car r ies ou t t h ese t r an sfor m at ion s:
• handle to variable
To con ver t a h an dle in t o an O 2 C var iable, you u se t h e followin g
fu n ct ion :
c_assign(O2c_variable, handle)
Th is O2 C fu n ct ion assign s t h e h an dle handle, an in teger in O 2 C, in to
t h e O2 C var iable O2c_variable.
Th is var iable is an object or a com plex valu e of a t ype con sist en t wit h
t h e act u al dat a r efer r ed t o by t h e h an dle. Dyn am ic type ch eck in g occu r s
(except wh en com piled wit h t h e O2 C opt ion -O).
• variable to handle
To con ver t a var iable in to a h an dle, you u se t h e followin g fu n ct ion :
c_assign(handle_variable, O2C_expression)
Th is O2 C fu n ct ion assign s t h e O2 C expr ession in to a C h an dle, an
in t eger in O2 C. Th e expr ession deliver ed an object or a com plex valu e
wh ich allows h an dles t o be r etu r n ed t o a C pr ogr am .
For exam ple, you can wr it e an O2 C fu n ct ion wh ich get s fr om a C
pr ogr am a 3-field C st r u ct u r e: a h an dle r epr esen tin g an object of t ype
Em ployee, a dou ble r epr esen t in g t h e n ew salar y for th is em ployee an d a
h an dle for an object descr ibin g t h e em ployee cat egor y.
Th e O2 C fu n ction u pdat es th e em ployee’s salar y, com pu t es t h e n ew
cat egor y fr om t h e n ew salar y an d r etu r n s it in th e C str u ct u r e.
Th e st r u ct u r e addr ess is passed as an O 2 C in t eger an d t h e st r u ct u r e
t ype is descr ibed in t h e C file: employee.h:
C In t er face t o O 2 User Man u al
35
2
Runtime Library
typedef void* handle;
typedef struct{ handle employee;
double salary;
handle category;} employee;
Th e O 2 C fu n ct ion is:
type employee_address: integer;
function promote(this: employee_address);
function body promote{
#include "employee.h"
o2 Employee emp;
o2 Category cat;
employee* e= (employee*) this;
c_assign(emp, e->employee); /* get the Employee: */
emp->salary = e->salary; /* update his salary */
cat = compute_cat(e->salary); /* compute new category */
c_assign(e->category, cat); /* return it */
}
Th e C pr ogr am calls t h e O2 C pr om ote fu n ct ion as:
#include employee.h
void* Void = 0;
employee smith;
smith.employee = 0; /* Careful with handle assignment */
smith.category = 0;
o2query(& smith.employee, "Smith");
smith.salary = 15000.0;
o2query(&Void, "promote($1)", o2_integer(&smith));
36
C In ter face to O2 User Man u al
Running an application
2.5 Running an application
You can st ar t an O2 C applicat ion fr om a C pr ogr am by u sin g t h e
followin g fu n ct ion :
int o2_run_application (char * application_name,
char * parameters)
o2_run_application h as t h e followin g par am et er s:
• application_name
Th is is th e n am e of th e O2 C application .
• parameters
Th e parameters opt ion gives t h e par am et er s wit h t h e syn t ax (param1,
param2...). Th i s opt i on equ al s NUL L i f t h e ap p l i cat i on h as n o
p ar am et er s.
Important
Before using o2_run_application, you must start up a transaction.
Th is fu n ct ion r et u r n s 1 if th e applicat ion is u n k n own , ot h er wise 0.
Example
o2_run_application ("customers",
"(1994, \"September\")";
C In ter face to O2 User Man u al
37
2
Runtime Library
2.6 Garbage Collection
To clean u p t h e base, you can u se t h e followin g fu n ct ion :
void o2_garbage_base(char *base_name)
Th e o2_garbage_base fu n ct ion collect s t h e u n r each able object s of a
given base. To u se th is fu n ct ion you m u st call it explicit ly fr om t im e t o
t im e.
To pr even t an y t em por ar y r efer en ces on t o per sist en t dat a, you m u st
com m it befor e callin g t h e gar bage collect or . If you do n ot do t h is you
m ay get wild r efer en ces.
Note
As gar bage collection wor k s wit h in a base, t h is m ean s th at t h ose
object s in a par t icu lar base t h at ar e on l y r each able fr om an ot h er base,
will also get gar bage collect ed .
Example
o2_link_commit();
o2_link_transaction();
o2_garbage_base("my_base");
38
C In ter face to O2 User Man u al
Leaving the database
2.7 Leaving the database
To en d an O2 session
void o2_link_end()
Th e o2_link_end fu n ction t er m in at es th e cu r r en t O2 session .
o2_link_commit is au t om at ically car r ied ou t an d t h e con n ect ion
establish ed by o2_link_init is th en br ok en .
Th e C applicat ion can t h en , of cou r se, con tin u e t o per for m t ask s
u n r elat ed t o O2 .
C In ter face to O2 User Man u al
39
2
40
Runtime Library
C In ter face to O2 User Man u al
3
3
An Example C
Application
Th is ch apt er aim s t o illu str at e h ow t o u se t h e C in t er face t o O 2 wit h a
sim ple exam ple t h at ou t lin es all t h e basic st eps t o wr it in g C pr ogr am s
wit h O2 .
Th is ch apt er is divided u p in t o t h e followin g sect ion s:
• In t r odu ct ion
• D efin e th e class Per son in file Per son .h
• Class Im plem en t at ion in Per son .c
• Th e applicat ion in t h e m ain .c file
• Com pilin g you r application
C In t er face t o O 2 User Man u al
41
3
An Example C Application
3.1 Introduction
To pr ogr am C u sin g t h e C in t er face t o O 2 , you m u st go t h r ou gh t h e
followin g st eps
• Defin e t h e C classes, t h e in st an ces of wh ich you wan t t o m ak e
per sist en t . In th is t u t or ial t h is is th e class Person in Person.h.
• Defin e t h e im plem en t at ion of t h e class Person in Person.c
• Wr it e you r application
• Com pile you r applicat ion an d lin k it to t h e r elevan t O2 libr ar y.
C class definition
Class1_name
libo2link.a
Class_name.h
Class_name_code.c
Application.c
....
....
C compiler and link editor
O2 - C application
Fi gu r e 3 .1 : C I n t er f a ce t o O2
42
C In t er face t o O 2 User Man u al
libo2lklink.a
Define the class Person in file Person.h
3.2 Define the class Person in file Person.h
Fir st of all, you m u st m ak e you r C st r u ct u r es per sist en t . As A poin ter is
on ly valid in side m em or y, you m u st ch an ge t h e type defin it ion an d
r eplacin g all t h e poin t er declar ation s with h an d l es.
For exam ple
typedef struct person{
char * name;
int age;
person[]* children; /* dynamic array of persons */
person* spouse;
struct {
int number;
char * * forename;
} forenames;
} person;
Recall t h at a h an dle is a void* an d it is u sefu l to give differ en t
sym bolic n am es t o h an dles in or der t o docu m en t t h e O2 dat a st or in g t h e
in for m ation .
For exam ple, you defin e a person as an O2 object an d so t h e field
spouse is also an object. You decide t o to pu t children in to a list of
per son s. For fu t u r e oper at ion s on per son object s, it is u sefu l t o
com plet e t h e st r u ct u r e by a t r an si en t (i.e. n on per sist en t ) at t r ibu t e
con t ain in g th e object iden t ifier .
In fact a h an dle con t ain s a u n iqu e iden t ifier for th e object it r epr esen ts
an d an applicat ion pr eser ves object iden t it y.
Th is is n ot so easy a task an d r equ ir es soph isticated dat a st r u ct u r es,
e.g. a h ash t able wh ich m aps t h e h an dle valu e in t o t h e m em or y addr ess
of t h e cor r espon din g C str u ct u r e.
Fin ally, in th e sam e file, you m ak e pr ovision for fu t u r e t ype ext en sion s
lik e o2_set_Person, or fu n ct ion declar at ion s lik e Person_new() wh ich
r et u r n s a n ewly cr eat ed person, th e defin it ion of wh ich is given lat er .
Th e per si st en t C t ype t h er efor e look s as follows:
C In t er face t o O2 User M an u al
43
3
An Example C Application
/* file "Person.h"
is: */
typedef void* o2_Person;
typedef void* o2_list_Person;
typedef void* o2_set_Person;
typedef void* o2_unique_set_Person;
typedef struct{
char * name;
int age;
o2_list_Person children;
o2_Person spouse;
struct {
int number;
char * * forename;
} forenames;
o2_Person object_id;
} person;
extern o2_Person Person_new(); /* defined further */
The class Person
You n ow k n ow h ow t o r epr esen t a “per son ” in O 2 .
So n ow defin e t h e class wit h th e cor r espon din g O2 t ype.
class Person type tuple(
name: string,
age: integer,
children: list(Person),
spouse: Person,
forenames: list(string))
end
Writing and reading a person from C
You n ow h ave a C t ype an d an O 2 class an d you ar e r eady t o defin e t h e
t wo C fu n ct ion s:
44
C In t er face t o O 2 User Man u al
Define the class Person in file Person.h
Person_read an d
Person_write.
Th e fir st tak es an O2 object an d pu t s it in a C st r u ct , wh ile
Person_write copies a C st r u ct in t o an O 2 object.
You can n ot dir ect ly wr ite t h ese con ver sion s in C bu t in O2 C. So t h e two
C fu n ct ion s sim ply call t wo cor r espon din g O2 C m et h ods of t h e class
Per son : wr ite an d r ead:
void Person_read(val, p)
person* val; o2_Person p;
{
/* reads the value of the Person p into the C struct */
void* Void = 0;
o2query(&Void, "$1->read($2)", o2_handle(p),
o2_integer(val));
val->object_id = p;
/* Note the object id inside the structure
This is useful to connect this value to the object. */
};
void Person_write(p, val)
o2_Person p; person val;
{
void* Void = 0;
/* updates the value of the Person p from the C struct */
o2query(&Void, "$1->write($2)", o2_handle(p),
o2_integer(&val));
};
Implementing O2C read and write methods
• Read method
Th e r ead m et h od t ak es a poin ter to t h e C st r u ct an d copies t h e object
in t o it .
C In t er face t o O2 User M an u al
45
3
An Example C Application
type pointer: integer;
method body read(val: pointer) in class Person{
#include "Person.h"
#include <malloc.h>
person* this = (person *) val;
this->name = malloc(count(self->name)+1);
strcpy(this->name, self->name);
this->age = self->age;
this->children = 0; this->spouse = 0;
c_assign(this->children, self->children);
c_assign(this->spouse, self->spouse);
{ o2 string fn; int i = 0;
this->forenames.number = count(self->forenames);
this->forenames.forename = malloc(sizeof(char*) *
this->forenames.number);
for(fn in self->forenames){
this->forenames.forename[i] = malloc(count(fn)+1);
strcpy(this->forenames.forename[i], fn);
i++;
}
}
};
• Write method
Th e wr it e m et h od t ak es a poin t er t o t h e st r u ct u r e an d copies t h e C
st r u ct in t o th e object .
method body write(val: pointer) in class Person{
#include "Person.h"
person* this = (person *) val;
strcpy(self->name, this->name);
self->age = this->age;
c_assign(self->children, this->children);
c_assign(self->spouse, this->spouse);
{ int i; self->forenames = list();
for(i=0; i<this->forenames.number; i++)
self->forenames += list((o2 string) this->forenames.forename[i]);
}
};
46
C In t er face t o O 2 User Man u al
Define the class Person in file Person.h
Creating O2 objects from C
To cr eat e an O 2 object in C, you defin e a C fu n ct ion wh ich calls an O2 C
fu n ct ion to cr eat e an d in it ialize t h is object .
Not ice h ow t h e O 2 C fu n ct ion r et u r n s it s par am et er .
Th e t ype is a n or m al Person t ype, an d t h e C fu n ct ion r eceives a h an dle.
The Person_new C function
o2_Person Person_new(name)
char* name;
{
/* creates a new persistent Person */
o2_Person p = 0;
o2query(&p, "Person_new($1)", o2_string(name));
return p;
};
Implementing Person_new in O2C
constant name people: set(Person);
/* the persistent extension */
method body init(name: string) in class Person{
/* constructor */
self->name = name;
people += set(self);
};
function Person_new(name:string): Person;
/* interface for C */
function body Person_new{
return new Person(name);
};
Now you can wr ite t h e com plet e applicat ion , en h an cin g it wit h fan cy
oper ation s.
C In t er face t o O2 User M an u al
47
3
An Example C Application
Th e n ext sect ion gives t h e code followed by t h e Mak efile t o gen er ate t h e
execu t able.
48
C In t er face t o O 2 User Man u al
The application code
3.3 The application code
The C header file Person.h
typedef void* o2_Person;
typedef void* o2_list_Person;
typedef void* o2_set_Person;
typedef void* o2_unique_set_Person;
typedef struct{
char * name;
int age;
o2_list_Person children;
o2_Person spouse;
struct {
int number;
char * * forename;
} forenames;
o2_Person object_id;
} person;
extern o2_Person Person_new();
The O2C schema
schema family_s;
type pointer: integer;
class Person type tuple(
name: string,
age: integer,
children: list(Person),
spouse: Person,
forenames: list(string))
method
init(name:string),
public birth(child: Person),
public ancestors: unique set(Person),
/* communication O2 <-> C methods: */
public read(val: pointer),
public write(val: pointer)
end;
C In t er face t o O2 User M an u al
49
3
An Example C Application
constant name people: set(Person);
/* persistent extension */
name God: Person;
/* a particular Person ! */
set class Person;
method body init(name: string){
self->name = name;
people += set(self);
};
method body birth(child: Person){
/* new child is born */
self->children += list(child);
if (self->spouse != nil)
self->spouse->children += list(child);
};
method body ancestors: unique set(Person){
/* What are the ancestors of this Person ? */
o2 unique set(Person) parents, ancestors;
o2query(parents,
"select unique x from x in people\
where $1 in x.children",
self);
o2query(ancestors,
"flatten(\
select unique a->ancestors\
from a in $1\
)union $1"
, parents);
return ancestors;
};
method body read(val: pointer){
/* read a C val from this O2 object */
#include "Person.h"
#include <malloc.h>
person* this = (person *) val;
this->name = malloc(count(self->name)+1);
strcpy(this->name, self->name);
this->age = self->age;
this->children = 0; this->spouse = 0;
c_assign(this->children, self->children);
c_assign(this->spouse, self->spouse);
{ o2 string fn; int i = 0;
this->forenames.number = count(self->forenames);
this->forenames.forename = malloc(sizeof(char*) *
this->forenames.number);
50
C In t er face t o O 2 User Man u al
The application code
for(fn in self->forenames){
this->forenames.forename[i] = malloc(count(fn)+1);
strcpy(this->forenames.forename[i], fn);
}
}
};
method body write(val: pointer){
/* write a C val into this O2 object */
#include "Person.h"
person* this = (person *) val;
strcpy(self->name, this->name);
self->age = this->age;
c_assign(self->children, this->children);
c_assign(self->spouse, this->spouse);
{ int i; self->forenames = list();
for(i=0; i<this->forenames.number; i++)
self->forenames += list((o2 string)
this->forenames.forename[i]);
}
};
/* Special C interfaces */
function Person_new(name:string): Person;
function body Person_new(name:string): Person{
return new Person(name);
};
function clear;
function body clear{
people = set();
};
/*-------- Create a database ----------*/
create base family;
/*-------- ... and possibly index ----------*/
create index people on name;
create index people on children;
quit
C In t er face t o O2 User M an u al
51
3
An Example C Application
3.4 Class Implementation in Person.c
Th e followin g gives t h e code wh ich im plem en t s t h e class Person.Th is is
in th e file Person.c.
#include
#include
#include
#include
#include
"Person.h"
"o2_c.h""
<stdio.h>
<malloc.h>
<string.h>
Header files
o2_Person Person_new(name)
char* name;
create a new persistent Person
{
o2_Person p = 0;
o2query(&p, "Person_new($1)", o2_string(name));
return p;
};
void Person_read(val, p)
read value of p into C struct
person* val; o2_Person p;
{
void* Void = 0;
o2query(&Void, "$1->read($2)", o2_handle(p), o2_integer(val));
val->object_id = p;
};
This value is of object id.
void Person_write(p, val)
o2_Person p; person val;
{
void* Void = 0;
o2query(&Void, "$1->write($2)", o2_handle(p), o2_integer(&val));
};
void Person_birth(p, child)
update value of p from C struct.
o2_Person p; o2_Person child;
{
void* Void = 0;
o2query(&Void, "$1->birth($2)", o2_handle(p), o2_handle(child));
};
o2_unique_set_Person Person_ancestors(p)
o2_Person p;
{
o2_unique_set_Person s = 0;
o2query(&s, "$1->ancestors()", o2_handle(p));
return s;
};
void clear(){
void* Void = 0;
o2query(&Void, "clear()");
};
void person_init(val)
person* val;
52
C In t er face t o O 2 User Man u al
Class Implementation in Person.c
{
/* initialize a "person" structure: any "handle" must be set
to 0, in order for future o2_assign_handle to work properly */
val->name = 0;
val->spouse = 0; val->children = 0;
val->forenames.number = 0;
}
void person_clean(val)
person* val;
{
/* frees mallocated parts of a C struct */
int i;
free(val->name); val->name = 0;
for(i=0; i<val->forenames.number; i++)
free(val->forenames.forename[i]);
if(val->forenames.number >0){
free(val->forenames); val->forenames.number = 0;
}
/* release internal handles: */
o2_unref_handle(val->spouse);
o2_unref_handle(val->children);
};
int has_forename(p, forename)
person p; char* forename;
{
int i;
for(i = 0; i<p.forenames.number; i++)
if(!strcmp(p.forenames.forename[i], forename)) return 1;
return 0;
};
void add_forename(p, forename)
person* p; char* forename;
{
if(!has_forename(*p, forename)){
p->forenames.forename = (char**)
realloc(p->forenames.forename,
sizeof(char*) * (++(p->forenames.number)));
p->forenames.forename[p->forenames.number-1] = forename;
}
};
C In t er face t o O2 User M an u al
53
3
An Example C Application
void print(val)
person val;
{
int i;
printf("-- %s", val.name);
printf(" ( %d years) ", val.age);
for(i=0; i<val.forenames.number; i++)
printf("%s", val.forenames.forename[i]);
printf("\n");
};
/* Using Iterator */
void print_persons(s)
o2_set_Person s;
{
o2_Person p = 0;
o2_iterator it;
person val;
person_init(&val);
it = o2_iterator_open(s);
while(o2_iterator_next(it, &p)){
Person_read(&val, p);
print(val);
person_clean(val);
/*free memory allocated for reading object*/
}
o2_unref_handle(p);
/* release the object refered to by "p" */
o2_iterator_close(it);
};
/* Keeping object references */
void mariage(val, with)
person* val; o2_Person with;
{
person the_spouse; person_init(&the_spouse);
o2_assign_handle(&val->spouse, with);
/* val->spouse gets a new reference to the spouse Person (with) ... */
Person_read(&the_spouse, with);
o2_assign_handle(&the_spouse.spouse, val->object_id);
/* and the spouse refers to this Person. */
Person_write(with, the_spouse);
person_clean(the_spouse);
};
54
C In t er face t o O 2 User Man u al
The application in the main.c file
3.5 The application in the main.c file
Th e followin g code is t h e m ain pr ogr am of ou r exam ple applicat ion .
#include "o2_c.h"
#include "Person.h"
static void transaction_load(){
/* Load the database */
o2_Person zeus, adam, eve, tmp;
person ad; person_init(&ad);
o2_link_transaction(); /* Start a new update transaction */
clear(); /* Create a new O2 object ... */
zeus = Person_new("zeus"); /* and give him an O2 name. */
o2_assign_name("God", zeus);
adam = Person_new("adam");
Person_birth(zeus, adam);
eve = Person_new("eve");
Person_birth(zeus, eve);
Person_read(&ad, adam);
mariage(ad, eve);
Person_write(adam, ad);
Person_birth(adam, tmp = Person_new("abel"));
o2_unref_handle(tmp);
Person_birth(adam, tmp = Person_new("cain"));
o2_unref_handle(tmp);
person_clean(ad);
o2_unref_handle(zeus); o2_unref_handle(adam); o2_unref_handle(eve);
o2_link_commit();
}
static o2_Person cain; /* A global variable */
static void transaction_consult(){
/* Read-only transaction. */
int rc;
o2_set_Person people = 0;
printf("----- ALL THE PEOPLE -------\n");
o2query(&people, "people");
print_persons(people);
printf("----- CAIN’S ANCESTORS -------\n");
cain = 0;
rc =
o2query(&cain,
"element(select p from p in people where p.name = 'cain')");
if(rc!=0){
printf("query failed\n");
o2_link_abort();
}else{
print_persons(Person_ancestors(cain));
}
o2_unref_handle(people); o2_unref_handle(cain);
}
C In t er face t o O2 User M an u al
55
3
An Example C Application
static void transaction_update(){
o2_Person p, q;
person jones; person_init(&jones);
/* Start a new update transaction */
o2_link_transaction();
Person_birth(cain, p = Person_new("jones"));
Person_read(&jones, p);
add_forename(jones, "Charles");
add_forename(jones, "Jean");
add_forename(jones, "Christian");
add_forename(jones, "Jean");
jones.age = 20;
Person_write(p, jones);
Person_birth(p, q = Person_new("Smith"));
print_persons(Person_ancestors(q));
person_clean(jones);
o2_unref_handle(p); o2_unref_handle(q);
o2_link_commit();
}
Main program
Th e m ain pr ogr am of t h e applicat ion in th e file m ain .cc is as follows:
56
C In t er face t o O 2 User Man u al
The application in the main.c file
main(argc, argv)
int argc; char* argv[];
{
static O2_sinit o2_sinit = {
"/o2_directory/home",
"user_system",
"machine",
".",
0,0
};
#define ALPHA 1
if(o2_link_init(argc, argv, &o2_sinit, ALPHA)!=0){
printf("Something wrong to start o2\n");
exit(1);
}
o2_link_set_base("family");
transaction_load();
transaction_consult();
transaction_update();
{o2_set_Person people = 0;
printf("----- ALL THE PEOPLE -------\n");
o2query(&people, "people");
print_persons(people);
}
o2_link_end();
}
C In t er face t o O2 User M an u al
57
3
An Example C Application
3.6 Compiling your application
The Makefile
To com pile th is applicat ion , you can wr it e t h e followin g M ak efile (for
H P).
LINK.c= cc $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $(TARGET_ARCH)
O2HOME = /o2_directory/home
IFLAGS= -I. -I$(O2HOME) -I$(O2HOME)/include
CFLAGS = -g $(IFLAGS)
LDLIBS = -Wl,-E -L$(O2HOME)/lib -lo2link -lo2 -lo2linkcuse -lm -ldld
#Using O2Look
# LDLIBS = -Wl,-E -L$(O2HOME)/lib -lo2lklink -lo2 -lo2linkcuse -lm
-ldld -lXm -lXt -lX11
#Using OQL
# LDLIBS = -Wl,-E -L$(O2HOME)/lib -lo2link -lo2sql -lo2 -lo2linkcuse
-lm -ldld
#Using O2Look and OQL
# LDLIBS = -Wl,-E -L$(O2HOME)/lib -lo2lklink -lo2sql -lo2 -lo2linkcuse
-lm -ldld -lXm -lXt\ -lX11
#---------------------------------------------------------------#
# Here are the .o necessary to build the application:
# OBJS.appli = main.o Person.o The user’s application
#---------------------------------------------------------------#
OBJS.appli = main.o Person.o
.KEEP_STATE:
appli:$(OBJS.appli)
$(LINK.c) -v $(OBJS.appli) -o $@ $(LDLIBS)
Makefiles and Platforms
Refer t o t h e docu m en tation of you r Oper at in g system t o wr it e t h e
M ak efiles bu ildin g you r applicat ion .
In par t icu lar t h e ld com m an d is differ en t for each plat for m .
For O2 , depen din g on th e plat for m you m u st u se t h e followin g opt ion s
for t h e lin k edit ion of you r applicat ion :
58
C In t er face t o O 2 User Man u al
Compiling your application
• SUN-OS
cc -Bstatic -o appli main.o Person.o -L$(O2HOME)/lib -lo2link -lo2\
-lo2linkcuse -lm
• HP UX
cc -Wl, -E -o appli main.o Person.o
-lo2linkcuse -lm -ldld
-L$(O2HOME)/lib -lo2link -lo2\
• IBM Aix
cc -bM:SRE -bE:$(O2HOME)/lib/o2.exp -o appli main.o Person.o\
-L$(O2HOME)/lib -lo2link -lo2 -lo2linkcuse -lm -lbsd
• IRIX
cc -o appli main.o Person.o -L$(O2HOME)/lib -lo2link -lo2\
-lo2linkcuse -lm -ldl
• Solaris
/opt/SUNWspro/bin/cc -o appli main.o Person.o -L$(O2HOME)/lib\
-lo2link -lo2 -lm -lsocket -lnsl -lgen -ldl -lo2linkcuse
• NeXTStep
cc -o appli main.o Person.o -L$(O2HOME)/lib -lo2link -lo2\ -all_load
C In t er face t o O 2 User Man u al
59
3
60
An Example C Application
C In t er face t o O 2 User Man u al
IN DEX
C In ter face t o O2 User Man u al
61
INDEX
Sym bol s
.c 52
.c file 52
.h file 43, 49
A
Com m it 24
Con n ectin g dat abase 20
Con ver t in g h an dles 34
D
Database
Con n ect ion 20
Exit 39
Defin in g t r an saction s 23
display 29
Applicat ion
C 13, 23
Code exam ple 49
Exam ple 43
Main Pr ogr am 56
O2 C 16, 37
Ru n 16, 37
Str u ct u r e 15
F
Ar ch itect u r e
O2 10
File
.c 52
.h 43
main.c 55
C
Fu n ct ion
c_assign 35
Call 15, 28
It er at or 33
Man ipu lat ion 31
o2query 26, 27
C 11
Applicat ion 13, 15, 43
In t er face 14
Readin g fr om 44
Wr it in g fr om 44
G
C++
In t er face 11
c_assign 16, 35
Class defin ition 44
Collect ion 15
It er at or s 16, 33
Qu er y 15
62
Gar bage Collect ion 38
C In ter face t o O2 User Man u al
INDEX
H
M
H an dle 15, 29, 43
Assign m en t 35
Con ver sion 34
Iden t ifier 43
Man agem en t 31
Mak efile 58
Met h od
Call 15, 28
display 29
read 45
write 46
I
Modu les
O2 12
N
In stallat ion dir ect or y 21
It er at or 33
J
Nam ed
Object 16
Valu e 16
J ava 11
O
L
O2
libname 21, 22
libo2link.a 20
libo2linkcuse.a 20
libpath 21
Libr ar ies 20
Advan t ages 13
Ar ch it ect u r e 10
Collect ion 15
Fu n ct ion s 15
In t egr at ed m odu les 12
Libr ar y 20
Met h ods 15
o2_assign_handle 31
o2_assign_name 32
o2_char 27
o2_garbage_base 38
o2_handle 27
o2_integer 27
C In ter face t o O2 User Man u al
63
INDEX
o2_iterator 33
o2_iterator_close 33
o2_iterator_next 33
o2_iterator_next_string 33
o2_iterator_open 33
o2_link_abort 15, 25
o2_link_commit 15, 24
o2_link_end 16, 39
o2_link_init 20–22
o2_link_set_base 22
o2_link_transaction 15, 23, 24
o2_link_validate 15, 24
o2_real 27
o2_run_application 16, 37
o2_string 27
o2_unref_handle 32
O 2 C 11
O 2C
Applicat ion 16, 37
Fu n ct ion call 15, 28
Met h od call 15, 28
O 2 Cor ba 11
O 2 DBAccess 11
O 2 En gin e 10
O 2 Gr aph 11
O 2 Kit 11
O 2 Look 11
O 2 Look
Libr ar ies 20
O 2 OD BC 11
o2query 26, 27
o2query_char 26
o2query_integer 26
o2query_real 26
o2query_string 27
O 2 Stor e 10
O 2 Tools 11
O 2 Web 11
Object 31
Assign m en t 16
Iden t ifier 43
64
OQL 11
Fu n ct ion call 28
In t er face 26
Met h od call 28
Usin g in C 15
P
Per sist en ce 13, 43
Platfor m s 58
Poin t er declar at ion s 43
Pr ogr am 23
Q
q_variable 27
Qu er yin g 15, 26–28
querytext 27
R
read 46
Readin g fr om C 44
Read-on ly
Tr an sact ion s 23
Ru n applicat ion 37
C In ter face t o O2 User Man u al
INDEX
S
set base 22
svname 21
swapdir 21
sysdir 21
sysname 21
Syst em
Ar ch it ectu r e 10
Featu r es 13
Valu e 15, 31
Assign m en t 16
W
write 46
Wr it in g fr om C 44
systems file 21
T
Tr an saction 15
Defin it ion 23
Man agem en t 23–25
Read-on ly 23
Updat e 24
U
Update t r an saction s 24
V
Validate 25
C In ter face t o O2 User Man u al
65