O2 DBAccess User Manual (O2C Interface)
Contents
1. O DB Access User Manual O C Interface Release 5 0 May 1998 Information in this document is subject to change without notice and should not be construed as a commitment by Oo 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 on magnetic tape disk or any other medium for any purpose other than the purchaser s own use Copyright 1992 1998 Os 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 O2 Technology O2 O2API OoC OoDBAccess OoEngine O2Graph Ookit OoLook O2Store Oo2Tools and 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 aregistered 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 Nixdorf A G NeXTStep is a registered trademark of the NeXT Compu2. printf error in log on d n log_status retcode return session log_status session status session gt rollback OsoDBAccess User Manual 45 Classes sqiquery method Summary Runs a statement and fetches the result if required Syntax receiver gt sqlquery result stmt params projection Arguments result iS a Parameter object specifying where the query result is stored or nil if not required stmt is a string of less than 4096 characters representing the SQL statement to be run params is a list of Parameter objects specifying the query parameters projection is a list of string specifying the projection attributes By default projection list the query result fully matches the Oo class type Description This method runs a statement and can fetch the result Only projection attributes are valued others get their Oo default values By default projection list the result totally matches the Oo class type Returns An integer of the number of fetched rows if successful O if there is no more data to fetch or a negative number representing an error code Example class Employees inherit Parameter type list tuple name string department integer salary real end class Integer inherit Parameter public type integer end class String inherit Parameter public type string end run body o2 o2 o2 o2 o2 o2 dept job Session integer status string stmt SELECT e
3. o2dbE NILREF 3024 Context define_projection Context define_bind Context exec Context fetch Session sqlquery The result object or a parameter is nil Check the method call syntax o2dbE NOMEM 3025 All Not enough memory Close some contexts OsDBAccess User Manual 67 Appendices 4001 Code o2dbE INTERNAL 4001 Call All Cause Internal error It should not normally be issued Action Contact OoLine 5001 Code o2dbW_NOT_UNIQUE 5001 Call Context fetch Session sqlquery Cause This a warning There is more than one row to fetch whereas the result type is not a collection Action Nothing Only the first row has been fetched 68 OoDBAccess User Manual INDEX OoDBAccess User Manual 69 INDEX A Application Example 54 61 Information transfer 25 Architecture Client server 13 Os 10 associate Example 58 Method 24 48 B Buffers Data 26 Definition 26 C C il C Interface 11 c name 62 Class 18 Connection 22 36 Context 47 O2DBAccess 34 Session 22 41 Client server architecture 13 close Example 61 Method 23 42 commit Method 30 43 54 Configuration File 62 connect Example 56 Method 22 37 Connection Class 18 36 Creation 22 56 Import 55 Methods 22 36 40 Context Class 18 23 47 Close 23 61 Import 33 Link to statement 24 Management 24 Maximum number 23 Methods 47 Open 23 57 D Data A
4. 1 You must firstly define the classes of objects where you want the data to be buffered These classes must be subclasses of the Parameter class You must then give the relevant transfer information This includes the objects in which the data is to be buffered and whether these objects define a parameter or the result object You do this by defining data buffers using the define_projection and define_bind methods described above These methods storethe transfer information in the context You can then run the statement using the exec method If you are transferring data from the database you must fetch it from the database to the designated result object using the fetch method This section now describes these steps in more detail OoDBAccess User Manual 25 Utilization Data buffers The data buffers are Oo objects the classes of which are user defined and must be inherited from the Parameter class Define the class type as follows Knowing that you can choose any collection types e For a parameter the class type must be atomic and match the scalar type of the associated parameter marker in the SQL statement e The result of a select statement is a relation A relation is a collection of tuples whose attributes have scalar types If the relation has only one attribute you can use a collection of atoms If you want to fetch data row by row or if the relation has only one row you can omit the collection and use
5. Should usually only be issued on a connect method call Action Check the link paramaters user name and password The connect failure reason is in lt network gt srv log file on the remote host 3001 Code o2dbE STILL_CONNECT 3001 Call Connection connect Cause You are still connected to a host Action The connect method was called but not the disconnect method 3002 Code o2dbE NOT CONNECT 3002 Call Connection logon Connection logoff Cause Not connected Action Check completion of the previous connect method call O 2DBAccess User Manual 63 4 Appendices e 3003 Code Call Cause Action e 3004 Code Call Cause Action e 3005 Code Call Cause Action e 3006 Code Call Cause Action e 3008 Code Call Cause Action o2dbE NOT MEMBER 3003 Connection logoff Session close The Session Context object has not been created by the receiver Check the method call syntax o2dbE_NOT_LOGON 3004 Session open Session close Session commit Session rollback Session sqlquery Not logged on Check completion of the previous logon method call o2dbE TOOLONG 3005 Connection logon Context associate The parameters are too long Decrease parameter length o2dbE_NOT_OPEN 3006 Context associate Context define_projection Context define bind Context exec Context fetch The context has not been opened Check the com
6. System Overview Programming Lanquages Oo objects may be created and managed using the following programming languages utilizing all the features available with Oo persistence collection management transaction management OQL queries etc e C e C e Java e OoC e OQL Oo functions can be invoked by C 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 Os objects and methods Oo Development Tools e OoGraph e OoLook e Ookit e OosTools 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 Oo database applications Standard Development Tools All standard programming languages can be used with standard environments e g Visual C Sun Sparcworks External Interfaces e OoCorba e OsDBAccess e O20DBC OoWeb Create an Oo Orbix server to access an Oo database with CORBA Connect Os applications to relational databases on remote hosts and invoke SQL statements Connec
7. 2 3 and Section 3 3 for further details OoDBAccess User Manual 57 Appendices Prepare the statement You must associate a statement by firstly associating it with the opened context using the associate method The statement is a select statement and has parameters You must therefore define and store in the context the result object and its projection list using the define_projection method in connection with the class Employees You define and store the parameters using the define_bind method in connection with the classes Integer and String ctxt open_status ctxt status ctxt gt associate stmt if status 0 printf error in associate d n status host gt disconnect return status ctxt gt define_projection res list name salary if status 0 printf error in define _projection d n status host gt disconnect return status ctxt gt define_bind job 2 if status 0 printf error in define _bind 2 d n status host gt disconnect return status ctxt gt define_bind dept 1 if status 0 printf error in define _bind 1 d n status host gt disconnect return Refer to Section 2 4 and Section 3 4 for full details 58 OoDBAccess User Manual Example Application Run the statement Run the statement All the relevant information has been given You can now run the statement using the exec method de
8. Once connected to the remote host and logged on to the database you must now open acontext for each SQL statement you want torun You do this using the open method from your Session object result of the logon method The context contains the statement itself and any additional information that may be needed to run the statement This method returns an object of class Context A Context object remains open until you explicitly close it using the close method of your Session object or until you end the database session using the Logoff method However you do not need to close a context in order to use it for a different statement You simply re use it For example run body o2 Connection host new Connection o2 Session session o2 Context contextl context2 host gt connect where username password session host gt logon db name db username password session contextl session gt open context statements session gt close contextl1 context2 session gt open context statements session gt close context2 host gt logoff session host gt disconnect Contexts and how to manage contexts are explained fully in Section 2 4 below and Section 3 3 gives a description of the open method Note The context is local to the logon session in which it is used and the number of contexts you can open at the same time is restricted to 100 However you rarely need more than 15 an
9. a tuple or an atom for a one attribute relation Note You can encapsulate collection elements and tuple attributes e Defining buffers You give the necessary information about the result object and the parameters using the define projection and define bind methods The define projection method has a projection mechanism with which you can define the result object You can declare a tuple type with more attributes in a different order and with different names than in the relation To do this you must give a link between the tuple attributes and the relation attributes This link is called the projection list and is made up of a list of attribute names where the ith member of the list obtains the value of the ith attribute of the relation The other tuple attributes get their default Oo values For example if you want to obtain data from the relation Relation A integer B char 1 C float D char 30 OoDBAccess User Manual Preparing a statement Transferring data You then want to store the result in an object of the Employees class which is defined as follows class Employees inherit Parameter type list tuple name string code integer entry_date Date mported from o2kit dept_id char salary real Once connected logged on and a context is opened you must create a new Employees object o2 Employees result_object new Employees Associate your statement to the op
10. all these classes and their respective methods It is divided into the following sections e O2DBAccess e Connection e Session e Context Oo2DBAccess User Manual 33 3 Classes 3 1 O DBAccess An o2dbaccess object defines the common resources of O2DBAccess classes It contains one method the server_error method with which you can obtain the RDBMS detected error codes 34 OoDBAccess User Manual O2DBAccess server_error method Summary Syntax Arguments Description Returns Example Gives the RDBMS detected error code receiver gt server_ error None You use this method to obtain RDBMS detected error codes The code and its description The type of the returned value is as follows tuple code integer msg string The code attribute contains the RDBMS detected error code and the msg attribute contains its textual description include o2dbaccess h o2 Context context o2 integer status o2 tuple code integer msg string error status context gt associate SELECT FROM emp if status O2DB OK if status o2dbE SERVER error host gt server_error printf Server Error d s n error code error msg O sDBAccess User Manual 35 3 Classes 3 2 Connection A Connection object defines and maintains a connection to a remote host The information needed to set up a link between the Oo application and the hos
11. fetch Session sqlquery The SQL statement is not a select statement Check the syntax of the SQL statement o2ZdbE_RANGE 3015 Context define bind The order number is out of range Check the order number o2ZdbE_ DEFINED 3016 Context define projection Context define_ bind The parameter or the result object is yet defined Check the order number o2dbE MISMATCH 3017 Context define projection Context define_ bind Session sqlquery Type checking failed Check the result or parameter type o2ZdbE_NOT_SUPPORTED 3018 Context define projection Context define_ bind Session sqlquery One of the atomic types used is not supported in the current version of OoDBAccess Check the type of result object OoDBAccess User Manual Possible Errors 3021 Code Call Cause Action 3022 Code Call Cause Action 3023 Code Call Cause Action 3024 Code Call Cause Action 3025 Code Call Cause Action o2dbE_INVALID_NAME 3021 Context define_ projection Session sqlquery One of the names is not an attribute name Check the list of attribute names o2dbE NOT EXECUTED 3022 Context fetch The statement hasn t been executed Check the completion of the previous exec method call o2dbE_NO_MORE_ CONTEXTS 3023 Context open Session sqlquery An attempt was made to exceed the maximum number open contexts allowed Close some contexts
12. host gt logon O2SCDEMO Connect o2tech identified by beaut if status retcode 0 printf error in log on d n status retcode return session status session O sDBAccess User Manual 39 Classes logoff method Summary Syntax Arguments Description Returns Example Ends a logon session receiver gt logof session session is a Session object that represents the session to close The logoff method ends a specified logon session and releases all its resources All contexts created during the session are closed Note that the receiver object of the Logoff method must be the same as the receiver object of the Logon method that originally created the Session object O if successfully logged off or an error code if not o2 Connection host new Connection o2 integer status o2 Session session status host gt logoff session if status 0 printf error in log off d n status return 40 OoDBAccess User Manual Session logoff method 3 3 Session A Session object defines and maintains the connection to a database server The Session class has the following methods close method commit method open method rollback method sqlquery method O oDBAccess User Manual 41 Classes close method Summary Syntax Arguments Description Returns Example Closes a context receiver gt clo
13. n open_status retcode return context open_status context status context gt associate stmt 48 OoDBAccess User Manual Context define_bind method define_bind method Summary Syntax Arguments Description Returns Example Stores the parameters in the context receiver gt define_bind param order param IS a Parameter object that will contain the value corresponding to a variable used in the SQL statement order is an integer specifying the position of this variable in the SQL statement Numbering begins at 1 The define_bind method declares a Parameter object that contains the current value corresponding to a variable used in the SQL statement The second parameter defines the position of this variable in the SQL statement If you use ORACLE you must call the marker n wheren is the position of the variable in the statement O if the method is successful or an error code if not class Employees inherit Parameter type list tuple name string department integer salary real end class Integer inherit Parameter public type integer end class String inherit Parameter public type string end run body o2 o2 o2 o2 o2 o2 Context context integer status string stmt SELECT ename esalary FROM emp WHERE deptno and job Employees res new Employees Integer dept new Integer String job new String status context gt associat
14. 5 R rollback Method 30 45 54 S Schema Definition 18 55 OoDBAccess User Manual INDEX server error Error codes 63 Method 24 35 service 62 Session Class 18 22 23 41 Close 23 31 61 Example 57 61 IMPOret 35 Methods 41 Open 23 57 sqilquery Method 46 Statement Link to context 24 Preparation 24 58 Running 29 59 System Architecture 10 Transferring data 25 type_checking 62 O oDBAccess User Manual 73 INDEX 74 O2DBAccess User Manual
15. Managing contexts When you want to run a select statement or a statement that contains parameter markers or both you need to provide more information before the statement is run The information needed includes the result object and its projection list which you storein the context using the define projection method of the class Context You also need to store any parameters in the context using the define bind method OoDBAccess User Manual Preparing a statement Transferring data You can manage your contexts in three different ways 1 Note Use one context for one specific SQL statement and close the context as soon as the statement has been run Open a context use it for one statement and then reuse for another statement by simply associating it to the new statement You can to do this as many times as you want until you want to close the context Open a context for a particular statement that you want to run several times You keep the context open and associated to the statement until you no long wish to rerun the statement While the context is open you can rerun the statement with new values for any of its parameters using the exec and fetch methods However you cannot redefine any objects using the define_projection or define_bind methods Re associating a context frees all defines Transferring data The transfer of data between the application and the database involves the following steps
16. at enable you to communicate and work with the remote database Parameter Figure 2 1 o2dbaccess schema The schema classes are as follows o2DBAccess An o2DBAccess object defines the common resources of O2DB Access classes It contains one method server_error which you use to obtain the RDBMS detected error codes Connection Connection is a subclass of o2dbaccess A Connection object defines and maintains a connection to a remote host Session Session is a subclass of o2dbaccess A Session object defines and maintains a connection to a database server It manages the transactions of the session Context Context is a subclass of o2dbaccess A Context object defines an access context to a database and contains information that is required to run an SQL statement Parameter Any classes used for the result object and parameters must bea subclass of the Parameter class 18 OoDBAccess User Manual The o2dbaccess schema Importing the schema Import the o2dbaccess schema using the Op import command import schema o2dbaccess class Parameter Connection Session Context This import command gives you access to any o2dbaccess Classes If you are using Oo Tools you see the class hierarchy shown in Figure 2 2 Figure 2 2 Imported OsDBAccess classes You can also import the O2DBAccess class if you are going to use generic error messages Figure 2 3 Import O2DBAc
17. ccecececeesesseseeeeeeeeeees a2 ee EE T 23 2 4 Preparing a StateMen cccccescsesscsesssseeeeeseonseseeseeneaseonseeeens 24 Linking statement and context 2 0 eeeeceeececececeeneseseeceeeceeeeeenees 24 Mnao CONES sarn 24 Pn a pE fie 2 5 Run statement and fetching Cata ccssccessceseeesseeeseeeeees 29 2 6 Commit and ke y e Coen ee 30 27 ENGNG a 0 9 eee eee ener een en enna eden Senn ener ene 31 Classes 33 i SDE ALCEE E oe Seee enn eeee pee eereeee eee nerrs 34 server_error method ssssssseserssesesssosssesesossrssssosesesessosssosssososos 35 TE 1 184 2 ice 36 o a E EN renee 37 TERS 6 1101S WHE O c JL erar E Ea h 38 Certo 6 e a RAITEEN EE AAT ETNIESE EA AAA TEE ETATE TTEA TETY J9 OoDBAccess User Manual TABLE OF CONTENTS Be I ee cieslivee cs er ee eet eee 40 EKE e p P E EN E E E EE E E EE A ET 41 close MEDO eusir AiE 42 commit method cccccecccsecscccceccscscoccecsececsccececssceccsceseaseces 43 Bo E EE E E 44 rollback method s sessssssesesssssesessssesesassccscsssrosososessesasssessssseeseso 45 salonon I saa EEEE 46 e LONON ar 47 associate method sssssssssrssesesareecsssseresososessesenssescsssresososeessses 48 define bind method sessssssrrssssssssssssesesosssessssssseseresesesesssssesssssss 49 define_projection method esesessoeeeresssssseseeresssssssseeressssssess 50 exec method sseessssre
18. ccess 22 Buffers 26 Fetching 29 60 Transfer 25 Database Access 22 23 Information transfer 25 Log off 22 61 Log on 22 56 define bind Example 58 Method 24 27 49 define projection Example 58 Method 24 26 50 OoDBAccess User Manual INDEX disconnect Example 61 Method 22 31 38 E Environment variable 62 Error codes 24 63 68 Example application 54 61 exec Example 59 Method 29 51 F fetch Example 60 Method 29 52 File Configuration 62 H Host Connection 22 56 Disconnect 22 31 61 host 62 import schema 55 Internal error codes 63 Java 11 logoff Example 6l Method 22 31 40 logon Example 56 Method 22 39 lu_ name 62 M Managing contexts 24 max contexts 62 OsoDBAccess User Manual 71 INDEX Method 21 associate 24 48 close 23 42 commit 30 43 connect 22 37 define bind 24 27 49 define projection 24 26 50 disconnect 272 31 38 exec 29 51 fetch 29 52 logoff 22 31 40 logon 22 39 open 23 44 rollback 30 45 server _error 35 sqlquery 46 mode 62 N network 62 O O2 Architecture 10 OC 11 O Corba 11 O2DBACCESS 62 O2DBAccess Class 18 34 Methods 35 O DBAccess 11 o2dbaccess Schema 18 55 o2dbaccess cf 62 OoEngine 10 12 OeGraph 11 Ookit 11 OoLook 11 O2ODBC 11 O Store 10 Overview 13 OsTools 11 OoWeb 11 open Example 57 Method 23 44 OQL 11 P Parameter Buffers 26 Class 18 26 Import 53 Subclass 5
19. cess class Note For fuller details of these classe and their methods refer to Chapter 3 OsoDBAccess User Manual 19 2 Utilization 2 2 Guidelines To send an SQL statement for processing on remote database you need to carry out the following steps 1 2 8 9 Set up a connection to the host server machine Set up a session on the database by logging on Open an access context for the statement Prepare the statement to be run This means putting information about the statement in the context Run the statement Ifthe statement is a select statement fetch the data from the database to your application into an Oo object If information has been inserted updated or deleted make the changes permanent or undo them If you do not want to rerun the statement close the context Close the session by logging off the database 10 End the connection by disconnecting from the host 20 OoDBAccess User Manual Guidelines Each step corresponds to a particular method Table 2 1 shows these methods and its corresponding step The class of the method is given after the method name These methods constitute the basic set of methods that you need to use Table 2 1 Method set associate Context define projection Context Prepare a statement define bind Context Fetch data from the database All these various steps are detailed below For a description of each specific metho
20. connection All the your transactions with database are finished The method logoff ends the session and the method disconnect ends the connection wth the host status host gt logoff sess if status 0 printf error in log off d n status host gt disconnect return host gt disconnect Refer to Section 2 7 and Section 3 2 for more details O oDBAccess User Manual 61 4 Appendices 4 2 Configuration File The configuration file o2dbaccess cf contains the information needed to link up your Oo application and a remote host in the form of a set of network and host specific parameters You can change the file name by specifying a new name and its path in the environment variable O2DBACCESS This variable must contain the full path of the file In order of priority the file is first taken from the working directory then SHOME and then the Oo installation directory It is an ASCII file where each line corresponds to a named link description It contains one entry for each named link with comments beginning with Theline format is c_name network host service lu_name mode max_contexts type_checking Each field is described below Cc name network host service lu_name mode max contexts type_checking Warning Link name Specify a link name each time you invoke the connect method Type of network protocol used Possible values TCP MacTCP on Macin
21. d refer to Chapter 3 Note Steps 3 to 8 can be reduced using the method sqlquery of the class Session See Section 3 3 for more details OoDBAccess User Manual 21 2 Utilization 3 Accessing a database You must first connect to the remote host and log onto the database Host connection and database log in With OsDBAccess you do this by creating a Connection object You must call the connect method on this object to connect to the remote host You then call the logon method on this object to log onto the database and begin a session The logon method returns a Session object Once connected and logged on you can run as many SQL statements as you want For example run body o2 Connection host new Connection Create the object o2 Session session Connection to the host defined by where host gt connect where username password Log on the database defined by db name session host gt logon db name db username password session Some transactions host gt logoff session End session host gt disconnect Disconnect from the host When your transactions with the database are finished you use the logoff and disconnect methods to respectively end the session and remote host connection Refer to Section 3 2 for a full description of all these Connection methods 22 OoDBAccess User Manual Accessing a database Open Context Open Context
22. d the external database or yourself can impose a lower limit OoDBAccess User Manual 23 2 Utilization 2 4 Preparing a statement The next step after accessing the database is to prepare the SQL statements you want to run Linking statement and context You must firstly link the statement to its context using the associate method of the Context class This method associates the statement to the opened context in order to pass information about the statement to the database server The information in the context can be used for a type checking on the client side The associate also sends the statement to the RDBMS database for validation It is at this point that any SQL syntax errors are trapped If any are found you can get the database error codes by calling the server_error method on the Context object see Section 3 1 for details of this method and Section 4 3 for a list of possible errors Finally the associate method stores the statement in the context If the SQL statement does not need a result object i e it is not a select statement and it contains no parameter markers Oo2DBAccess needs no more information You can therefore immediately run your statement using the exec method See Section 2 5 for more details However if the statement a select statement and or it contains parameter markers you must provide OoDBAccess with more information This is explained in the remainder of this section
23. e stmt status context gt define projection res list name salary status context gt define_bind job 2 status context gt define_bind dept 1 O DBAccess User Manual 49 Classes define_projection method Summary Syntax Arguments Description Returns Example clas Stores the result object in the context receiver gt define_ projection result projection result iS a Parameter object specifying where the result of the query will be stored The parameter must be not nil projection isa list of strings specifying the projection attributes By default projection list the query result matches the Oo class type The define projection method stores the result object in the context The query result is assigned to the value of the result object Only projection attributes are valued others get their Oo default values By default projection list the query result matches the Oo class type O if the method is successful or an error code if not s Employees inherit Parameter type list tuple name string department integer salary end run o2 o2 o2 o2 o2 o2 body Session session Context context integer status tuple retcode integer context Context open_status string stmt SELECT ename esalary FROM emp WHERE deptno 80 Employees res new Employees open_status session gt open if open_status retcode 0
24. ened context context gt associate SELECT A B C D FROM Relation Define the result object using the define _ projection method the entry date attribute is not be valued context gt define_projection result_object list code dept_id salary name The define_bind method declares an object that will contain the value of a variable used in the SQL statement A second parameter defines the position of this variable in the SQL statement Note With ORACLE the variable markers must be called 1 2 etc For example you want to update the C attribute where the B attribute is C and T in the following relation Relation A integer B char 1 C float D char 30 For this you define the Char class as follows class Char inherit Parameter public type char end Once connected logged on and a context is opened you must create a new Char object o2 Char parameter new Char OoDBAccess User Manual 27 Utilization Associate your statement to the opened context context gt associate UPDATE Relation SET C C 1 1 WHERE B Define the result object using the define_bind method context gt define_bind parameter 1 Fix the parameter value and run the statement parameter C context gt exec You can rerun the statement with another value parameter T context gt exec 28 OoDBAccess User Manual Run statement and f
25. ess User Manual 13 1 Introduction O DB Access O oDBAccess is a set of Oo classes that enables Oo applications to communicate and work with relational databases on remote hosts These classes allow you to carry out the following actions from your applications e Connect to a server and set up a session on a remote database e Run any SQL statement in the SQL syntax of that database e Fetch data as required from the database to the user application into Oo objects e Mirror the commit and rollback facilities of some databases e Close the database session and terminate the connection to the host You can also retrieve error message text corresponding to database error codes O2DBAccess is based on the SequeLink protocol as shown in Figure 1 4 This is a software package that enables a client application to access simultaneously different relational databases residing on different servers that are connected to one or more types of local networks SequeLink uniformly manages the different network protocols and the heterogeneity between platforms With O2DBAccess you can link to any platform currently supported for SequeLink 1 For information about all possible network host database combinations call O Line OoDBAccess User Manual System Overview oops Access CLIENT SERVER Relational O DBAccess DBMS Interface module database A Kernel i A Interface module network pro
26. etching data 2 5 Run statement and fetching data If the SQL statement does not need a result object i e it is not a select statement and it contains no parameter markers you can run your statement using the exec method If the statement is a select and or it contains parameter markers you must provide the relevant transfer information as detailed above in Section 2 4 and then transfer the data using the fetch method For example suppose you set up a single connection a single session in which you want torun three SQL statements a create statement an insert statement containing three parameters which you want run twice and a select statement You call the following sequence of methods in order to process each step run body o2 Connection host new Connection o2 Session session o2 Context contextl context2 context3 host gt connect where username password session host gt logon db name db username password session contextl session gt open context contextl1l gt associate CREATE context1 gt exec session gt close contextl context2 session gt open context context2 gt associate INSERT context2 gt define bind context2 gt define bind context2 gt define bind context2 gt exec context2 gt exec session gt commit session gt close context2 context3 gt associate SELECT context3 gt define_ projection contex
27. g_status session status session gt commit OsoDBAccess User Manual 43 Classes open method Summary Syntax Arguments Description Returns Example Creates a new context receiver gt open None The open method creates a new access context for the receiver by creating an object of class Context An object defining the new context or an error code if something went wrong The type of returned value is tuple retcode integer context Context o2 Session session o2 Context context o2 integer status o2 tuple retcode integer context Context open_status open_status session gt open if open_status retcode 0 printf error in open d n open_status retcode return context open_status context 44 OoDBAccess User Manual Session rollback method rollback method Summary Syntax Arguments Description Returns Example Reverses all modifications since last commit receiver gt rollback None The rollback method rollbacks any modifications you have carried out in this session since last commit O if the method is successful or an error code if not Connection host new Connection Session session integer status tuple retcode integer session Session log_status log on SUPRA Server log_status host gt logon O2SCDEMO connect o2tech identified by beaut if log_status retcode 0
28. host and log onto the database you must create a Connection object You must then call the connect and logon methods on this object run body o2 Connection host new Connection o2 Session sess o2 Context ctxt o2 tuple retcode integer sess Session log_status o2 tuple retcode integer ctxt Context open_status o2 integer status o2 string stmt SELECT ename esalary FROM emp WHERE deptno and job o2 Employees res new Employees o2 Integer dept new Integer o2 String job new String status host gt connect Supra_server scott TIGER if status 0 printf error in connection d n status return log on SUPRA Server log_status host gt logon O2SCDEMO connect o2tech identified by beaut if log_status retcode 0 printf error in log on d n log_status retcode host gt disconnect return Refer to Section 2 3 and Section 3 2 for more details 56 OoDBAccess User Manual Example Application Open a context Open a context You open acontext for each statement using the open method of the Session object This object contains the statement and other information needed for running the statement sess log_status sess open _status sess gt open if open_status retcode 0 printf error in open d n open_status retcode host gt disconnect Close all sessions and disconnect Refer to Section
29. name esalary FROM emp 80 tailor session WHERE deptno and job Employees res new Employees Integer dept new Integer String job new String status session gt sqlquery res stmt list dept job list name salary res gt display 46 OoDBAccess User Manual Context sqiquery method 3 4 Context A Context object defines an access context to a database and contains information that is required to execute an SQL statement The Context class has the following methods e associate method e define bind method e define _ projection method e exec method e fetch method OsoDBAccess User Manual 47 Classes associate method Summary Syntax Arguments Description Returns Example Associates a statement with an opened context receiver gt associate stmt stmt is a string of less than 4096 characters representing the SQL statement to execute The associate method associates an SQL statement to the context receiver You can reuse a context for a new query but the previous association is then lost 0 if the method is successful or an error code if not Session session Context context integer status tuple retcode integer context Context open_status string stmt SELECT ename esalary FROM emp WHERE deptno 80 open_status session gt open if open_status retcode 0 printf error in open d
30. pletion of the previous open method call o2dbE_NOSTMT 3008 Context associate Session sqlquery The SQL statement is empty Check the method call syntax 64 O2DBAccess User Manual Possible Errors 3009 Code Call Cause Action 3010 Code Call Cause Action 3011 Code Call Cause Action 3012 Code Call Cause Action 3013 Code Call Cause Action o2dbE FILE NOTFOUND 3009 Connection connect The configuration file was not found Check that the configuration file exists o2dbE_RC_ NOTFOUND 3010 Connection connect No description of the link parameters for this link name Check configuration file contents and the method call syntax o2dbE INVALID RC 3011 Connection connect Invalid line in the configuration file Check the configuration file contents o2dbE UNKN NETWORK 3012 Connection connect Unknown network protocol Check configuration file contents o2dbE OPEN FILE 3013 Connection connect The configuration file cannot be opened Check that the configuration file exists and check its access rights O sDBAccess User Manual 65 Appendices 3014 Code Call Cause Action 3015 Code Call Cause Action 3016 Code Call Cause Action 3017 Code Call Cause Action 3018 Code Call Cause Action o2dbE_NOT_SELECT 3014 Context define projection Context
31. printf error in open d n open_status retcode return context open_status context st atus context gt associate stmt 50 OoDBAccess User Manual Context exec method exec method Summary Runs the query Syntax receiver gt exec Arguments None Description The exec method binds the current values defined as input to the SQL statement and runs the query Returns O if the method is successful or an error code if not Example class Employees type list tuple name string department integer salary real end class Integer public type integer end class String public type string end run body o2 Context context o2 integer status o2 string stmt SELECT ename esalary FROM emp WHERE deptno and job o2 Employees res new Employees o2 Integer dept new Integer o2 String job new String status context gt associate stmt status context gt define_projection res list name salary status context gt define_bind job 2 status context gt define_bind dept 1 now we can run the query dept 80 jJob tailor status context gt exec OsoDBAccess User Manual 51 3 Classes fetch method Summary Fetches the results Syntax receiver gt fetch row_count Arguments row_count is an integer The maximum number of rows to fetch You can specify 0 O2DB_ALL in order to fetch as many row
32. pt 80 jJob tailor status ctxt gt exec if status 0 printf error in exec 1 d n status host gt disconnect return Refer to Section 2 5 and Section 3 4 for further details of this method O oDBAccess User Manual 39 4 Appendices Fetch the data As the statement is a select statement you can transfer data from database to your application into an Oo object using the fetch method status ctxt gt fetch O2DB ALL if status lt 0 printf error in fetch 1 d n status host gt disconnect return else printf d fetched rows n status res gt display job grocer status ctxt gt exec if status 0 printf error in exec 2 d n status host gt disconnect return status ctxt gt fetch 10 if status lt 0 printf error in fetch 2 d n status host gt disconnect return else printf d fetched rows n status res gt display Refer to Section 2 5 and Section 3 4 for more details OoDBAccess User Manual Example Application Close the context Close the context As the statement is not re run you can now close the context using the close method of the Session object status sess gt close ctxt if status 0 printf error in close d n status host gt disconnect return Refer to Section 2 7 and Section 3 3 Close database session and end host
33. rs Oo2DBAccess User Manual 53 4 Appendices 4 1 Example Application This example illustrates the various steps you must go through in order to use OoDBAccess in order to send an SQL statement for processing on a remote database This section enables you to follow all these various steps and Is divided up into the following sections e Define the schema Host connection and database log on e Open a context e Prepare the statement e Run the statement e Close the context e Fetch the data e Close database session and end host connection Note Commit or rollback any changes made the commit and rollback methods depend on the database you are using are therefore not illustrated in this example 54 OoDBAccess User Manual Example Application Define the schema Define the schema You begin by importing the o2dbaccess schema You then must define all the various classes Employees Integer and String in which the result of your SQL statement and the query parameters are stored import schema o2dbaccess class Parameter Connection Session Context class Employees inherit Parameter type list tuple name string department integer salary real end class Integer inherit Parameter public type integer end class String inherit Parameter public type string end O 2DBAccess User Manual 55 4 Appendices Host connection and database log on To connect to the
34. s as possible Description The fetch method fetches the results into the result object Returns An integer of the number of rows that were actually fetched When no more rows can be fetched it returns 0 If the fetch is unsuccessful it returns an error code a negative number With o2dbW_NOT_UNIQUE only the first row is stored in the result object Example class Employees inherit Parameter type list tuple name string department integer salary real end class Integer inherit Parameter public type integer end class String inherit Parameter public type string end run body include o2dbaccess h o2 Context context o2 integer status o2 string stmt SELECT ename esalary FROM emp WHERE deptno and job o2 Employees res new Employees o2 Integer dept new Integer o2 String job new String status context gt associate stmt status context gt define_projection res list name salary status status context gt define_bind dept 1 context gt define_bind job 2 a eee now you can run the query dept 80 job tailor status context gt exec status context gt fetch O2DB ALL res gt display jJob grocer status context gt exec status context gt fetch 10 res gt display OoDBAccess User Manual Appendices This chapter contains the following appendices e Example Application e Configuration File e Possible Erro
35. se context context is a Context object that represents the context to close The context must have been created by the receiver The close method closes a context and releases all its resources Note that the receiver object of the close method must be the same as the receiver object of the open method that originally created the Context object 0 if the method is successful or an error code if not o2 Session session o2 Context context o2 integer status o2 tuple retcode integer context Context open_status open_status session gt open if open_status retcode 0 printf error in open d n open_status retcode return context open_status context status session gt close context 42 OoDBAccess User Manual Session commit method commit method Summary Commits modifications Syntax receiver gt commit Arguments None Description The commit method commits what has been done in the session since last commit or start of the session Returns O if the method is successful or an error code if not Example Connection host new Connection Session session integer status tuple retcode integer session Session log_status log on SUPRA Server log_status host gt logon O2SCDEMO Connect o2tech identified by beaut if log_status retcode 0 printf error in log on d n log_status retcode return session lo
36. sesesssessssassrosesssessasasssessessresosesrssasesasescsss 51 lee in ia t PAENT 52 Appendices 53 4 1 Example Application sasnannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn 54 Define the schema c secscocceccscccoccescecscsccececscecscecccneces 55 Host connection and database log OM essssssoseesesssssssseeresssssses 56 Eoo ca RTTE EEI ELETA AAEE TE EEEIEE ET a7 Pe Fe eserves 58 Run the statement ccsccsccccecsscecscceseccscsscecscscecsececeeseces 59 Fetch the AG sienna sonra kacdicekacecscucheaseceveticdusancavsdotevatsesesasiesesetadiees 60 Close the context c ccccsccscecoececescscsccscescncecoscecescscececeseaceces 61 Close database session and end host connection ccceceeee 61 4 2 Configuration File cccccsesscccsesseccsenseecenseeseensseeeesseseeeass 62 tS FOSSIDIO al 9 fo fe E eee eee esa 63 INDEX 69 OsoDBAccess User Manual 7 TABLE OF CONTENTS OoDBAccess User Manual Introduction Congratulations You are now a user of O2DBAccess O2DBAccess is the Op module that enables you to communicate and work with relational databases on remote hosts This chapter introduces the Os system and O2DBAccess and outlines its various features and advantages An overview of this User Manual is then given OoDBAccess User Manual 9 1 Introduction 1 1 System Overview The system arch itect
37. t remote ODBC client applications to Oo databases Create an Oso World Wide Web server to access an Oo database through the internet network OsoDBAccess User Manual 11 1 Introduction O Engine OoEngine has all the features of a database engine providing transparent management of data persistence data sharing and data reliability as well as all the features of an object oriented system including the manipulation of complex objects with identity classes types methods multiple inheritance overriding and late binding of methods ERVER g OA aS ces lt i Figure 1 2 Client server architecture 12 OoDBAccess User Manual System Overview 09 store O Store The O2Store physical storage management system offers you the following features e Transactional management of persistent structures e Client server architecture e Rollbacks and crash recovery OoStore has the client server architecture shown in Figure 1 2 The server process provides persistence disk management concurrency control data recovery and database security The features offered by O2Engine and OoStore are shown in Figure 1 3 below peewee Schema Manager Global Transaction Manager Object Manager Global Log Local Transaction Manager Manager Page Buffer Page Buffer Client Process Server Process Figure 1 3 Global architecture showing OoStore layer OsoDBAcc
38. t system is found in a configuration file It is made up of a set of network and host specific parameters Refer to Section 4 2 for a full description of the configuration file This section now describes the methods associated to the Connection class e connect method e disconnect method e logon method e logoff method 36 OoDBAccess User Manual Connection connect method connect method Summary Syntax Arguments Description Returns Example Connects to a remote host receiver gt connect c_name username password C_name is a string that defines the link parameters used in the configuration file username is a string specifying the host user name password is a string specifying the host user password The connect method sets up a link between the workstation anda remote SequeLink server 0 if the connection is successful or an error code if not o2 Connection host new Connection o2 integer status supra_server TCP salome LSPSUPRA2 15 false This is the corresponding resource line in the configuration file status host gt connect Supra_server scott TIGER if status 0 printf error in connection d n status return OoDBAccess User Manual 37 Classes disconnect method Summary Syntax Arguments Disconnects the remote host receiver gt disconnect None Description The disconnect method disconnects the link between the
39. t3 gt exec context3 gt fetch session gt close context3 host gt logoff session host gt disconnect OoDBAccess User Manual 29 2 Utilization 2 6 Commit and rollback The commit and rollback methods mirror a feature of some databases in allowing you to systematically and explicitly make permanent or unroll a series of related database actions at strategic points in a session 30 OoDBAccess User Manual Ending a session Transferring data 2 Ending a session When all your transactions with the database are complete the methods logoff and disconnect end the session and connection respectively close the context etc run body o2 Connection host new Connection o2 Session session o2 Context contextl context2 host gt connect where username password session host gt logon db name db username password session contextl session gt open context statements session gt close contextl1 context2 session gt open context statements session gt close context2 host gt logoff session host gt disconnect O sDBAccess User Manual 31 2 Utilization 32 O2DBAccess User Manual Classes CLASS SET AND THEIR METHODS OoDBAccess is a set of Oo classes that enables Oo applications to communicate and work with relational databases on remote hosts This chapter details
40. ter 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 describes how to use OoDBAccess This Ob module enables to connect Oo applications to relational databases on remote hosts and to import and export data from and to such systems OsDBAccess provides class libraries OoC and C for these tasks The manual also describes how to invoke SQL statements from Obs An example program is presented Other documents available are outlined click below See O2 Documentation set P Technology TABLE OF CONTENTS This manual is divided into the following chapters e e ee gt O N Introduction Utilization Classes Appendices O gt DBAccess User Manual TABLE OF CONTENTS Introduction 9 gg ee 2 C OVerviCW secite e e e e eeeeree 10 Oe ages as eases tances dees eset E nese 12 BA o t PEITIEN IEE ON AT 13 CVAD A 2 E E A ENA 14 Le Manual O31 lt 1 sacon 16 Utilization 17 2 1 The o2dbaccess SCHEMA 22 cceccceensneeeeeeeeneneeeeeeeeeenaeeeeeees 18 a E E E eae 18 POTTS me Che eE 19 EE S E aa 20 2 3 Accessing a databasSe sssnssnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn n 22 Host connection and database log 11 ccec
41. tocol Odd Eee PS Tee ad Client Kernel Interface module network protocol Standard Network Protocol reli 0 Oy Gere er cee eee are Figure 1 4 OoDBAccess and SequeLink O sDBAccess User Manual a Introduction 1 2 Manual Overview This manual is divided up into the following chapters Chapter 1 Introduction A short introduction to the O2 system O2Engine O2Store and OsDBAccess Chapter 2 Utilization This chapter describes how to use OoDBAccess accessing a database preparing a statement fetching data commit and rollback and running the statement Chapter 3 Classes This chapter details all the various classes and methods of the OsoDBAccess schema o2DBAccess Connection Session and Context Chapter 4 Appendices This chapter includes an example program It gives possible error codes and the configuration file OoDBAccess User Manual P Utilization This chapter details how to use O2DBAccess It is divided into the following chapters The o2dbaccess schema Guidelines Accessing a database Preparing a statement Run statement and fetching data Commit and rollback Ending a session Oo2DBAccess User Manual 17 2 Utilization 2 1 The o2dbaccess schema Classes OoDBAccess is in fact a standard Os schema called o2dbaccess that you can usein any of your user defined schemas The o2dbaccess schema shown in Figure 2 1 has classes th
42. tosh ADSP APPC DECnet NetBIOS and AppleTalk RDBMS remote host node zone name SequeLink database service name that you want to connect to You can find this name in the servermap file on the remote host See SequeLink manual Physical LU Name in APPC network protocol optional APPC mode in APPC network protocol optional Integer from O to 100 specifying maximum number of contexts that can be opened at the same time duringa session If 0 the default value 15 is used Boolean specifying whether to enable true or disable false type checking in the define_projection and define bind methods Default value is false The type checking is not supported for all RDBMS call OoLine for more details An example configuration 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 62 OoDBAccess User Manual Possible Errors 4 3 Possible Errors Each method returns an internal error code This section describes these error codes You can obtain RDBMS detected error codes using the server_error method See Section 3 1 for a description of this method 1001 Code o2dbE SERVER 1001 Call All Cause RDBMS detected error has occurred Action Consult error code and message text calling the server error method 2001 Code o2dbE SQOLNK 2001 Call All Cause A SequeLink error has occurred
43. ure of Oo is illustrated in Figure 1 1 Development Tools External O Dev Tools BELELO CIE e E Interfaces Standard Dev Tools O Corba ODB O Engine Access O Store O2Web Figure 1 1 O2 System Architecture The Oo 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 Os development tools and any standard development tool Numerous External Interfaces are provided All encompassing Oo is a versatile portable distributed high performance dyn amic object oriented database system Database Engine e QOoStore e OoEngine The database management system provides low level facilities through OoStore API to access and managea database disk volumes files records indices and transactions The object database engine provides direct control of schemas classes objects and transactions through OoEngine API It provides full text indexing and search capabilities with OoSearch and spatial indexing and retrieval capabilities with OoSpatial It includes a Notification manager for informing other clients connected to the same Oo 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 10 OoDBAccess User Manual
44. workstation Returns Example and the remote SequeLink server All the current sessions of this connection are closed Nothing o2 Connection host new Connection o2 integer status supra_server TCP salome LSPSUPRA2 15 false This is the corresponding resource line in the configuration file status host gt connect Supra_server scott TIGER if status 0 printf error in connection d n status return host gt disconnect 38 OoDBAccess User Manual Connection logon method logon method Summary Logs onto the database Syntax receiver gt logon logonl logon2 Arguments logoni logon2 are strings that specify the parameters required in order to log onto the database you are using Refer to the documentation Using SequeLink with your Database and server for the specific logon parameters needed for the database you want to use The parameter length must be less than 256 characters Description The Logon method passes both the logonl1 and logon2 parameters to the database server It then starts a new session by creating man object of class Session Returns An object defining a link with the database or an error code if something goes wrong The type of returned value is tuple retcode integer session Session Example o2 Connection host new Connection o2 tuple retcode integer session Session status o2 Session session log on SUPRA Server status
Download Pdf Manuals
Related Search