UNIX: Objectivity/SQL++ ODBC Driver Configuration

Printer-friendly version

To configure the Objectivity/SQL++ ODBC Driver, refer to the following:

Setting Your OO_SQL_DIR

Set the environment variable OO_SQL_DIR to the fully qualified pathname of the Objectivity/DB installation directory (installDir). You may wish to set the variable in a startup file such as .login.

Note: You must set the OO_SQL_DIR environment variable for every user that will interact with the provided ODBC driver-manager—for example, to list registered drivers or to add data sources. This variable enables the ODBC driver-manager to use installDir/etc/sql as its system directory.

Checking that Objectivity/ODBC is Registered with the ODBC Driver-Manager

When you install Objectivity/ODBC, it is automatically registered with the provided ODBC driver-manager (unixODBC DriverManager). Objectivity/ODBC must be registered so that unixODBC DriverManager can load it whenever an ODBC-complient client application requests data from an Objectivity/DB federated database.

After the Objectivity installation script completes, you should query the provided ODBC driver-manager to check whether Objectivity/ODBC was registered correctly.

Checking Whether Objectivity/ODBC is Registered

To verify that Objectivity/ODBC is registered with unixODBC DriverManager:

  1. Enter the following at a command prompt:
    odbcinst -q -d
    
  2. Look for the following driver name in the list of registered ODBC drivers:
    ObjectivitySQL
    
  3. If you do not see ObjectivitySQL listed as a registered ODBC driver:
    • Make sure the OO_SQL_DIR environment variable for your account is set to the fully qualified pathname of the Objectivity/DB installation directory (installDir).
    • Repeat step 1.

Registering Objectivity/ODBC

If Objectivity/ODBC is not registered with unixODBC DriverManager or if you want to change some aspect of its registration, you can perform the registration steps yourself:

  1. Make sure the OO_SQL_DIR environment variable for your account is set to the fully qualified pathname of the Objectivity/DB installation directory (installDir).
  2. Change your working directory to the Objectivity/SQL++ support directory. Enter:
    cd installDir/etc/sql
    
  3. Inspect the driver template file odbcinst.ini_template. If necessary, edit the file in a text editor—for example, to enter the correct pathname for the Objectivity/DB installation directory.
  4. Register Objectivity/ODBC using the information in the driver template file. Enter:
    odbcinst -i -d -f odbcinst.ini_template
    
  5. Check for the resulting driver file:
    installDir/etc/sql/odbcinst.ini

Note: To get help for the odbcinst tool, run it with no options or arguments.

Adding Objectivity/DB Data Sources

You enable ODBC-compliant client applications to access an Objectivity/DB federated database by adding a data source for it. In general, a data source identifies the data to be accessed and the means of accessing it (for example, host and network information). The data source you add for a federated database specifies its boot file and a host running a particular Objectivity/SQL++ ODBC server.

You can add a personal data source, which is specific to applications running under your user account, or a system data source, which is available to applications running under any user account.

Before you add a data source for a federated database:

  • Identify the Objectivity/SQL++ ODBC server that will access the federated database, and obtain:
    • The TCP/IP name of the host that runs the ODBC server.
    • The service name under which the ODBC server is running.
  • Obtain the location and name of the federated database’s boot file.
  • Ensure that you have a valid user account on the host running the Objectivity/SQL++ ODBC server.

To add a data source for a federated database:

  1. Log in under an appropriate user account. In particular, you must log in under your user account if you are adding a personal data source.
  2. Make sure the OO_SQL_DIR environment variable for your account is set to the fully qualified pathname of the Objectivity/DB installation directory (installDir).
  3. Copy the provided data-source template file to a separate location and change your working directory to this new location. For example, enter the following, where homeDir represents your home directory:
    cp installDir/etc/sql/odbc.ini_template homeDir/odbc.ini_tmpl
    cd homeDir
    
  4. Open your copy of the data-source template file in a text editor.
  5. Edit the first line so that it contains the desired data-source name enclosed in brackets—for example, [MyObjyData]. The data-source name should uniquely identify the data source.
  6. Edit the subsequent lines so that each keyword has an appropriate value. Each keyword-value entry should consist of a single line:
    Description = A description for the data source.
    Driver = The name under which Objectivity/ODBC is registered with the ODBC driver-manager—for example, ObjectivitySQL.
    Host = The TCP/IP name of the host machine running the Objectivity/SQL++ ODBC server (the oosqld process).
    Database = Fully qualified pathname of the federated database’s boot file on the specified host.
    User ID = The username of your Objectivity/SQL++ account. This is normally your login account on the ODBC server host, provided that this account has been granted access rights to tables in the federated database (see your Objectivity/SQL++ database administrator). The Objectivity/SQL++ database administrator account (systpe) has access to all tables.
    Password = Password for the account you entered in the User ID field. The password you enter is not encoded before it is sent across the network.
    Service = The service name of the ODBC server on its host (oosqlnw).

    Note: The Host, Database, and Service fields together must not exceed a string-length of 988 characters.

  7. Save the data-source template file.
  8. Add the data source using the information in the template file you edited.
    • To add a personal data source, enter:
    • odbcinst -i -s -f odbc.ini_template

    • To add a system data source, enter:
      odbcinst -i -s -f odbc.ini_template -l

  9. Verify that the data source was successfully added. Enter:
    odbcinst -q -s
    

