Getting started

This section shows you how to install the Easysoft ODBC-Access Driver and configure the ODBC data source that stores the connection details for your Access database. You’re then ready to work with Access data in your application.

Installing the Easysoft ODBC-Access Driver

Install the Easysoft ODBC-Access Driver on the computer where the application you want to connect to Access is running.

Installing on Linux or UNIX

The installation can be done by anyone with root access.

  1. Download the Easysoft ODBC-Access Driver distribution for your client application platform.

    If your client application is 64-bit, choose the 64-bit driver distribution form the Platforms list. If your client application is 32-bit, choose the 32-bit driver distribution form the Platforms list.

  2. Copy the distribution to a temporary directory on the machine where the application you want to connect to Access is installed.

  3. Unpack the distribution and cd into the resultant directory.

  4. As root, run:

    ./install

  5. Follow the onscreen instructions to progress through the installation.

Further information

Preinstallation requirements

To install the Easysoft ODBC-Access Driver you need:

  • The Bourne shell in /bin/sh. If your Bourne shell is not located there, you may need to edit the first line of the installation script.

  • Various commonly used commands such as:

    grep, awk, test, cut, ps, sed, cat, wc, uname, tr, find, echo, sum, head, tee, id

If you do not have any of these commands, they can usually be obtained from the Free Software Foundation. As the tee command does not work correctly on some systems, the distribution includes a tee replacement.

  • Depending on the platform, you’ll need up to 10 MB of temporary space for the installation files and up to 10 MB of free disk space for the installed programs. If you also install the unixODBC Driver Manager, these numbers increase by approximately 1.5 MB.

  • For Easysoft licensing to work, you must do one of the following:

    • Install the Easysoft ODBC-Access Driver in /usr/local/easysoft.

    • Install the Easysoft ODBC-Access Driver elsewhere and symbolically link /usr/local/easysoft to wherever you chose to install the software.

The installation will do this automatically for you so long as you run the installation as someone with permission to create /usr/local/easysoft.

  • Install the Easysoft ODBC-Access Driver elsewhere and set the EASYSOFT_ROOT environment variable. For more information about setting the EASYSOFT_ROOT environment variable, refer to Post installation steps for non-root installations.

    • An ODBC Driver Manager.

Easysoft ODBC-Access Driver distributions include the unixODBC Driver Manager.

  • You do not have to be the root user to install, but you will need permission to create a directory in the chosen installation path. Also, if you are not the root user, it may not be possible for the installation to:

    1. Register the Easysoft ODBC-Access Driver with unixODBC.

    2. Create the example data source in the SYSTEM odbc.ini file.

    3. Update the dynamic linker entries (some platforms only).

If you are not root, these tasks will have to be done manually later.

We recommend that you install all components as the root user.

What you can install

This distribution contains:

  • The Easysoft ODBC-Access Driver.

  • The unixODBC Driver Manager.

You need an ODBC Driver Manager to use the Easysoft ODBC-Access Driver from your applications. The distribution therefore contains the unixODBC Driver Manager. Most (if not all) UNIX and Linux applications support the unixODBC Driver Manager. For example, Perl DBD::ODBC, PHP, Python, and so on.

You do not have to install the unixODBC Driver Manager included with this distribution. You can use an existing copy of unixODBC. For example, a version of unixODBC installed by another Easysoft product, a version obtained from your operating system vendor or one that you built yourself. However, as Easysoft ensure that the unixODBC distributed with the Easysoft ODBC-Access Driver has been tested with that driver, we recommend you use it.

If you choose to use an existing unixODBC Driver Manager, the installation script will attempt to locate it. The installation script looks for the ODBC Driver Manager in the standard places. If you have installed it in a non-standard location, the installation script prompts you for the location. The installation primarily needs unixODBC’s odbcinst command to install drivers and data sources.

Where to install

This installation needs a location for the installed files. The default location is /usr/local.

At the start of the installation, you’re prompted for an installation path. All files are installed in a subdirectory of your specified path called easysoft. For example, if you accept the default location /usr/local, the product will be installed in /usr/local/easysoft and below.

If you choose a different installation path, the installation script tries to symbolically link /usr/local/easysoft to the easysoft subdirectory in your chosen location. This allows us to distribute binaries with built in dynamic linker run paths. If you are not root or the path /usr/local/easysoft already exists and is not a symbolic link, the installation will be unable to create the symbolic link. For information about how to correct this manually, refer to Post installation steps for non-root installations.

Note that you cannot license Easysoft products until either of the following is true:

  • /usr/local/easysoft exists either as a symbolic link to your chosen installation path or as the installation path itself.

  • You have set EASYSOFT_ROOT to installation_path/easysoft.

Changes made to your system

The installation script installs files in subdirectories of the path requested at the start of the installation, Depending on what is installed, a few changes may be made to your system:

  1. If you choose to install the Easysoft ODBC-Access Driver into unixODBC, unixODBC’s odbcinst command will be run to add an entry to your odbcinst.ini file. You can locate this file with odbcinst -j. (odbcinst is in installation_path/easysoft/unixODBC/bin, if you are using the unixODBC included with this distribution.)

  2. The installation script installs an example data source into unixODBC. This data source will be added to your SYSTEM odbc.ini file. You can locate your SYSTEM odbc.ini file by using odbcinst -j. The data source will look similar to this:

  3. Dynamic linker. On operating systems where the dynamic linker has a file listing locations for shared objects (Linux and FreeBSD), the installation script will attempt to add paths under the path you provided at the start of the installation to the end of this list.

    • On Linux, this is usually the file /etc/ld.so.conf.

    • On FreeBSD this is usually the file /etc/defaults/rc.conf.

