Download O2DB Access User Manual
Transcript
O2DBAccess User Manual C++ Interface Release 5.0 - May 1998 In for m ation in t h is docu m en t is su bject t o ch an ge with ou t n ot ice an d sh ou ld n ot be con str u ed as a com m it m en t by O2 Tech n ology. Th e soft war e descr ibed in th is docu m en t is deliver ed u n der a licen se or n on disclosu r e agr eem en t. Th e soft war e can on ly be u sed or copied in accor dan ce wit h t h e ter m s of th e agr eem en t . It is again st t h e law t o copy t h is soft war e on m agn et ic t ape, disk , or an y ot h er m ediu m for an y pu r pose ot h er t h an t h e pu r ch aser ’s own u se. Copyr igh t 1992-1998 O 2 Tech n ology. All r igh t s r eser ved. No par t of t h is pu blicat ion can be r epr odu ced, st or ed in a r et r ieval syst em or t r an sm it t ed in an y for m or by an y m ean s, elect r on ic, m ech an ical, ph ot ocopy with ou t pr ior wr itt en per m ission of O2 Tech n ology. O2 , O 2 API, O 2 C, O2 DBAccess, O2 En gin e, O 2 Gr aph , O2 Kit , O2 Look , O2 St or e, O2 Tools, an d O2 Web ar e r egist er ed tr adem ar k s of O2 Tech n ology. SQL an d AIX ar e r egist er ed t r adem ar k s of In t er n at ion al Bu sin ess Mach in es Cor por at ion . Su n , Su n OS, an d SOLARIS ar e r egist er ed t r adem ar k s of Su n Micr osystem s, In c. X Win dow System is a r egist er ed tr adem ar k of t h e Massach u set t s In st itu t e of Tech n ology. Un ix is a r egist er ed t r adem ar k of Un ix Syst em Labor at or ies, In c. HPUX is a r egist er ed t r adem ar k of H ewlet t -Pack ar d Com pan y. BOSX is a r egist er ed t r adem ar k of Bu ll S.A. IRIX is a r egist er ed t r adem ar k of Siem en s Nixdor f, A.G. NeXTSt ep is a r egister ed t r adem ar k of t h e NeXT Com pu t er , In c. Pu r ify, Qu an t ify ar e r egist er ed tr adem ar k s of Pu r e Soft war e In c. Win dows is a r egist er ed t r adem ar k of Micr osoft Cor por ation . All oth er com pan y or pr odu ct n am es qu ot ed ar e t r adem ar k s or r egist er ed t r adem ar k s of t h eir r espect ive t r adem ar k h older s. Who should read this manual Th is m an u al descr ibes h ow t o u se O 2 D BAccess. Th is O 2 m odu le en ables to con n ect O 2 applicat ion s t o r elation al databases on r em ot e h ost s, an d t o im por t an d expor t dat a fr om an d t o su ch syst em s. O 2 D BAccess pr ovides class libr ar ies (O2 C an d C++) for t h ese t ask s. Th e m an u al also descr ibes h ow t o in vok e SQL st at em en t s fr om O2 . An exam ple pr ogr am is pr esen t ed. Oth er docu m en t s available ar e ou t lin ed, click below. See O2 Documentation set. T A B L E O F CON T E N T S Th is m an u al is divided in t o t h e followin g ch apt er s: • 1 - In t r odu ct ion • 2 - Ut ilizat ion • 3 - Classes • 4 - Appen dices O2 DBAccess User Man u al 5 TABLE OF CONTENTS 1 Introduction 9 1.1 System Overview......................................................................10 O2 Engine ....................................................................................12 O2 Store .......................................................................................13 O2DB Access ...............................................................................14 1.2 Manual Overview ......................................................................16 2 Programming Guide 17 2.1 The o2dbaccess Library ..........................................................18 Classes..........................................................................................18 2.2 Guidelines .................................................................................19 2.3 Accessing a Database .............................................................21 Host connection and database log in............................................21 Open Statement ............................................................................22 2.4 Preparing a Statement .............................................................23 Associating an SQL statement .....................................................23 Managing statements....................................................................23 Storing a query result set..............................................................24 2.5 Running a Statement ...............................................................25 2.6 Commit and Rollback...............................................................28 2.7 Ending a Session .....................................................................28 3 Class Library 29 3.1 o2db_O2DBAccess ..................................................................30 server_error ..................................................................................31 3.2 o2db_Connection .....................................................................32 connect .........................................................................................33 disconnect.....................................................................................34 logoff ............................................................................................35 logon.............................................................................................36 6 O2 DBAccess User M an u al TABLE OF CONTENTS 3.3 o2db_Session .......................................................................... 38 close............................................................................................. 39 commit ......................................................................................... 40 open ............................................................................................. 41 rollback ........................................................................................ 43 3.4 o2db_Statement ....................................................................... 44 add_cursor_variable .................................................................... 45 add_input_variable ...................................................................... 46 associate....................................................................................... 48 operator >> .................................................................................. 50 operator << .................................................................................. 51 o2db_sql_execute ........................................................................ 53 4 Appendices 55 4.1 Example Application ............................................................... 56 Defining a C++ schema ............................................................... 57 Connecting to O2......................................................................... 58 Connecting to the Relational database server.............................. 59 Creating a table............................................................................ 61 Populating the table ..................................................................... 62 Displaying the table content ........................................................ 64 Querying the RDBMS ................................................................. 66 Building the application .............................................................. 68 4.2 Configuration File .................................................................... 69 4.3 Possible Errors ........................................................................ 71 INDEX O2 DBAccess User Man u al 77 7 TABLE OF CONTENTS 8 O2 DBAccess User M an u al 11 I ntr oduction Con gr at u lat ion s! You ar e n ow a u ser of O 2 D BAccess! O2 DBAccess is t h e O2 m odu le t h at en ables you t o com m u n icat e an d wor k wit h r elat ion al dat abases on r em ot e h osts Th is ch apt er in t r odu ces t h e O2 syst em an d O2 DBAccess an d ou t lin es it s var iou s feat u r es an d advan t ages. An over view of t h is User Man u al is t h en given . O2 DBAccess User Man u al 9 1 Introduction 1.1 System Overview Th e syst em ar ch it ect u r e of O2 is illu st r at ed in Figu r e 1.1. External Interfaces Development Tools Standard Dev. Tools O2 Dev. Tools OQL Java O2 C C++ C O2ODBC O2Corba Database Engine O2Engine O2Store O2DB Access O2Web Fi gu r e 1 .1 : O2 Sy st em Ar ch i t ect u r e Th e O 2 system can be viewed as con sist in g of t h r ee com pon en t s. Th e Database Engine pr ovides all t h e feat u r es of a D at abase syst em an d an object -or ien t ed syst em . Th is en gin e is accessed wit h Development Tools , su ch as var iou s pr ogr am m in g lan gu ages, O 2 developm en t t ools an d an y st an dar d developm en t tool. Nu m er ou s External Interfaces ar e pr ovided. All en com passin g, O 2 is a ver sat ile, por t able, dist r ibu t ed, h igh per for m an ce dyn am ic object -or ien ted dat abase system . Database En gin e: 10 • O2 St or e Th e dat abase m an agem en t syst em pr ovides low level facilit ies, t h r ou gh O2 Stor e API, t o access an d m an age a dat abase: disk volu m es, files, r ecor ds, in dices an d t r an sact ion s. • O2 En gin e Th e object dat abase en gin e pr ovides dir ect con t r ol of sch em as, classes, object s an d t r an sact ion s, t h r ou gh O2 En gin e API. It pr ovides fu ll t ext in dexin g an d sear ch capabilit ies wit h O 2 Sear ch an d spat ial in dexin g an d r et r ieval capabilit ies wit h O 2 Spat ial. It in clu des a Not ificat ion m an ager for in for m in g oth er clien t s con n ect ed t o t h e sam e O 2 ser ver t h at an even t h as occu r r ed, a Ver sion m an ager for h an dlin g m u lt iple object ver sion s an d a Replicat ion API for syn ch r on izin g m u lt iple copies of an O2 system . O2 DBAccess User Man u al System Overview Pr ogr am m in g Lan gu ages: O 2 object s m ay be cr eat ed an d m an aged u sin g t h e followin g pr ogr am m in g lan gu ages, u tilizin g all t h e featu r es available wit h O2 (per sist en ce, collection m an agem en t , t r an sact ion m an agem en t , OQL qu er ies, et c.) • C O2 fu n ct ion s can be in vok ed by C pr ogr am s. • C++ OD MG com plian t C++ bin din g. • J ava OD MG com plian t J ava bin din g. • O2 C A power fu l an d elegan t object-or ien t ed fou r t h gen er at ion lan gu age specialized for easy developm en t of object dat abase applicat ion s. • OQL OD MG st an dar d, easy-t o-u se SQL-lik e object qu er y lan gu age wit h special feat u r es for dealin g wit h com plex O2 object s an d m eth ods. O 2 Developm en t Tools: • O2 Gr aph Cr eat e, m odify an d edit an y t ype of object gr aph . • O2 Look Design an d develop gr aph ical u ser in ter faces, pr ovides in t er active m an ipu lation of com plex an d m u ltim edia object s. • O2 Kit Libr ar y of pr edefin ed classes an d m et h ods for fast er developm en t of u ser applicat ion s. • O2 Tools Com plet e gr aph ical pr ogr am m in g en vir on m en t t o design an d develop O 2 dat abase applicat ion s. St an dar d Developm en t Tools: All stan dar d pr ogr am m in g lan gu ages can be u sed wit h st an dar d en vir on m en t s (e.g. Visu al C++, Su n Spar cwor k s). Exter n al In t er faces: • O2 Cor ba Cr eat e an O2 / Or bix ser ver t o access an O2 dat abase wit h CORBA. • O2 DBAccess Con n ect O2 applicat ion s to r elation al dat abases on r em ot e h ost s an d in vok e SQL st at em en ts. • O2 OD BC Con n ect r em ot e ODBC clien t applicat ion s t o O2 dat abases. • O2 Web Cr eat e an O2 Wor ld Wide Web ser ver t o access an O 2 dat abase th r ou gh t h e in t er n et n etwor k . O2 DBAccess User Man u al 11 1 Introduction O2 Engine O 2 En gin e h as all t h e featu r es of a dat abase en gin e pr ovidin g t r an spar en t m an agem en t of dat a per sisten ce, data sh ar in g an d dat a r eliability, as well as all t h e feat u r es of an object -or ien t ed syst em in clu din g t h e m an ipu lation of com plex object s with iden tit y, classes, t ypes, m et h ods, m u lt iple in h er it an ce, over r idin g an d late bin din g of m et h ods. CLIENT CLIENT CLIENT SERVER DATABASE Fi gu r e 1 .2 : Cl i en t /ser ver a r ch i t ect u r e 12 O2 DBAccess User Man u al System Overview : O2 Store O2 Store Th e O2 St or e ph ysical st or age m an agem en t syst em offer s you th e followin g feat u r es: • Tr an sact ion al m an agem en t of per sist en t st r u ct u r es. • Clien t/ ser ver ar ch it ect u r e. • Rollback s an d cr ash r ecover y. O 2 St or e h as t h e clien t / ser ver ar ch it ectu r e sh own in Figu r e 1.2. Th e ser ver pr ocess pr ovides per sist en ce, disk m an agem en t , con cu r r en cy con t r ol, dat a r ecover y, an d dat abase secu r it y. Th e featu r es offer ed by O 2 En gin e an d O 2 St or e ar e sh own in Figu r e 1.3 . O2Store Schema Manager Global Transaction Manager Object Manager Global Log Manager Local Transaction Manager Page Buffer Page Buffer O2Store Client Process DB Log Server Process Fi gu r e 1 .3 : Gl oba l a r ch i t ect u r e sh ow i n g O2 St or e l a y er O2 DBAccess User Man u al 13 1 Introduction O2DB Access O2 DBAccess is a set of C++ classes t h at en ables O2 applicat ion s t o com m u n icate an d wor k wit h r elation al dat abases on r em ote h ost s. Th ese classes allow you t o car r y ou t t h e followin g action s fr om you r applicat ion s: • Con n ect t o a ser ver an d set u p a session on a r em ot e dat abase. • Ru n an y SQL st at em en t in t h e SQL syn t ax of t h at dat abase. • Fet ch dat a as r equ ir ed fr om t h e dat abase to t h e u ser applicat ion in t o O 2 object s. • Mir r or t h e com m it an d r ollback facilit ies of som e dat abases. • Close t h e dat abase session an d t er m in at e th e con n ect ion to t h e h ost . You can also r et r ieve er r or m essage t ext cor r espon din g to dat abase er r or codes. O2 DBAccess is based on t h e Sequ eLi n k pr ot ocol as sh own in Figu r e 1.4. Th is is a soft war e pack age t h at en ables a clien t applicat ion t o access sim u lt an eou sly differ en t r elat ion al dat abases r esidin g on differ en t ser ver s th at ar e con n ect ed to on e or m or e types of local n et wor k . Sequ eLin k u n ifor m ly m an ages t h e differ en t n et wor k pr otocols an d t h e h et er ogen eit y bet ween platfor m s1 . Wit h O2 DBAccess you can lin k to an y platfor m cu r r en tly su ppor t ed by Sequ eLin k . 1. For in for m ation abou t all possible n et wor k -h ost -dat abase com bin ation s, call O2 Lin e. 14 O2 DBAccess User Man u al System Overview : O2DB Access CLIENT SERVER O2DBAccess Relational DBMS Interface module database Client Kernel Server Kernel Interface module network protocol Interface module network protocol Standard Network Protocol SequeLink Fi gu r e 1 .4 : O2 DBAccess a n d Sequ eLi n k O2 DBAccess User Man u al 15 1 Introduction 1.2 Manual Overview Th is m an u al is divided u p in t o t h e followin g ch apt er s: • Chapter 1 - Introduction A sh or t in t r odu ct ion t o t h e O2 syst em , O2 En gin e, O2 St or e, an d O2 DBAccess. • Chapter 2- Programming Guide Th is ch apt er descr ibes h ow t o u se O 2 D BAccess. It cover s accessin g a dat abase, pr epar in g a st at em en t , fet ch in g dat a, com m it an d r ollback , an d r u n n in g t h e st at em en t . • Chapter 3 - Class Library Th is ch apt er details th e var iou s classes of t h e O2 DBAccess libr ar y: o2db_O2DBAccess, o2db_Connection, o2db_Session, an d o2db_Statement. • Chapter 4 - Appendices Th is ch apt er in clu des an exam ple pr ogr am . It gives possible er r or codes an d t h e con figu r at ion file. 16 O2 DBAccess User Man u al 22 Progra m mi ng G uide Th is ch apt er det ails h ow t o u se O 2 D BAccess. It is divided in t o t h e followin g ch apt er s: • Th e o2dbaccess Libr ar y • Gu idelin es • Accessin g a Database • Pr epar in g a St at em en t • Ru n n in g a St at em en t • Com m it an d Rollback • En din g a Session O2 DBAccess User Man u al 17 2 Programming Guide 2.1 The o2dbaccess Library O2 DBAccess is in fact a st an dar d C++ libr ar y called o2dbaccess th at you can u se in an y of you r C++ applicat ion . Classes Th e o2dbaccess libr ar y, sh own in Figu r e 2.1, pr ovides classes th at en able you t o com m u n icat e an d wor k wit h th e r em ot e dat abase. o2db_Connection o2db_O2DBAccess o2db_Session o2db_Statement Fi gu r e 2 .1 : o2 d ba ccess l i br a r y Th e libr ar y classes ar e as follows: • o2db_O2DBAccess An o2db_O2DBAccess object defin es t h e com m on r esou r ces of O 2 DBAccess classes. It con tain s on e fu n ct ion , server_error, wh ich you u se to obt ain th e RDBMS-det ect ed er r or codes. • o2db_Connection o2db_Connection is a su bclass of o2db_O2DBAccess. An o2db_Connection object defin es an d m ain t ain s a con n ection t o a r em ote h ost . • o2db_Session o2db_Session is a su bclass of o2db_O2DBAccess. An o2db_Session object defin es an d m ain t ain s a con n ect ion t o a dat abase ser ver . It m an ages t h e tr an sact ion s of t h e session . • o2db_Statement o2db_Statement is a su bclass of o2db_O2DBAccess. An o2db_Statement object defin es an access con t ext t o a dat abase an d con tain s in for m at ion t h at is r equ ir ed t o r u n an SQL st at em en t . 18 O2 DBAccess User Man u al Guidelines 2.2 Guidelines To sen d an SQL st at em en t for pr ocessin g on r em ot e dat abase, you n eed t o car r y ou t t h e followin g st eps: 1. Set u p a con n ection t o th e h ost server m ach in e. 2. Set u p a session on t h e dat abase by loggin g on . 3. Open a st at em en t on t h e r em ot e database ser ver . 4. Pr epar e t h e st at em en t t o be r u n . Th is m ean s pu tt in g in for m at ion abou t t h e SQL qu er y you wan t to execu te in t h e statem en t an d t h e C++ object s t h at will st or e t h e SQL r esu lt . 5. Ru n t h e st at em en t . 6. If in for m at ion h as been in ser t ed, u pdat ed or delet ed, m ak e t h e ch an ges per m an en t , or u n do t h em . 7. If you do n ot wan t t o r er u n t h e st at em en t , close it . 8. Close t h e session by loggin g off th e dat abase. 9. En d t h e con n ect ion by discon n ect in g fr om t h e h ost. Each step cor r espon ds to a par t icu lar fu n ct ion . Table 2.1 sh ows t h ese fu n ct ion s an d it s cor r espon din g st ep. Th e class of t h e fu n ction is given befor e t h e fu n ct ion n am e. Th ese fu n ction s con st it u t e t h e basic set of fu n ct ion s t h at you n eed t o u se. Table 2.1 Function set Funct i ons St ep o2db_Connect::connection Set u p a con n ect ion o2db_Connection::logon Set u p a session o2db_Session::open Open an access con t ext O2 DBAccess User Man u al 19 2 Table 2.1 Programming Guide Function set Funct i ons St ep o2db_Statement::associate o2db_Statement::add_cursor_variable Pr epar e a st at em en t o2db_Statement::add_input_variable o2db_Statement::>> o2db_Statement::<< o2db_Statement::execute Ru n a st at em en t o2db_Session::commit Mak e t h e ch an ges per m an en t o2db_Session::rollback Un do a tr an sact ion o2db_Session::close Close t h e con t ext o2db_Connection::logoff En d t h e session o2db_Connection::disconnect En d t h e con n ect ion All t h ese var iou s st eps ar e detailed below. For a fu ll descr iption of each specific fu n ct ion r efer t o Ch apt er 3. 20 O2 DBAccess User Man u al Accessing a Database 2.3 Accessing a Database You m u st fir st con n ect to t h e r em ot e h ost an d log on t o t h e dat abase. Host connection and database log in Wit h O 2 D BAccess, you do th is by cr eat in g a o2db_Connection object . You m u st call t h e connect fu n ction on t h is object t o con n ect t o t h e r em ot e h ost . You t h en call t h e logon fu n ction on t h is object t o log on to t h e database an d begin a session . Th e logon fu n ct ion r et u r n s a poin ter t o an o2db_Session object . On ce con n ect ed an d logged on , you can r u n as m an y SQL stat em en t s as you wan t . For exam ple: #include "o2db_o2db_access.h" int create_session() { int code, status; char *msg; o2db_Connection connection; o2db_Session *session; status = connection.connect("oracle", "user", "pwd"); session = connection.logon("dbuser", "dbpasswd", &status); if ( status == o2dbE_SERVER) { msg = connection.server_error(&code); cerr << "Error: " << code << " msg: " << msg << endl; } else if (status != O2DB_OK) cerr << "An error occurs: " << status << endl; ... } Wh en you r t r an sact ion s wit h t h e dat abase ar e fin ish ed, you u se t h e logoff an d disconnect fu n ct ion s t o r espectively en d t h e session an d r em ot e h ost con n ect ion . Refer to Sect ion 3.2 for a fu ll descr ipt ion of all th ese o2db_Connection fu n ct ion s. O2 DBAccess User Man u al 21 2 Programming Guide Open Statement On ce con n ect ed t o t h e r em ot e h ost an d logged on to t h e dat abase, you m u st n ow open a st at em en t in wh ich you can r u n an SQL stat em en t . You do t h is u sin g t h e open fu n ct ion fr om you r o2db_Session object (r esu lt of t h e logon fu n ction ). Th e st at em en t con t ain s t h e st at em en t itself an d an y addit ion al in for m at ion t h at m ay be n eeded t o r u n t h e st at em en t. Th is fu n ction r et u r n s an object of class o2db_Statement. A o2db_Statement object r em ain s open u n t il you explicit ly close it u sin g t h e close fu n ct ion (of you r o2db_Session object ), or u n t il you en d t h e dat abase session u sin g t h e logoff fu n ction . H owever , you do n ot n eed t o close a st at em en t if you wan t to u se it for a differ en t st at em en t. You sim ply r e-u se it . For exam ple: #include "o2db_o2db_access.h" int open() { int code, status; char *msg; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; status = connection.connect("oracle", "user", "pwd"); session = connection.logon( "dbuser", "dbpasswd", &status); statement = session->open(&status); if (status == o2dbE_SERVER) { msg = connection.server_error(&code); cerr << "Error: " << code << " msg: " << msg << endl; } else if (status != O2DB_OK) cerr << "An error occurs: " << status << endl; ... } o2db_Statement an d h ow t o m an age st at em en t s ar e fu lly explain ed in Sect ion 2.4 below; Sect ion 3.3 gives a descr ipt ion of t h e open fu n ction . Note Th e statem en t is local t o t h e logon session in wh ich it is u sed an d t h e n u m ber of st at em en t s you can open at t h e sam e t im e is r est r ict ed t o 100. However , you r ar ely n eed m or e t h an 15 an d t h e ext er n al database or you r self can im pose a lower lim it. 22 O2 DBAccess User Man u al Preparing a Statement : Associating an SQL 2.4 Preparing a Statement Th e n ext st ep aft er accessin g t h e database is to pr epar e t h e SQL st at em en t s you wan t t o r u n . Associating an SQL statement You m u st fir st ly defin e t h e SQL st at em en t you wan t to r u n u sin g t h e associate fu n ct ion of t h e o2db_Statement class. Th e associate fu n ction also sen ds th e statem en t t o t h e RDBM S dat abase for validat ion . It is at t h is poin t t h at an y SQL syn t ax er r or s ar e t r apped. If an y ar e fou n d, you can get t h e database er r or codes by callin g t h e server_error fu n ct ion on t h e o2db_Statement object (see Sect ion 3.1 for details of th is fu n ct ion an d Sect ion 4.3 for a list of possible er r or s). If t h e SQL st at em en t does n ot n eed a r esu lt object (i.e. it is n ot a select st at em en t ) an d it con t ain s n o par am eter m ar k er s, O 2 D BAccess n eeds n o m or e in for m at ion . In t h is case, you can r u n you r st at em en t im m ediately u sin g t h e o2db_sql_execute fu n ct ion . See Section 2.5 for m or e det ails. In t h e oth er cases, i.e. if th e st at em en t is a sel ect st at em en t an d/ or if it con t ain s par am et er m ar k er s, you m u st pr ovide O 2 DBAccess wit h m or e in for m ation . Th is is explain ed in t h e r em ain der of t h is section . Managing statements Wh en you wan t t o r u n a select st at em en t or a st at em en t t h at con t ain s par am eter m ar k er s or bot h , you n eed to pr ovide m or e in for m at ion befor e t h e statem en t is r u n . Th e in for m at ion n eeded in clu des t h e r esu lt object an d it s pr oject ion list , wh ich you st or e in t h e st at em en t u sin g t h e add_cursor_variable fu n ct ion or t h e ’>>’ oper at or of t h e class o2db_Statement. You also n eed t o st or e t h e in pu t par am et er s of t h e st at em en t u sin g th e add_input_variable fu n ct ion or t h e ’<<’ oper at or of t h e class o2db_Statement. O2 DBAccess User Man u al 23 2 Programming Guide You can m an age you r st at em en t s in t h e followin g th r ee differ en t ways: 1. Use on e st at em en t for on e specific SQL statem en t an d close it as soon as it h as been r u n . 2. Open a st at em en t , u se it for on e SQL st at em en t , an d t h en r eu se it for an ot h er SQL statem en t by sim ply associatin g it t o a n ew SQL st at em en t. You can to do t h is as m an y t im es as you wan t u n t il you wan t t o close t h e st at em en t . 3. Open a st at em en t for a par t icu lar SQL st at em en t t h at you wan t t o r u n sever al t im es. You k eep t h e st at em en t open an d associat ed t o t h e sam e SQL st at em en t u n t il you n o lon ger wish t o r er u n t h e st at em en t . Wh ile t h e st at em en t is open , you can r er u n it wit h n ew valu es for an y of it s par am et er s u sin g th e o2db_sql_execute fu n ct ion . Th e n ew valu es of t h e par am et er s ar e given u sin g t h e add_input_variable fu n ct ion (or t h e ’<<’ oper at or ). Note Re-associat in g a statem en t r eset s t h e par am et er list of th e st at em en t as well as th e r esu lt in for m at ion . Storing a query result set Stor in g t h e r esu lt set of a qu er y fu n ct ion in volves t h e followin g st eps: 1. You m u st fir stly defin e th e C++ classes wh er e you wan t t h e r et r ieved dat a t o be st or ed. 2. You m u st t h en give t h e r elevan t t r an sfer in for m ation . Th is m ean s associat in g a par t of th e r esu lt set (i.e. t h e n am e of a colu m n ) t o a par t of t h e C++ st or age class (i.e. t h e n am e of a C++ at tr ibu t e). You do t h is by defin in g dat a bu ffer s u sin g t h e add_cursor_variable fu n ct ion or th e ’>>’ oper at or of th e class o2db_Statement. You can t h en r u n th e statem en t u sin g t h e o2db_sql_execute fu n ct ion . See t h e exam ple in t h e n ext sect ion . 24 O2 DBAccess User Man u al Running a Statement : Storing a query result set 2.5 Running a Statement If t h e SQL st at em en t does n ot n eed a r esu lt object (i.e. it is n ot a select st at em en t ), you can r u n it dir ect ly u sin g t h e o2db_sql_execute fu n ct ion wit h on ly you r st atem en t as a par am et er . If t h e st at em en t is a select st at em en t, you m u st pr ovide t h e r elevan t t r an sfer in for m ation as det ailed in Section 2.4, an d t h en call t h e o2db_sql_execute fu n ct ion wit h t h e statem en t an d t h e C++ object th at will st or e t h e r esu lt of th e qu er y as par am eter s. For exam ple, su ppose you set u p a sin gle con n ect ion , a sin gle session in wh ich you wan t t o r u n t h r ee SQL st at em en ts: a CREATE st at em en t , an INSERT st at em en t wit h par am et er s t h at you wan t t o r u n t wice, an d a SELECT st at em en t ; you call t h e followin g sequ en ce of fu n ct ion s t o pr ocess each step. int test() { d_Set<d_Ref<Person> > the_persons("ThePersons"); d_Iterator<d_Ref<Person> > iter; d_Ref<Person> person; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; int status, code; status = connection.connect("oracle", "user", "passwd"); if (status != O2DB_OK) return status; session = connection.logon("oracleuser", "oracleuserpasswd", &status); if (status != O2DB_OK) return status; statement = session->open(&status); if (status != O2DB_OK) return status; // (1) A statement without parameters: // ----------------------------------status = statement->associate("CREATE TABLE person \ (id_person SMALLINT null, \ name VARCHAR(16) null, \ firstname VARCHAR(16) null)"); if (status != O2DB_OK) return status; O2 DBAccess User Man u al 25 2 Programming Guide status = o2db_sql_execute(statement); if (status != O2DB_OK) return status; // (2) A statement with 3 input parameters: //----------------------------------------status = statement->associate( "INSERT INTO \ person(id_person, name, firstname) \ VALUES (?, ?, ?)"); // First execution *statement << 1 << "Doe" << "John"; status = o2db_sql_execute(statement); if (status != O2DB_OK) return status; // Second execution with different parameters *statement << 2 << "Smith" << "Paul"; status = o2db_sql_execute(statement); if (status != O2DB_OK) return status; // (3) A statement returning a result //-----------------------------------status = statement->associate("SELECT name, firstname \ FROM person"); // The class Person has at least 2 attributes: // pname and pfirstname *statement >> "pname" >> "pfirstname"; status = o2db_sql_execute(statement, the_persons); if (status != O2DB_OK) return status; // Now the C++ set contains the selected information iter = the_persons.create_iterator(); while (iter.next(person)) { cout << "\t*** [ " << person -> pname << " " << person -> pfirstname << " ]" << endl; } 26 O2 DBAccess User Man u al Running a Statement : Storing a query result set // Ending the session and disconnecting status = session->close(statement); if (status != O2DB_OK) return status; status = connection.logoff(session); if (status != O2DB_OK) return status; connection.disconnect(); } O2 DBAccess User Man u al 27 2 Programming Guide 2.6 Commit and Rollback Th e commit an d rollback fu n ct ion s m ir r or a feat u r e of som e dat abases in allowin g you to syst em at ically an d explicit ly m ak e per m an en t or u n r oll a ser ies of r elat ed dat abase act ion s at st r at egic poin t s in a session . 2.7 Ending a Session Wh en all you r t r an sact ion s wit h t h e dat abase h ave been car r ied ou t , t h e fu n ct ion s close, logoff an d disconnect close t h e st at em en t an d en d t h e session an d con n ect ion r espect ively.. #include "o2db_o2db_access.h" int end_session() { int status; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; ... statement = session->open(&status); ... status = session->close(statement); connection.logoff(session); connection.disconnect(); return status; } 28 O2 DBAccess User Man u al 33 C lass L ibrar y CLASS SET AND THEIR MEM BER FUNCTIONS O2 DBAccess is a set of C++ classes th at en ables O 2 applicat ion s t o com m u n icat e an d wor k wit h r elat ion al dat abases on r em ot e h osts. Th is ch apt er det ails all t h ese classes an d t h eir r espect ive m em ber fu n ct ion s. It is divided in t o t h e followin g sect ion s: • o2db_O2DBAccess - Th is is t h e su per class of all t h e ot h er classes of t h e pack age. • o2db_Con n ect ion - Th is class m an ages t h e con n ect ion t o a r em ot e h ost. • o2db_Session - Th is class m an ages t h e con n ect ion t o a database ser ver . • o2db_St at em en t - Th is class m an ages all t h e r esou r ces belon gin g t o t o an SQL st at em en t . O2 DBAccess User Man u al 29 3 Class Library 3.1 o2db_O2DBAccess o2db_O2DBAccess is t h e su per class of t h e classes o2db_Connection, o2db_Session, an d o2db_Statement. It m an ages com m on r esou r ces an d own s t h e followin g pu blic m em ber fu n ction : • server_error 30 O2 DBAccess User Man u al o2db_O2DBAccess server_error Summary Get s th e last er r or code fr om t h e dat abase ser ver . Syntax char* server_error(int *code); Arguments code Description Th is m em ber fu n ct ion is u sed by an O 2 D BAccess pr ogr am m er t o obt ain ext r a in for m at ion abou t a dat abase ser ver r elat ed er r or . It can be applied to an in stan ce of th e o2db_O2DBAccess class or on e of it s su bclasses aft er an er r or of t ype o2dbE_SERVER occu r ed. Th e fu n ction pu t s in t h e in t eger poin t ed by code t h e database ser ver er r or code r aised by t h e failu r e. Th e str in g r etu r n ed by t h is fu n ction con t ain s a t ext u al descr ipt ion of t h e er r or , wh en applicable. A poin ter on an in t eger t h at in r et u r n will con t ain t h e er r or code. As t h is str in g is st or ed in a st at ic ar ea, it is on ly available u n t il t h e n ext call t o server_error occu r s. Th is st r in g m u st n ot be fr eed by t h e u ser . Returns A st r in g wit h t h e t ext u al descr ipt ion of t h e er r or . Example #include "o2db_o2db_access.h" int get_emp(o2db_Session *session) { int code, status; char *msg; o2db_Statement statement = session->open(&status); status = statement->associate("SELECT * from emp"); if (status == o2dbE_SERVER) { msg = statement->server_error(&code); cerr << "error: " << code << " msg: " << msg << endl; } ... } O2 DBAccess User Man u al 31 3 Class Library 3.2 o2db_Connection An object of t h is class defin es an d m ain t ain s t h e con n ect ion t o a r em ot e h ost. Th e in for m ation n eeded t o set u p a lin k bet ween t h e O 2 applicat ion an d t h e h ost syst em is fou n d in a con figu r at ion file. It is m ade u p of a set of n et wor k an d h ost specific par am eter s. Refer t o Sect ion 4.2 for a fu ll descr ipt ion of t h e con figu r at ion file. Th is sect ion descr ibes t h e followin g m em ber fu n ct ion s of t h e o2db_Connection class: • connect • disconnect • logoff • logon 32 O2 DBAccess User Man u al o2db_Connection : connect connect Summary Con n ect s t o a r em ote h ost . Syntax int connect(char *c_name,char *username,char *password); Arguments c_name Th is is a st r in g con tain in g a valid en t r y in t h e O2DBAccess con figu r at ion file (see Section 4.2). username Th is is a st r in g con tain in g th e u ser n am e on t h e r em ot e h ost . password Th is is a st r in g con tain in g t h e passwor d of t h e u ser on th e r em ot e h ost. Description Th is fu n ct ion set s u p a lin k bet ween th e wor k st at ion an d a r em ote Sequ eL i n k ser ver . Returns O2DB_OK if th e con n ect ion su cceeded, or on e of t h e followin g er r or codes if t h e con n ection failed: • o2dbE_STILL_CONNECT • o2dbE_RC_NOTFOUND • o2dbE_FILE_NOTFOUND • o2dbE_INVALID_RC • o2dbE_UNKN_NETWORK • o2dbE_OPEN_FILE • o2dbE_SERVER Example #include "o2db_o2db_access.h" int connect() { int code, status; char *msg; o2db_Connection connection; status = connection.connect("oracle", "user", "pwd"); if ( status != O2DB_OK) { cerr << "Connection error: " << status << endl; } ... } O2 DBAccess User Man u al 33 3 Class Library disconnect Summary Discon n ect s fr om a r em ote h ost . Syntax void disconnect(void); Arguments Non e. Description Th e disconnect m em ber fu n ct ion discon n ect s th e lin k bet ween t h e applicat ion an d th e r em ot e Sequ eL i n k ser ver . All th e cu r r en t session s an d st at em en t s ar e r eleased by th is fu n ct ion . Returns Not h in g Example #include "o2db_o2db_access.h" int dbaccess() { int code, status; char *msg; o2db_Connection connection; status = connection.connect("oracle", "user", "pwd"); ... connection.disconnect(); return status; } 34 O2 DBAccess User Man u al o2db_Connection : logoff logoff Summary En ds a database ser ver session . Syntax int logoff(o2db_Session *session); Arguments session Description Th e logoff m em ber fu n ct ion en ds an exist in g session on a dat abase ser ver . All t h e st at em en t s cr eat ed du r in g t h e session ar e destr oyed an d t h e dat abase ser ver r esou r ces ar e r eleased. Th e poin t er s t o o2db_Statement object s ar e n o lon ger valid aft er t h is call. Returns A st at u s code wh ose valu e is O2DB_OK if t h e oper at ion was su ccessfu ll, or on e of th e followin g er r or codes if t h e oper ation failed: A poin ter on t h e session t o close. • o2dbE_NOT_CONNECT • o2dbE_NOT_MEMBER • o2dbE_SQLNK • o2dbE_SERVER Example #include "o2db_o2db_access.h" int dbaccess() { int code, status; char *msg; o2db_Connection connection; o2db_Session *session; status = connection.connect("oracle", "user", "pwd"); session = connection.logon( "dbuser", "dbpasswd", &status); ... status = connection.logoff(session); if (status == o2dbE_SERVER) { msg = connection.server_error(&code); cerr << "error: " << code << " msg: " << msg << endl; } else if (status != O2DB_OK) cerr << "An error occurs: " << status << endl; ... connection.disconnect(); return status; } O2 DBAccess User Man u al 35 3 Class Library logon Summary Logs on t o a dat abase ser ver . Syntax o2db_Session *logon( char *logon1,char *logon2, int *retcode); Arguments logon1 A par am et er n eeded t o log on t o t h e dat abase ser ver . logon2 A par am et er n eeded t o log on t o t h e dat abase ser ver . retcode A poin t er on an in t eger t h at will con tain an er r or code on failu r e. Description Th e logon m em ber st ar t s a n ew session on t h e dat abase ser ver . Th e logon1 an d logon2 par am et er s ar e database depen den t bu t u su ally con t ain s a database u ser an d it s passwor d. For m or e in for m ation , r efer t o t h e docu m en t at ion Using SequelLink w ith y our Database and Server . Th e par am et er len gth m u st be less t h an 256 ch ar acter s. retcode is a poin t er t o an in teger t h at will be set t o an er r or code in case of failu r e. Th e possible er r or codes r et u r n ed in retcode ar e as follows: • o2dbE_NOT_CONNECT • o2dbE_TOOLONG • o2dbE_SQLNK • o2dbE_SERVER Returns 36 A poin ter to an object of t h e class o2db_Session, or NULL if th e login failed. O2 DBAccess User Man u al o2db_Connection : logon Example #include "o2db_o2db_access.h" int create_session() { int code, status; char *msg; o2db_Connection connection; o2db_Session *session; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon("dbuser", "dbpasswd", &status); if ( status == o2dbE_SERVER) { msg = connection.server_error(&code); cerr << "Error: " << code << " msg: " << msg << endl; } else if (status != O2DB_OK) cerr << "An error occurs: " << status << endl; ... connection.disconnect(); return status; } O2 DBAccess User Man u al 37 3 Class Library 3.3 o2db_Session An object of t h e o2db_Session class is cr eat ed by t h e logon fu n ct ion of t h e o2db_Connection class an d m an ages t h e con n ect ion t o a dat abase ser ver . Th is class h as t h e followin g m em ber fu n ct ion s: • close • commit • open • rollback 38 O2 DBAccess User Man u al o2db_Session : close close Summary Closes a st at em en t . Syntax int close(o2db_Statement *statement); Arguments statement Description Th is fu n ct ion closes an alr eady open ed st at em en t an d r eleases all r esou r ces associat ed with t h is statem en t . Returns A st at u s code wh ose valu e is O2DB_OK if t h e oper at ion was su ccessfu l, or on e of t h e followin g er r or codes if t h e oper ation failed: A poin t er on a st at em en t r et u r n ed by t h e m em ber fu n ction open. • o2dbE_NOT_LOGON • o2dbE_NOT_MEMBER • o2dbE_SQLNK • o2dbE_SERVER Example #include "o2db_o2db_access.h" int dbaccess() { int code, status; char *msg; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon( "dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... status = session->close(statement); ... connection.disconnect(); return status; } O2 DBAccess User Man u al 39 3 Class Library commit Summary Per for m s a com m it on t h e dat abase ser ver . Syntax int commit(void); Arguments Non e Description Th is fu n ct ion per for m s a com m it on t h e database ser ver , th u s validat in g wh at h as been don e in th e cu r r en t session . Returns A st at u s code wh ose valu e is O2DB_OK if t h e oper ation was su ccessfu l, or on e of th e followin g er r or codes if t h e oper ation failed: • o2dbE_NOT_LOGON • o2dbE_SQLNK • o2dbE_SERVER Example #include "o2db_o2db_access.h" int dbaccess() { int code, status; char *msg; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon( "dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... status = session->commit(); ... status = session->close(statement); ... connection.disconnect(); return status } 40 O2 DBAccess User Man u al o2db_Session : open open Summary Cr eat es a n ew st at em en t . Syntax o2db_Statement *open(int *retcode); Arguments retcode Description Th is fu n ct ion open s a n ew st at em en t t h at will allow a pr ogr am m er t o execu te SQL st at em en t s. A poin t er on t h e cr eat ed st at em en t is r et u r n ed. A poin ter on an in t eger t h at will con t ain an er r or code on failu r e. retcode is a poin t er on an in t eger t h at will be set t o an er r or code in case of failu r e. Th e possible er r or codes r et u r n ed in retcode ar e as follows: • o2dbE_NOT_LOGON • o2dbE_NO_MORE_STATEMENTS • o2dbE_SQLNK • o2dbE_SERVER Returns A poin ter on an object of t h e class o2db_Statement or NULL if t h e oper at ion failed. O2 DBAccess User Man u al 41 3 Class Library Example #include "o2db_o2db_access.h" int dbaccess() { int code, status; char *msg; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon( "dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... status = session->commit(); ... status = session->close(statement); ... connection.disconnect(); return status; } 42 O2 DBAccess User Man u al o2db_Session : rollback rollback Summary Per for m s a r ollback on t h e dat abase ser ver . Syntax int rollback(void); Arguments Non e. Description Th is fu n ct ion per for m s a r ollback on t h e dat abase ser ver , th u s in validat in g wh at h as been don e in t h e cu r r en t session . Returns A st at u s code wh ose valu e is O2DB_OK if t h e oper at ion was su ccessfu l, or on e of t h e followin g er r or codes if t h e oper ation failed: • o2dbE_NOT_LOGON • o2dbE_SQLNK • o2dbE_SERVER Example #include "o2db_o2db_access.h" int dbaccess() { int code, status; char *msg; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon("dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... status = session->rollback(); ... status = session->close(statement); ... connection.disconnect(); return status; } O2 DBAccess User Man u al 43 3 Class Library 3.4 o2db_Statement An object of t h e o2db_Statement class is cr eat ed by t h e open fu n ction of t h e o2db_Session class an d m an ages all t h e r esou r ces r elat ed t o SQL st at em en t s. Th is class h as th e followin g m em ber fu n ct ion s: • add_cursor_variable • add_input_variable • associate • operator >> • operator << An d t h e followin g fu n ct ion : • o2db_sql_execute 44 O2 DBAccess User Man u al o2db_Statement : add_cursor_variable add_cursor_variable Summary Specifies a C++ at t r ibu t e n am e t o stor e an SQL r esu lt set colu m n . Syntax int add_cursor_variable(char *s); Arguments s Description Wh en a select st at em en t is per for m ed, t h e r esu lt set h as to be st or ed in a C++ object or in a collection of C++ object s. Th is fu n ct ion m u st be called on ce for each colu m n of t h e r esu lt set r etu r n ed by t h e SQL statem en t , in or der t o specify in wh ich at t r ibu t e of a C++ object t h e valu es of a colu m n will be pu t. A st r in g r epr esen t in g a C++ at t r ibu te n am e. Th e calls t o t h is fu n ct ion m u st be don e in t h e or der th e colu m n s of t h e r esu lt set occu r in t h e SQL st at em en t . Returns O2DB_OK. Example #include "o2db_o2db_access.h" int get_persons() { int code, status; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; d_Set<d_Ref<Person> > persons; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon("dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... status = statement->associate("SELECT name,age FROM emp"); // asuming class Person { // char *name_att; // int age_att; // } statement->add_cursor_variable("name_att"); statement->add_cursor_variable("age_att"); ... status = session->close(statement); ... connection.disconnect(); return status; } O2 DBAccess User Man u al 45 3 Class Library add_input_variable Summary Evalu ates an in pu t var iable of an SQL st at em en t . Syntax int int int int int int int int int int int int Arguments xx Description Th is fu n ct ion is u sed by a pr ogr am m er wh o defin ed an SQL st at em en t con t ain in g in pu t var iables. Th ese var iables ar e wr it t en u sin g '?' in t h e SQL statem en t . It is n ecessar y to give a valu e for t h ese var iables befor e r u n n in g t h e st at em en t . add_input_variable(const char *s); add_input_variable(char c); add_input_variable(unsigned char uc); add_input_variable(short s); add_input_variable(unsigned short us); add_input_variable(int i); add_input_variable(unsigned int ui); add_input_variable(long l); add_input_variable(unsigned long ul); add_input_variable(float f); add_input_variable(double d); add_input_variable(const d_Bits &s); A C++ valu e t o assign to t h e in pu t var iable. xx can be an y k in d of C++ t ype, accor din g t o t h e t ype expect ed by t h e dat abase ser ver . Th is fu n ct ion associat es a valu e of an y t ype wit h an in pu t var iable. Th e t ype u sed m u st be con sist en t wit h t h e expect ed t ype in t h e dat abase ser ver . Th is fu n ct ion m u st be called on ce for each in pu t var iable defin ed in t h e st at em en t , in th e or der of th e ’?’ m ar k er s appear in g in t h e SQL st at em en t . Returns A st at u s code wh ose valu e is O2DB_OK if t h e oper ation was su ccessfu l, or on e of th e followin g er r or codes if t h e oper ation failed: • o2dbE_NOT_OPEN • o2dbE_NOSTMT • o2dbE_INTERNAL • o2dbE_NOT_SUPPORTED • o2dbE_NILREF • o2dbE_RANGE • o2dbE_MISMATCH • o2dbE_SQLNK • o2dbE_SERVER 46 O2 DBAccess User Man u al o2db_Statement : add_input_variable Example #include "o2db_o2db_access.h" int get_persons() { int code, status; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; d_Set<d_Ref<Person> > persons; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon("dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... status = statement->associate("SELECT name,age FROM emp WHERE age<?"); ... statement->add_cursor_variable("name_att"); statement->add_cursor_variable("age_att"); statement->add_input_variable(20); ... status = session->close(statement); connection.disconnect(); return status; } O2 DBAccess User Man u al 47 3 Class Library associate Summary Defin es an SQL st at em en t . Syntax int associate(char *stmt); Arguments stmt Description Th is fu n ct ion is u sed t o defin e an SQL st at em en t . It can be an y valid SQL sen t en ce in wh ich in pu t var iables ar e r eplaced by qu est ion m ar k s ('?'). Th e t ext of t h e SQL st at em en t t h at will be execu t ed. Th e act u al valu es for th e in pu t var iables ar e given u sin g t h e fu n ct ion add_input_variable or t h e operator <<. Callin g associate on a st at em en t in validat es all pr eviou s var iable defin it ion s for t h is st at em en t . Returns A st at u s code wh ose valu e is O2DB_OK if t h e oper ation was su ccessfu l, or on e of th e followin g er r or codes if t h e oper ation failed: • o2dbE_NOT_OPEN • o2dbE_NOSTMT • o2dbE_TOOLONG • o2dbE_SQLNK • o2dbE_SERVER 48 O2 DBAccess User Man u al o2db_Statement : associate Example #include "o2db_o2db_access.h" int get_persons() { int code, status; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; d_Set<d_Ref<Person> > persons; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon( "dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... status = statement->associate("SELECT name,age FROM emp WHERE age<?"); ... status = session->close(statement); ... connection.disconnect(); return status; } O2 DBAccess User Man u al 49 3 Class Library operator >> Summary Adds a cu r sor var iable. Syntax o2db_Statement & operator >>( o2db_Statement &q , const char *s); Arguments q A r efer en ce t o an object of t h e class o2db_Statement t h at m an ages t h e SQL st at em en t for wh ich t h e var iable is defin ed. s A st r in g r epr esen tin g a C++ at t r ibu te n am e. Description Th is oper at or act s in exact ly t h e sam e way as t h e m em ber fu n ct ion add_cursor_variable. It is a m or e dir ect in t er face t o it . Returns A r efer en ce t o t h e st at em en t. Example int get_persons() { int code, status; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; d_Set<d_Ref<Person> > persons; d_Iterator<d_Ref<Person> > iter; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon("dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... status = statement->associate("SELECT name,age FROM emp WHERE age<?"); *statement >> "name_att" >> "age_att"; statement->add_input_variable(20); status = o2db_sql_execute(*statement, persons); ... status = session->close(statement); connection.disconnect(); iter = persons.create_iterator(); while (iter.next(p)) { cout << "Name : " << p.name_att << endl; cout << "Age : " << p.age_att << endl; cout << endl; } return status; } 50 O2 DBAccess User Man u al o2db_Statement : operator << operator << Summary Adds an in pu t var iable. Syntax o2db_Statement &operator << ( o2db_Statement &q, const char *s); o2db_Statement &operator << ( o2db_Statement &q, char c); o2db_Statement &operator << ( o2db_Statement &q, unsigned char uc); o2db_Statement &operator << ( o2db_Statement &q, short s); o2db_Statement &operator << ( o2db_Statement &q, unsigned short us); o2db_Statement &operator << ( o2db_Statement &q, int i); o2db_Statement &operator << ( o2db_Statement &q, unsigned int ui); o2db_Statement &operator << ( o2db_Statement &q, long l); o2db_Statement &operator << ( o2db_Statement &q, unsigned long ul); o2db_Statement &operator << ( o2db_Statement &q, float f); o2db_Statement &operator << ( o2db_Statement &q, double d); o2db_Statement &operator << ( o2db_Statement &q, const d_Bits &s); Arguments q A r efer en ce to an object of t h e class o2db_Statement th at m an ages t h e SQL st at em en t for wh ich th e var iable is defin ed. xx A C++ valu e t o associat e t o t h e in pu t var iable. xx can be an y k in d of C++ t ype, accor din g t o t h e t ype expect ed by th e dat abase ser ver . Description Th is oper at or acts in exact ly th e sam e way as t h e m em ber fu n ction add_input_variable. It is a m or e dir ect in t er face t o it Returns A r efer en ce to t h e st at em en t . O2 DBAccess User Man u al 51 3 Class Library Example int get_persons() { int code, status; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; d_Set<d_Ref<Person> > persons; d_Iterator<d_Ref<Person> > iter; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon("dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... statement->associate( "SELECT name,age FROM emp WHERE age<?"); *statement >> "name_att" >> "age_att"; *statement << 20; status = o2db_sql_execute(*statement, persons); ... status = session->close(statement); ... connection.disconnect(); iter = persons.create_iterator(); while (iter.next(p)) { cout << "Name : " << p.name_att << endl; cout << "Age : " << p.age_att << endl; cout << endl; } return status; 52 O2 DBAccess User Man u al o2db_Statement : o2db_sql_execute o2db_sql_execute Summary Execu t es an SQL st at em en t . Syntax int o2db_sql_execute(o2db_Statement & q); int o2db_sql_execute( o2db_Statement & q, o2_col_root & coll); int o2db_sql_execute(o2db_Statement & q, d_Ref<T> & o); Arguments q A r efer en ce t o an object of t h e class o2db_Statement t h at m an ages t h e SQL st at em en t t o be execu t ed. coll A r efer en ce to an y O 2 collect ion in wh ich t h e r esu lt of th e st at em en t m u st in ser t ed. o A r efer en ce to an O2 object in wh ich th e r esu lt (for a sin gle lin e r esu lt set ) m u st be pu t . Description Th is fu n ct ion execu tes a pr eviou sly defin ed SQL st at em en t . Th e fir st fu n ct ion r et u r n s im m ediatly aft er t h e statem en t h as been r u n (u sed for a st at em en t wit h ou t r esu lt ) an d t h e ot h er t wo fu n ct ion s pu t t h e r esu lt of t h e st at em en t in to t h e t ar get object. Th e t ar get object can be a collect ion of object wh en t h e pr ogr am m er expect s t o h ave a r esu lt set wit h m u lt iple r ows or can be an object wh en t h e pr ogr am m er k n ows t h at th e statem en t will r et u r n a sin gle r ow r esu lt set . Returns A st at u s code wh ose valu e is O2DB_OK if t h e oper at ion was su ccessfu l, or on e of t h e followin g er r or codes if t h e oper ation failed: • o2dbE_NOT_OPEN • o2dbE_NOSTMT • o2dbE_NOT_SELECT • o2dbE_DEFINED • o2dbE_MISMATCH • o2dbE_NOT_SUPPORTED • o2dbE_NOT_UNIQUE • o2dbE_INVALID_NAME • o2dbE_NOT_EXECUTED • o2dbE_NILREF • o2dbE_SQLNK • o2dbE_SERVER O2 DBAccess User Man u al 53 3 Class Library Example int get_persons() { int code, status; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; d_Set<d_Ref<Person> > persons; d_Iterator<d_Ref<Person> > iter; status = connection.connect("oracle", "user", "pwd"); ... session = connection.logon("dbuser", "dbpasswd", &status); ... statement = session->open(&status); ... statement->associate( "SELECT name,age FROM emp WHERE age<?"); statement->add_cursor_variable("name_att"); statement->add_cursor_variable("age_att"); statement->add_input_variable(20); status = o2db_sql_execute(*statement, persons); ... status = session->close(statement); connection.disconnect(); iter = persons.create_iterator(); while (iter.next(p)) { cout << "Name : " << p.name_att << endl; cout << "Age : " << p.age_att << endl; cout << endl; } return status; } 54 O2 DBAccess User Man u al 44 A ppe ndices Th is ch apt er con t ain s t h e followin g appen dices: • Exam ple Applicat ion • Con figu r at ion File • Possible Er r or s O2 DBAccess User Man u al 55 4 Appendices 4.1 Example Application Th is exam ple illu st r at es t h e var iou s st eps you m u st go t h r ou gh in or der t o u se O2 DBAccess in side an ODMG C++ applicat ion . Th is sect ion is divided u p in t o t h e followin g sect ion s: • Defin in g a C++ sch em a • Connecting to O2 • Con n ect in g to t h e Relation al dat abase ser ver • Cr eatin g a table • Popu lat in g t h e t able • Displayin g t h e t able con t en t • Qu er yin g t h e RDBMS • Bu ildin g t h e applicat ion 56 O2 DBAccess User Man u al Example Application : Defining a C++ schema Defining a C++ schema You m u st fir st defin e t h e C++ classes th at will be u sed t o r eceive t h e r esu lt s of th e SQL statem en t s r u n in t h e applicat ion . In th is exam ple, we defin e a class Person. Th e C++ classes defin ed h er e m u st be im por t ed in O 2 as per sist en ce capable classes. To be able t o st or e an SQL r esu lt set , you will n eed t o defin e collect ion s for th ese classes. #include "o2util_CC.hxx" class Person { public: d_Short id_person; char *name; char *firstname; int age; d_Char employed; d_Long zip_code; }; Note You m ak e a C++ class per sist en ce capable u sin g o2im por t or a dir ective in t h e o2makegen con figu r ation file (see t h e Sect ion "Bu ildin g t h e applicat ion "). O2 DBAccess User Man u al 57 4 Appendices Connecting to O2 Th e m ain fu n ct ion of t h e applicat ion is an OD MG C++ fu n ction t h at open s a session wit h t h e O2 ser ver , open s a dat abase, star t s an O2 t r an sact ion an d cr eat es a per sist en t r oot . It t h en calls t h e fu n ct ion manage_sql, wh ich h an dles all t h e dbaccess par t an d fin ally com m it s t h e O 2 t r an sact ion an d discon n ect s fr om t h e O2 ser ver . main(int argc , char *argv[]) { char *o2_home = getenv("O2HOME"); char *o2_system = getenv("O2SYSTEM"); char *o2_server = getenv("O2SERVER"); d_Session session; d_Database database; d_Transaction transaction; if (! o2_home) { cerr << "Cannot retrieve O2HOME" << endl; exit(1); } if (! o2_system) { cerr << "Cannot retrieve O2SYSTEM" << endl; exit(1); } if (! o2_server) { cerr << "Cannot retrieve O2SERVER" << endl; exit(1); } if (session.begin(argc, argv, o2_system, o2_server, o2_home)) { cerr << "Cannot connect to o2" << endl; exit(1); } database.open("o2dbaccess_b"); transaction.begin(); database.create_persistent_root( "ThePersons", "d_Set<d_Ref<Person> >"); manage_sql(); transaction.commit(); database.close(); session.end(); } 58 O2 DBAccess User Man u al Example Application : Connecting to the Relational Connecting to the Relational database server Th is fu n ct ion is t h e en t r y poin t of t h e O2 DBAccess r elat ed code. It establish es a con n ect ion with t h e r em ot e dat abase ser ver , open s a dat abase, an d cr eat es a st at em en t . At t h is poin t , t h e fu n ction s th at issu e t h e qu er ies ar e called, an d fin ally, all t h e r esou r ces open ed on t h e r em ot e dat abase ser ver ar e closed. void manage_sql() { int retcode, svr_error; char *msg; o2db_Connection connection; o2db_Session *session; o2db_Statement *statement; // connection with the Sequelink server. retcode = connection.connect( "oracle", "user", "userpasswd"); if (retcode != O2DB_OK) cerr << "Cannot open a connection with the Sequelink server" << endl; // open an session session = connection.logon( "oracleuser", "oracleuserpasswd", &retcode); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = connection.server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } O2 DBAccess User Man u al 59 4 Appendices // create a statement statement = session->open(&retcode); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = connection.server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } // call the queries person_table_creation(statement); person_table_initialization(statement); person_table_display(statement); retcode = connection.logoff(session); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = connection.server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } retcode = connection.disconnect(); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = connection.server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } } 60 O2 DBAccess User Man u al Example Application : Creating a table Creating a table Th is fu n ct ion cr eat es a n ew t able on t h e RDBMS. Th e SQL CREATE st at em en t is associat ed t o t h e O 2 D BAccess st at em en t an d as th er e is n o m or e in for m at ion t o give, t h e st at em en t is execu t ed. void person_table_creation(o2db_Statement * statement) { int retcode, svr_error; char *msg; retcode = statement->associate("CREATE TABLE person \ ( id_person SMALLINT null, \ name VARCHAR(16) null, \ firstname VARCHAR(16) null, \ age INTEGER null, \ employed INTEGER default 0, \ zip_code NUMERIC null)"); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = statement->server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } retcode = o2db_sql_execute(*statement); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = statement->server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } } O2 DBAccess User Man u al 61 4 Appendices Populating the table Th e followin g fu n ct ion popu lat es t h e pr eviou sly cr eat ed table. Th e INSERT SQL st at em en t is associat ed t o th e O2 DBAccess st at em en t . It con t ain s par am et er s m ar k er s (den ot ed wit h '?'), t h at m u st be bou n d wit h t h e act u al valu es of t h e par am et er s. In t h is exam ple, t h is is per for m ed u sin g th e '<<' oper at or . It cou ld also h ave been per for m ed u sin g t h e add_input_variable m em ber fu n ct ion . Th e person_data t able u sed in th e exam ple is n ot det ailed an d cou ld be r eplaced by an y in pu t sou r ce. Aft er t h e par am et er s ar e bou n d, t h e st at em en t is execu t ed. In t h is exam ple, n ot e t h at t h e sam e associat ed statem en t is u sed sever al t im es t o in ser t sever al r ows in t h e per son t able, each t im e wit h a n ew bin din g of t h e act u al par am eter s. void person_table_initialisation(o2db_Statement * statement) { int retcode, svr_error; char *msg; retcode = statement->associate( "INSERT INTO \ person (id_person, \ name, \ firstname, \ age, \ employed, \ zip_code) \ VALUES (? , ? , ? , ? , ?, ?)"); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = statement->server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } 62 O2 DBAccess User Man u al Example Application : Populating the table for (int i = 0 ; *statement << *statement << *statement << *statement << *statement << *statement << i<NB_PERSON ; i++) { person_data[i].id_person; person_data[i].name; person_data[i].firstname; person_data[i].age; person_data[i].employed; person_data[i].zip_code; retcode = o2db_sql_execute(*statement); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = statement->server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } } } O2 DBAccess User Man u al 63 4 Appendices Displaying the table content Th is fu n ct ion sh ows h ow t o h an dle a SELECT SQL st at em en t . Th is k in d of st at em en t r etu r n s a r esu lt set t h at n eeds t o be st or ed in C++ object s. A collect ion of C++ objects of t h e per sist en ce capable class Person is cr eat ed an d is given as par am et er t o t h e o2db_sql_execute fu n ct ion . Aft er t h e st at em en t execu t ion , t h is collect ion will con t ain t h e r esu lt set of t h e SQL qu er y. In t h is exam ple, t h e collect ion "Th ePer son s" is per sist en t , bu t r esu lt s can be st or ed in t em por ar y collect ion s t oo. Not e t h at n o cu r sor var iables ar e defin ed in t h is fu n ct ion t o specify t o wh ich C++ at t r ibu t es t h e t able colu m n s ar e associat ed. In t h is case, all t h e C++ at t r ibu t es of t h e class given t o t h e o2db_sql_execute fu n ct ion ar e im plicit ly associat ed t o th e r esu lt set in t h e or der t h ey appear in t h e C++ class defin it ion . You m u st ch eck th at t h e SQL qu er y r etu r n s a valid dat a set for t h e given C++ object. Aft er t h e st at em en t is execu t ed, an it er at or is cr eat ed on t h e collection an d is u sed t o display each r et r ieved per son 64 O2 DBAccess User Man u al Example Application . void person_table_display(o2db_Statement * statement) { int retcode, svr_error; char *msg; d_Set<d_Ref<Person> > the_persons("ThePersons"); d_Iterator<d_Ref<Person> > iter; d_Ref<Person> person; retcode = statement->associate( "SELECT * \ FROM person"); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = statement->server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } retcode = o2db_sql_execute(*statement, the_persons); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = statement->server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } iter = the_persons.create_iterator(); while (iter.next(person)) { cout << "\t*** [ " << person -> id_person << " " << person -> name << " " << person -> firstname << " " << person -> age << " " << person -> employed << " " << person -> zip_code << " ]" << endl; } } O2 DBAccess User Man u al 65 4 Appendices Querying the RDBMS Th is qu er y is qu ite sim ilar to t h e pr eviou s on e except t h at cu r sor var iables ar e explicit ly defin ed (becau se t h e n u m ber an d or der of appear an ce of t h e at tr ibu t es of t h e given C++ class ar e n ot t h e sam e as t h e colu m n s of t h e r esu lt set . Th is exam ple also sh ows h ow t o com bin e in pu t var iables an d cu r sor var iables in t h e sam e st at em en t . M or eover t h e r esu lt is n ow pu t in a t em por ar y list . Th e fu n ct ion fir st ly associat es t h e SQL st at em en t t o th e O2 DBAccess st at em en t, gives t h e valu e '35' as t h e act u al par am et er for t h e m ar k er u sed in t h e SQL st at em en t , an d defin es t h e cu r sor var iables. In t h is case t h e colu m n "name" of t h e r esu lt set is associat ed t o t h e at t r ibu t e "name" of th e C++ class (*statement >> "name") an d t h e colu m n "firstname" of t h e r esu lt set is associated t o t h e at t r ibu t e "firstname" of t h e C++ class (*statement >> ... >> "firstname"). Note Even if it is t h e case in t h is fu n ction , t h e C++ at t r ibu te associat ed t o a colu m n of t h e SQL r esu lt set does n ot n eed t o h ave th e sam e n am e as t h e colu m n . For in stan ce, we cou ld h ave associat ed an att r ibu t e called "person_name" t o t h e colu m n "name" of t h e r esu lt set 66 O2 DBAccess User Man u al Example Application void person_table_query(o2db_Statement * statement) { int retcode, svr_error; char *msg; d_List<d_Ref<Person> > young_people; d_Iterator<d_Ref<Person> > iter; d_Ref<Person> person; retcode = statement->associate("SELECT name, firstname\ FROM person \ WHERE age < ? \ ORDER BY age"); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = statement->server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } // binds the input variable *statement << 35; // binds the cursor variables. *statement >> "name" >> "firstname"; retcode = o2db_sql_execute(*statement, young_people); if (retcode != O2DB_OK) { if (retcode == o2dbE_SERVER) { msg = statement->server_error(&svr_error); cerr << "error: " << svr_error << " msg: " << msg << endl; } else cerr << "dbaccess error: " << retcode; return; } iter = young_people.create_iterator(); while (iter.next(person)) { cout << "\t*** [ " << person -> name << " " << person -> firstname << " ]" << endl; } } O2 DBAccess User Man u al 67 4 Appendices Building the application You bu ild t h e applicat ion in exact ly th e sam e way as you bu ild a classical OD MG C++ applicat ion . To u se O2 DBAccess you ju st n eed to lin k -edit you r application wit h th e O2 DBAccess libr ar y an d wit h th e Sequ eLin k clien t libr ar ies an d t o add a dir ect ive t o look for Sequ eLin k clien t in clu de files. Th e followin g code gives an o2makegen con figu r at ion file t h at can be u sed t o cr eat e an application (see t h e "C++ Bi n d i n g Gu i d e M an u al "). Note Befor e u sin g a gen er at ed applicat ion , it is m an dat or y t o cr eat e an O 2 sch em a an d base u sin g t h e o2dsa pr ogr am . O2System: $O2SYSTEM O2Server: $O2SERVER O2Schema: o2dbaccess_s +UseConfirmClasses O2Home: $O2HOME ImpFiles: Person.hxx [Person.hxx]ImpClasses: Person ImpSet: Person Sources: example.cc ProgramLib: o2dbaccess SqlnkCor SqlnkNet SqlnkDef ProgramLibDir: $O2HOME/thirdparty/SequeLink/lib/IRIX Include: $O2HOME/thirdparty/SequeLink/include ProgramName: example ProgramObjs: example.o . 68 O2 DBAccess User Man u al Configuration File 4.2 Configuration File Th e con figu r at ion file o2dbaccess.cf con tain s t h e in for m at ion n eeded t o lin k u p you r O2 application an d a r em ote h ost , in th e for m of a set of n et wor k an d h ost -specific par am eter s. You can ch an ge t h e file n am e by specifyin g a n ew n am e an d it s pat h in t h e en vir on m en t var iable O2DBACCESS. Th is var iable m u st con t ain t h e fu ll pat h of t h e file. In or der of pr ior it y, t h e file is fir st t ak en fr om th e wor k in g dir ector y, t h en $HOME an d t h en t h e O 2 in st allat ion dir ect or y. It is an ASCII file wh er e each lin e cor r espon ds t o a n am ed lin k descr ipt ion . It con tain s on e en t r y for each n am ed lin k with com m en t s begin n in g wit h #. Th e lin e for m at is: c_name:network:host:port:service:lu_name:mode:max_statements:type_checking Each field is descr ibed below. c_name Lin k n am e. Specify a lin k n am e each t im e you in vok e t h e o2db_Connection::connect m em ber fu n ct ion . network Type of n et wor k pr otocol u sed. Possible valu es: TCP (MacTCP on Macin t osh ), ADSP, APPC, D ECn et, Net BIOS an d AppleTalk . host RDBMS r em ote h ost / n ode/ zon e n am e. port Por t on wh ich th e Sequ elin k ser ver is list en in g. Defau lt is 2000. If you wan t t o u se t h e defau lt por t n u m ber , u se a ’*’. service Sequ eLin k (dat abase) ser vice n am e t h at you wan t t o con n ect t o. You can fin d t h is n am e in t h e ser ver m ap file on t h e r em ot e h ost . See Sequ eLin k m an u al. lu_name Ph ysical LU Nam e in APPC n et wor k pr ot ocol (opt ion al). If it is n ot applicable, u se a ’*’. mode APPC m ode in APPC n et wor k pr ot ocol (opt ion al). If it is n ot applicable, u se a ’*’. max_statements In teger (fr om 0 to 100) specifyin g m axim u m n u m ber of st at em en t s t h at can be open ed at t h e sam e t im e du r in g a session . If 0, th e defau lt valu e (15) is u sed. type_checking Boolean specifyin g wh et h er t o en able (true) or disable (false) type ch eck in g in t h e o2db_Statement::add_cursor_variable an d o2db_Statement::add_input_variable m em ber fu n ct ion s. Defau lt valu e is false. O2 DBAccess User Man u al 69 4 Appendices Warning ! Th e t ype ch eck in g is n ot su p por t ed for al l RDBM S. An exam ple con figu r ation file is as follows: supra on salome:TCP:salome:LSPSUPRA2:*:*:15:false db2 on sgphl1:DECnet:sgphl1:MVSDB2:*:*:0:true oracle:TCP:o2tech:oracle_services:*:*:0:false 70 O2 DBAccess User Man u al Possible Errors : Building the application 4.3 Possible Errors Each m em ber fu n ct ion r et u r n s an in t er n al er r or code. Th is sect ion descr ibes th ese er r or codes. You can obtain RD BM S-det ect ed er r or codes u sin g th e server_error m em ber fu n ct ion . See Sect ion 3.1 for a descr ipt ion of t h is m em ber fu n ct ion . • -1001 Code: o2dbE_SERVER (-1001) Call: All. Cau se: RDBMS-detect ed er r or h as occu r r ed. Act ion : Con su lt er r or code an d m essage t ext callin g t h e o2db_O2DBAccess::server_error m em ber fu n ct ion . • -2001 Code: o2dbE_SQLNK (-2001) Call: All. Cau se: A Sequ eLin k er r or h as occu r r ed. Sh ou ld u su ally on ly be issu ed on a o2db_Connection::connect m em ber fu n ct ion call. Act ion : Ch eck t h e lin k par am et er s, u ser n am e an d passwor d. Th e con n ect failu r e r eason is in <network>srv.log file on t h e r em ot e h ost . • -3001 Code: o2dbE_STILL_CONNECT (-3001) Call: o2db_Connection::connect Cau se: You ar e st ill con n ect ed t o a h ost . Act ion : Th e o2db_Connection::connect m em ber fu n ct ion was called bu t n ot t h e o2db_Connection::disconnect m em ber fu n ct ion . • -3002 Code: o2dbE_NOT_CONNECT (-3002) Call: o2db_Connection::logon, o2db_Connection::logoff Cau se: Not con n ect ed. Act ion : Ch eck com plet ion of t h e pr eviou s connect m em ber fu n ct ion call. O2 DBAccess User Man u al 71 4 Appendices • -3003 Code: o2dbE_NOT_MEMBER (-3003) Call: o2db_Connection::logoff, o2db_Session::close Cau se: Th e Session / St at em en t object h as n ot been cr eat ed by t h e r eceiver . Act ion : Ch eck th e m em ber fu n ction call syn t ax. • -3004 Code: o2dbE_NOT_LOGON (-3004) Call: o2db_Session::open, o2db_Session::close, o2db_Session::commit, o2db_Session::rollback Cau se: Not logged on . Act ion : Ch eck com plet ion of t h e pr eviou s o2db_Connection::logon m em ber fu n ct ion call. • -3005 Code: o2dbE_TOOLONG (-3005) Call: o2db_Connection::logon, o2db_Statement::associate Cau se: Th e par am et er s ar e t oo lon g. Act ion : D ecr ease par am et er len gt h . • -3006 Code: o2dbE_NOT_OPEN (-3006) Call: o2db_Statement::associate, o2db_Statement::add_input_variable, o2db_sql_execute Cau se: Th e st at em en t h as n ot been open ed. Act ion : Ch eck t h e com pletion of t h e pr eviou s o2db_Session::open m em ber fu n ct ion call. • -3008 Code: o2dbE_NOSTMT (-3008) Call: o2db_Statement::associate, o2db_Statement::add_input_variable, o2db_sql_execute Cau se: Th e SQL st at em en t is em pt y. Act ion : 72 Ch eck th e m em ber fu n ction call syn t ax. O2 DBAccess User Man u al Possible Errors : Building the application • -3009 Code: o2dbE_FILE_NOTFOUND (-3009) Call: o2db_Connection::connect Cau se: Th e con figu r at ion file was n ot fou n d. Act ion : Ch eck t h at t h e con figu r at ion file exist s. • -3010 Code: o2dbE_RC_NOTFOUND (-3010) Call: o2db_Connection::connect Cau se: No descr ipt ion of t h e lin k par am et er s for t h is lin k n am e. Act ion : Ch eck con figu r at ion file con t en t s an d th e m em ber fu n ct ion call syn t ax. • -3011 Code: o2dbE_INVALID_RC (-3011) Call: o2db_Connection::connect Cau se: In valid lin e in t h e con figu r at ion file. Act ion : Ch eck t h e con figu r at ion file con t en t s. • -3012 Code: o2dbE_UNKN_NETWORK (-3012) Call: o2db_Connection::connect Cau se: Un k n own n etwor k pr ot ocol. Act ion : Ch eck con figu r at ion file con t en t s. • -3013 Code: o2dbE_OPEN_FILE (-3013) Call: o2db_Connection::connect Cau se: Th e con figu r at ion file can n ot be open ed. Act ion : Ch eck t h at t h e con figu r at ion file exist s an d ch eck it s access r igh t s. O2 DBAccess User Man u al 73 4 Appendices • -3014 Code: o2dbE_NOT_SELECT (-3014) Call: o2db_sql_execute Cau se: Th e SQL st at em en t is n ot a select st at em en t . Act ion : Ch eck t h e syn t ax of t h e SQL st at em en t. • -3015 Code: o2dbE_RANGE (-3015) Call: o2db_Statement::add_input_variable Cau se: Th e or der n u m ber is ou t of r an ge. Act ion : Ch eck t h e or der n u m ber . • -3016 Code: o2dbE_DEFINED (-3016) Call: o2db_sql_execute Cau se: Th e par am et er or t h e r esu lt object is yet defin ed. Act ion : Ch eck t h e or der n u m ber . • -3017 Code: o2dbE_MISMATCH (-3017) Call: o2db_Statement::add_input_variable, o2db_sql_execute Cau se: Type ch eck in g failed. Act ion : Ch eck t h e r esu lt or par am et er t ype. • -3018 74 Code: o2dbE_NOT_SUPPORTED (-3018) Call: o2db_Statement::add_input_variable, o2db_sql_execute Cau se: On e of t h e atom ic t ypes u sed is n ot su ppor ted in th e cu r r en t ver sion of O2 DBAccess. Act ion : Ch eck t h e t ype of r esu lt object . O2 DBAccess User Man u al Possible Errors : Building the application • -3021 Code: o2dbE_INVALID_NAME (-3021) Call: o2db_sql_execute Cau se: On e of t h e n am es is n ot an att r ibu t e n am e. Act ion : Ch eck t h e list of att r ibu t e n am es. • -3022 Code: o2dbE_NOT_EXECUTED (-3022) Call: o2db_sql_execute Cau se: Th e stat em en t h as n ot been execu ted. Act ion : Ch eck t h e com plet ion of t h e pr eviou s o2db_sql_execute m em ber fu n ct ion call. • -3023 Code: o2dbE_NO_MORE_STATEMENTS (-3023) Call: o2db_Statement::open Cau se: An at t em pt was m ade t o exceed th e m axim u m n u m ber open statem en t s allowed. Act ion : Close som e statem en t s. • -3024 Code: o2dbE_NILREF (-3024) Call: o2db_Statement::add_input_variable, o2db_sql_execute Cau se: Th e r esu lt object or a par am et er is nil. Act ion : Ch eck t h e m em ber fu n ct ion call syn t ax. • -3025 Code: o2dbE_NOMEM (-3025) Call: All. Cau se: Not en ou gh m em or y. Act ion : Close som e statem en t s. O2 DBAccess User Man u al 75 4 Appendices • -4001 Code: o2dbE_INTERNAL (-4001) Call: All. Cau se: In t er n al er r or . It sh ou ld n ot n or m ally be issu ed. Act ion : Con t act you r local t ech n ical su ppor t. • -5001 76 Code: o2dbW_NOT_UNIQUE (-5001) Call: o2db_sql_execute Cau se: Th is a war n in g. Th er e is m or e t h an on e r ow t o fet ch wh er eas t h e r esu lt t ype is n ot a collect ion . Act ion : Noth in g. On ly t h e fir st r ow h as been fet ch ed. O2 DBAccess User Man u al IN DEX O2 DBAccess User Man u al 77 INDEX A D add_cu r sor _var iable Function 23–24, 45 Data Access 21 add_in pu t _var iable Function 23–24, 46 Database Access 21–22 Log off 21 Log on 21 Applicat ion Bu ildin g 68 Exam ple 56–68 Ar ch itect u r e Clien t / ser ver 13 O2 10 associat e Function 23, 48 C discon n ect Function 21, 28, 34 E En vir on m en t var iable 69 Er r or codes 23, 71–76 Exam ple application 56–68 C 11 C++ In t er face 11 F C++ Sch em a Defin it ion 57 c_name 69 Class 18 o2db_Connection 21, 32 o2db_O2DBAccess 30 o2db_Session 21, 38 o2db_Statement 44 File Con figu r at ion 69 Clien t / ser ver ar ch it ect u r e 13 close Function 22, 39 com m it Function 28, 40 Con figu r at ion File 68, 69 con n ect Function 21, 33 78 O2 DBAccess User Man u al INDEX Fu n ct ion 19 add_cursor_variable 23–24, 45 add_input_variable 23–24, 46 associate 23, 48 close 22, 39 commit 28, 40 connect 21, 33 disconnect 21, 28, 34 logoff 21, 28, 35 logon 21, 36 o2db_sql_execute 25, 53 open 22, 41 operator << 51 operator >> 50 rollback 28, 43 server_error 31 L Libr ar y Defin it ion 18 logoff Function 21, 28, 35 logon Function 21 lu_name 69 M H H ost Con n ection 21, 58 Discon n ect 21, 28 Man agin g st at em en t s 23 max_statements 69 mode 69 host 69 N I network 69 In t er n al er r or codes 71 O J O2 Ar ch it ect u r e 10 J ava 11 O2 C 11 O2 Cor ba 11 O2 DBAccess User Man u al 79 INDEX o2db_Con n ect ion Class 18, 32 Creation 21 Functions 21, 32–37 o2db_O2DBAccess Class 18, 30 Functions 31 o2db_Session Class 18, 21–22, 38 Functions 38–43 R RDBM S Qu er yin g 66 r ollback Function 28, 43 o2db_sql_execu te Function 25, 53 o2db_St at em en t Class 18, 22, 44 Functions 44–54 O2DBACCESS 69 O 2 DBAccess 11 o2dbaccess Schema 18 o2dbaccess.cf 69 O 2 En gin e 10 O 2 Gr aph 11 O 2 Kit 11 O 2 Look 11 O 2 OD BC 11 O 2 Stor e 10 Over view 13 O 2 Tools 11 O 2 Web 11 open Function 22, 41 oper ator << Function 51 S ser ver _er r or Error codes 71 Function 23, 31 service 69 Session Close 22, 28 Open 22 Statem en t Close 22 Man agem en t 23 Maxim u m n u m ber 22 Open 22 Pr epar at ion 23 Ru n n in g 25 Syst em Ar ch it ect u r e 10 oper ator >> Function 50 OQL 11 P port 69 80 T Table Cr eat in g 61 Displayin g con t en t 64 Popu lat in g 62 type_checking 69 O2 DBAccess User Man u al