DataSource - Data source

A data source describes an ODABA data source on a certain level ( Dictionary , Database , ObjectSpace , Property , Value ). A data source can be parametrized by means of an configuration or ini-file. The configuration file contains options for access objects on different levels. Not specified lower levels are not opened and have to be opened in the application (e.g. when defining dictionary and database, only, the extent is not opened and no instance is selected),

The data source is defined as section in the configuration file starting with the [data source name] or as xml option element with that name in an configuration file.

A data source can connect to a server. In this case, the data source client becomes a server client, which might be created by the application. Usually, the data source works properly with implicit clients.

A data source can be opened and closed as a whole ( open() , close() ) or separately on each level ( connect() , openDictionary() , openDatabase() ,...).

A connection name can be associated with a data source in order to cache the connection when connecting to a server. The connection name is used to reconnect to the server using a cached connection, which is faster than reestablishing the connection from scratch.

An application may refer to any number of data sources. Usually, the first data source opened will initialize the application environment, which contains the currently set options from the configuration and from the application.

In order to open a data source a client object is required. The client object manages the communication between the application and the database. Because of the client object the application becomes scalable, since the client object manages local database connections as well as different types of server connections. A client handle can manage the connection to one server, which is identified by server name and port. At the same time, each client is able to manage local connections, i.e. local connections can be opened with any client handle.

By default, each application implicitly creates a main client, which is used to manage all connections that have not opened a client object explicitly. When not passing a specific client opened by the application to the data source, the main client is assigned to the data source.

When connecting the data source to a server, the data source checks whether the assigned client is already connected to the server requested by the data source. When the client is already connected but to another server, the data source implicitly creates a new client object and releases the currently connected client.

Since implicit client handles automatically manage connections to any number of servers, it is suggested to use implicit client handles whenever possible. In order to manage complex client server applications, however, explicit defined clients might perform better. When connecting several data sources to the same server, which is not connected to the main client, a client handle connected to this server should be set for the data source ( setClient() ) in order to reduce the number of connections.

In order to open a data source,data source properties have to be set properly. Data source properties can be set directly from within the application program.

The more flexible way is to read setting for the data source from a configuration or ini-file ( initialize() ) or from optional variables currently set in the application ( setupOptions() ).

Before opening a data source, at least dictionary and database path should refer to proper database locations. Database locations may contain options enclosed in %...%, which will be replaced by the option value currently set for the referenced option.

In order to open a data source, usually three steps are necessary.

• Create a data source ( DataSource() )
• [ set client handle ( setClient() ) ]
• Initialize data source ( initialize( sIniFile , sDataSourceName ) )
• Open data source ( open() )

A short way to create and open a data source is provided with the data source constructor DataSource( sIniFile , sDataSourceName ) . In order to create and open a data source with an application defined client DataSource( rClient , sIniFile , sDataSourceName ) might be called.

Same sort of short cuts are provided with the open() function. Calling open( sIniFile , sDataSourceName ) will initialize and open the data source from the configuration file. open( rClient , sIniFile , sDataSourceName ) does the same but sets the passed application client as client handle for the data source. open( sDataSourceName ) initializes the data source from an option section defined in the default configuration file assigned to the application ( odaba::initializeApplication( sIniFile ) ).

Data source properties are set in order to open a data source. When a data source has been opened, properties may change values, but this will not affect the opened access handles. Thus, data source properties should not be used in order to retrieve information about currently opened access handles.

Data source handle properties will be reset completely, when calling initialize() .