Installing alongside other existing Easysoft product installations

Each Easysoft distribution contains common files shared between Easysoft products. These shared objects are placed in installation_path/easysoft/lib. When you run the installation script, the dates and versions of these files are compared with the same files in the distribution. The files are only updated if the files being installed are newer or have a later version number.

You should ensure that nothing on your system is using Easysoft software before starting an installation. This is because on some platforms, files in use cannot be replaced. If a file cannot be updated, you get a warning during the installation. All warnings are written to a file called warnings in the directory you unpacked the distribution into.

If the installer detects you’re upgrading a product, the installer will suggest you delete the product directory to avoid having problems with files in use. An alternative is to rename the specified directory.

If you are upgrading, you will need a new license from Easysoft to use the new driver.

Gathering information required during the installation

During the installation, you’re prompted for various pieces of information. Before installing, you need to find out whether you have unixODBC already installed and where it is installed. The installation script searches standard places like /usr and /usr/local.

However, if you installed the Driver Manager in a non-standard place and you do not install the included unixODBC, you will need to know the location.

Unpacking the distribution The distribution for UNIX and Linux platforms is a tar file. To extract the installation files from the tar file, use:

tar -xvf odbc-access-1.4.0-linux-x86-64-ul64.tar.tar

This creates a directory with the same name as the tar file (without the .tar postfix) containing further archives, checksum files, an installation script and various other installation files.

Change into the directory created by unpacking the tar file to run the installation script. For example:

# cd odbc-access-1.4.0-linux-x86-64-ul64.tar

License to use

The end-user license agreement (EULA) is in the file license.txt. Be sure to understand the terms of the agreement before continuing, as you’re required to accept the license terms at the start of the installation.

Answering questions during the installation

Throughout the installation, you’re prompted to answer some questions. In each case, the default choice displays in square brackets and you need only press Enter to accept the default. If there are alternative responses, these are shown in round brackets; to choose one of these, type the response and press Enter.

For example:

Do you want to continue? (y/n) [n]:

The possible answers to this question are y or n. The default answer when you type nothing and press Enter is n.

Running the installer

If you are considering running the installation as a non root user, we suggest you review this carefully as you will have to get a root user to manually complete some parts of the installation afterwards. We recommend installing as the root user. (If you’re concerned about the changes that will be made to your system, refer to Changes made to your system.)

To start the installation, run:

./install

You need to:

  • Confirm your acceptance of the license agreement by typing "yes" or "no". For more information about the license agreement, refer to License to use.

  • Supply the location where the software is to be installed.

We recommend accepting the default installation path.

For more information, refer to Where to install.

Locating or installing unixODBC

We strongly recommend you use the unixODBC Driver Manager because:

  • The installation script is designed to work with unixODBC and can automatically add Easysoft ODBC-Access Driver and data sources during the installation.

  • Most applications and interfaces that support ODBC are compatible with unixODBC. The Easysoft ODBC-Access Driver and any data sources that you add during the installation are automatically available to your applications and interfaces therefore.

  • The unixODBC project is currently led by Easysoft developer Nick Gorham. This means that there is a great deal of experience at Easysoft of unixODBC in general and of supporting the Easysoft ODBC-Access Driver running under unixODBC. It also means that if you find a problem in unixODBC, it’s much easier for us to facilitate a fix.

The installation starts by searching for unixODBC. There are two possible outcomes here:

  1. If the installation script finds unixODBC, the following message displays:

    Found unixODBC under path and it is version n.n.n

  2. If the installation script can’t find unixODBC in the standard places, you will be asked whether you have it installed.

If unixODBC is installed, you need to provide the unixODBC installation path. Usually, the path required is the directory above where odbcinst is installed. For example, if odbcinst is in /opt/unixODBC/bin/odbcinst, the required path is /opt/unixODBC.

If unixODBC is not installed, you should install the unixODBC included with this distribution.

If you already have unixODBC installed, you do not have to install the unixODBC included with the distribution, but you might consider doing so if your version is older than the one we provide.

The unixODBC in the Easysoft ODBC-Access Driver distribution is not built with the default options in unixODBC’s configure line.

Option Description

--prefix=/etc

This means the default SYSTEM odbc.ini file where SYSTEM data sources are located is /etc/odbc.ini.

--enable-drivers=no

This means other ODBC drivers that come with unixODBC are not installed.

--enable-iconv=no

This means unixODBC does not look for libiconv. Warnings about not finding an iconv library were confusing our customers.

--enable-stats=no

Turns off unixODBC statistics, which use system semaphores to keep track of used handles. Many systems do not have sufficient semaphore resources to keep track of used handles.

--enable-readline=no

This turns off readline support in isql. We did this because it ties isql to the version of libreadline on the system we build on. We build on as old a version of the operating system as we can for forward compatibility. Many newer Linux systems no longer include the older readline libraries and so turning on readline support makes isql unusable on these systems.

--prefix=/usr/local/easysoft/unixODBC

This installs unixODBC into /usr/local/easysoft/unixODBC.

Installing the Easysoft ODBC driver

The Easysoft ODBC-Access Driver installation script:

  • Installs the driver.

  • Registers the driver with the unixODBC Driver Manager.

    If the Easysoft ODBC-Access Driver is already registered with unixODBC, a warning displays that lists the drivers unixODBC knows about. If you’re installing the Easysoft ODBC-Access Driver into a different directory than it was installed before, you need to edit your odbcinst.ini file after the installation and correct the Driver and Setup paths. unixODBC’s odbcinst doesn’t update these paths if a driver is already registered.

  • Creates an example Easysoft ODBC-Access Driver data source. If unixODBC is installed and you registered the Easysoft ODBC-Access Driver with unixODBC, the installation script adds example data source to your odbc.ini file.

Licensing

The installation_path/easysoft/license/licshell program lets you obtain or list licenses.

Licenses are stored in installation_path/easysoft/license/licenses.

After obtaining a license, you should make a backup copy of this file.

The installation script asks you if you want to request an Easysoft ODBC-Access Driver license:

Would you like to request a Easysoft ODBC-Access Driver license now (y/n) [y]:

You do not need to obtain a license during the installation, you can run licshell after the installation to obtain or view licenses.

If you answer y, the installation runs the licshell script.

To obtain a license automatically, you need to be connected to the Internet and allow outgoing connections to license.easysoft.com on port 8884. If you’re not connected to the Internet or don’t allow outgoing connections on port 8884, the License Client can create a license request file that you can email to us.

When you start the License Client, the following menu displays:

[0] exit
[1] view existing license
[n] obtain a license for the desired product.

To obtain a license, select one of the options from [2] onwards for the product you’re installing. The License Client then runs a program that generates a key that’s used to identify the product and operating system (we need this key to license you).

After you have chosen the product to license (Easysoft ODBC-Access Driver), you need to supply:

  • Your full name.

  • Your company name.

  • An email contact address. This must be the email address that you used when you registered on the Easysoft web site.

  • A reference number (also referred to as an authorization code). When applying for a trial license, press Enter when prompted for a reference number. This field only applies to full (paid) licenses.

You’re then asked to choose how you want to obtain the license.

The choices are:

  • [1] Automatically by contacting the Easysoft License Daemon

    This requires a connection to the Internet and the ability to support an outgoing TCP/IP connection to license.easysoft.com on port 8884.

  • [2] Write information to file

    The license request is output to license_request.txt.

  • [3] Cancel this operation

If you choose to obtain the license automatically, the License Client true to open a TCP/IP connection to license.easysoft.com on port 8884 and send the details you supplied along with your machine number. No other data is sent. The data sent is transmitted as plain text, so if you want to avoid the possibility of this information being intercepted by someone else on the Internet, you should choose [2] and send the the request to us. The License daemon returns the license key, print it to the screen and make it available to the installation script in the file licenses.out.

If you choose option [2], the license request is written to the file license_request.txt. You should then exit the License Client by choosing option [0] and complete the installation. After you have sent the license request to us, we’ll return a license key. Add this to the end of the file installation_path/easysoft/license/licenses.

Post installation steps for non-root installations

If you installed the Easysoft ODBC-Access Driver as a non-root user (not recommended), there may be some additional steps you to do manually:

  1. If you attempt to install the Easysoft ODBC-Access Driver under the unixODBC Driver Manager and you do not have write permission to unixODBC’s odbcinst.ini file, the driver can’t be added.

    You can manually install the driver under unixODBC by adding an entry to the odbcinst.ini file. Run odbcinst -j to find out the location of the DRIVERS file then append the lines from drv_template file to odbcinst.ini. (drv_template is in the directory where the Easysoft distribution was untarred to.)

  2. No example data sources can be added into unixODBC if you do not have write permission to the SYSTEM odbc.ini file. Run odbcinst -j to find out the location of the SYSTEM DATA SOURCES file then add your data sources to this file.

  3. On systems where the dynamic linker has a configuration file defining the locations where it looks for shared objects (Linux and FreeBSD), you need to add:

    installation_path/easysoft/lib
installation_path/easysoft/unixODBC/lib

    The latter entry is only required if you installed the unixODBC included with this distribution. Sometimes, after changing the dynamic linker configuration file, you need to run a program to update the dynamic linker cache. (For example, /sbin/ldconfig on Linux.)

  4. If you didn’t install the Easysoft ODBC-Access Driver in the default location, you need to do one of the following:

    • Link /usr/local/easysoft to the easysoft directory in your chosen installation path.

      For example, if you installed in /home/user, the installation creates /home/user/easysoft and you need to symbolically link /usr/local/easysoft to /home/user/easysoft:

      ln -s /home/user/easysoft /usr/local/easysoft

    • Set and export the EASYSOFT_ROOT environment variable to installation_path/easysoft.

  5. If your system doesn’t have a dynamic linker configuration file, you need to add the paths listed in step 3 to whatever environment path the dynamic linker uses to locate shared objects. You may want to add these paths to a system file run whenever someone logs. For example, /etc/profile.

    The environment variable depends on the dynamic linker. Refer to your ld or ld.so man page. It is usually:

    LD_LIBRARY_PATH, LIBPATH, LD_RUN_PATH, or SHLIB_PATH.

Uninstalling on Linux or UNIX

There is no automated way to remove the Easysoft ODBC-Access Driver in this release. However, removal is quite simple. To do this:

  1. Change directory to installation_path/easysoft and delete the product directory. installation_path is the Easysoft ODBC-Access Driver installation directory, by default /usr/local.

  2. If you had to add this path to the dynamic linker search paths (for example, /etc/ld.so.conf on Linux), remove it. You may have to run a linker command such as /sbin/ldconfig to get the dynamic linker to reread its configuration file. Usually, this step can only be done by the root user.

  3. If you were using unixODBC, the Easysoft ODBC-Access Driver entry needs to be removed from the odbcinst.ini file. To check whether the Easysoft ODBC-Access Driver is configured under unixODBC, use odbcinst -q -d. If the command output contains [Easysoft ODBC-ACCESS], uninstall the driver from unixODBC by using:

    odbcinst -u -d -n Easysoft ODBC-ACCESS

