Menu
Simba Technologies
Simba Technologies

SimbaEngine X SDK 10.1.11
Build a C++ ODBC Driver in 5 Days (Linux/Unix)

Configure the Driver and Data Source

You configure the Data Source Name (DSN) in the odbc.ini file and the and driver in the odbcinst.ini file. The driver manager uses information in these files to locate and load ODBC drivers. You configure driver-specific information , such as log file location, in the .simba.QuickStart.ini file.

Driver Managers

On Linux and Unix platforms, the SimbaEngine X SDK supports both the iODBC and the unixODBC driver managers.

Unlike Windows platforms, Linux, Unix, and macOS platforms do not come with a driver manager as part of the operating system. You need to install your own driver manager before loading a driver and accessing data stores. For more information on installing a driver manager, see Driver Managers.

Using the Sample Configuration Files

If the odbc.ini and odbcinst.ini files already exist on your machine, you can add the QuickStart driver entries to these files. If these files do not exist on your machine, you can create them and add the required entries. The SimbaEngine X SDK includes sample files in the following directory:

[INSTALL_DIR]/SimbaEngineSDK/10.1/Documentation/Setup

where [INSTALL_DIR] is the SimbaEngine X SDK installation directory.

Important:
  • The sample odbc.ini and odbcinst.ini files show how to configure DSNs and driver entries for 32-bit drivers on Linux platforms. To configure a 64-bit driver, a debug driver, or a driver for platforms other than Linux, you will need to make the changes shown below.
  • The sample .simba.quickstart.ini file is hidden, so you may need to configure your window or terminal listing to view hidden files.

Configuring an ODBC Data Source in the odbc.ini File

ODBC Data Sources are defined in the .odbc.ini configuration file. If this file does not exist, you must create it in the correct location.

To create and configure the odbc.ini file:

  1. To see if the .odbc.ini file already exists in the home directory, run the following command:

    ls -al ~ | grep .odbc.ini

  2. If no response is returned, the .odbc.ini file does not exist in the home directory.

  3. To see if the file already exists in another location, check if the ODBCINI environment variable is set. If it is set, then check the specified location to see if the file exists.
  4. If the file does not exist, copy the sample odbc.ini file to the desired directory. This example shows how to copy the file to the user's home directory, but you can choose another directory:
  5. cp [INSTALL_DIR]/SimbaEngineSDK/10.1/Documentation/Setup/odbc.ini ~/.odbc.ini

  6. Using a text editor, open the ~/.odbc.ini configuration file.
  7. Note:

    The “.” before odbc.ini in ~/.odbc.ini causes the copied file to be hidden. To open the file, you may need to configure your text editor to show hidden files.

  8. Replace every instance of [INSTALLDIR] with the installation location of the SimbaEngine X SDK.

  9. Make sure there is an entry in the [ODBC Data Sources] section that defines the Data Source Name (DSN). The [ODBC Data Sources] section is used to specify the available data sources.
  10. Example

    [ODBC Data Sources]

    QuickstartDSII=QuickstartDSIIDriver

  11. Make sure there is a section with a name that matches the data source name (DSN). This section specifies the configuration options as key-value pairs.
  12. Be sure to use the path to the driver that you built in the previous step, as shown below. By default, the sample odbcinst.ini file contains a path to the pre-built drivers that ship with the SimbaEngine X SDK.

    Example: 32-bit driver 

    [QuickstartDSII]

    Description=Sample 32-bit SimbaEngine QuickStart DSII

    DBF=[INSTALL_DIR]/SimbaEngineSDK/10.1/Examples/Databases/Quickstart

    Driver=[INSTALL_DIR]/SimbaEngineSDK/10.1/Examples/
    Source/Quickstart/Bin/Linux_x86_gcc/debug32/libQuickstart32.so

    Note: replace [INSTALL_DIR] with the installation directory.

    Example: 64-bit driver 

    [QuickstartDSII]

    Description=Sample 64-bit SimbaEngine QuickStart DSII

    DBF=[INSTALL_DIR]/SimbaEngineSDK/10.1/Examples/Databases/Quickstart/

    Driver=[INSTALL_DIR]/SimbaEngineSDK/10.1/Examples/
    Source/Quickstart/Bin/Linux_x86_gcc/debug64/libQuickstart64.so

    Locale=en-US

    Note: replace [INSTALL_DIR] with the installation directory.

    Important:

    Take care not to include characters such as spaces or tabs at the end of a value. This can cause failure to connect.

Configuring an ODBC Driver in the odbcinst.ini File

ODBC Drivers are defined in the odbcinst.ini configuration file. This configuration is optional, because drivers can be specified directly in the odbc.ini configuration file as discussed in the previous section. Before defining the driver, see if the odbcinst.ini file exists.