Adding a personal data source creates a file called .odbc.ini in your home directory. Adding a system data source creates a file called installDir/etc/sql/odbc.ini.

Configuring TCP/IP

You or your system administrator must perform the following steps to enable your ODBC-compliant application to communicate with the Objectivity/SQL++ ODBC server across the network.

Identifying the ODBC Server’s Host to TCP/IP

TCP/IP must be able to recognize the hostname you specify when you register a data source. That is, TCP/IP must be able to convert the hostname into an Internet address. Many sites use the TCP/IP hosts file to map hostnames to Internet addresses, although some sites use domain name servers for this purpose.

You should verify that the computer on which you installed Objectivity/ODBC recognizes a valid hostname for the computer on which the ODBC server is running. For example, to verify that your computer recognizes hostname:

? Enter the following command at a command prompt:

   ping hostname

Specifying the ODBC Server’s Port Number

The Objectivity/SQL++ ODBC Driver and the Objectivity/SQL++ ODBC server must be able to communicate through the same TCP/IP port. Consequently, you must register the port number with TCP/IP on each Objectivity/ODBC (driver) host. To do so:

  1. Find the TCP port assigned to the oosqlnw service on the host running the Objectivity/SQL++ ODBC server. The port is normally 1990.
  2. On the host where you installed Objectivity/ODBC (the driver), open the TCP/IP services file (typically, /etc/services).
  3. Add the following entry to the TCP/IP services file:
    oosqlnw       portNumber/tcp       # Objectivity/SQL++ server 
    
    where portNumber is the TCP port number you found in step 1—for example:
    oosqlnw     1990/tcp               # Objectivity/SQL++ server
  4. Send a hang-up signal to your inetd process. For example, if inetdPid is the process identifier for the inetd process, enter:
    kill -HUP inetdPid

Note: You must assign the same port to the oosqlnw service on every Objectivity/SQL++ ODBC Driver host.

Testing Objectivity/ODBC

You can verify the correct operation of Objectivity/ODBC in combination with an Objectivity/SQL++ ODBC server by running the following test. This test compiles and links a sample ODBC application and then runs it to access a demonstration federated database. You need Objectivity/C++ to run this test.

The demo federated database is provided with Objectivity/SQL++ on the ODBC server host.

The sample application is a C++ application that calls ODBC 3.0 functions to query and modify a federated database. You can inspect the sample to see how such an application is compiled and linked.

To build and run the sample ODBC-compliant application:

  1. Verify that the demo federated database and the Objectivity/SQL++ ODBC server have been set up for this test:
  2. On the host where you installed Objectivity/ODBC (the driver), change your working directory to the Objectivity/SQL++ support directory. Enter:
    cd installDir/etc/sql
    
  3. In the Objectivity/SQL++ support directory, open the data-source template file odbc.ini_template in a text editor.
    • Make sure the data-source name on the first line is [DEMO].
    • Update each entry as necessary to reflect your environment:

    Description = DEMO DSN for Objectivity SQL++ ODBC demo
    Driver = driverName (probably ObjectivitySQL)
    Host = hostName (name of the host running your Objectivity/SQL++ ODBC server)
    Database = Fully qualified boot-file path for the demo federated database under the Objectivity/DB installation directory (installDir) on hostName—that is:
    installDir\samples\sql\ooisql\DEMO        (Windows)
    installDir/samples/sql/ooisql/DEMO   (UNIX)
    User ID = A username that has been granted access rights for the tables in the demo federated database. By default, this is the Objectivity/SQL++ database administrator account (systpe).
    Password = Password for the account you entered in the User ID field.
    Service = oosqlnw

  4. Save the data-source template file.
  5. Add the [DEMO] data source as a personal data source. Enter:
    odbcinst -i -s -f odbc.ini_template
    
    For details, see Adding Objectivity/DB Data Sources.
  6. Change your working directory to the Objectivity/ODBC samples directory. In a command window, enter:
    cd installDir/samples/sql/odbc
    
    You may wish to make a backup copy of this directory.
  7. Edit makefile in the Objectivity/ODBC samples directory.
    • Set INSTALL_DIR to be the location of the Objectivity/DB installation directory—for example:
      INSTALL_DIR = /opt/Objectivity/version
    • Set LS_HOST to be the name of the host running the lock server—for example::
      LS_HOST = myLockServerHost
  8. Check whether the lock server is running; start it, if necessary.
  9. Build and run the sample application. At the command prompt, enter:
    make
    
  10. Run the sample application. Enter:
    ./demo.sh
    Press Return at each prompt to continue the demo.

If the Objectivity/SQL++ ODBC programming interface is set up correctly, you will see messages like these:

Welcome to the Objectivity/SQL++ ODBC demo
...
Building the ooODBCdemo executable
...
Running the demo...
Demo complete.
Comparing the results.
Test PASSED -- The expected results were achieved.
No errors.

 

Date: 
Monday, August 20, 2012
Product: 
Objectivity/DB
Version: 
11.0