If a reduced usage count message is displayed, repeat this command until odbcinst reports that the driver has been removed.

  1. If you created any Easysoft ODBC-Access Driver data sources under unixODBC, you may want to delete these. To do this, first use odbcinst -j to locate USER and SYSTEM odbc.ini files. Then check those files for data sources that have the driver attribute set to Easysoft ODBC-ACCESS.

  2. Remove the install.info for the Easysoft ODBC-Access Driver from the /usr/local/easysoft directory.

Connecting to Access

Applications that support ODBC interface with an ODBC Driver Manager, which is included with the operating system, and also the Easysoft ODBC driver distribution on some platforms. One of the jobs that the ODBC Driver Manager does is to manage ODBC data sources. A data source specifies which ODBC driver to load, which data store to connect to, and how to connect to it.

Before setting up a data source, you must have successfully installed the Easysoft ODBC-Access Driver.

Connecting from Linux or UNIX

Creating an ODBC data source

There are two ways to create a data source to your Access data:

  • Create a SYSTEM data source, which is available to anyone who logs on to the computer where the Easysoft ODBC-Access Driver is installed.

    – Or –

  • Create a USER data source, which is only available to the user who is currently logged on to the computer where the Easysoft ODBC-Access Driver is installed.

By default, the Easysoft ODBC-Access Driver installation creates a sample SYSTEM data source named ACCESS_SAMPLE. If you’re using the unixODBC included in the Easysoft ODBC-Access Driver distribution, the SYSTEM odbc.ini file is in /etc.

If you built unixODBC yourself, or installed it from some other source, SYSTEM data sources are stored in the path specified with the configure option --sysconfdir=directory. If sysconfdir was not specified when unixODBC was configured and built, it defaults to /usr/local/etc.

If you accepted the default choices when installing the Access, USER data sources must be created and edited in $HOME/.odbc.ini.

Notes

  • To display the directory where unixODBC stores SYSTEM and USER data sources, type odbcinst -j.

  • By default, you must be logged in as root to edit a SYSTEM data source defined in /etc/odbc.ini.

You can either edit the sample data source or create new data sources.

Each section of the odbc.ini file starts with a data source name in square brackets [ ] followed by a number of attribute=value pairs.

The Driver attribute identifies the ODBC driver in the odbcinst.ini file to use for a data source. When the Easysoft ODBC-Access Driver is installed into unixODBC, it places a Easysoft ODBC-ACCESS entry into the odbcinst.ini file. You should always have Driver = Easysoft ODBC-ACCESS in your Easysoft ODBC-Access Driver data sources therefore.

To configure a Easysoft ODBC-Access Driver data source, in your odbc.ini file, you need to specify:

  • The path to the Access database file (.mdb or .accdb).

For example:

[ACCESS_SAMPLE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /home/myuser/ms-access/Northwind.mdb

The Easysoft ODBC-Access Driver must be able to find the following shared objects:

  • libodbcinst.so

    By default, this is located in /usr/local/easysoft/unixODBC/lib/libodbcinst.so.

  • libeslicshr.so

    By default, this is located in /usr/local/easysoft/lib/libeslicshr.so.

  • libessupp.so By default, this is located in /usr/local/easysoft/lib/libessupp.so.

You may need to set and export LD_LIBRARY_PATH, SHLIB_PATH, or LIBPATH (depending on your operating system and run-time linker) to include the directories where libodbcinst.so, libeslicshr.so, and libessupp.so are located.

The isql query tool lets you test your Easysoft ODBC-Access Driver data sources. To test the Easysoft ODBC-Access Driver connection:

  1. Change directory into /usr/local/easysoft/unixODBC/bin.

  2. Enter ./isql -v data_source, where data_source is the name of the target data source.

  3. At the prompt, enter an SQL query. For example:

    SQL> SELECT * FROM Suppliers;

    –Or–

  4. Enter help to return a list of tables:

    SQL> help

Connection attributes

Setting on Linux and UNIX

To configure an Access data source, in your odbc.ini file, you need to specify:

  • The path to the Access database file (.mdb or .accdb).

For example:

[ACCESS_SAMPLE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /home/myuser/ms-access/Northwind.mdb

-Or-

[ACCESS_SAMPLE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /home/myuser/ms-access/Northwind.accdb

If you’re using the Easysoft ODBC-Access Driver to open an database file that Windows users may also be accessing, specify these settings:

  • The SMB URL for the database file.

  • The path to the SMB client library on the Easysoft ODBC-Access Driver machine.

  • The user name and password of a user who can access the Windows or Samba share where the database file is located.

For example:

[ACCESS_SAMPLE_WINDOWS_SHARE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /mnt/accounts/access/Northwind.mdb
smbpath = smb://mswin_machine/accounts/access/Northwind.mdb
smblib = /usr/lib/libsmbclient.so
smbuser = mywindows_user
smbauth = mywindows_password

-Or-

[ACCESS_SAMPLE_SAMBA_SHARE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /home/samba/sales/access/Northwind.mdb
smbpath = smb://samba_server/sales/access/Northwind.mdb
smblib = /usr/lib/libsmbclient.so
smbuser = my_samba_share_valid_user
smbauth = my_samba_share_valid_password

For more information about the Easysoft ODBC-Access Driver’s data source attributes, refer to the following table.

Name Value

Description

Some applications display this to help users identify a particular data source.

mdbfile = value

The path to the Access database file (.mdb or .accdb) on the computer where the Easysoft ODBC-Access Driver is installed.

If the database file is stored on the same computer as the Easysoft ODBC-Access Driver, specify the path to the database file. For example:

# Path to .mdb file stored on
# Easysoft ODBC-Access Driver computer.
mdbfile = /home/myuser/ms_access/Northwind.mdb

-Or-

# Path to .accdb file stored on
# Easysoft ODBC-Access Driver computer.
mdbfile = /home/samba/ms_access/Northwind.accdb

If the database file is stored on a Windows computer, you need to share the directory where the file is located and then mount the Windows share from the Easysoft ODBC-Access Driver computer. Specify the mounted share’s path with mdbfile, along with the remote database file name. For example:

# Local path to .mdb file stored on
# Windows. /mnt/access_windows is local mount
# point for a remote Windows share.
mdbfile = /mnt/access_windows/Northwind.mdb.

dbq = value

The path to the Access database file (.mdb or .accdb) on the computer where the Easysoft ODBC-Access Driver is installed.

The dbq attribute is an alternative to the mdbfile attribute, and is provided for symmetry with Microsoft’s Access ODBC driver. You don’t need to specify both the dbq and mdbfile attributes in your data source.

smbpath = value

The SMB URL for the database file. This attribute (along with smblib, smbuser, and smbauth) is required when you open a database file that Windows users may also be accessing.

When you specify a SMB URL, the Easysoft ODBC-Access Driver uses the libsmbclient library to: let Windows know that it has opened a database file; prevent Windows users from opening a database file it has opened for exclusive access. Without this mechanism, there is the potential for database file corruption when Windows users and Easysoft ODBC-Access Driver users are working simultaneously with same the database.

Use this syntax for the SMB URL:

smb://host/share/path/filename

where:

host is the name or IP address of the computer on which the share is located.

share is the share name.

path specifies any subdirectories under share.

filename is the database file name, which should be the same one as specified by the mdbfile attribute.

For example:

# SMB URL for a .mdb file shared by a Windows computer.
smbpath = smb://mswin_box/accounts/access/Northwind.mdb

# SMB URL for a .accdb file shared from a UNIX
# computer through Samba server.
smbpath = smb://unix_box/sales/access/Northwind.accdb

Note that SMB URLs for Samba shares are case sensitive; SMB URLs for Windows shares are not case sensitive.

smblib = value

The path to the libsmbclient library on the computer where the Easysoft ODBC-Access Driver is installed. For example:

smblib = /usr/lib/libsmbclient.so

libsmbclient is part of the Samba suite.

The Easysoft ODBC-Access Driver uses libsmbclient to:

  • Allow Linux and Unix users to safely edit a database file that Windows users may also be accessing.

  • Prevent Windows users from opening a database file it has opened for exclusive access.

  • Prevent users from locking records in Windows that are already locked in the Easysoft driver and vice versa.

smbuser = value

The name of a user who can access the share where the database file is located.

If the database file is stored on a Samba share, specify a Samba user.

If the database file is stored on a Windows share, specify a Windows user.

The user must have either read or read-write permissions for the share. If the user only has read access to the share, set the readonly data source attribute to yes.

smbauth = value

The password for smbuser.

lockfile = value

By default, when you open a database file for shared access, the Easysoft ODBC-Access Driver uses a locking information file named dbfiledir/dbfilename.ldb. For example, if you open a database named Nwind.mdb, the Easysoft ODBC-Access Driver expects a locking information file named Nwind.ldb in the same directory as Nwind.mdb.

Use the lockfile attribute to specify an alternative .ldb file path if directory permissions prevent the Easysoft ODBC-Access Driver from manipulating a .ldb file in the default directory. Specify a directory where all users who connect to this data source have write access to. For example:

lockfile = /tmp/Nwind.ldb

Don’t use the lockfile attribute if users may access the database file from Windows at your site. Windows applications access database files through the Jet or Access database engine, which expects the dbfiledir/dbfilename.ldb convention for lock files. There must only be one lock file per database file.

readonly = yes | no

To open the database file for read-only access, set readonly to yes. When opened for read-only access, you can view the Access database, but not change it.

By default, readonly is set to no, which means the Easysoft ODBC-Access Driver opens the database for read-write access.

If you open a database for read-write access without setting the smb* data source attributes, the Easysoft ODBC-Access Driver returns the warning:

read write access without SMB channel can potentially allow corruption of the MDB file

The Easysoft ODBC-Access Driver uses the smb* attributes to allow users to safely edit a database file that Windows users may also be accessing. If your database is shared with Windows users, configure the smb* attributes before opening the database for read-write access. Otherwise, set readonly to yes.

double_precision = num

The decimal precision to return for a DOUBLE column that’s bound as a char. For example:

double_precision = 15

Set this attribute if DOUBLE column data returned by the Easysoft ODBC-Access Driver does not have the expected number of decimal places.

exclusive = yes | no

To open the database file for exclusive access, set exclusive to yes. By default, exclusive is set to no.

Notes for libsmbclient users

When you set exclusive to yes, the Easysoft ODBC-Access Driver uses libsmbclient to the mark the database as share mode DENY_ALL. This share mode denies all open requests on the database file, which prevents other users from opening the database while you are connected to the Easysoft ODBC-Access Driver data source.

Using share mode DENY_ALL is the only way to prevent Windows users from opening a database that you have opened for exclusive access with the Easysoft ODBC-Access Driver.

To enable the Easysoft ODBC-Access Driver to use libsmbclient, you need to set the smb* attributes in the data source. If you set exclusive to yes without setting the smb* attributes, the Easysoft ODBC-Access Driver cannot prevent other users from opening the database and so returns the warning:

exclusive access without SMB channel can not exclude other access, and can potentially allow corruption of the MDB file

Notes for non-libsmbclient users

Setting exclusive to yes prevents other Easysoft ODBC-Access Driver users from opening the database file while you’re connected to the Easysoft ODBC-Access Driver data source.

ignore_rel = yes | no

Whether the Easysoft ODBC-Access Driver takes into account any relationships defined for a particular table when doing inserts, updates, or deletes. For example, with ignore_rel set to yes, the Easysoft ODBC-Access Driver would prevent a record from being deleted if one of its columns was a foreign key for another table.

By default, ignore_rel is set to no.

work_mem_size = value

The size of the memory cache, in megabytes (MB), where the Easysoft ODBC-Access Driver will store rows before storing them on disk.

For example:

work_mem_size = 10

work_dir_path = value

The directory where the Easysoft ODBC-Access Driver temporarily stores result set rows when work_mem_size is exceeded.

For example:

work_dir_path = /tmp

htime_pattern = value

Use htime_pattern to specify the format used for hash (#) quoted date constants in queries. Available formats are:

MDY (month/day/year)
DMY (day/month/year)
YMD (year/month/day)

For example:

htime_pattern = MDY

unicode_map = 0 | 1 | 2

How Easysoft ODBC-Access Driver maps 16-bit characters to 8-bit characters.

The unicode_map attribute affects: TEXT, MEMO, and HYPERLINK data in result sets; metadata (column names); DELETE, INSERT INTO, UPDATE statements (TEXT columns only); SQL statement parameters.

Use unicode_map if you experience data loss or corruption when working with character data.

The available values for the unicode_map attribute are:

0 When retrieving data, the Easysoft ODBC-Access Driver preserves the low 8 bits of the encoded character and discards the high 8 bits. When unicode_map is set to 0, some applications may replace non-ASCII characters retrieved from the Access database with question marks (?).

1 When retrieving data, the Easysoft ODBC-Access Driver preserves ASCII characters and replaces non-ASCII characters with question marks. For example, Forêts d’érables becomes For?ts d'?rables.

2 The Easysoft ODBC-Access Driver converts characters to UTF-8 when retrieving data and from UTF-8 when submitting data (for example, inserting data into TEXT columns).

By default, unicode_map is set to 0.

Connection examples

In this section:

Connecting to an Access database on Windows from Linux

  1. On the Easysoft ODBC-Access Driver machine, use smbmount to mount the Windows share where the database file is located.

    For example:

    # smbmount //mywindowsmachine/myshare /mylinuxmountpoint -o username=mywindowsuser,rw,directio
    For read-write access to the database, you must specify the directio option when mounting the share. Check the man page for your version of smbmount to find out whether it supports the directio option. Specifying directio turns off inode data caching on files opened on the mount. The Easysoft ODBC-Access Driver relies on this functionality when managing concurrent access to the database file.

    When mounting the share, you need to supply the user name and password of a Windows user who has read, write, create and delete privileges for the share. When testing the Easysoft ODBC-Access Driver with a database file located in a Windows share, this requirement equated to these Windows permissions:

    Name Value

    Share permissions

    Shared folder permissions

    Change

    Read

    Modify Read Write

    These permissions allow the Easysoft ODBC-Access Driver to write to or create a locking information file (.ldb).

  2. Configure the Easysoft ODBC-Access Driver data source.

    Example data sources:

    # This Easysoft ODBC-Access Driver data source opens an Access
# database that is stored on a Windows share. The data source
# opens the database for shared read/write access; other users can
# open the database therefore.
[ACCESS_SAMPLE_WINDOWS_SHARE]
Driver = Easysoft ODBC-ACCESS

# The Windows share (accounts) has been attached under /mnt on the
# Easysoft ODBC-Access Driver machine.
mdbfile = /mnt/accounts/access/Northwind.mdb

# The smb* attributes allow the Easysoft ODBC-Access Driver to
# manage concurrent access to the database.
# The SMB URL for the database on the Windows share.
smbpath = smb://mswin_machine/accounts/access/Northwind.mdb

# The path to the SMB client library on the
# Easysoft ODBC-Access Driver machine
smblib = /usr/lib/libsmbclient.so

# The user name and password of a Windows user who has read and
# write privileges to the share.
smbuser = mywindows_user
smbauth = mywindows_password

# Opens the database for shared read/write access.
readonly = no
exclusive = no

    -Or-

    # This data source opens the same Access database for exclusive
# access; the Easysoft ODBC-Access Driver will prevent other
# users from accessing the database, therefore.
[ACCESS_SAMPLE_WINDOWS_SHARE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /mnt/accounts/access/Northwind.mdb
smbpath = smb://mswin_machine/accounts/access/Northwind.mdb
smblib = /usr/lib/libsmbclient.so

# The user name and password of a Windows user who can access the
# share and who has read and write privileges to the .mdb file.
smbuser = mywindows_user
smbauth = mywindows_password

# Opens the database for exclusive read/write access.
readonly = no
exclusive = yes

    -Or-

    # This data source opens the same Access database for read-only
# access; the Easysoft ODBC-Access Driver will prevent its users
# from making updates to the database, therefore.
[ACCESS_SAMPLE_WINDOWS_SHARE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /mnt/accounts/access/Northwind.mdb
smbpath = smb://mswin_machine/accounts/access/Northwind.mdb
smblib = /usr/lib/libsmbclient.so

# The user name and password of a Windows user who has read
# privilege to the share.
smbuser = mywindows_user
smbauth = mywindows_password

# Opens the database for read-only access.
readonly = yes
exclusive = no

    For more information about Easysoft ODBC-Access Driver data source attributes, refer to Connection attributes.

Connecting to an Access database located on a Samba share

  1. Copy the Access database file to a Samba share on the Easysoft ODBC-Access Driver machine.

    The Easysoft ODBC-Access Driver requires the following Samba configuration options to be set for the share in which the database file is located.

    Option Value

    oplocks

    yes

    This is the default setting.

    posix locking

    yes

    This is the default setting.

    blocking locks

    yes

    This is the default setting.

    veto oplock files

    /.mdb/.MDB/.ldb/.LDB/.accdb/.ACCDB

  2. Configure the Easysoft ODBC-Access Driver data source.

    Example data sources:

    # This Easysoft ODBC-Access Driver data source opens an Access
# database that is stored on a Samba share. The data source
# opens the database for shared read/write access; other users can
# open the database therefore.
[ACCESS_SAMPLE_SAMBA_SHARE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /home/samba/sales/access/Northwind.mdb

# The smb* attributes allow the Easysoft ODBC-Access Driver to
# manage concurrent access to the database.
# The SMB URL for the database on the Samba share.
smbpath = smb://samba_server/sales/access/Northwind.mdb

# The path to the SMB client library on the
# Easysoft ODBC-Access Driver machine
smblib = /usr/lib/libsmbclient.so

# The user name and password of a Samba user who has read/write
# access to the share.
smbuser = my_samba_share_valid_user
smbauth = my_samba_share_valid_password

# Opens the database for shared read/write access.
readonly = no
exclusive = no

    -Or-

    # This data source opens the same Access database for exclusive
# access; the Easysoft ODBC-Access Driver will prevent other
# users from accessing the database, therefore.
[ACCESS_SAMPLE_SAMBA_SHARE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /home/samba/sales/access/Northwind.mdb
smbpath = smb://samba_server/sales/access/Northwind.mdb
smblib = /usr/lib/libsmbclient.so

# The user name and password of a Samba user who has read/write
# access to the share.
smbuser = my_samba_share_valid_user
smbauth = my_samba_share_valid_password

# Opens the database for exclusive read/write access.
readonly = no
exclusive = yes

    -Or-

    # This data source opens the same Access database for read-only
# access; the Easysoft ODBC-Access Driver will prevent its users
# from making updates to the database, therefore.
[ACCESS_SAMPLE_SAMBA_SHARE]
Driver = Easysoft ODBC-ACCESS
mdbfile = /home/samba/sales/access/Northwind.mdb
smbpath = smb://samba_server/sales/access/Northwind.mdb
smblib = /usr/lib/libsmbclient.so

# The user name and password of a Samba user who has read
# access to the share.
smbuser = my_samba_share_valid_user
smbauth = my_samba_share_valid_password

# Opens the database for read-only access.
readonly = yes
exclusive = no

Troubleshooting database connection problems

This section lists some common connection problems and their solutions.

Failed to open MDB file

The Easysoft ODBC-Access Driver can open either a local or remote Access database file (.mdb or .accdb). The path to the database file is specified in the Easysoft ODBC-Access Driver data source in /etc/odbc.ini.

In the Easysoft ODBC-Access Driver data source, check the mdbfile attribute value.

Use ls to check that the mdbfile attribute in your data source specifies a valid path and that the directory is accessible.

If the ls command output contains "permission denied", contact your administrator. The directory containing the database file needs to be accessible (execute permission set) to you.

If the path is not valid, check with your administrator whether the database file is located on another machine. (The Easysoft ODBC-Access Driver can open a database file that is located on a Windows share.) If the database file is remote, use the mount command to check whether the share has been attached on the Easysoft ODBC-Access Driver machine. There should be an entry in the mount command output that corresponds with the directory specified with mdbfile. For example:

$ mount
/dev/sda3 on / type ext3 (rw,errors=remount-ro)
proc on /proc type proc (rw,noexec,nosuid,nodev)
/sys on /sys type sysfs (rw,noexec,nosuid,nodev)
.
.
.
//mywindowsmachine/myshare on /mnt/myshare type smbfs (rw)

$ grep mdbfile /etc/odbc.ini
mdbfile = /mnt/myshare/Northwind.mdb

If the mount command does not show the mount point specified in the mdbfile attribute, consult with your administrator. The share on which the database file is located needs to be mounted.

If the database file is on a Windows share, the user specified when mounting the share needs to have read, write, create, and delete permissions for the share. When testing the Easysoft ODBC-Access Driver with a database file located in a Windows share, this requirement equated to these Windows permissions:

Share permissions Shared folder permissions

Change

Read

Modify

Read

Write

If the database file is located on UNIX, the Easysoft ODBC-Access Driver will also return a "Failed to open MDB file" if:

  1. The user running the application that is connecting to the data source only has read access to a local database file.

    -Or-

    The user specified by smbuser only has read access to a database file located on a Samba share.

  2. The readonly attribute in the data source is set to yes. (Change this attribute’s value to no and try again.)

Failed to open SMB channel

The Easysoft ODBC-Access Driver uses the libsmbclient library, which is part of the Samba suite, to:

  • Let Windows know that it has opened a database file (.mdb or .accdb).

  • Prevent Windows users from opening a database file it has opened for exclusive access.

Without this mechanism, there is the potential for database file corruption when Windows users and Easysoft ODBC-Access Driver users are working with the database specified by mdbfile.

To configure the driver for use with libsmbclient you use the smb* attributes in the driver data source.

If the "Failed to open SMB channel" error contains "file not found", check the smbpath attribute in the data source. The smbpath attribute needs to specify the SMB URL for the database file specified with mdbfile. The SMB URL has the format smb://host/share/path/filename.

In the following example, a remote Access database named Northwind.mdb is located on the Easysoft ODBC-Access Driver machine in /mnt/myshare_mountdir. The mount command shows that /mnt/myshare_mountdir is the mount point for a share named myshare on a machine named myremotemachine.

$ grep mdbfile /etc/odbc.ini
mdbfile = /mnt/myshare_mountdir/Northwind.mdb

$ mount
//myremotemachine/myshare on /mnt/myshare_mountdir type smbfs (rw)

The SMB URL for the database file would therefore be:

smb://myremotemachine/myshare/Northwind.mdb

If the "Failed to open SMB channel" error contains "errno=13", check the smbuser and smbauth attributes in the data source.

If the database file is located on a Samba share, the smbuser and smbauth attributes need to specify the user name and password for a Samba user (created with Samba tools such as smbpasswd) who has read access to the share. To open a database file for read-write access (readonly data source attribute set to no), the Samba user also needs write access to the share).

If the database file is located in a Windows share, the smbuser and smbauth attributes need to specify the user name and password for a Windows user who can access the share. If smbuser only has read privilege to the database file (as opposed to read and write), the readonly attribute in the data source needs to be set to yes. Otherwise, an "errno=13" error will be returned.

Could not open/create lock file, check sharing permissions

To allow its users to safely edit a database file that Windows users may also be accessing and updating, the Easysoft ODBC-Access Driver uses a locking information file (.ldb).

The driver uses a .ldb file to:

  • Determine which records in the database are locked and by whom.

  • Let other applications know which records in the database are locked by a Easysoft ODBC-Access Driver user.

The Easysoft ODBC-Access Driver may have to create and delete a .ldb file as well as write to it. If directory permissions prevent the Easysoft ODBC-Access Driver from writing to or creating a .ldb file, the Easysoft ODBC-Access Driver may return a "Could not open/create lock file, check sharing permissions" error.

If you get this error when opening a database file that Windows users do not require access to, specify an alternative .ldb file directory with the lockfile data source attribute. Specify a directory where you and other users who connect to the data source have write access to. For example:

lockfile = /tmp/Nwind.ldb

Permissions summary

This table lists the various permissions that may need to be set to allow the Easysoft ODBC-Access Driver to open your Access database file (.mdb or .accdb).

Permission Applies to Type Notes

execute

write

database file directory

Local UNIX permissions on Easysoft ODBC-Access Driver machine

The local directory from which the database file is opened must be accessible (execute permission set) by the user who is connecting to the data source.

The local directory must also be writeable by the user who is connecting to the data source if the database file is opened for shared access (exclusive data source attribute set to no).

read

write

database file

Local UNIX permissions on Easysoft ODBC-Access Driver machine

The database file must be readable (read permission set) by the user who is connecting to the data source. If the database file is opened for read/write access (readonly data source attribute set to no), the database file must also be writeable (write permission set) by this user.

read

write

Samba share containing database file

Samba

These permissions are only applicable if the database file is located on a Samba share on UNIX.

The Samba user specified by the smbuser data source attribute needs to have read access to the share. If the database file is opened for read/write access (readonly data source attribute set to no), this user must also have write access to the share.

read

write

create

delete

Windows share containing database file

Windows

These permissions are only applicable if the database file is located on a Windows share. The Windows user whose authentication details are supplied when mounting the share needs to have read, write, create and delete privileges on the share. Note that on some versions of Windows, the create and delete privileges may be replaced by the modify privilege.

read

write

Windows share containing database file

Windows

These permissions are only applicable if the database file is located on a Windows share. The Windows user specified by the smbuser data source attribute needs to have read privilege on the share. If the database file is opened for read/write access (readonly data source attribute set to no), this user must also have write privilege.

DSN-less connections

Some applications allow you to make an ODBC connection without configuring a data source. To do this, you supply a connection string that contains the ODBC driver name and other driver-specific attribute-value pairs.

Here’s an example Easysoft ODBC-Access Driver connection string:

Driver=Easysoft ODBC-ACCESS;MDBFILE=/home/myuser/ms_access/Northwind.mdb;

For a list of the other attributes you can set in the connection string, refer to this section.

Logging

If you report an issue to us, we may ask you to turn on ODBC Driver Manager or Easysoft ODBC-Access Driver logging, to help us diagnose the cause of the issue.

To turn on logging, refer to the following sections.

If your application is a service (for example, Oracle or SQL Server), you may need to restart the service before enabling logging takes effect. To do this on Linux or UNIX, use service, systemctl, or a vendor-supplied script. To do this on Windows, use the Windows Services app.

ODBC Driver Manager logging on Linux or UNIX

For the unixODBC Driver Manager, add the following attributes to the [ODBC] section (create one if none exists) in odbcinst.ini.

Trace = Yes
TraceFile = /path/filename

For example:

[ODBC]
Trace = Yes
TraceFile = /tmp/sql.log

Ensure that the user who’s running the application to log has write permission to TraceFile (and to the directory containing it), otherwise no logging information will be produced.

Easysoft ODBC-Access Driver logging on Linux and UNIX

Driver manager trace files show all the ODBC calls an application makes, including their arguments and return values. Easysoft ODBC-Access Driver logging is specific to the Easysoft driver and is of most use when making a support call.

To turn on Easysoft ODBC-Access Driver logging, edit your ODBC data source in odbc.ini. For example:

[ACCESS_SAMPLE]
.
.
Logging = Yes
LogFile = /tmp/easysoft-odbc-driver.log

The value shown in the example specifies a log file named /tmp/easysoft-odbc-driver.log. Ensure that the user who’s running the application to log has write permission to the log file (and to the directory containing it), otherwise no logging information will be produced.