To configure a driver in the .odbcinst.ini file:

  1. To see if the .odbcinst.ini. file exists in your home directory, type the following command:

    ls -al ~ | grep .odbcinst.ini

    If the file does not exist, then nothing is returned at the command prompt.

  2. To see if the file already exists in another location, check if the ODBCINSTINI environment variable is set. If it is set, then check the specified location to see if the file exists.
  3. If the file does not exist, copy the sample odbcinst.ini file to the desired directory. This example shows how to copy the file to the user's home directory, but you can choose another directory as described in Configure the Driver and Data Source:
  4. cp [INSTALL_DIR]/SimbaEngineSDK/10.1/Documentation/Setup/
    odbcinst.ini ~/.odbcinst.ini

    where [INSTALL_DIR] is the SimbaEngine X SDK installation directory.

  5. Open the .odbcinst.ini configuration file in a text editor.
  6. Replace every instance of [INSTALLDIR] with the installation location of the SimbaEngine X SDK.

  7. Add a new entry to the [ODBC Drivers] section. The [ODBC Drivers] section is used to specify the available drivers. Enter the driver name and the value Installed. The driver name should be used for the "Driver" value in the data source definition instead of the driver shared library name.
  8. Example:

    [ODBC Drivers]

    QuickstartDSIIDriver=Installed

  9. Add a new section with a name that matches the new driver name. This section will contain the configuration options specified as key-value pairs.
  10. Be sure to use the path to the driver that you built in the previous step, as shown below. By default, the sample odbcinst.ini file contains a path to the pre-built drivers that ship with the SimbaEngine X SDK.

    Example - 32-bit Linux:

    [QuickstartDSIIDriver]

    APILevel=1

    ConnectFunctions=YYY

    Description=Sample 32-bit SimbaEngine QuickStart DSII

    Driver=[INSTALL_DIR]/SimbaEngineSDK/10.1/Examples/
    Source/Quickstart/Bin/Linux_x86_gcc/debug32/libQuickstart32.so

    DriverODBCVer=03.80

    SQLLevel=1

    Note: replace [INSTALL_DIR] with the installation directory.

Configuring the QuickStart Driver in the simba.ini File

Configuration options for drivers created using the SimbaEngine X SDK appear in the driver's configuration file, which by default is called .simba.drivername.ini. This file specifies driver-wide settings. The SimbaEngine X SDK searches for the driver .ini file in the following locations, in the specified order:

  1. The path, including the file name, specified using the SIMBAINI environment variable.
  2. The driver directory, as a non-hidden .ini file.
  3. The directory that the client application is launched from.
  4. In $HOME, as a hidden .ini file
  5. In /etc/ as a non-hidden .ini file

Note:

Examples in this section assume that the .ini file exists in the user’s home directory.

To configure the QuickStart Driver in the .simba.quickstart.ini:

  1. To see if the .simba.quickstart.ini file already exists in your home directory, type the following command:

    ls -al ~ | grep .simba.quickstart.ini

    If the file does not exist, then nothing is returned at the command prompt.

  2. If the file does not exist, copy the sample .simba.quickstart.ini file to the desired directory. Note that the sample .simba.quickstart.ini file is hidden. This example shows how to copy the file to the user's home directory, but you can choose another directory:
  3. cp [INSTALL_DIR]/SimbaEngineSDK/10.1/Documentation/
    Setup/.simba.quickstart.ini ~/.simba.quickstart.ini

  4. Open the ~/.simba.quickstart.ini configuration file in a text editor.
  5. Replace every instance of [INSTALLDIR] with the installation location of the SimbaEngine X SDK.

  6. Edit the DriverManagerEncoding setting:

    Note:

    • This step is optional, because the SimbaEngine X SDK automatically detects the type and version of the driver manager.
    • If you are unsure which driver manager you are using, or where the driver manager is installed, contact your system administrator or see Driver Managers for more information.

    • If you are using the iODBC ODBC driver manager set the DriverManagerEncoding setting to UTF-32.
    • Or, If you are using the unixODBC ODBC driver manager, check which setting to use:
      1. At a command prompt, type odbc_config –-cflags .
      2. If you see the “DSQL_WCHART_CONVERT” flag, then set DriverManagerEncoding to UTF-32.
      3. Otherwise, set DriverManagerEncoding to UTF-16.
        For more information about your ODBC driver manager, consult your system administrator or your ODBC Driver Manager documentation.
  7. Edit the ErrorMessagesPath setting to replace [INSTALLDIR] with your install directory.
  8. Set the ODBCInstLib to the absolute path of the ODBCInst library for the Driver Manager that you are using.
  9. Note:

    This step is optional, because the SimbaEngine X SDK automatically detects the type and version of the ODBCInst library. Set this value only if you want to override the value that is automatically detected.

    The ODBCInst library is a part of the driver manager but is used by the driver to read values from the odbc.ini file. The value of this key is the absolute path of the ODBCInst library and depends on which driver manager you are using. For example, for the iODBC Driver Manager this would be <driver manager dir>/lib/libiodbcinst.so (notice the ‘i’ after the lib) and for unixODBC this would be <driver manager dir>/lib/libodbcinst.so

    Example: the iODBC Driver Manager

    (notice the i after lib)

    ODBCInstLib=<driver manager dir>/lib/libiodbcinst.so

    Example: the unixODBC driver manager

    ODBCInstLib=<driver manager dir>/lib/libodbcinst.so

  10. Save the file.

 

Related Links

Locating the Configuration Files

Driver Managers

Troubleshooting