libgda"> GNOME-DB"> API"> DBMS"> DSN"> ODBC"> GDA"> LDAP"> CORBA"> IDL"> ORB"> SQL"> RPM"> XML"> PostgreSQL"> MySQL"> Oracle"> Interbase"> Sybase"> MS Access"> Informix"> ]> Michael Lausch

michael.lausch@1012surf.net

Rodrigo Moya

rodrigo@gnome-db.org

Vivien Malerba

malerba@linuxave.net

Sean Allen

zeroone@worldonline.co.za

GDP compliancy, FDL, added markup, English and syntax 1999 February 1999-2001 The Free Software Foundation GNU Data Access (&GDA;) is an architecture whose purpose is to provide universal access to many different kinds and types of data sources. This goes from traditional relational database systems, to any imaginable kind of data source such as a mail server, a &LDAP; directory... This universality is obtained through the use of &CORBA; as the mechanism for communication between the different components in the architecture. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found in . Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps. &ODBC; and &SQL; are established standards. The problem is, that &ODBC; doesn't specify the wire protocol and for some databases no &ODBC; driver exists. You might use RPC, TCP/IP, or shared memory and signals to pass the request from the client to the server. So you have to use the database specific &ODBC; library. This library might not be available for the CPU or operating system on which the client is running. &SQL; itself is also not standardized enough, so that source compatibility can not be assured for all database servers. And for some sort of servers, &SQL; is not even feasable (think about &LDAP;). &GDA; tries to tackle the &ODBC; problem and help you with the &SQL; problem. It's a sort of middleware (or can be blown up to be a middleware layer) to access different data sources. It offers a high level view of data sources and has some places where you can plug in low level access to the database for special tasks. GNU Data Access (&GDA;) is defined as a set of &CORBA; &IDL; interfaces. The level of abstraction provided by &GDA; makes it possible to access any kind of data source, provided that a &CORBA; server implementing those &IDL; interfaces and accessing this particular data source is written. &LIBGDA; is an implementation of the &GDA; &CORBA; interfaces, using ORBit as the &CORBA; implementation. So, in theory, it would be possible to implement &LIBGDA; for another &CORBA; &ORB; or operating system, provided that &CORBA; support is present on that system. It offers a wrapper around the &CORBA; internals, thus making it easier for programmers to make use of all the power provided by &CORBA; without even knowing about it. It comes along with several libraries, for both clients and servers, as a C implementation of this wrapper. This level of abstraction would make possible to, at a later time, change all the internals without having to modify applications using the libraries, as well as, most importantly, keeps application developers away from the continous changes in the different &CORBA;-related &API;s being used, such as OAF, GConf... Along with these libraries (and associated header files and language bindings for development), &LIBGDA; includes several tools and utilities to help you with the task of developing applications based on &LIBGDA;, as well as for automating some database-related tasks. &LIBGDA; is implemented for UNIX -like operating systems (including Linux), and does not depend on other libraries apart from ORBit, GConf, OAF and Glib, which makes it a very lightweight system also ideal for applications to be run on hardware-limited systems. It was once part of the &GNOMEDB; project, and is still used as the basis for it, but it's been separated from it to remove all GNOME dependencies and thus allow non-GNOME applications to be developed based on it. &LIBGDA; is composed of three independant layers. The lower level is covered by the &GDA; providers, which are &CORBA; servers whose task is to map the RDBMS-specific &API; to the &GDA; model. That is, they are &CORBA; objects implementing the &GDA; &CORBA; interfaces. Then, in a midlle layer, are the client libraries: a &CORBA; client library, which hides all the &CORBA; complexity to client applications, also including several utility functions to help you on the development of applications based on &GDA;. Finally, at the upper level sit all the client applications provided in the suite, as well as any application that may make use of the client libraries. &LIBGDA; is &CORBA; based and uses ORBit as the &CORBA; implementation. Basically the system provides an &IDL; file as the interface to the client. For every different data source type (&ODBC;,&SYBASE;, &INFOR;, &MYSQL;, &LDAP;, ...) a server must be written. This server ideally is a shared library which is linked with a small driver program to form a standalone &CORBA; server. The shared driver approach makes it possible to use the server as a library for the client, reducing round trip time (no sockets and context switches required). The advantage of using a &CORBA; server is, that the server may run on another machine, balancing the load. This is possible because ORBit is small and fast. You can use the same server from a &CORBA; aware scripting language and you might do tracing and transaction control in the server, without needing to change the client. The drawback is that if such a provider crashes all the clients are disconnected from the database. To overcome this problem it is possible for each client to request a new copy of the provider (although the client &API; doesn't yet provide this flag). The other type of providers are shared library providers. These providers are linked to the client when the client requests something from the provider. The disadvantage is that the server is hosted on the same machine as the client. But a server crash only affects one client. The startup cost is comparable to an executable provider. The big advantage of this sort of providers is that debugging the provider code is simpler, since you must not attach &GDA; to a running provider and you also can catch errors during server initialization. Per default every &GDA; provider is available as an executable and as a shared library. The build process and the conventions used to implement the provider make sure that the executable and the shared library are made and installed. Thus, &GDA; providers are implemented in shared libraries, which are then linked with a small program which just acts as a driver for the shared library. On our web site, RedHat and Debian packages are available, so you shouldn't have any problem installing it. For a standard installation, there is are no further steps, but, you'd better know all the &CORBA; and &GDA; configuration options, just in case you come across a non-standard installation, or in case of problems during a standard installation. Installation depends on which format you choose to download. If you've got a package such as &RPM; or DEB, check your package manager documentation for how to install new packages. If you downloaded the source code (in a tarball), you must compile the software. For doing so, once you have unpacked the source tree, you must: $./configure $make $make install This will generate the makefiles for your specific platform, compile all the source tree, and install the binaries and documentation in your system. If you don't find a file named configure, there should be one called autogen.sh. In this case, run autogen.sh, which will create and run the generated configure file. You can specify several arguments to configure (or autogen.sh). The most significant are (you can check all the available arguments by running configure --help): --prefix=<directory>: Prefix where package will be installed --with-mysql=<directory>: Specify directory where &MYSQL; libraries are installed --with-postgres=<directory>: Specify directory where &PGSQL; libraries are installed --with-sybase=<directory>: Specify directory where &SYBASE; libraries are installed --with-ldap=<directory>: Specify directory where &LDAP; libraries are installed --with-oracle=<directory>: Specify directory where &ORAC; libraries are installed --with-interbase=<directory>: Specify directory where &INTERB; libraries are installed --with-mdb=<directory>: Specify directory where the MDB libraries (for accessing &MSACC; files) are installed Providers are not installed by default, so you must specifically add those arguments when running configure. If you find any problem during the configuration, compilation or installation process, do not hesitate in contacting the &GNOMEDB; mailing list (gnome-db-list@gnome.org, first send an email to gnome-db-list-request@gnome.org with the subject SUBSCRIBE, if you are not already subscribed). Depending on the use you're going to get out of &LIBGDA;, you may have to dig deep into its internals, but don't be afraid, things have been implemented to be easy to use. If you want to develop applications using &LIBGDA;, you should install the libgda-dev[el] package if you do a &RPM; or Debian-based installation. If you compiled the source code, development files are installed in your system. The only step you need to do to make sure everything is well installed, is to check that &LIBGDA; libraries and binaries are seen by your system. That is, make sure that the &LIBGDA; bin/ directory is in your PATH environment variable, as well as the lib/ in your LD_LIBRARY_PATH (or /etc/ld.so.conf file). If you want to access a data source through a &GDA; provider, you must first of all have access to this provider, and most importantly, this provider should have access to its specific data source. So, first have your database up and running. For this, you'll have to check your specific data source documentation, or see the &LIBGDA; providers' specific documentation. Once you've got your &GDA; provider installed, whether on your machine or on another one on the network, you must configure your local system to have access to it. If you're on a local installation, once you have installed the &GDA; provider (by compiling it or by installing its &RPM; or Debian package), the provider is visible in your machine. This is because the provider package provides an .oafinfo file in which it specifies the location and other information about itself. If, on the orher hand, your provider is on another machine, you'll have to create the .oafinfo yourself. For this, you'll need to check the OAF installation documentation. Then, the next step is to configure the data sources you want available on your system. For doing this, you should, as for now, use &GNOMEDB;, which is a frontend to &LIBGDA; for the GNOME project. It would be a good idea to add a command-line tool for managing the configuration, as now, using GConf, is not a matter of hacking on a config text file, as it was befofe with gnome_config. The &API; for doing so is already available in the libgda-commonlibrary, so it would be really easy. Volunteers? Command-line tools will be provided in &LIBGDA; for doing so in a not-too-distant future, so you may want to know what information you need to setup a data source. One of the problem &GDA; solves is the naming of data sources. Every database system has it's own way of defining names for it's databases. For example &MYSQL; uses the hostname, port number, and the name of the database. Other databases, like Solid use the hostname and port number only. There is no support for multiple databases per server. Because the client does not need all these details, the &LIBGDA; configuration defines all the properties of such a data source, so that the correct data base server can be contacted. This information is accessed by the client library and sent to the provider, which in turn will parse the string to decide which database must be connected to. The data stored for each data source is as follows: [sales] Provider=OAFIID:GNOME_GDA_Provider_MySQL_ConnectionFactory DSN=DATABASE=test;HOST=localhost;PORT=1111 Description=MySQL Test Database in native mode Configurator=None The provider for this database is the gda-mysql provider. The value of this entry is used as the object ID for the OAF activation. This is the most important entry. The value of this entry is the string sent to the provider so that it knows which datasouce to access. How this entry is interpreted by the providers is described in the provider section. The value of this entry is a short description of the datasource. It is here for convenience only and it is not used for any purpose. This section provides information specific to each of the available &LIBGDA; providers. The &GDA; default provider is always installed with &LIBGDA, which means that you've got always a default database system available for you. To connect to a default provider's database, you only need to specify, in the &DSN; string, a string of the form "DIRECTORY=/directory/for/the/database". When you first connect to the new data source, the &GDA; default provider will create the database, in the directory you specified in the &DSN; string, if it does not exist. The &ODBC; provider is a special case, since &ODBC; is itself a data access layer, the same as &LIBGDA;, So, in the case of the &GDA; &ODBC; provider, the &DSN; string is completely up to the &ODBC; driver manager. That is, the &GDA; &ODBC; provider does not parse it all, nor does it try to understand what it means; it simply passes it over to the &ODBC; library. So, if you want to use &LIBGDA; with &ODBC;, you should first know how to set up an &ODBC; data source, and then just specify the &DSN; string you would pass to the &ODBC; library in the &DSN; string of the &GDA; data sources. There is a project called unixODBC, which provides some graphical tools to help you in setting up &ODBC; data sources. You may find it interesting to give it a try. To use the &GDA; &PGSQL; provider, you'll need the gda-postgres package. The &PGSQL; provider accepts the following arguments in the &GDA; data source's &DSN; string: HOST: name of the host where the database server is running DATABASE: name of the database you want to access To configure a data source to access a &MYSQL; database, you'll need to install the &GDA; &MYSQL; provider (package gda-mysql). It accepts the following arguments in the &DSN; string: The &GDA; common library contains a rich set of utility functions that are common to both &GDA; clients and servers, and which can be easily used in applications. As another way of hiding all the &CORBA; code, the libgda-common includes a set of functions that offer a low-level access to the &CORBA; stuff, in case you need to do something special with it. The log facility provided by the &GDA; common library uses a special file format which allows an easy retrieval of all the log messages. Thus, you can view your logs by date, time, remove entries, etc. &LIBGDA; offers a special &XML; file format intended to represent the whole structure of a data source's structure. This file format is used to import/export data to/from a given data source. It is also used by the (non-existant yet) &XML; provider, which simulates a database system by using the data stored in one of these files. The gda-common library includes a class, called GdaXmlDatabase, which offers a way for programatically read and modify one of these &XML; files. The client library is a thin wrapper around the &CORBA; interface. The wrapper takes care about memory allocation and de-allocation when you do not need the results from a query anymore, or you close the connection to a database. It's second purpose is to do caching, so that it's possible to navigate forward and backward through the results of a query, even if the database does not support such scrolling cursor. Of course the consistency checks and locking strategies of the database are not supported anymore, but I hope to find workarounds for this. There is also support for managing different datasources with different servers and connection characteristics. To achieve this goal the GConf configuration system is used. It also contains utility functions to help you confront different database-related tasks. This includes batch execution of commands (transactions), &GDA; provider access, ... The main concept of the client library is that a provider allows you to connect to various data sources. Such a provider is a &CORBA; server implemented with ORBit. A provider provides a factory interface which allows the client to request uninitialized connections from the provider. The activation of the provider is done through the OAF activation system. OAF handles the identification of the name server and the registration of the &CORBA; server (the &GDA; provider), once it is active. OAF also allows the client to choose whether to start a new server for every instance of the factory , or if an already running server should be used. This has implications on the startup time used and the number of processes connected to the data base server (and therefore the number of licences used). In order to get a connection to a data source the client usually must provide some information to the provider. First it must pass a connection string to the provider. The provider then uses this string in it's specific way to find the missing pieces required to establish a connection to the real data source server. This can be a hostname and a port number, the name of a shared library to load, whatever is necessary for the data base system or data source provider to be accessed. Additionaly the client must pass a username and a password to be authorized by the data source server. The provider itself does not do any authentication checks. Also note the connection between the client and the server is not encrypted, so the data is sent in clear text. This will change once ORBit supports encrypted communication between a &CORBA; server and it's clients. If this behaviour is not acceptable, use the provider as a shared library. After the connection has been opened, the client may ask for data dictionary information from the data source. The semantics of the data returned from such queries is highly provider dependent and usually will not be portable between different data sources. If the providers belong to the same class (databases for example), this information will be interchangeable, but do not expect to have the same client program querying the &LDAP; provider or the &ODBC; provider without changes in the client source code. The client may then create GdaCommand objects which are used to do actual queries to the providers. For &SQL;-like providers, the query is the actual &SQL; statement. Of course the provider is free to change the statements (conversion between &SQL; dialects) and some providers may even specify their own query language (the &LDAP; provider will do this). It's also possible to call stored procedures. These procedures may be stored in the actual backend (the database system) or they may be implemented by the provider. The result of a query is accessed through an object of type GdaRecordset. The actual data rows might be stored on the client side, the provider side or in the database server. This depends on various flags and options used when the recordset is created. Positions in a recordset are defined through bookmarks, which are an opaque datatype. A bookmark can be used to position the current access pointer in a recordset. Since some database systems don't allow arbitrary positioning of the access pointer in the result set of a query, the provider stores and caches all retrieved data rows. If the recordset is configured to store the data on the client side then the bookmark is simply a pointer into the rows. You can read more about storing of data rows, caching and transaction in the section about recordsets. The main class for &GDA; is the GdaConnection class. Objects of this class establish the connection to the &CORBA; server and they are needed for nearly all activity on the client side. Each object has a direct or indirect pointer to a connection object. Another very important class is the GdaCommand class. It is used to store a command string and to execute this command on the &CORBA; server. It has a reference to a connection object. The execute function returns an object of the GdaRecordset class. This class is responsible for buffering, caching and managing memory for the data items returned from the server. One problem &GDA; tries to hide from the user is the difference between data types as they are stored in the database and how they are used by an application. An easy example is the representation of prices. They are a fixed floating point number with two digits after the decimal point. Most databases allow you to specify a DECIMAL datatype with a length and a precission. In C no such datatype exists. You might want to store the value as a string, which is also often convenient for displaying, but not for computing taxes or other things. &GDA; therefore decouples the storage type of a column from the type the user wants. This is done via the GDA_Type of a value. The database capability to convert between different data types is used, if available. Otherwise the type conversion is done in the client. Converting the data in the server may lead to unpredictable results when the server is a 64bit machine and the client is a 32bit machine. Here will be a table of &GDA; data types, their C and &SQL; equivalents, and the allowed conversions. &GDA; type C type &SQL type Description FIXME FIXME FIXME FIXME All datasources must provide functions to access their meta information. If the datasource is a database, metainformation is the names of the tables, the columns, user rights, and so on. The results from a meta information query are represented as a GdaRecordset. The problem is that most of the time the client is only interested in some part of the information. The client wants to query the data source about the indices for a table, not all indices for all tables. Therefore it is possible to pass constraints to the meta information query. But this is further complicated by he fact that each query might need to have different constraints. The following table shows which query types are implemented and which constraints are valid for each query. The constraints are passsed as name-value pairs. The name is an enum and the value is a string. The query function is a variadic function and the argument list must be closed with a enum value of 0. The following table shows the most often used constraints and when to use them. Some schemas may require that you give a constraint. Constraint Usage Observations GDA_Connection_OBJECT_CATALOG Used to specify the Database GDA_Connection_OBJECT_SCHEMA Used to specify the owner GDA_Connection_OBJECT_NAME Used to specify the name of the object to query (table, ...) GDA_Connection_EXTRA_INFO Set it to get a more detailed answer from the provider Set it to a non NULL string (e.g. "") The following table shows the "standard" schemas that must be supported by each &GDA; provider, although a specific provider may not support one of these. To test wether a schema is supported, see the gda_connection_supports() function. Object Type GDA identifier Supported Constraints Returned fields Extra Info Tables GDA_Connection_GDCN_SCHEMA_TABLES GDA_Connection _OBJECT_NAME, GDA_Connection _OBJECT_CATALOG, GDA_Connection _OBJECT_SCHEMA, GDA_Connection _EXTRA_INFO name, comments name, owner, comments, SQL definition Tables' parents (for providers that support tables inheritance) GDA_Connection_GDCN_SCHEMA_TAB_PARENTS GDA_Connection _OBJECT_NAME (required), GDA_Connection _OBJECT_CATALOG name, order of inheritance Not Supported Views GDA_Connection_GDCN_SCHEMA_VIEWS GDA_Connection _OBJECT_NAME, GDA_Connection _OBJECT_CATALOG, GDA_Connection _OBJECT_SCHEMA, GDA_Connection _EXTRA_INFO name, comments name, owner, comments, SQL definition Table (or view) columns GDA_Connection_GDCN_SCHEMA_COLUMNS GDA_Connection _OBJECT_NAME (required), GDA_Connection _OBJECT_CATALOG, GDA_Connection _OBJECT_SCHEMA, GDA_Connection _COLUMN_NAME name, type, size, precision, nullable, is key, default value, comments Not supported Sequences GDA_Connection_GDCN_SCHEMA_SEQUENCES GDA_Connection _OBJECT_NAME, GDA_Connection _OBJECT_CATALOG, GDA_Connection _OBJECT_SCHEMA, GDA_Connection _EXTRA_INFO name, comments name, owner, comments, SQL definition Procedures GDA_Connection_GDCN_SCHEMA_PROCS GDA_Connection _OBJECT_NAME, GDA_Connection _OBJECT_CATALOG, GDA_Connection _OBJECT_SCHEMA, GDA_Connection _EXTRA_INFO name, object Id, comments name, object Id, owner, comments, number of arguments, SQL definition Procedures' parameters GDA_Connection_GDCN_SCHEMA_PROC_PARAMS GDA_Connection _OBJECT_NAME (required) Usage(in, out or inout), type Not Supported Aggregates GDA_Connection_GDCN_SCHEMA_AGGREGATES GDA_Connection _OBJECT_NAME, GDA_Connection _OBJECT_CATALOG, GDA_Connection _OBJECT_SCHEMA, GDA_Connection _EXTRA_INFO name, object Id, In type, comments name, object Id, In type, owner, comments, &SQL; definition Types GDA_Connection_GDCN_SCHEMA_PROV_TYPES GDA_Connection _OBJECT_NAME, GDA_Connection _OBJECT_CATALOG, GDA_Connection _OBJECT_SCHEMA, GDA_Connection _EXTRA_INFO name, owner, comments, Gda type, provider type name, comments You must pay special attention to the constraints used (both in client applications and &GDA; providers), because it is required for providers to return an error if an invalid constraint is passed to the server. This is specially important, since there are schemas that may mean different things depending on the set of constraints used. As you can imagine, this could lead to the client receiving not-required data. The client library provides a very interesting object: the GdaBatch object, which is an abstract class which allows you to treat a series of commands as a unique entity. It offers this feature along with a real transaction support (if the underlying database supports it). All changes made to the database are committed if no error is found, whereas the execution is cancelled (and all changes discarded) if an error is returned from the database. This model lets you provide transaction-like support in your applications with just a few lines of code. The GdaBatch object is also flexible enough to be used as a simple batch job, ignoring errors if this fits your needs, and disabling database transactions. In this case, the best way to use the object is to connect to it's different signals, which let you know at any moment the status of each command's execution. &GDA; client applications may be of two types: Applications making use of the &LIBGDA; client libraries. These are the most common, being its use straightforward, since they hide all the &CORBA; complexity with a complete and easy-to-use &API;. &CORBA; clients. You may want to develop a &GDA; client application in another language or in another platform where there is a different &CORBA; &ORB; implementation. In this case, you would need to generate &CORBA; client stubs by using your &IDL; compiler with the &IDL; files that come with &GNOMEDB;. If you do something like this, please get in touch with the &GNOMEDB; developers so that we know how it works under these circumstances. There is a script called gda-buildclient which takes care of all the libraries needed for a &GDA; client application. This is all it does, so you may not find it worthy and bypass its use, but it is included for simplicity. A typical call to this script would look like this: gda-buildclient --o client --f <list of .o files> [--l <list of additional libs>] [--L <list of directories to search libs for>] There is also a script called gda-config which you can use to retrieve compilation and linking flags for &GDA; clients, in case you want to integrate &GDA; into your Makefiles. Its syntax is: Usage: gda-config [OPTIONS] [LIBRARIES] Options: [--prefix[=DIR]] [--exec-prefix[=DIR]] [--version] [--libs] [--cflags] Libraries: client server cpp As you can see, gda-config can be used to retrieve all the information you want about &GDA;. The two most interesting are --libs and --cflags, which return , respectively, the linking and compilation flags needed for a program making use of the &LIBGDA; libraries. As there are several ways of using &LIBGDA;, this script offers parameters to deal with this situation. So, you've got the LIBRARIES parameter, which can take one of three values: client server cpp (for C++). To show how to do this, the JAVA &IDL; compiler will be used as an example. As you may know if you wish to write a &CORBA; client, an &IDL; file is used to define the interface provided by a &CORBA; server. This &IDL; file is then used by a program called "IDL compiler" to generate client stubs and server skeletons implementing the particular &ORB; interface. &LIBGDA; provides a top-level &IDL; file which defines all the &CORBA; interfaces exported. This file is called gda.idl and is found with your &GNOMEDB; distribution. This &IDL; compiler is what you have to use to generate, in this case, client stubs. So, for example, using the JAVA &IDL; compiler, you would run: $java-idl gda.idl This should generate a list of .java files. These are executables or shared libraries doing the conversion work. They map the &CORBA; calls to the data source specific calls. They may use &ODBC;, a native library for the database, &XML; parsers and generators, &LDAP;, POP3 or whatever you can imagine . There is much work involved in the &GDA; providers, specially if the backend to be used is not a database. In this case, apart from mapping the underlying &API; to the &GDA; model, special attention must be paid to map the database-like structure to a non-database architecture. In either case, this is the most complex part of the &GDA; architecture. A server framework is provided with &LIBGDA; to ease the process of adding a new server. This is done by using a set of template files and a shell script called gda-buildserver, which can be used for both creating the basic structure of a new server, and building the server itself. If you do so, contact the &LIBGDA; developers to talk about its inclusion in the &LIBGDA; source tree. Another way of adding a &GDA; provider, would be to use the &IDL; files to generate a server implementation. This way, you can code the server in your preferred language/&CORBA; &ORB;. If you want to do something like this, please contact the &LIBGDA; developers. The purpose of the gda-server library is to hide all the &CORBA; details from the provider's programmer and avoid duplication of work which leads to code that is much easier to debug. That library stands at the same level as the gda-client library from the &CORBA; point of view. The gda-server library imposes a framework on the way the provider needs to be implemented, but allows for specific customization. All the objects here are the mirror objects from the gda-client library from the server side of the &LIBGDA; &CORBA; framework. These objects are: The GdaServerConnection object: this is the main object and handles everything regarding a connection to the &DBMS; (given the DB name, user name, password, etc). Usually the client will use only one of this kind of object. the GdaServerCommand object: this object is used to prepare a query to be executed. the GdaServerRecordset object: every time a command is executed, an object of this type is returned, and can then be examined to see what the results of the command were. Under &LIBGDA;, the recordset is examined in a sequential way, row after row (for some &DBMS; it is the way query results are handled while for others there is possible random access). the GdaServerField object: for every column, an object of this kind is used. It describes the column name, the data type, and its contents. Each GdaServerField object will be initialized when the recordset is created, and a new value will be stored in it every time a new row is examined. The gda-server will then use these objects to send the contents to the client &CORBA; side. When a client makes a query, what happens in the server side is: A GdaServerConnection is created The connection is opened A GdaServerCommand is created The actual command is set in the GdaServerCommand object The command is executed, and if no error occurs, a GdaServerRecordset is created and returned The GdaServerCommand can safely be destroyed The first row of the recordset can be examined, then the 2nd, etc The GdaServerRecordset is destroyed The connection can be closed, and the GdaServerConnection can be destroyed. All the steps described above are imposed by the &LIBGDA; framework. The work of writing a provider for a specific &DBMS; is in writing the specific parts of the operations described above. As the C library for a &DBMS; uses some specific structures to handle connection references, etc, it is possible to attach some information to the gda-server library objects. So usually the provider's programmer defines the following structures (here replace &DBMS; for the actual &DBMS; name like for example MYSQL or POSTGRES): a connection structure usually named DBMS_Connection a command structure usually named DBMS_Command a recordset structure usually named DBMS_Recordset In this section are some recommandations on how to handle some specific items for each &DBMS;. &LIBGDA; has some defined data types, covering all the usual data types (strings, numbers, dates, binary, etc). However, because each &DBMS; has some more specific data types (like for example arrays, IP adresses), and it is sometimes possible to create some user defined data types, not all the data types can be predefined by &LIBGDA;. So, for the most common ones where a &LIBGDA; data type exists, it will be used, otherwise the GdaTypeUnknown will be used (and then is it up to the application programmer using &LIBGDA; to take good care of that information). Under &LIBGDA;, the client application cannot know the &DBMS; to which it is connected, but as it can know if the &DBMS; supports some features and what the tables, sequences, indexes, etc. are in the DB. One of the most time consuming jobs is to write the fuctions to return answers to all these client requests. The basic work to do is implement a set of functions necessary for the gda-server library to manipulate the provider. When a provider wants to start, it has to give pointers to these fuctions in a structure (see the main-DBMS.c file for this). The other sets of functions to implement are schema request functions. Among the functions that you MUST implement is a function to request schemas. This function can be implemented in the way you want, but a common practice (used in all the 'standard' &LIBGDA; providers), is to have this function call other functions depending on the type of schema requested by the client application. Usually a provider has only one header (gda-DBMS.h ) which contains all the structure definitions, and the main function declarations. This header needs to include the gda-server.h header file. The provider also needs the common elements of the gda-common library (for &XML; stuff, etc when completed). Usually there is one .c file for the implementation of the different &DBMS; structures mentioned above, except for the GdaServerField object, which is entirely managed by the gda-server library, and one for the program itself. You can have a look at the providers distributed with &LIBGDA;, which make use of this library. It is especially interesting to look at the &PGSQL; provider, since it is a good example of provider customization. It includes some extra features not present in other providers, such as the built-in recordsets, which are used to get data out of the box, not being a value directly returned by &PGSQL;. &FDL-INC;