Chapter 5. GDA Client Library

Table of Contents
Introduction
Overview of the GDA Objects
Data Types
Datasource Meta Information
Batch Jobs
Function Reference

Introduction

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 some configuration files in the users home directory (no global configuration files yet supported) are read. The gda-manager program can be used to browse these files and edit their content.

It also contains utility functions to help you confront different database-related tasks. This includes batch execution of commands (transactions), GDA provider access, configuration access through the gda-manager's plug-in system, ...

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 GNORBA library. This library handles the identification of the GNOME name server and the registration of the CORBA server (the GDA provider), once it is active. GNORBA also allows the client to choose, if for every instance of the factory a new server shall be started, 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 the name of the data source to the provider. The provider then uses this name 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 is not encrypted, so that the data is sent in clear text. This will change when 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 about 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 (data bases for example), this information will be exchangeable, but don't expect the same client program querying the LDAP provider or the ODBC provider without changes in the client source code.

The client may then create Gda_Command objects which are used to do actual queries to the providers. For ODBC and MySQL 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. This procedures may be stored in the actual backend (the database system) or they may be implemented by the provider. Another possibility is to pass just the name of a table to the provider. The provider will then return all rows and columns of the table to the client.

The result of a query is accessed through an object of type Gda_Recordset. 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 is 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.