DataSource :: open - Open data source

A data source consists of a dictionary and a database. In addition, an object space and a data collection (access path) can be defined. The data source can be closed calling close(). If a data source is already opened, it will be closed before reopening the data source with the parameters currently set.

Usually, the function refers to the main client handle, which will be created on demand when not being initialized by calling odaba::initializeApplication(). In order to connect via an application specific client, a client handle can be passed (rClient). When connecting a data source to a server, the function checks, whether the server fits to the client passed. When the client is already connected to a different server, the function automatically creates a new client handle. Client handle should be passed only, in order to optimize client connections.

Usually, the data source refers to the main client, which is sufficient for many applications. In order to open the property data source, a data source name has to be set in the dataSourceName property.

// re-using client for several data sources referring to same server

ds1.initialize("c:/temp/myAppl.ini","Sample");

ds1.open();

ds2.dataSourceName("ApplData");

ds2.setClient(ds1.client()); // re-use client in data source 2

ds2.Open();

Return value: Data source handle ( odaba::DataSource & )

The data source handle refers to a data source definition.

Implementation overview

Create data source with application client
DataSource :: open ( cClient, sIniFile, sDataSourceName )
Open data source for data source name
DataSource :: open ( sDataSourceName )
Open data source with current settings
DataSource :: open ( )
Open data source with dictionary in write mode
DataSource :: open ( eAccessMode )
Create a data source by options from ini-file
DataSource :: open ( sIniFile, sDataSourceName )

Implementation details

Create data source with application client
odaba::DataSource & DataSource  :: open ( odaba::Client &cClient, odaba::String &sIniFile, odaba::String &sDataSourceName )

The function sets the client handle passed in rClient as client handle for the data source. The data source will be initialized from the option section with the name passed in sDataSourceName, which has to refer to an option section in the configuration file passed in sIniFile.

When the data source could not be opened, the function throws an exception. The data source handle remains as initialized data source handle.

// calling DataSource ds(rClient,"c:/temp/myAppl.ini","Test") is a short cut for:

  DataSourceHandle  dsh();

  setClient(rClient);

  dsh.initialize("c:/temp/myAppl.ini","Test");

  dsh.open();
- cClient - Client handle
  The client handle refers to an (usually) opened ODABA client. Calling functions with invalid client handles may cause an exception. For checking the client handle, isValid() can be called.
- sIniFile - Path to ini-file location
  The path may contain any type of folder separator ('/' or '\'). Folder separators will be converted according to the conventions of the target system.
  
  In order to pass no ini-file, an empty string ( String() ) has to be passed.
- sDataSourceName - Data source name
  The name of the data source refers to a section in a configuration or ini-file or to a data source defined in the data catalog defined for the application. Other data source variables are set from the data source definition referred to by the data source name.

to list

Open data source for data source name
odaba::DataSource & DataSource  :: open ( odaba::String &sDataSourceName )

The data source will be initialized from the option section with the name passed in sDataSourceName. Options must have been initialized before by calling odaba::initializeApplication() or initializeOptions(). The data source name to refer to an option section in the application configuration file or to a valid data source name defined in the data catalog of the application.

When the data source could not be opened, the function throws an exception. The data source handle remains as initialized data source handle.

// initialize application and data source

  initializeApplication("c:/temp/myAppl.ini","Test",ConsoleApplication);

  DataSource  ds("TestData"); // open Test data source

    ...                       // do something for Test data source

  ds.open("Sample");          // refill options from Sample section

                              // or catalog definition
- sDataSourceName - Data source name
  The name of the data source refers to a section in a configuration or ini-file or to a data source defined in the data catalog defined for the application. Other data source variables are set from the data source definition referred to by the data source name.

to list

Open data source with current settings
odaba::DataSource & DataSource  :: open (  )

The function opens the data source for the current settings in the data source handle. In order to call this function, the options in the data source handle have to be set properly. At least a dictionary path (dictionaryPath property) has to refer to a valid dictionary database.

In order to initialize data source options from data source specifications defined in a configuration or ini-file, the application has to be initialized before with the required configuration file.

// initialize application and data source

  ds.initialize("c:/temp/myAppl.ini","Test",ConsoleApplication);

  ds.open();  // open Test data source

    ...       // do something for Test data source

  ds.setOptions("Sample"); // refill options from Sample section or catalog definition

    ...       // update options as required

  ds.open();  // open Sample data source

to list

Open data source with dictionary in write mode
odaba::DataSource & DataSource :: open ( odaba::AccessModes eAccessMode )

The function can be called in order to open the dictionary of the data source with the access mode passed in eAccessMode. Usually, the dictionary will be opened read-only. In order to open the dictionary in write mode, Write has to be passed in eAccessMode.

The function opens the data source for the current settings in the data source handle. In order to call this function, the options in the data source handle have to be set properly. At least a dictionary path (dictionaryPath property) has to refer to a valid dictionary database.

In order to initialize data source options from data source specifications defined in a configuration or ini-file, the application has to be initialized before with the required configuration file.
- eAccessMode - Access mode
  Access mode for a property handle or database.

to list

Create a data source by options from ini-file
odaba::DataSource & DataSource  :: open ( odaba::String &sIniFile, odaba::String &sDataSourceName )

The data source will be initialized from the option section with the name passed in sDataSourceName, which has to refer to an option section in the configuration file passed in sIniFile or to a valid data source name defined in the data catalog of the application

When the data source could not be opened, the function throws an exception. The data source handle remains as initialized data source handle.

// calling DataSource ds("c:/temp/myAppl.ini","Test") is a short cut for:

  DataSourceHandle  dsh();

  dsh.initialize("c:/temp/myAppl.ini","Test");

  dsh.open();
- sIniFile - Path to ini-file location
  The path may contain any type of folder separator ('/' or '\'). Folder separators will be converted according to the conventions of the target system.
  
  In order to pass no ini-file, an empty string ( String() ) has to be passed.
- sDataSourceName - Data source name
  The name of the data source refers to a section in a configuration or ini-file or to a data source defined in the data catalog defined for the application. Other data source variables are set from the data source definition referred to by the data source name.

to list

to top Comment