Home

C Interface to O2 User Manual

1. 17 Runtime Library 19 2 1 Database CASON nnna 20 Starine an OA onn i 20 22 2 2 Transaction 0 1 112222 23 Denmas Transat NONS eie 23 Read only transacto 23 Loo dtp oni ED dim n 24 Ed Using LL nein nnn niente 26 26 Method and function call 28 2 4 Handle management usua erai dna FER RR RAM AI ER RRRA PAM tia 31 Manipulating 31 33 Handle 34 25 Hunning 37 37 2 6 Garbage Collection 38 38 2 7 Leaving the daltaDaBB 39 C Interface to Oo User Manual TABLE CONTENTS An Example C Application 41 31 42 3 2 Define the class Person file Person h 43 44 Writing and reading person from 44 Implementing O2C read and writ
2. Interface to User Manual Release 5 0 May 1998 2 Information in this document is subject to change without notice and should not be construed as a commitment by O Technology The software described in this document is delivered under a license or nondisclosure agreement The software can only be used or copied in accordance with the terms of the agreement It is against the law to copy this software to magnetic tape disk or any other medium for any purpose other than the purchaser s own use Copyright 1992 1998 O Technology All rights reserved No part of this publication can be reproduced stored in a retrieval system or transmitted in any form or by any means electronic mechanical photocopy without prior written permission of Oo Technology 2 2 OoGraph 2 OoLook OoStore OoTools OoWeb are registered trademarks of Oo Technology SQL and AIX are registered trademarks of International Business Machines Corporation Sun SunOS and SOLARIS are registered trademarks of Sun Microsystems Inc X Window System is a registered trademark of the Massachusetts Institute of Technology Unix is a registered trademark of Unix System Laboratories Inc HPUX is a registered trademark of Hewlett Packard Company BOSX is a registered trademark of Bull S A IRIX is a registered trademark of Siemens Ni
3. family transaction load transaction consult transaction update 02 set Person people 0 printf ALL THE PEOPLE o2query amp people people print persons people o2 link end C Interface to O User Manual 57 3 An Example C Application 3 6 Compiling your application The Makefile To compile this application you can write the following Makefile for HP LINK c cc CFLAGS CPPFLAGS LDFLAGS O2HOME o2 directory home IFLAGS I I O2HOME I O2HOME include CFLAGS g IFLAGS LDLIBS W1 E L O2HOME lib lo2link 102 lo2linkcuse lm 1 1 Using O2Look LDLIBS 1 L O2HOME lib 1021klink 102 lo2linkcuse lm 1414 1Xm 1Xt 1X11 Using OQL LDLIBS W1l E L O2HOME lib lo2link 102541 102 lo2linkcuse lm ldld Using O2Look and OQL LDLIBS W1 E L O2HOME lib 1021 11 102541 102 lo2linkcuse lm ldld 1Xm 1xt 1X11 Here are the o necessary to build the application OBJS appli main o Person o user s application OBJS appli main o Person o 5 appli OBJS appli LINK c v OBJS appli o LDLIBS Makefiles and Platforms Refer to the documentation of your Operating system to write the Makefiles building your application In particular the 1d command is different for each platform For Oo depending on
4. vold Person read val read value of p into C struct person val o2 Person p void Void 0 o2query amp Void 1 gt read 2 o2 handle p o2_integer val val object id p i This value is of object id void Person_write p val o2 Person p person val void Void 0 o2query amp Void 1 gt write 2 o2 handle p o2 integer amp val void Person_birth p child 02 Person p o2 Person child update value of p from C struct void Void 0 o2query amp Void 1 birth 2 o2 handle p o2_handle child o2_unique_set_Person Person ancestors o2 Person p o2 unique set Person 0 o2query amp s 1 ancestors o2 handle p return s void 1 void Void 0 o2query amp Void clear void person_init val person val C Interface to O User Manual Class Implementation 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 gt spouse 0 val children 0 val gt forenames number 0 void person_clean val person val frees mallocated parts of struct int i free val gt name val name 0 for 1 0 i lt val gt forenames number i free 1 gt forename 1 if val forenames number gt 0 free val forenames val forenames number re
5. All standard programming languages can be used with standard environments e g Visual C Sun Sparcworks External Interfaces OoDBAccess e O2Web Create 2 Orbix server to access database with CORBA Connect 2 applications to relational databases on remote hosts and invoke SQL statements Connect remote ODBC client applications to Oo databases Create an World Wide Web server to access an Oo database through the internet network C Interface to User Manual 11 1 Introduction Integrated modules If you choose to use the C interface to you see that inherits all the advantages of the system database engine O Engine Objects C applications are manipulated in the same way as standard C objects Any existing application can be made persistent after very minor modification ensures database consistency referential integrity and automatically manages the dynamic memory of objects It also provides facilities for creating and manipulating O and collections e You use the complementary tools OQL and O Look database query complex value creation and initialization object browsing and object editing C Interface User Manual Features and advantages 1 2 Features and advantages Developing applications in has several key benefits data persis
6. o2 link init function sets up a working connection between the external C program and the specified Oo system name and is much like starting up an session under Unix by invoking the o2 executable program The function passes the argc and argv parameters as command line arguments to the o2 executable The argc and argv parameters arethe number and list of command line arguments with which the external C application was launched C Interface User Manual Database Connection Any valid O2 command line options can be used when launching aC application The sinit parameter is a pointer to an instance of the following structure typedef struct char sysdir An Og installation directory char sysname An named system char svname Machine where o2server is running char swapdir Special swap directory char libpath Paths to search for libraries char libname Library names to search for O2 sinit The definition of this structure is given in the header file o2 c h All the various members of the structure are described below The first four members of the structure identify which system to use and the last two only serving those applications needing dynamic run time linking to one or more libraries of C functions sysdir This is the absolute path of an Oo installation directory con taining the systems file and the bin subdirectory holding the executables This must be
7. application code for fn 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 gt age c assign self children this children c assign self spouse this spouse int i self gt forenames list 0 i this forenames number i self gt forenames list o2 string this forenames forename i Special interfaces function Person_new name string Person function body Person_new name string Person return new Person 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 Interface to O User Manual 51 3 An Example C Application 3 4 Class Implementation in Person c The following gives the code which implements the class Person This is in the file Person c include Person h include o2 c h include lt stdio h gt include lt malloc h gt Header files include lt string h gt o2 Person Person_new name char name create a new persistent Person o2_Person p 0 o2query amp p Person_new 1 o2 string name return p
8. o2 assign handle amp val spouse with val spouse gets a new reference to the spouse Person with Person read amp the spouse with 02 assign handle amp the spouse spouse val object id and the spouse refers to this Person Person write with the spouse person clean the spouse 54 C Interface to O User Manual The application the main c file 3 5 The application in the main c file The following code is the main program of our example application include o2 c h include Person h static void transaction 1 Load the database o2 Person zeus adam eve tmp person ad person init amp 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 amp 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 global variable static void transaction consult Read only transaction int rc o2 set Person people 0 printf ALL THE PEOPLE
9. o2query amp people people print persons people printf CAIN S ANCESTORS cain 0 rc o2query amp cain element select p from p in people where p name cain if rc 0 printf query failed n o2 link abort 1 print persons Person ancestors cain o2 unref handle people o2 unref handle cain C Interface to O User Manual 55 3 An Example C Application static void transaction update o2 Person p q person jones person init amp jones Start a new update transaction o2 link transaction Person birth cain Person new jones Person read amp 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 Person new Smith print persons Person ancestors person clean jones o2 unref handle p o2 unref handle o2 link commit Main program The main program of the application in the file main cc is as follows C Interface to O User Manual The application the main c file main argc argv int char argv static O2_sinit o2_sinit o2 directory home user system machine define ALPHA 1 if o2 link init argc argv amp o2 sinit ALPHA 0 printf Something wrong to start 2 exit 1 2 link set
10. updating objects adding new information deleting information etc By default an application runs in a read only transaction This is a transaction where no updates on persistent data are allowed Using OQL in C Inside a transaction the object query language OQL is used so that your C application can use an O database in order to query O collection call function call an O5C method Handles For a C application object or an value is handle Your program manipulates these O objects and values by calling O5C functions or methods and passing and receiving the objects and values as parameters C Interface to O User Manual 15 Introduction You can carry out the following operations on handles assign a value to another value assign an object to another object assign a value to a named value assign an object to a named object iterate a collection You can also carry out handle conversion Inside an function body or method body you can convert a handle into an o2 variable or conversely convert an o2 variable into a handle You do this by using the function assign e Running the application You can start an application from a C program using the function 02 run application Leaving an Oo session You end the session and leave the database using the function o2 link end C Interface User Manu
11. 26 27 o2query char 26 o2query integer 26 o2query real 26 o2query string 27 OzStore 10 2 11 OoWeb 11 Object 31 Assignment 16 Identifier 43 OQL 11 Function call 28 Interface 26 Method call 28 Using in C 15 P Persistence 13 43 Platforms 58 Pointer declarations 43 Program 23 Q q variable 27 Querying 15 26 28 querytext 27 R read 46 Reading from C 44 Read only Transactions 23 Run application 37 C Interface to User Manual INDEX Value 15 31 Assignment 16 W set base 22 svname 21 swapdir 21 sysdir 21 write 46 sysname 21 Writing from C 44 System Architecture 10 Features 13 systems file 21 T Transaction 15 Definition 23 Management 23 25 Read only 23 Update 24 U Update transactions 24 V Validate 25 C Interface to O User Manual 65
12. Library 2 3 Using OQL inC o2query This section now describes how to call OQL from aC program using this function pass C parameters to it and get the result of the query It then describes how to call method or function from OQL in order to use the Oo database The interface to has a set of functions each with beginning with o2query which are the interface between C applications and OQL The first argument is a pointer to the result returned by the query The function returns a zero unless there is a syntax error in the query specified in querytext The and synopsis of the function depends on the type of the expected result object or value If the query result is an object or value tuple unique set list int o2query void handle address char querytext qvariable integer If the query result is an integer int o2query integer int i char querytext qvariable real If the query result is a real number int o2query real double d char querytext qvariable character or boolean If the query result is a character or boolean int o2query char char char querytext qvariable 26 C Interface User Manual Using OQL string If the result of the query is a string int o2query string char s char querytext qvariable o2query string dynamically allocates a C arra
13. a macro which frees the handle passed as parameter and sets this handle to 0 void o2 unref handle handle The parameter must contain a valid handle or else 0 Otherwise the application would crash somewhere This macro must be called as soon as a handle variable is no longer used by the application and allows the 2 system to release garbage objects and values which are no longer reachable Keeping references to unused objects or values can slow performance For example void temp 0 o2query amp 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 amp temp list blue white red o2query amp temp list yellow same type cannot assign temp with an OBJECT without freeing it before o2 unref handle temp 02 assign handle amp temp node C Interface User Manual Handle management Iterator functions These functions enable you to iterate on acollection object or value and use a type definition o2 iterator Thefunction o2 iterator openinitializes a scan passed as parameter 02 iterator o2 iterator open collection handle This function returns o2 iterator which must be passed to the next and close macros below The function int o2 iterator next iterator element address int o2 iterator next string iterat
14. amp Void promote 1 o2 integer amp smith C Interface User Manual Running application 2 5 Running an application You can start an 2 application from a C program by using the following function int o2_run_application char application_name char parameters o2 run application has the following parameters application name This is the name of the 2 application parameters The parameters option gives the parameters with the syntax param1 param2 This option equals NULL if the application has no param eters Important Before using 02 run application you must start up a transaction This function returns 1 if the application is unknown otherwise 0 Example o2 run application customers 1994 N September NV C Interface to O User Manual 37 2 Runtime Library 2 6 Garbage Collection To clean up the base you can use the following function void o2 garbage base char base_name The o2 garbage base function collects the unreachable objects of a given base To use this function you must call it explicitly from time to time To prevent any temporary references onto persistent data you must commit before calling the garbage collector If you do not do this you may get wild references Note As garbage collection works within a base this means that those objects in a particular base that are on
15. link transaction This leaves read only mode Consistency is guaranteed by O which automatically rereads the variables which have been read during read only mode Commit The following transaction ends the current transaction on the current database void o2 link commit o2 link commit updates the database releases all locks frees all memory allocated at runtime and then starts a read only transaction All changes made to the database during the present transaction are written to disk and a new transaction is initiated After a commit all handles held by aC application are no longer valid and they must be recomputed starting from persistent roots Validate The validate function is as follows void o2 link validate 24 C Interface User Manual Transaction Management This function is the same as o2 link commit except that it does free the memory allocated by to run this transaction After a validate all handles held by a C application are still valid Abort The abort function is as follows void o2 link abort This function also ends the current database transaction Any changes made to the database during the present transaction are abandoned and a new transaction is initiated After an abort all handles held by a C application are no longer valid and they must be recomputed starting from persistent roots C Interface to User Manual 25 Runtime
16. p name zeus oZ list Person new amp lp p children lp p spouse NULL Person write amp zeus 8 oz unique set Person insert all zeu oZ link commit z spouse name Figure 1 2 interface to O2 14 C Interface User Manual Introducing the interface to 2 C Application structure An application is a C executable which at some moment connects itself to opens a database and then runs under the control of the O transaction manager It then uses OQL to query the database and to call up functions and methods in order to manipulate handles objects or values Database connection A C application communicates with O via various functions defined in an O library The application starts up an session using the o2 link init function and defines a database context against which the application runs using the o2 link set base function e Transactions It can then start up a transaction using the o2 link transaction function and can end the transaction by committing the transaction using the o2 link commit function validating the transaction using the o2 link validate function or aborting the transaction using the o2 link abort function An application is usually made up of many transactions each one reflecting a particular utilization of the database creating objects querying information
17. the object identifier In fact ahandle contains a unique identifier for the object it represents and an application preserves object identity This is not so easy a task and requires sophisticated data structures e g a hash table which maps the handle value into the memory address of the corresponding C structure Finally in the same file you make provision for future type extensions like o2 set Person or function declarations like Person new which returns a newly created person the definition of which is given later The persistent C type therefore looks as follows C Interface to O User Manual 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 now know how to represent a person in Oo So now define the class with the corresponding O type 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 now have C type and an Oo class and you are ready to define the two C functions 44 C In
18. the platform you must use the following options for the link edition of your application 58 C Interface to O User Manual Compiling your application SUN OS Bstatic o appli main o Person o L O2HOME lib lo2link 102 lo2linkcuse lm HP UX Wl E o appli main o Person o L O2HOME lib 1o21ink 102 lo2linkcuse lm ldld BM Aix bM SRE bE O2HOME lib o2 exp o appli main o Person o L O2HOME lib lo21ink 102 lo2linkcuse lm lbsd IRIX cc o appli main o Person o L O2HOME lib 1o21ink 102 lo21inkcuse lm 141 Solaris opt SUNWspro bin cc o appli main o Person o L O2HOME libN lo21ink 102 lm lsocket 1 51 lgen 141 1o21inkcuse NeXTStep C Interface to O User Manual 59 Example Application 60 Interface to O User Manual INDEX C Interface User Manual 61 INDEX Symbols 26 52 file 52 file 43 49 A Application 13 23 Code example 49 Example 43 Main Program 56 2 16 37 16 37 Structure 15 Architecture 10 Application 13 15 43 Interface 14 Reading from 44 Writing from 44 C Interface 11 c_assign 16 35 Class definition 44 Collection 15 Iterators 16 33 Query 15 Commit 24 Connecting database 20 Converting handles 34 D Database Conne
19. Look 1 indicates that the application is alphanumeric o2 link init function returns zero if the link to Oo was successfully established or an error code if not Setting a base The C program then sets the database with which it wants to work by using the following O2 function int o2 link set base base name char base name This is the same as the schema command set base The o2 link set base function identifies the base with which the external program wants to work A base with the specified name must already exist within the named database system specified in the o2 1ink init function above The function returns zero if the base indicated is found or an error code if not 1 Only meaningful with the graphical version of O2 C Interface User Manual Transaction Management 2 2 Transaction Management This section describes all the various runtime library functions you need to work with transactions This section is divided as follows Defining transactions e Read only transactions Update transactions Defining transactions You start up a new transaction using the following function void o2 link transaction By default a C application runs as a program i e it is allowed to read persistent data but not to update In order to update the application must start a transaction Read only transactions to the o2 1ink transactionis not obliga
20. Person new 1 o2_string name return p Implementing Person new 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 write the complete application enhancing it with fancy operations C Interface to O User Manual 47 Example Application The next section gives the code followed by the Makefile to generate the executable 48 C Interface O User Manual 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 O5C 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 point
21. al Manual overview 1 4 Manual overview This manual is divided up into the following chapters Chapter 1 Introduction This chapter introduces the interface to outlines the system and gives all the features and advantages the interface has to offer It then goes on to introduce the structure of a C application in O outlining such concepts as database connection transaction management using to query the database and to call functions and methods in order to manipulate objects and values handles O objects and values running the application and leaving an session Chapter 2 Runtime Library This chapter gives all the runtime library functions you need to use the C interface to and is divided up into the following sections Database connection Transaction management Using OQL in C Handle management Running the application Leaving the database Chapter 3 Example application This chapter gives a complete example of how to use the C interface to showing how to make structures persistent how to create data as well as store and retrieve these structures to and from a database C Interface to User Manual 17 Introduction Interface User Manual 2 Runtime Library This chapter gives the runtime library functions you need to use the C inter face to Oo The chapter is divided into th
22. ction 20 Exit 39 Defining transactions 23 display 29 F File 52 h 43 main c 55 Function c_assign 35 Call 15 28 Iterator 33 Manipulation 31 o2query 26 27 G Garbage Collection 38 C Interface to User Manual INDEX H Handle 15 29 43 Assignment 35 Conversion 34 Identifier 43 Management 31 Installation directory 21 Iterator 33 Java 11 libname 21 22 libo21link a 20 libo2linkcuse a 20 libpath 21 Libraries 20 M Makefile 58 Method Call 15 28 display 29 read 45 write 46 Modules Oo 12 N Named Object 16 Value 16 O Advantages 13 Architecture 10 Collection 15 Functions 15 Integrated modules 12 Library 20 Methods 15 o2 assign handle 31 02 assign name 32 o2 char 27 o2 garbage base 38 o2 handle 27 o2 integer 27 C Interface to O User Manual 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 2 link commit 15 24 02 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 11 2 Application 16 37 Function call 15 28 Method call 15 28 11 OsDBAccess 11 10 11 OokKit 11 11 OoLook Libraries 20 11 o2query
23. dren 0 this gt spouse 0 c assign this children self gt children c assign this spouse self gt spouse 2 string fn int i 0 this forenames number count self gt 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 gt forenames forename i fn i Write method The write method takes a pointer to the structure and copies the C struct into the object method body write val pointer in class Person include Person h person this person val strcpy self name this name self age this gt age assign self children this children c assign self spouse this spouse int i self gt forenames list for 1 0 i this forenames number i self gt forenames list o2 string this gt forenames forename 1 46 C Interface to O User Manual Define the class Person in Person h Creating Os objects from C To create an object in C you define a C function which calls an O2C function to create and initialize this object Notice how the O5C function returns its parameter The type is a normal Person type and the C function receives a handle The Person new C function o2 Person Person new name char name creates new persistent Person o2 Person 0 o2query amp p
24. e following sections Database Connection Transaction Management Using OQL in C Handle management e Running an application Garbage Collection Leaving the database Note Please refer to the O2C and OQL manuals for more details on how to use these languages C Interface to O User Manual 19 2 Runtime Library 2 1 Database Connection To build the final 2 application the C interface has a runtime library through which the connection between is carried out Your program communicates with Oo by invoking the functions defined in the following libraries e libo2lklink a libo2linkcuse a to use OoLook inside gt methods and functions libo2link a and libo2linkcuse a these not include OoLook The external application must be linked to the library situated in the lib subdirectory of the Oo installation directory If the application uses it must be linked to MOTIF 1 2 and standard X libraries This section is divided up into the following sections Starting an O2 session Setting base Starting an session To use Oo in a C program the application program must start an Oo session which initializes the connection to the server do this your application uses the Oo library function int o2 link init argc argv sinit mode int argc char argv O2 sinit sinit int mode
25. e methods 45 ieee ees 47 The Person new C function lt lt enr uu nu 47 Implementing Person TN 47 29 The application COUR 49 The header 49 OA achen ee eee 49 3 4 Class Implementation Person c 52 3 5 The application in the main c file 55 hier PETS 56 3 6 Compiling your application 58 The PER M 58 and a an sioe dedii 58 INDEX 61 C Interface to Oo User Manual 7 TABLE CONTENTS C Interface to Oo User Manual 1 Introduction GENERAL OVERVIEW OF THE INTERFACE TO Congratulations You are now a user of the C interface to You will find that developing applications in C has several key advantages data persistence conformance to C standards reuse of existing C applications extended C programming and openness to all tools including the OQL query language and graphical interface generator This chapter introduces the Oo interface to C The chapter is divided into the following sections System overview Features and advantages Introducing the C interfac
26. e to O2 Manual overview C Interface to O User Manual Introduction 1 1 System overview The system architecture of Oo is illustrated in Figure 1 1 Dev Tools Development Tools External Interfaces Standard Dev Tools OQL Java Database Engine ODB Access gt Figure 1 1 Oo System Architecture The O system can be viewed as consisting of three components The Database Engine provides all the features of a Database system and an object oriented system This engine is accessed with Development Tools such as various programming languages 2 development tools and any standard development tool Numerous External Interfaces are provided All encompassing is a versatile portable distributed high performance dynamic object oriented database system Database Engine e OoStore e OpEngine The database management system provides low level facilities through to access and manage a database disk volumes files records indices and transactions The object database engine provides direct control of schemas classes objects and transactions through API It provides full text indexing and search capabilities with O2Search and spatial indexing and retrieval capabil
27. er public write val pointer end C Interface to O User Manual 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 2 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 gt ancestors from a in 1 union 1 parents return ancestors method body read val pointer read val from this 02 object include Person h include lt malloc h gt person this person val this name malloc count self gt name 31 strcpy this name self name this gt age self gt age this children 0 this gt spouse 0 c assign this children self gt children c assign this spouse self gt spouse 2 string fn int i 0 this forenames number count self gt forenames this forenames forename malloc sizeof char this forenames number C Interface to O User Manual
28. ities with OoSpatial It includes a Notification manager for informing other clients connected to the same O server that an event has occurred a Version manager for handling multiple object versions and a Replication API for synchronizing multiple copies of an O2 system C Interface User Manual System overview Programming Languages O objects be created and managed using the following programming languages utilizing all the features available with Oo persistence collection management transaction management OQL queries etc C e 2 OQL Oo functions be invoked by programs ODMG compliant C binding ODMG compliant Java binding A powerful and elegant object oriented fourth generation language specialized for easy development of object database applications ODMG standard easy to use SQL like object query language with special features for dealing with complex O objects and methods O Development Tools e OoGraph e e Ookit e OoTools Create modify and edit any type of object graph Design and develop graphical user interfaces provides interactive manipulation of complex and multimedia objects Library of predefined classes and methods for faster development of user applications Complete graphical programming environment to design and develop database applications Standard Development Tools
29. ject or a complex value which allows handles to be returned to a C program For example you can write an O2C function which gets from a C program a 3 field C structure a handle representing an object of type Employee a double representing the new salary for this employee and a handle for an object describing the employee category The 2 function updates the employee s salary computes the new category from the new salary and returns it in the C structure The structure address is passed as 2 integer and the structure type is described in the C file employee h C Interface to O User Manual 35 Runtime Library typedef void handle typedef struct handle employee double salary handle category employee 2 function 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 gt salary update his salary cat compute cat e salary compute new category c assign e category cat return it The C program calls the O2C promote function as include employee h void Void 0 employee smith smith employee 0 Careful with handle assignment smith category 0 o2query amp smith employee Smith smith salary 15000 0 o2query
30. lease internal handles o2_unref_handle val gt spouse o2 unref handle val children int has forename p forename person p char forename int i for i 0 i p forenames number 1 if strcmp p forenames forename i forename return 1 return 0 void forename p forename char forename if has forename p forename p gt forenames forename char realloc p gt forenames forename sizeof char p gt forenames number p gt forenames forename p gt forenames number 1 forename C Interface to O User Manual 53 3 An Example C Application void print val person val int i printf 5 val name printf d years val age 0 i lt val forenames number i printf s val forenames forename i printf Using Iterator void print_persons s 2 set Person s o2 Person p 0 o2 iterator it person val person init amp val it o2 iterator open s while o2 iterator next it amp p Person read amp val p print val person clean val free memory allocated for reading object o2_unref_handle p release the object refered to by 2 iterator close it Keeping object references void mariage val with person val o2 Person with person the spouse person init amp the spouse
31. ly Integrated tools You can take advantage of complementary tools database query complex value creation and initialization object browsing and object editing Complementary tools can be integrated with the C interface such as database query complex value creation and initialization as well as object browsing and editing from C C Interface to User Manual 13 1 Introduction 1 3 Introducing the interface to As is a superset of C you will find that the object oriented 4th generation language in itself has all the features you need However you cannot use the application model if for example your application needs a main program written in plain C This manual explains how to write C programs which can use the database in order to store and retrieve C data A a C programmer you will find programming an application using the O database very easy main argc argv int argc chars argv 02 Person zeus adam eve abel cain Person p oZ list Person lp oZ unique set Person all Connect to the 02 server static O2_sinit o2 sinit 2 25 5 0 oZ link init argv 802 sinit 1 LLLI Set the working base oZ link set base family LLLI Open a transaction for creating data o _link_transaction Person name fall people 1 Person new amp zeus
32. ly reachable from another base will also get garbage collected Example o2 link commit o2 link transaction o2 garbage base my base 38 C Interface O User Manual Leaving the database 2 7 Leaving the database To end an Oo session void o2 link end The o2 link end function terminates the current Oo session o2 link commit is automatically carried out and the connection established by o2 link init is then broken The C application can then of course continue to perform tasks unrelated to Oo C Interface to User Manual 39 Runtime Library 40 C Interface User Manual 3 An Example C Application This chapter aims to illustrate how to use the C interface to Oo with simple example that outlines all the basic steps to writing C programs with Oo This chapter is divided up into the following sections Introduction Define the class Person in file Person h Class Implementation in Person c The application in the main c file Compiling your application C Interface O User Manual 41 3 An Example C Application 31 Introduction To program using the interface to 02 you must go through the following steps Define the C classes the instances of which you want to make persistent In this tutorial this is the class Personin Person h Define the imple
33. mentation of the class Person in Person c Write your application Compile your application and link it to the relevant Oo library C class definition Class1_name libo2link a Class_name h 5 name code c Application c libo2Iklink a C compiler and link editor C application Figure 3 1 C Interface to Os 42 C Interface O User Manual Define the class Person Person h 3 2 Define the class Person in file Person h First of all you must make your C structures persistent As A pointer is only valid inside memory you must change the type definition and replacing all the pointer declarations with handles For example typedef struct person char name int age person children dynamic array of persons person spouse struct int number char forename forenames person Recall that a handle is a void and it is useful to give different symbolic names to handles in order to document the O data storing the information For example you define a person as an O object and so the field spouse is also an object You decide to to put children into a list of persons For future operations on person objects it is useful to complete the structure by a transient i e non persistent attribute containing
34. null sysname The name of the database system working with the C appli cation This must be defined in the systems file indicated by sysdir and must not be null svname The name of a machine on the local network on which the o2server process is running If null o2 1ink init looks for the server specification in the systems file in the Oo installation directory swapdir The absolute path of a directory for special swap files If null the default location Oo installation directory swap subdirec tory is used libpath C Interface to User Manual 21 2 Runtime Library A null terminated array of absolute paths which are searched for libraries during a dynamic loading procedure for C func tions This is similar to the L option of the o2 executable It is important to C programs that invoke dynamically linked mod ules from user specified libraries otherwise this can benull libname A null terminated array of library names which are each searched for dynamically loaded functions called by the appli cation This is similar to the 1 option of the o2 executable It is important to C programs that invoke dynamically linked mod ules from user specified libraries otherwise this can benull Finally the mode parameter is an integer which determines whether or not the external application uses the OoLook graphic user interface Zero indicates that the application uses Oo
35. or char array address gets the next element from the collection for which theiterator has been opened If the scan is exhausted it returns 0 or returns 1 if not The next element is the address passed as second parameter and must be the address of char for collections of booleans or chars e an int for collections of integers double for collections of reals handle for collections of complex values or collections of objects The handle is set to 0 before or is valid and consistent as with 02 assign handle Thefunction o2 iterator next string gets the next element from a collection of O2 strings or bits and puts the string into a C array This array is defined by the second parameter which is of type char and which is allocated by the application before calling this function and must be big enough to hold the string Thefunction o2 iterator close terminates the scan o2 iterator close iterator C Interface to O User Manual 33 2 Runtime Library For example for collection of objects o2 set Person s o2 Person p 0 o2 iterator it Person val o2query amp s people it o2 iterator open s while o2 iterator next it amp Person read amp val p print val o2 unref handle p release reference to the last collection element o2 iterator close it For collection of strings char element 20 void flag 0 o2 itera
36. s class Vector type list real end function stats v Vector upper bound real integer At calling time if the handle his not an object of class Vector or one of its subclasses a type error exception is raised Likewise an object or a value returned by an O2C method or function is received as a handle by C For example you havea C handle representing a list of integers and you want to call an O2C function which adds an integer to this list and returns the new inserted list C Interface to O User Manual 29 2 Runtime Library function insert 1 list integer e integer function body insert 1 list e return 1 You call the function from C as follows void vector o2query amp vector insert 1 100 o2 handle vector list integer 30 C Interface User Manual Handle management 2 4 Handle management A handle represents an object or an value inside an application written in C Manipulating functions Thefollowing C functions allow you to manipulate handles Tousethese functions a C program must include the file header o2 c h The o2 assign handle function assigns the source handle to the target handle void o2 assign handle target handle address source handle void target handle address void source handle Before assign ment it automatically de references the handle contained in the targe
37. t variable if one exists and consequently at the time of call the target handle must be set to 0 or else must contain a valid handle Moreover if the target handle is not 0 before assignment it must contain a handle of the same kind as the one contained in the source handle i e if source contains a value target must be a value and if source is an object target must also be an object Note that a handle is freed explicitly and set to 0 by the o2 unref handle function below If the above conditions are not satisfied the assignment fails and the application crashes possibly with the message Internal inconsistency in the Complex Object Manager followed by an automatic abort For example to get a handle of a named collection people into a variable called people and assign it to another variable called copy people include o2 c h typedef void o2 set Person 02 set Person people 0 copy people 0 o2query amp people people 02 assign handle amp copy people people C Interface to O User Manual 31 Runtime Library The function void o2 assign name name source handle char name void source handle updates the named object or value identified by name with the object or value found in source handle The name must be defined in the current base For example void node 0 compute root amp node 02 assign name Graph root node The o2 unref handle is
38. tence conformance to C standards reuse of existing C applications extended C programming and openness to all O2 tools including the OQL query language and OoLook graphical interface generator C inherits all the advantages of the Oo system database engine 2 Persistence The data applications be made persistent with functions for creating reading and writing objects Your C applications can be made to have persistent structs after very minor modification Persistent roots are defined dynamically in C Persistence of data is achieved through the declaration of persistent roots to the application Edit and display facilities for C data are generated automatically Code reuse Existing C applications are easily extended and their objects made persistent Code reuse by importing classes from different schemas Database consistency is maintained Improved and extended O has libraries for creating and manipulating O2 and C collections Generic libraries for easily creating and manipulating O2 collections with reuse of existing libraries without recompilation OQL and OzgLook can be integrated and applied to C objects Primitives for database transaction management are available from C applications Programming O2 in C features include User programmed transaction commit and abort Standard C compiler A C programmer needs no previous knowledge of to start developing applications immediate
39. ter the named list value Employees and select only those employees between the ages of min and max typedef void o2 list Person o2 list Person s 0 int min max o2query amp 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 belongs to this set of employees char is_here char M name 10 o2query char amp is here exists p in 1 p name 2 o2 handle s o2 string M name The o2query function is also used to initialize C variables which are instances of collections This is probably the best way to initialize such variables You can write for instance typedef void o2 list integer o2 list integer L 0 o2query amp L list 1 4 9 16 25 Method and function call An O2C method or function is easily called using OQL 28 C Interface User Manual Using OQL For example to call the method display on handle n and then call the function stats you use the following OQL queries void Void 0 int rc double max o2query amp Void 1 gt display o2_handle h o2query integer amp stats 1 2 o2_handle h o2_real max From 2 when a method or function is called it receives handle parameters as normal 2 parameters provided their types match the corresponding gt 2 parameters For example the O2C function stats is declared a
40. terface O User Manual Define the class Person in Person h Person_readand Person write The first takes an object and puts it in a C struct while Person write copies a C struct into an Oo object You cannot directly write these conversions in C but in 2 So the two C functions simply call two corresponding O2C methods of the class Person write and read void Person read val p person val o2 Person p reads the value of the Person into the struct void Void 0 o2query amp Void 1 gt 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 from the struct o2query amp Void 1 gt write 2 o2_handle p o2 integer amp val Implementing read and write methods Read method The read method takes a pointer to the C struct and copies the object into it C Interface to O User Manual 45 3 An Example C Application type pointer integer method body read val pointer in class Person include Person h include lt malloc h gt person this person val this name malloc count self gt name 31 strcpy this name self name this gt age 1 gt this gt chil
41. tor it o2query amp flag list blue white red it o2 iterator open flag while o2 iterator next string it element printf sWMn element o2 iterator close it Handle conversion Sometimes you have to convert a C handle into an O2C variable or con versely put 2 data into C types For example a C program wants to pass a C struct or a C array containing handles to an O2C function or method 34 C Interface User Manual Handle management To interpret these handles 2 transforms it to normal 2 typed data Conversely an 2 function or method may need to put 2 data into struct array to deliver it to a calling program c_assign carries out these transformations handle to variable To convert a handle into an O2C variable you use the following function c assign O2c variable handle This 2 function assigns the handle handle an integer in 2 into the 2 variable 02 variable This variable is an object or a complex value of a type consistent with the actual data referred to by thehandle Dynamic type checking occurs except when compiled with the option O variable to handle To convert a variable into a handle you use the following function c assign handle variable O2C expression This 2 function assigns the 2 expression into a C handle integer in 2 The expression delivered an ob
42. tory is you only want to read data because by default an application runs in a read only transaction This is a transaction where no updates on persistent data are allowed and no locks are set by the system After a transaction ends the application is automatically reset into a read only transaction Such a read only transaction is useful because it does not conflict with other transactions It can read any objects or collections and it can create any temporary O objects or collections as complex as needed The read only transaction is therefore ideally suited to that part of your application where an interactive dialogue with the end user occurs or where some complex calculation is necessary after reading stable data C Interface to O User Manual 23 Runtime Library This part of an application is usually followed by a standard transaction which manages the creation and updating of persistent data Note When you start a transaction using o2 link transaction 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 update transaction begins with the function void o2
43. xdorf A G NeXTStep is a registered trademark of the NeXT Computer Inc Purify Quantify are registered trademarks of Pure Software Inc Windows is a registered trademark of Microsoft Corporation All other company or product names quoted are trademarks or registered trademarks of their respective trademark holders Who should read this manual This manual presents the basic concepts of the C interface to Oo and describes how to link external C applications to Oo It details the management of object handles iterator functions and how to use OoLook OQL with C The interface with 2 is also described including method and function calls and object handle conversions to 2 variables A complete programming example is presented Other documents available are outlined click below See O2 Documentation set TABLE OF CONTENTS This manual is divided into the following chapters e 1 Introduction e 2 Runtime Library e 3 Example C application C Interface to Oo User Manual Q2 TABLE OF CONTENTS Introduction 9 Lid System QVOLUIIMI 10 ep ccona p 12 1 2 Features and advantages ree 13 1 3 Introducing the C interface to O2 14 15 1 4 Manual
44. y for the query result and it is you the user who frees this char when it is no longer used The other two arguments of the o2query function are querytext A string containing the text of the query and can include references to O schema names but not to local program variables The string can however contain references to query variables defined by subsequent variable parameters described below in the form of 1 for the first variable 2 for the second etc and these query variables refer to local program variables See the examples below 4 variable An expression representing a value to be substituted for the n references in the querytext argument There must as many of these q variable arguments as there distinct n references Each query variable identifies the type as well as the value of a n reference and must therefore take one of the following forms e o2 integer int for a C integer variable o2 real double for a C floating point number variable o2 char char for a C character variable o2 string char fora string variable o2 handle x wherex is a handle standing for an object or complex value tuple list set unique set Example queries To find the value of the age attribute of named object Father int i o2query integer amp i Father age C Interface to User Manual 27 2 Runtime Library To fil

C Interface to O2 User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents