Getting started

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

Installing the Easysoft ODBC-SQL Server Driver

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

Installing on Linux or UNIX

The installation can be done by anyone with root access.

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

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

  2. Copy the distribution to a temporary directory on the machine where the application you want to connect to SQL Server 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-SQL Server 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-SQL Server Driver in /usr/local/easysoft.

    • Install the Easysoft ODBC-SQL Server 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-SQL Server 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-SQL Server 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-SQL Server 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-SQL Server Driver.

  • The unixODBC Driver Manager.

You need an ODBC Driver Manager to use the Easysoft ODBC-SQL Server 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-SQL Server 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-SQL Server 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.

  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-sqlserver-2.2.0-linux-x86-64-ul64.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-sqlserver-2.2.0-linux-x86-64-ul64

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-SQL Server Driver and data sources during the installation.

  • Most applications and interfaces that support ODBC are compatible with unixODBC. The Easysoft ODBC-SQL Server 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-SQL Server 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-SQL Server 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-SQL Server Driver installation script:

  • Installs the driver.

  • Registers the driver with the unixODBC Driver Manager.

    If the Easysoft ODBC-SQL Server Driver is already registered with unixODBC, a warning displays that lists the drivers unixODBC knows about. If you’re installing the Easysoft ODBC-SQL Server 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-SQL Server Driver data source. If unixODBC is installed and you registered the Easysoft ODBC-SQL Server 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-SQL Server Driver license:

Would you like to request a Easysoft ODBC-SQL Server 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-SQL Server 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 tries 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, prints 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.

Testing the connection to SQL Server

The Easysoft ODBC-SQL Server Driver installation lets you test the connection to SQL Server, save the connection settings in an ODBC data source and retrieve some SQL Server data. Although the installation default is to do this test, you don’t have to.

The installation guides you through the connection process step by step, using tdshelper (a diagnostic program supplied with the Easysoft ODBC-SQL Server Driver) to test the SQL Server connection and check that you can access SQL Server with your login name and password. If at any time you want to stop the test, type q at any prompt.

If you decide to skip this part of the installation, you can use tdshelper after the installation completes to check your SQL Server connection settings. The installation script installs tdshelper in the installation_path/easysoft/sqlserver/bin directory.

The installation uses tdshelper to search for SQL Server instances that are listening on your network. The results of a successful search will look similar to this:

Using /usr/local/easysoft/sqlserver/bin/tdshelper -i -c 1

==================================================================
ServerName MYSQLSERVER2022HOST Port 1433 (Default)
ServerName MYSQLEXPRESSHOST\SQLEXPRESS Port 2777
ServerName MYSQLSERVER2019HOST\MYINSTANCEI Port 1510
ServerName MYSQLSERVER2019HOST\MYINSTANCEII Port 1511
==================================================================

If you do not see the SQL Server instance that you want to connect to in the list or the list is empty, the SQL Server Browser may not be running. tdshelper uses the SQL Server Browser to find out the available SQL Server instances. If the browser is not running, the installation will be unable to use tdshelper to help you interactively connect to SQL Server and create a data source. Type q to exit and then manually create a data source after the installation completes. The installation creates a sample data source that you can use as a starting point when setting up your own Easysoft ODBC-SQL Server Driver data sources..

The example output shows that:

  • The default SQL Server instance on a computer named MYSQLSERVER2022HOST is listening on the default SQL Server TCP port 1433.

  • The default named SQL Server Express instance on a computer named MYSQLEXPRESSHOST is listening on port 2777.

  • There are two named instances running on MYSQLSERVER2019HOST. The instances are listening on ports 1510 and 1511 respectively.

If the SQL Server instance that you want to connect to is listed in the results, enter y to continue interactively creating your SQL Server data source.

If you chose to continue, enter the name (or IP address) of the computer where your SQL Server instance is running when prompted. To connect to a named instance, use the format computername\instancename. To connect to a SQL Server Express instance, use the format computername\SQLEXPRESS. To connect to a SQL Server instance that is not listening on the default port (1433), use the format computername:port.

Based on the example output shown earlier, you would enter:

  • MYSQLSERVERHOST to connect to the default instance on this computer.

  • MYSQLEXPRESSHOST\SQLEXPRESS to connect to the SQL Server Express instance.

  • MYSQLSERVER2005HOST:1510 to connect to the first named instance on this computer and MYSQLSERVER2005HOST:1511 to connect to the second.

Enter your SQL Server login name when prompted. If you usually connect to SQL Server through your Windows account, type your Windows user name. Use the format domain\username, where domain is the name of the Windows domain to which username belongs.

Otherwise, enter a valid SQL Server user name.

Enter the password for your user name when prompted.

If tdshelper can successfully connect to the SQL Server instance, a list of databases that you can access is displayed.

When setting up your SQL Server login, your database administrator will have associated a database with your login. This is the default database for the connection. The default database is listed first in the tdshelper output. If you want to connect to a different database, type the name of another databases in the list. Otherwise, press RETURN to connect to the default database.

If you want to change the language of SQL Server system messages, type one of the listed languages when prompted. Otherwise, press RETURN to accept the default language (again, this is listed first in the tdshelper output).

The Easysoft ODBC-SQL Server Driver installation has now gathered enough information to connect to SQL Server. The installation lets you save this connection information in an ODBC data source. You can use this data source to connect to SQL Server now and when the installation completes. The data source is written to your system odbc.ini file.

Finally, the installation prompts you whether to retrieve version information from the SQL Server database. The installation uses unixODBC’s isql and your new data source to do this. Note that if you chose not to license the Easysoft ODBC-SQL Server Driver earlier in the installation, skip this step. The Easysoft ODBC-SQL Server Driver needs to be licensed before it can be used to connect to a data source. When the installation has finished, you can use isql to test the data source after you have licensed the Easysoft ODBC-SQL Server Driver.

Post installation steps for non-root installations

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

  1. If you attempt to install the Easysoft ODBC-SQL Server 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-SQL Server 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.

Setting dynamic linker search paths

Your applications are linked against an ODBC Driver Manager, which loads the ODBC driver for your chosen data source. The dynamic linker needs to know where to find the ODBC Driver Manager shared object. The ODBC Driver Manager loads the Easysoft ODBC-SQL Server Driver, which is dependent on further common Easysoft shared objects; the dynamic linker needs to locate these too.

On operating systems where the dynamic linker has a file specifying locations for shared objects (Linux, for example), the installation attempts to add paths under the path you provided at the start of the installation to the end of this list; no further action should be required.

On other UNIX platforms, there are two methods of telling the dynamic linker where to look for shared objects:

  1. You add the search paths to an environment variable and export it.

    This method always works and overrides the second method, described below.

  2. At build time, a run path is inserted into the executable or shared objects. On most System V systems, Easysoft distribute Easysoft ODBC-SQL Server Driver shared objects with an embedded run path. The dynamic linker uses the run path to locate Easysoft ODBC-SQL Server Driver shared object dependencies.

For the first method, the environment variable you need to set depends on the platform (refer to the platform documentation for ld(1), dlopen or ld.so(8)) .

Environment variable Platform

LD_LIBRARY_PATH

System V based operating systems and Solaris.

LIBPATH

AIX

SHLIB_PATH

HP-UX

LD_RUN_PATH

Many platforms use this in addition to those listed above.

To use the Easysoft ODBC-SQL Server Driver, you need to add:

<InstallDir>/easysoft/sqlserver:<InstallDir>/easysoft/lib

where <InstallDir> is the directory in which you chose to install the Easysoft ODBC-SQL Server Driver. If you accepted the default location, this is /usr/local.

An example of setting the environment path in the Bourne shell on Solaris is:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/easysoft/sqlserver:/usr/local/easysoft/lib
export LD_LIBRARY_PATH
The exact command you need to set and export an environment variable depends on your shell.

If you installed the unixODBC Driver Manager included in the Easysoft ODBC-SQL Server Driver distribution, you also need to add installationdir/easysoft/unixODBC/lib to the dynamic linker search path.

Uninstalling on Linux or UNIX

There is no automated way to remove the Easysoft ODBC-SQL Server 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-SQL Server 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-SQL Server Driver entry needs to be removed from the odbcinst.ini file. To check whether the Easysoft ODBC-SQL Server Driver is configured under unixODBC, use odbcinst -q -d. If the command output contains [Easysoft ODBC-SQL Server], uninstall the driver from unixODBC by using:

    odbcinst -u -d -n Easysoft ODBC-SQL Server

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-SQL Server 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-SQL Server.

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

Installing on Windows

The Windows installation can be done by anyone with local administrator privileges.

  1. Download the Easysoft ODBC-SQL Server Driver installer.

  2. Follow the onscreen instructions to progress through the installation wizard.

Updating files that are in use

To avoid rebooting your computer, the Easysoft ODBC-SQL Server Driver installer prompts you when files that it needs to update are in use by another application or service. This frees the locked files and allows the installation to complete without a system restart. The installer uses the Restart Manager to locate the applications that are using files that need updating. These applications are displayed in the Files in Use dialog box. To avoid a system restart, choose Automatically close applications and attempt to restart them after setup is complete. The Easysoft ODBC-SQL Server Driver installer then uses Restart Manager to try to stop and restart each application or service in the list. If possible, Restart Manager restores applications to the same state that they were in before it shut them down.

Licensing

By default, the installer starts the Easysoft License Manager, because you can’t use the Easysoft ODBC-SQL Server Driver until you have a license. If you choose not to run Easysoft License Manager as part of the installation process, run License Manager from the Easysoft group in the Windows Start menu when you’re ready to license the Easysoft ODBC-SQL Server Driver. These types of license are available:

  • A free time-limited trial license, which gives you free and unrestricted use of the product for a limited period (usually 14 days).

  • A full license if you have purchased the product. On purchasing the product you are given an authorization code, which you use to obtain a license.

To license the Easysoft ODBC-SQL Server Driver:

  1. In License Manager, enter your contact details.

    You must complete the Name, E-Mail Address, and Company fields.

    The e-mail address must be the same as the one used to register at the Easysoft web site. Otherwise, you won’t be able to obtain a trial license.

  2. Choose Request License.

    You’re prompted to choose a license type.

  3. Do one of the following:

    • For a trial license, choose Time Limited Trial, and then choose Next.
      -Or-

    • For a purchased license, choose Non-expiring License, and then choose Next.

  4. Choose your product from the drop-down list when prompted, and then choose Next.

  5. For a purchased license, enter your authorization code when prompted, and then choose Next.

  6. Choose how to get your license when prompted.

  7. Do one of the following:

    • Choose On-line Request if your machine is connected to the internet and can make outgoing connections to port 8884.
      With this method, License Manager automatically requests and then applies your license.
      -Or-

    • Choose View Request. Then open a web browser and go to https://www.easysoft.com/support/licensing/trial_license.html or https://www.easysoft.com/support/licensing/full_license.html, as appropriate. In the web page, enter your machine number (labelled Number in the license request). For purchased licenses, you also need to enter your authorization code (labelled Ref in the license request).
      We’ll automatically email your license to the email address you supplied in License Manager.
      -Or-

    • Choose Email Request to email your license request to our licensing team.
      Once we’ve processed you request, we’ll email your license to the email address you supplied in License Manager.

  8. Close the License Manager windows and then choose Finish.

If you chose either View Request or Email Request, apply your license by double-clicking the email attachment when you get the license email from us. Alternatively, start License Manager from the Easysoft folder in the Windows Start menu. Then choose Enter License and paste the license in the space provided.

Once you’ve licensed the Easysoft ODBC-SQL Server Driver, the installation is complete.

Repairing the installation

The installer can repair a broken Easysoft ODBC-SQL Server Driver installation. For example, you can use the installer to restore missing Easysoft ODBC-SQL Server Driver files or registry keys. To do this:

  1. In the Windows Taskbar, enter Add or remove programs in the Windows Search box.

  2. Select Easysoft ODBC-SQL Server Driver in the list, and then choose Repair.

Uninstalling on Windows

This section explains how to remove the Easysoft ODBC-SQL Server Driver from your system.

Removing Easysoft ODBC-SQL Server Driver data sources

Easysoft ODBC-SQL Server Driver data sources are not removed when you uninstall the Easysoft ODBC-SQL Server Driver. You don’t therefore need to recreate your Easysoft ODBC-SQL Server Driver data sources if you reinstall or upgrade. If you don’t want to keep your Easysoft ODBC-SQL Server Driver data sources, use Microsoft ODBC Data Source Administrator to remove them, before uninstalling the Easysoft ODBC-SQL Server Driver:

  1. In the Windows Taskbar, enter Run in the Windows Search box.

  2. In the Windows Run dialog box, enter:

    odbcad32.exe

  3. Locate your data source in either the User or System tab.

  4. Select the data source from the list, and then choose Remove.

    If the Remove button isn’t available, close ODBC Data Source Administrator, and then, in the Windows Run dialog box, enter:

    %windir%\syswow64\odbcad32.exe

    Repeat the previous two steps.

Removing the Easysoft ODBC-SQL Server Driver

  1. In the Windows Taskbar, enter Add or remove programs in the Windows Search box.

  2. Select Easysoft ODBC-SQL Server Driver in the list, and then choose Uninstall.

Easysoft product licenses are stored in the Windows registry. When you uninstall, your licenses are not removed, so you do not need to relicense the product if you reinstall or upgrade.

Connecting to SQL Server

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-SQL Server Driver.

Connecting from Linux or UNIX

Creating an ODBC data source

There are two ways to create a data source to your SQL Server data:

  • Create a SYSTEM data source, which is available to anyone who logs on to the computer where the Easysoft ODBC-SQL Server 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-SQL Server Driver is installed.

By default, the Easysoft ODBC-SQL Server Driver installation creates a sample SYSTEM data source named SQLSERVER_SAMPLE. If you’re using the unixODBC included in the Easysoft ODBC-SQL Server 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 SQL Server, 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-SQL Server Driver is installed into unixODBC, it places a Easysoft ODBC-SQL Server entry into the odbcinst.ini file. You should always have Driver = Easysoft ODBC-SQL Server in your Easysoft ODBC-SQL Server Driver data sources therefore.

The Easysoft ODBC-SQL Server Driver Driver distribution includes two drivers:

  • One with SSL support that should be used if you want to access SQL Server over an encrypted connection.

  • One without SSL support that should be used for SQL Server when encryption is not required.

When the Easysoft ODBC-SQL Server Driver is installed into unixODBC, entries for the standard driver (Easysoft ODBC-SQL Server) and the driver with SSL support (Easysoft ODBC-SQL Server SSL) are placed in odbcinst.ini.

For Easysoft ODBC-SQL Server Driver data sources, you need to include a Driver = Easysoft ODBC-SQL Server entry.

For Easysoft ODBC-SQL Server Driver with SSL Support data sources, you need to include a Driver = Easysoft ODBC-SQL Server SSL entry. For more information about configuring the Easysoft ODBC-SQL Server Driver with SSL Support data sources, refer to Encrypting connections to SQL Server.

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

  • The host name or IP address of the machine where the SQL Server instance is running. To connect to a named instance you also need to specify the instance name. (Server)

  • A valid SQL Server login name (User) and password (Password). For example:

[SQL Server]
Driver = Easysoft ODBC-SQL Server Driver

# To connect to the default instance, omit \my_instance_name.
Server = my_sqlserver_hostname\my_instance_name
User = my_domain\my_domain_user
Password = my_password

If the SQL Server Browser is not in use at your site and you want to connect to an instance that is not listening on the default TCP port (1433), you also need to specify the port. For example, to connect to a SQL Server instance that is listening on port 1500, add this entry:

Port = 1500

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

  • libodbcinst.so

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

  • libeslicshr.so

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

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

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

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-SQL Server Driver data sources. To test the Easysoft ODBC-SQL Server 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

Connecting from Windows

Creating an ODBC data source

  1. In the Windows Taskbar Search box, enter “Run”.

  2. Do one of the following:

    • If your application is 64-bit, in the Run dialog box, enter:

      odbcad32.exe

      -Or-

    • If your application is 32-bit, in the Run dialog box, enter:

      %windir%\syswow64\odbcad32.exe
      If you’re not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit). For example, the process name for the 32-bit version of Excel is Microsoft Excel (32-bit); the process name for the 64-bit version of Excel is Microsoft Excel. On older versions of Windows, 32-bit applications contain *32 in the process name rather than (32-bit).
      For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
      If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the .exe file for the programming language. For example, run perl, php, python, or node. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains (32-bit).

  3. Do one of the following:

    • To create a data source that only the user you’re currently logged in as can access, choose the User tab.
      If your application is a Windows service (for example, SQL Server or Oracle) creating a user data source won’t work, unless the service is running as the same user you’re logged in as.

    • To create a data source that all users on this computer can access, choose the System tab.

  4. Choose Add.

  5. In the list of ODBC drivers, select Easysoft ODBC-SQL Server Driver, and then choose Finish.

  6. Complete the Easysoft ODBC-SQL Server Driver configuration dialog box.
    To find out how to do this, refer to the Connection attributes section.

  7. To test the connection to SQL Server, choose Test.
    Note that this doesn’t test that the Easysoft ODBC-SQL Server Driver is licensed. If you haven’t yet licensed the Easysoft ODBC-SQL Server Driver, this ODBC data source won’t work with your application, even if the Test button succeeds.

Connection attributes

Setting on Linux and UNIX

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

  • The host name or IP address of the machine where the SQL Server instance is running. To connect to a named instance you also need to specify the instance name. (Server)

  • A valid SQL Server login name (User) and password (Password). For example:

[SQL Server]
Driver = Easysoft ODBC-SQL Server Driver

# To connect to the default instance, omit \my_instance_name.
Server = my_sqlserver_hostname\my_instance_name
User = my_domain\my_domain_user
Password = my_password

If the SQL Server Browser is not in use at your site and you want to connect to an instance that is not listening on the default TCP port (1433), you also need to specify the port. For example, to connect to a SQL Server instance that is listening on port 1500, add this entry:

Port = 1500

For more information about these mandatory attributes and other optional attributes, refer to this table:

Attribute Description

Driver = value

The name of the ODBC driver to use with this data source. To connect to a SQL Server instance over an encrypted connection, set this attribute value to Easysoft ODBC-SQL Server SSL. Otherwise, set this attribute value to Easysoft ODBC-SQL Server.

Description

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

Server = value

The SQL Server instance that you want to connect to. To connect to the default SQL Server instance, enter:

computername

where computername is the name or IP address of the host where SQL Server is running.

Note that if you’re connecting to a SQL Server or later instance that’s listening on an IPv6 address, set the IPv6 attribute to 1.

To connect to a named instance, enter:

computername\instancename

where instancename is the SQL Server instance.

To connect to the default SQL Server Express named instance, enter:

computername\sqlexpress

On Windows, you also have the option of using a named pipe connection. To use named pipes, use this format for the Server value:

\\localhost\pipe\MSSQL$instance\sql\query

For example:

\\localhost\pipe\MSSQL$sqlexpress\sql\query

Connection failover

If your SQL Server database is available on more than one SQL Server computer, you can define a primary server for the database and additional fallback database servers. By default, the Easysoft ODBC-SQL Server Driver will try to connect to the first server that you specify. If that server is unavailable the Easysoft ODBC-SQL Server Driver will try to connect to the next server in the list and so on. Use the format:

Server = primaryserver[:port] [, fallbackserver[:port]...]

where:

  • primaryserver is the name or IP address of the primary SQL Server computer on which your database is available.

  • port is the TCP port on which the instance is listening. If omitted, the driver will try to connect to the instance that is listening on port 1433.

  • fallbackserver is the name or IP address of an alternative SQL Server computer on which your database is available.

For example:

Server = sqlsrvhostA,sqlsrvhostB,sqlsrvhostC:1583

Server = value

Connection attempts continue until either a connection is successfully made or all the servers in the list have been tried once.

Note that your SQL Server login (as specified by User and Password) needs to be valid on each SQL Server computer in the list. The SQL Server login must have permission to access the database on each SQL Server computer.

If you want to balance the load between database servers, configure the driver to randomly choose the database server it connects to. To do this, set the ClientLB attribute to 1.

Port = num

The TCP port that SQL Server is listening on.

If you’re connecting to a default instance that’s listening on port 1433, the Port setting can be omitted.

If the SQL Server Browser service is running, the Easysoft ODBC-SQL Server Driver will automatically detect the port number and the Port setting can be omitted.

By default, named instances of SQL Server use dynamic ports, which means that an available port is assigned when the instance starts. If a SQL Server instance is listening on a dynamically allocated port number, you must omit the Port setting and let the Easysoft ODBC-SQL Server Driver use the browser or listener to detect the port number.

If the SQL Server Browser is not running at your site, your database administrator will have configured each SQL Server instance to listen on a specific TCP port. You need to specify this port with the Port setting.

If your database administrator has hidden the SQL Server instance from the SQL Server Browser, you need to specify the port number of the hidden instance.

If your database administrator has configured the SQL Server instance to listen on multiple ports, use the Port setting to specify the appropriate port number from the available alternatives.

User = value

The SQL Server login name to use when connecting to SQL Server.

If the SQL Server instance uses Windows Authentication (also known as trusted connections), the Windows user name to use to authenticate the connection. Use this format:

domain\username

where:

  • domain is the name of the Windows domain that the SQL Server computer is in or one that the SQL Server computer trusts.

  • username is the user name of a user who belongs to this domain.

If the SQL Server instance permits SQL Server Authentication, you can also specify a SQL Server user name.

To specify the login name in the connection string, use UID rather than User. For more information about specifying Easysoft ODBC-SQL Server Driver attributes in the connection string, refer to DSN-less Connections.

On Windows, if you want to access SQL Server with a Windows log in, choose With Integrated Windows Authentication.

Password = value

The password for the login name specified by User.

To specify the login password in the connection string, use PWD rather than Password.

Authentication = value

Controls the authentication mode used by the Easysoft ODBC-SQL Server Driver. Currently, the only value for this attribute is ActiveDirectoryPassword, which you need to set if you’re connecting to SQL Azure with an Azure Active Directory account user name and password.

ServerName = value

This attribute is only relevant if you are using SQL Azure and lets you specify the fully qualified domain name (FQDN) of the SQL Azure server that you want to connect to. For example:

xyz12345yzx.database.windows.net

There are two ways to specify the SQL Azure server, as shown by the following data source extracts:

ServerName = xyz12345yzx.database.windows.net
User = myuser

-Or-

Server = xyz12345yzx.database.windows.net
User = myuser@xyz12345yzx

For more information about SQL Azure, refer to the following Easysoft tutorial:

https://www.easysoft.com/products/data_access/odbc-sql-azure-driver/linux-unix.html

Database = value

The default database to use for the connection.

If you omit this attribute, the connection uses the default database defined for the login in SQL Server. The default database for users who do not have their own SQL Server login depends on the local group on the SQL Server computer that they belong to. The default database for members of the local Administrators group is the one defined for the BUILTIN\Administrators login. The default database for members of the local Users group is the one defined for the BUILTIN\Users login (SQL Server Express Edition only).

If the database does not exist or the login does not have permission to access the database, the connection will fail.

Note that using the default database for the login ID is more efficient than specifying a default database in the ODBC data source.

QuotedId = Yes | No

When turned on (set to Yes), QUOTED_IDENTIFIERS is set to ON for the connection. SQL Server will then follow the SQL-92 rules regarding the use of quotation marks in SQL statements. Double quotes can only be used for identifiers, such as column and table names. Character strings must be enclosed in single quotes:

SELECT CompanyName
FROM "Customer and Suppliers by City"
WHERE City = 'New York'

If a single quotation mark is part of the literal string, it can be represented by two single quotation marks.

When turned off (set to No), QUOTED_IDENTIFIERS is set to OFF for the connection. SQL Server then follows the legacy Transact-SQL rules regarding the use of quotation marks. Identifiers cannot be quoted and must follow all Transact-SQL rules for identifiers. Literals can be delimited by either single or double quotation marks.

For more information about the QUOTED_IDENTIFIERS option, refer to the SQL Server Transact-SQL documentation.

By default, QuotedId is turned on.

User_Domain = value

If your user name contains a domain, specify the domain with this attribute. So, myuser@mydomain becomes:

User = myuser
User_Domain = mydomain

Omit the @ symbol.

Some applications (for example Oracle Heterogeneous Services) don’t support the use of domains in user names.

OFFAnsiNPW = Yes | No

When turned on (set to Yes), the ANSI_NULLS, ANSI_WARNINGS, and ANSI_PADDING options are set to ON for the connection.

When ANSI_NULLS is turned on, SQL Server enforces ANSI rules for handling NULL comparisons. The ANSI syntax IS NULL or IS NOT NULL must be used for all NULL comparisons. For example:

SELECT *
FROM MyTable
WHERE MyColumn IS NULL

The Transact-SQL syntax = NULL and <> NULL are not supported.

When ANSI_NULLS is turned off, the equals (=) and not equal to (<>) comparison operators must be used to make comparisons with NULL and non NULL values in a table.

When ANSI_WARNINGS is turned on, SQL Server generates warning messages for conditions that violate ANSI rules but do not violate the rules of Transact-SQL. For example, SQL Server will generate error and warning messages for divide-by-zero errors, string too large for database column errors and when NULL values are encountered when using aggregate functions. When SET ANSI_WARNINGS is OFF, these errors and warnings are not raised.

When ANSI_PADDING is turned on, trailing blanks on VARCHAR values and trailing zeroes on VARBINARY values are not automatically trimmed.

For more information about the ANSI_NULLS, ANSI_WARNINGS, and ANSI_PADDING options, refer to the SQL Server Transact-SQL documentation.

By default, AnsiNPW is turned on.

Language = value

The national language to use for SQL Server system messages. Use this format:

Language = language

where language is one the language aliases contained in the sys.syslanguages table.

For example:

Language = French

If no language is specified, the connection uses the default language specified for the login on the server.

Appname = value

The name SQL Server uses to identify the application that connects using this data source. For example, the following entry identifies an application as isql:

Appname = isql

The default value is ODBC.

SQL Server stores the application name in the master.dbo.sysprocesses column program_name. The name is returned by the APP_NAME function.

MARS_Connection = Yes | No

When turned on (set to Yes), multiple active result sets (MARS) are enabled on the connection. MARS allows applications to have more than one pending request per connection, and in particular, to have more than one active default result set per connection. Applications can execute other statements (for example, INSERT, UPDATE, DELETE, and stored procedure calls) while result sets are open. For example, an application might retrieve unprocessed items from an Orders table and then, while looping through the active result set, use an UPDATE statement to mark each order as processed.

For non-MARS connections (MARS_Connection turned off), applications cannot maintain multiple active statements on a connection. Applications that attempt to do this fail with the error "connection is busy with results of another hstmt". The application has to process or cancel all result sets from one batch before it can execute any other batch on that connection. Note that server-side cursors can be used to work around this limitation. There is a performance penalty associated with server-side cursors however.

By default, MARS_Connection is turned off.

Logging = Yes | No

Whether Easysoft ODBC-SQL Server Driver logging is turned on. To turn on Easysoft ODBC-SQL Server Driver logging, add a Logging=Yes entry to the relevant DSN section of the odbc.ini file.

LogFile = value

Use the LogFile attribute to specify the Easysoft ODBC-SQL Server Driver log file name and location. Ensure that the user who is running the application to be traced has write permission to the log file (and to the directory containing it).

PreserveCursor = Yes | No

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver preserves cursors when SQLEndTran commits or rolls back a transaction.

By default, PreserveCursor is turned off, which means that cursors are closed when a transaction is committed or rolled back by using SQLEndTran.

This behaviour can also be configured by setting SQL_COPT_SS_PRESERVE_CURSORS with SQLSetConnectAttr. For more information and a code sample, refer to SQL_COPT_SS_PRESERVE_CURSORS.

Wsid = value

The workstation ID. The default value is the host name of the computer where the ODBC application is running. SQL Server stores the workstation ID in the master.dbo.sysprocesses column hostname. The ID is returned by sp_who and the HOST_NAME function.

Version7 = Yes | No

Set to Version7 to Yes if you’re connecting to a SQL Server 7.0 database.

When initiating the connection, the Easysoft ODBC-SQL Server Driver tries to discover the version of the SQL Server instance. Setting Version7 to Yes reduces the number of steps in the discovery process for SQL Server 7.0 databases. This results in a slightly faster connection time.

By default, Version7 is turned off (set to No).

ForceShiloh = Yes | No

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver assumes that it’s connecting to a SQL Server 2000 instance and only uses the SQL Server 2000 version of TDS to communicate with the instance.

By default, ForceShiloh is off (set to No).

ClientLB = Yes | No

Whether the Easysoft ODBC-SQL Server Driver tries to balance the load between the servers specified by the Server setting. The ClientLB setting only has an effect if you specify a primary server and additional fallback servers with Server.

When ClientLB is turned on (set to Yes), the Easysoft ODBC-SQL Server Driver randomly selects a server to connect to. If the server is unavailable, the Easysoft ODBC-SQL Server Driver then moves sequentially through the list of other servers.

When ClientLB is turned off (set to No, the default), the Easysoft ODBC-SQL Server Driver tries to connect to the servers in the order that they are defined in. (Primary server first and then each additional fallback server.)

Example:

You specify a primary server (sqlsrvhostA) and two fallback servers (sqlsrvhostB and sqlsrvhostC):

Server = sqlsrvhostA,sqlsrvhostB,sqlsrvhostC:1583

When ClientLB is turned on, the Easysoft ODBC-SQL Server Driver will randomly choose a server to connect to. If, for example, the driver tries to connect to sqlsrvhostB first, it will then try to connect to sqlsrvhostC (if sqlsrvhostB is unavailable) and sqlsrvhostA (if sqlsrvhostC is unavailable).

When ClientLB is turned off, the Easysoft driver will try to connect to sqlsrvhostA and then sqlsrvhostB (if sqlsrvhostA is unavailable) and finally sqlsrvhostC (if sqlsrvhostB is unavailable).

Failover_Partner = value

Use Failover_Partner to specify the current mirror database server. If the initial connection to the principal database server fails, the Easysoft ODBC-SQL Server Driver will attempt a connection to the server specified by Failover_Partner.

MultiSubnetFailover = Yes | No

Set MultiSubnetFailover to Yes when connecting to a SQL Server Failover Cluster Instance or the availability group listener of a SQL Server availability group. Setting MultiSubnetFailover to Yes provides faster detection of and connection to the (currently) active server.

By default, MultiSubnetFailover is turned off (set to No).

ApplicationIntent = ReadOnly | ReadWrite

Specifies the application workload enter when connecting to a SQL Server Failover Cluster Instance or the availability group listener of a SQL Server availability group. The default is ReadWrite.

ConnectRetryCount = num

Specifies the number of reconnection attempts if there is a connection failure. Valid values range from 0 to 255. Zero (0) means do not attempt to reconnect. The default value is one reconnection attempt.

ConnectRetryInterval = num

Specifies the number of seconds between each connection retry attempt. Valid values are 1-60. The default value is 10 seconds,

VarMaxAsLong = Yes | No

When turned off (set to No), the Easysoft ODBC-SQL Server Driver returns a VARCHAR(MAX) column as a SQL_VARCHAR with a zero length, which means the maximum size is unlimited. Some applications may interpret this to mean that the column size is zero bytes rather than unlimited and allocate a buffer that is too small for the column data. To work around this, try setting VarMaxAsLong to Yes. When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver returns a VARCHAR(MAX) column as a SQL_LONGVARCHAR.

By default, VarMaxAsLong is turned off.

VarMaxAsVarchar = Yes | No

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver maps a VARCHAR(MAX) column to a VARCHAR(4000) column and an NVARCHAR(MAX) column to a NVARCHAR(4000) column.

By default, VarMaxAsVarchar is turned off.

DisguiseGuid = Yes | No

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver describes the UNIQUEIDENTIFIER data types as CHAR rather than GUID. This is a workaround for applications such as Oracle’s HSODBC that don’t recognise UNIQUEIDENTIFIER types and therefore fail to return data from tables containing these column types.

By default, DisguiseGuid is turned off (set to No).

DisguiseLong = Yes | No

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver describes IMAGE and TEXT data types as VARBINARY and VARCHAR. This is a workaround for applications such as Oracle’s HSODBC that cannot handle IMAGE and TEXT types and therefore fail to return data from tables containing these column types.

By default, DisguiseLong is turned off (set to No).

LimitLong = num

The maximum size in bytes that the Easysoft ODBC-SQL Server Driver returns for IMAGE, NTEXT, TEXT, NVARCHAR(MAX), VARBINARY(MAX), and VARCHAR(MAX) columns. Use LimitLong to restrict the size returned by the driver when describing these data types.

LimitLong only has an effect on MAX data, if VarMaxAsLong is turned on (set to Yes).

By default, LimitLong is turned off (set to No).

DPrec = num

The precision to use when converting FLOAT(25-53) data in a result set to a string

If an application specifies a string as the target type for non-character data in a SQLBindCol or SQLGetData call, the Easysoft ODBC-SQL Server Driver converts the data to the target type. Use the FPrec attribute to specify the precision to use when the driver does this conversion for FLOAT(25-53) data.

The default precision is 6.

FPrec = num

The precision to use when converting FLOAT(1-24) or real data in a result set to a string

If your application specifies a string as the target type for non-character data in a SQLBindCol or SQLGetData call, the Easysoft ODBC-SQL Server Driver converts the data to the target type. Use the FPrec attribute to specify the precision to use when the driver does this conversion for FLOAT(1-24) or real data.

The default precision is 6.

Strftime = format

The format to use when converting ftimestamp data in a result set to a string.

If your application specifies a string as the target type for timestamp data in a SQLBindCol or SQLGetData call, the Easysoft ODBC-SQL Server Driver converts the data to the target type. Use the Strftime attribute to specify the format to use when the driver does this conversion for DATE, DATETIME, DATETIME2, DATETIMEOFFSET, SMALLDATETIME, and TIME data.

The Easysoft ODBC-SQL Server Driver uses strftime to do the conversion, and so the format should be one of the format strings supported by strftime. For the available format strings, refer to the strftime(3) man page.

For example, the format string specified in the following line:

STRFTIME = %d %h %Y %T

would produce:

11 March 2025 12:35:29

given this SQL statement:

SELECT CAST('2025-03-11 12:35:29.123' AS datetime)

Strfsize = num

The display size of a column is the maximum number of characters needed to display data in character form. It may be necessary to increase the default display size for timestamp data to accommodate some of the formats that strftime supports.

For example, to set the display size to 32, add the following line to your data source:

STRFSIZE = 32

ConvToUtf = Yes | No

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver converts UCS-2 encoded data to UTF-8 and vice versa. This enables applications running on UTF-8 platforms to work with Unicode data stored in NCHAR, NVARCHAR, NVARCHAR(MAX), and NTEXT columns.

SQL Server uses UCS-2 to encode data in NCHAR, NVARCHAR, NVARCHAR(MAX), and NTEXT columns. If your application expects UTF-8 encoded data, and is unable to convert data to this encoding scheme, it will be unable to process Unicode data stored in NCHAR, NVARCHAR, NVARCHAR(MAX), and NTEXT columns. To work around this, add this line to your ODBC data source.

ConvToUtf = Yes

ConvToUtf also affects SQL statement text, metadata (table names and so on), and SQL statement parameters that are bound as a wide type (SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR). For example:

SQLPrepare( hstmt, "INSERT INTO MYNCHARTABLE VALUES (?)", SQL_NTS );
SQLBindParameter( hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_WCHAR, 100, 0, &cval, sizeof( cval ), &len1 );

By default, ConvToUtf is turned off (set to No).

Example: Retrieving data

We ran LibreOffice on Ubuntu from a shell in which the LANG environment was set to en_GB.UTF-8. With ConvToUtf set to No, we connected to a SQL Server data source in Base and ran this SQL:

USE Northwind
SELECT CompanyName FROM Suppliers WHERE SupplierID = 29

SQL Server stores data in the CompanyName column as a UCS-2 encoded NVARCHAR type.

The results for this query should be:

Forêts d'érables

Instead, we got these results:

For?ts d'?rables

The ? symbols indicate that application was unable to convert the character from the server encoding scheme to the client encoding scheme.

In LibreOffice Writer, we used the Insert > Special Character command to insert ê and é into a new document. We did this to show that LibreOffice running on this system and environment was capable of rendering these two characters. We then saved the document as a Text file and ran the following command at the shell prompt:

ConvToUtf = Yes | No

 
$ file ooo_chars.txt
ooo_chars.txt: Unicode text, UTF-8

The file command’s output indicates that the encoding scheme LibreOffice was using is UTF-8.

We set ConfToUTF to Yes and reconnected to the data source in Base. Running the same query returned the expected results. This is because the Easysoft ODBC-SQL Server Driver converts the UCS-2 encoded data to UTF-8, the encoding LibreOffice expects.

Example: inserting data

We created a SQL file named insert-northwind-shipper.sql on a Ubuntu computer:

-- Insert new record into the Northwind shippers table
USE Northwind;
INSERT INTO Shippers (CompanyName, Phone) VALUES (N'♦'> Diamond Shipping', '(11) 555-2167');
SELECT * FROM Shippers;

To create the file, we used the Vi IMproved (vim) text editor from a shell in which the LANG environment was set to en_GB.UTF-8. To insert the ♦ character in vim, we used CTRL+V u2666. (u+2666 is the Unicode code point for this character.) The N prefix before the INSERT statement value tells SQL Server that the string contains a Unicode character. To confirm that the SQL file was UTF-8 encoded, we ran the file command:

$ file insert-northwind-shipper.sql
insert-northwind-shipper.sql: Unicode text, UTF-8

In the same shell, we used insert-northwind-shipper.sql as an input file to isql:

/usr/local/easysoft/unixODBC/bin/isql -v SQLSERVER_SAMPLE < insert-northwind-shipper.sql

The SQLSERVER_SAMPLE data source connects to a SQL Server instance that serves the Northwind database. In the data source, ConfToUTF was set to Yes. The command’s output confirmed that the new record had been successfully inserted and that the Ubuntu computer was capable of rendering the ♦ character:

ConvToUtf = Yes | No

 
SQL>--+---------------------+----------------------+

| ID | CompanyName | Phone |

+-----+------------------------+-------------------------+

| 1 | Speedy Express | (503) 555-9831 |

| 2 | United Package | (503) 555-3199 |

| 3 | ♦ Diamond Shipping | (11) 555-2167 |

+------+-----------------------+-------------------------+

ConvWToUtf = Yes | No

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver converts strings passed to Unicode ODBC calls (with suffix "W") to UTF-8. The Easysoft ODBC-SQL Server Driver also converts metadata and result sets returned by Unicode ODBC calls to UTF-8.

By default, ConvWToUtf is turned off (set to No).

SQLServerUTF = Yes | No

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver sets the ConvWToUtf attribute to Yes prior to connecting to the data source. This provides a workaround for applications that pass UTF-8 encoded strings to SQLConnectW, SQLDriverConnectW, and SQLBrowseConnect.

The SQLServerUTF attribute must be specified in a section named ODBC in odbc.ini. For example:

[ODBC]
SQLServerUTF = Yes

By default, SQLServerUTF is turned off (set to No).

UTF8DB = Yes | No

If you have set a UTF-8 collation at instance, database, or column level, add this entry to your data source:

UTF8DB = Yes

UTF-8 collations were introduced in SQL Server 2019 and have the suffix UTF8.

Client_CSet = encoding

Specifies the encoding on the Easysoft ODBC-SQL Server Driver computer.

If set, the Easysoft ODBC-SQL Server Driver tries to convert to and from the specified encoding when retrieving and submitting character data. For example, if you have an application that is expecting EUC-JP encoded character data, you would need to set Client_CSet to specify the EUC-JP encoding:

# Convert from EUC-JP when submitting data to SQL Server
# Convert to EUC-JP when retrieving data from SQL Server
Client_CSet = EUC-JP

All character data is affected by Client_CSet, including data stored in CHAR, VARCHAR, TEXT, NCHAR, NVARCHAR, NVARCHAR(MAX), and NTEXT columns, metadata (table names, and so on) and SQL statement text and parameters.

Use Client_CSet if you experience data loss or corruption when working with character data and your application cannot convert data to the encoding scheme it expects.

The Easysoft ODBC-SQL Server Driver uses a built-in version of iconv to do the conversion. For a list of available encodings for Client_CSet, run this command on the computer where the Easysoft ODBC-SQL Server Driver is installed:

iconv -l

Set Client_CSet to the encoding that corresponds with the LANG environment variable value on the client computer. For example, if LANG was set to en_US.UTF-8 on the client computer, you would set Client_CSet to UTF-8.

If iconv cannot convert a character, the Easysoft ODBC-SQL Server Driver will omit the character and write this entry to the unixODBC or driver log file (assuming logging is turned on):

One or more characters in the input stream could not be converted

Note that if your client computer encoding is UTF-8, you can use Client_CSet as an alternative to ConvToUTF. You do not need to set both data source attributes.

If you specify a Server_CSet value without specifying a Client_CSet value, the Easysoft ODBC-SQL Server Driver uses ISO8859-1 as the client computer encoding.

Server_CSet = encoding

Specifies the SQL Server encoding for non-Unicode character data.

If set, the Easysoft ODBC-SQL Server Driver tries to convert character data from the specified encoding when retrieving SQL Server data stored in CHAR, VARCHAR, and TEXT columns. The Easysoft ODBC-SQL Server Driver also tries to convert strings to the specified encoding when binding parameter markers. For example:

INSERT INTO my_table(my_char_col, my_varchar_col, my_text_col) VALUES (?,?,?)
SELECT * FROM my_table WHERE my_varchar_col = ?

Use Server_CSet if you experience data loss or corruption when working with data stored in CHAR, VARCHAR, and TEXT columns.

The Easysoft ODBC-SQL Server Driver links to iconv on your computer at run-time to do the conversion.

Set Server_CSet to the iconv encoding that corresponds with the SQL Server code page. To find out the SQL Server code page, run:

SELECT COLLATIONPROPERTY('collation' , 'CodePage') AS CodePage

where collation is the SQL Server database collation, if set, otherwise the SQL Server instance collation.

In the following example, collation would be Cyrillic_General_CI_AS.

SELECT DATABASEPROPERTYEX('MyDatabase', 'Collation') SQLCollation;

SQLCollation
------------
NULL

SELECT SERVERPROPERTY('Collation') SQLCollation;

SQLCollation
------------
Cyrillic_General_CI_AS

For a list of iconv encodings, run this command on the computer where the Easysoft ODBC-SQL Server Driver is installed:

iconv -l

As an example, if the SQL Server collation was Cyrillic_General_CI_AS, the associated code page is 1251, and you would set Server_CSet to WINDOWS-1251.

If you set the Client_CSet attribute without setting the Server_CSet attribute, the Easysoft ODBC-SQL Server Driver uses the ISO8859-1 encoding as the Server_CSet value.

Server_UCSet = encoding

Specifies the SQL Server encoding for character data.

If set, the Easysoft ODBC-SQL Server Driver tries to convert character data from the specified encoding when retrieving SQL Server data stored in NCHAR, NVARCHAR, and NTEXT columns. The Easysoft ODBC-SQL Server Driver also tries to convert strings to the specified encoding when binding parameter markers.

The default Unicode encoding is UTF-16le.

Use_LCID = Yes | No

Whether to automatically work out which character set to use based on the SQL Server column or instance Locale ID (LCID).

If set, the Easysoft ODBC-SQL Server Driver tries to convert character data from the character set when retrieving SQL Server data stored in CHAR, VARCHAR, and TEXT columns. The Easysoft ODBC-SQL Server Driver also tries to convert strings to the character set when inserting data into CHAR, VARCHAR, and TEXT columns.

The ODBC application must bind the character data as a Unicode data type (for example, a SQL_WCHAR).

This feature emulates the Microsoft Native Client ODBC Driver’s automatic translation of character data, and, as is the case with the Microsoft driver, not all character sets are supported.

If your character set is not supported, the Client_CSet and Server_CSet attributes provide an alternative conversion mechanism.

By default, Use_LCID is turned off (set to No).

LCID = localeid

Sets the ClientLCID the parameter in the TDS login packet. The ClientLCID parameter is described in the TDS protocol specification:

https://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-TDS%5D.pdf

Trusted_Domain = value

The Windows domain that the user specified with User belongs to.

If the user belongs to the same domain as the one that the SQL Server computer is in, you can omit Trusted_Domain. The Easysoft ODBC-SQL Server Driver automatically detects the domain in this case.

If you specify a Domain with Trusted_Domain, set Trusted_Connection to Yes and omit the domain from User. For example:

# Windows authentication
User = mylocalcomputeruser
Password = mypassword
Trusted_Connection = 1
Trusted_Domain = mycomputername

Trusted_Connection = Yes | No

Whether to use Windows or SQL Server authentication to validate the connection.

NTLMv2 = Yes | No

If you want to use NTLMv2 to authenticate the Windows user specified with User, set set NTLMv2 to Yes. Otherwise, leave NTLMv2 set to its default value No (turned off).

IPv6 = Yes | No

Set IPv6 to Yes when connecting to a SQL Server instance that’s listening on an IPv6 address.

By default, IPv6 is turned off (set to No), which means that the Easysoft ODBC-SQL Server Driver assumes that the target SQL Server instance is listening on an IPv4 address.

For more information about IPv6, refer to Connecting to SQL Server by using IPv6.

ConnectionTimeout = num

The number of milliseconds to wait for any request on the connection to complete before returning to the application. After the initial connection to the SQL Server computer has been established, the Easysoft ODBC-SQL Server Driver will wait num milliseconds each time it needs a response from SQL Server. If no response is received from SQL Server before the timeout expires, the Easysoft ODBC-SQL Server Driver returns the error "Timeout expired".

The default value 0 means that no connection timeout is applied by the Easysoft ODBC-SQL Server Driver.

A timeout set by calling SQLSetConnectAttr with the SQL_ATTR_CONNECTION_TIMEOUT connection attribute will override ConnectionTimeout.

LogonTimeout = num

The number of milliseconds to wait for a TCP connection to the SQL Server computer to be established before returning to the application. When you define a timeout, the initial connection phase lasts for num milliseconds. If the Easysoft ODBC-SQL Server Driver is unable to connect to the target SQL Server computer before the timeout expires, it returns the message "Connection timeout expired". Note that if you specify a named instance in the Server attribute value, the driver returns a different timeout message: "Failed to get datagram from socket".

The default value 0 means that no initial connection timeout is applied by the Easysoft ODBC-SQL Server Driver.

The Easysoft ODBC-SQL Server Driver classes the connection phase as obtaining the IP address of the SQL Server computer and connecting to it. This means that if you specify the Server attribute value as a computer name rather than an IP address, your system resolver library will be used (possibly examining /etc/hosts or doing a DNS query). On some operating systems, gethostbyname(), the call used to resolve a computer name into an IP address, cannot be interrupted and the connection timeout will not work. If this is a problem for you, either specify the SQL Server computer as an IP address or tell your resolver library to consult /etc/hosts before DNS and place an entry in /etc/hosts.

A timeout set by calling SQLSetConnectAttr with the SQL_ATTR_LOGIN_TIMEOUT connection attribute will override LogonTimeout.

RcvBuffer = num

The size of the receive buffer for the socket in bytes. Possible values for num are:

0, do not set the receive buffer size, use the system default value.

n, where n is a number greater than 0, set the receive buffer to the specified size by passing n to the setsockopt() function .

By default, the system default receive buffer size is used.

SoKeepalive = Yes | No

Whether to use TCP keepalive probes to verify that an idle connection is still intact.

When turned on (set to Yes), keepalive probes are sent, after a period of inactivity, to verify that the connection to the SQL Server computer is still valid. To do this, the Easysoft ODBC-SQL Server Driver sets the SO_KEEPALIVE socket option by using setsockopt(). If no response to the probes is received, the socket is closed.

The duration of the period of inactivity is a system default, and is typically two hours.

By default, SoKeepalive is turned off (set to No).

PacketSize = num

The TDS packet size in bytes that the Easysoft ODBC-SQL Server Driver will request. The specified packet size must be lower than 65536 bytes.

The default packet size is 4096 bytes.

ColumnEncryption = Enabled | Disabled

Set this attribute to Enabled if you want to query or update data held in an Always Encrypted column. You will also need to set the Driver attribute to Easysoft ODBC-SQL Server SSL.

Always Encrypted columns were introduced in SQL Server 2016. For more information, refer to:

https://www.easysoft.com/blog/sql-server-always-encrypted.html

Allow_C_Comment = Yes | No

SQL comments are nonexecuting text strings used to document or temporarily disable SQL statements. SQL Server supports comments preceded by double hyphens (--) or delimited by forward slash-asterisk character pairs (/* …​ */).

By default, the Easysoft ODBC-SQL Server Driver strips single line /* …​ */ comments from SQL statements before passing the SQL to SQL Server. For example:

SELECT ContactID, /* FirstName, */ LastName FROM Person.Contact

becomes:

SELECT ContactID, LastName FROM Person.Contact

To preserve single line /* …​ */ comments in the SQL that is passed to SQL Server, set the Allow_C_Comment attribute to Yes.

XATimeout = num

Sets the timeout in seconds for an XA transaction created by an xa_open call initiated by the Easysoft ODBC-SQL Server Driver. For more information about the driver’s XA support, refer to the Easysoft blog on the Easysoft web site.

XASTimeout = num

Sets the socket timeout in seconds for an XA transaction created by an xa_open call initiated by the Easysoft ODBC-SQL Server Driver. If not set, the socket timeout defaults to the XATimeout value + 5.

Kerberos = Yes | No

Whether to access a SQL Server instance as a Kerberos service.

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver will attempt to obtain a service ticket for the following Service Principal Name (SPN):

MSSQLSvc/server:port

where:

  • server is the name or IP address of the SQL Server computer specified with the Server attribute.

  • port is the port on which the SQL Server instance is listening, which is specified with the Port attribute.

The ServerSPN attribute provides an alternative way to supply a service principal name.

Don’t specify a User or Password value in the data source if you set Kerberos to Yes. The Kerberos application kinit must have already been used for authentication on the Easysoft ODBC-SQL Server Driver computer. For more information about kinit and accessing SQL Server as a Kerberos service, refer to the following Easysoft tutorial:

https://www.easysoft.com/products/data_access/odbc-sql-server-driver/kerberos.html

By default, Kerberos is turned off (set to No), and the Easysoft ODBC-SQL Server Driver will use either SQL Server or Windows authentication (refer to SQL Server authentication modes) to validate a user specified in the data source.

ServerSPN = value

The Service Principal Name (SPN) for a SQL Server instance that has been registered as a Kerberos service.

Your database administrator will have registered an SPN for your SQL Server instance. Contact your database administrator for the SPN value and then specify that value with ServerSPN.

As an alternative to the ServerSPN attribute, you can set the Kerberos attribute to 1 and the Easysoft ODBC-SQL Server Driver will build an Service Principal Name from the Server and Port attribute values.

If the SPN contains an instance name (for example, MSSQLSvc/mysqlservercomputer:myinstance), you need to use the ServerSPN attribute rather than the Kerberos attribute.

Do not specify a User or Password value in the data source if you specify a ServerSPN value.

On Windows, this attribute is labelled SPN.

FailoverServerSPN = value

The SPN for a mirror server instance that has been registered as a Kerberos service. For more information about Kerberos and Database Mirroring, refer to this Easysoft tutorial:

https://www.easysoft.com/products/data_access/odbc-sql-server-driver/kerberos.html

GSSLib = value

The Easysoft ODBC-SQL Server Driver uses libgssapi_krb5.so, the Kerberos GSS-API library, to request service tickets for accessing SQL Server instances. If the Easysoft ODBC-SQL Server Driver is unable to open this library, the connection will fail with the error:

Krb5: failed to open gss lib (libgssapi_krb5.so)

If the Kerberos GSS-API library is not called libgssapi_krb5.so in your GSS-API distribution, use the GSSLIB attribute in your data source to specify the alternative GSS-API library. For example:

GSSLIB = /opt/extension/lib/libgssapi.so

GSSHost = Yes | No

Whether the Easysoft ODBC-SQL Server Driver allows the use of GSS_C_NT_HOSTBASED_SERVICE or GSS_C_NT_USER_NAME as the target principal name.

When turned on (set to Yes), the Easysoft ODBC-SQL Server Driver allows the use of GSS_C_NT_HOSTBASED_SERVICE.

By default, GSSHOST is turned off (set to No).

GSSFlag = req_flags

The Easysoft ODBC-SQL Server Driver allows you to pass req_flags to the gss_init_sec_context() function, which is used to initiate a security context for the driver. The Key Distribution Center (KDC) uses this security context to verify the identity of the client. To pass req_flags to gss_init_sec_context(), use the GSSFLAG attribute:

GSSFLAG = req_flags

where req_flags is a bitmask specifying the requested GSS services. To look up the available bitmask values, refer to the gssapi.h header file for the GSS-API distribution on the Easysoft ODBC-SQL Server Driver computer. The driver default GSSFLAG value is 4, which sets the GSS_C_REPLAY_FLAG flag.

As an example, to request credential delegation, set the GSS_C_DELEG_FLAG flag by including this line in your data source:

GSSFLAG = 1

ODBC Driver Manager attribute fields

The following attributes may be set in the ODBC section of the odbc.ini file:

Attribute Description

SQLServerUTF = Yes | No

When turned on (set to Yes), the ConvWToUtf attribute is set to Yes prior to connecting to the data source. This provides a workaround for applications that pass UTF-8 encoded strings to SQLConnectW, SQLDriverConnectW, and SQLBrowseConnect.

The SQLServerUTF attribute must be specified in a section named ODBC in odbc.ini. For example:

[ODBC]
SQLServerUTF = Yes

By default, SQLServerUTF is turned off (set to No).

Setting on Windows

The Easysoft ODBC-SQL Server Driver data source configuration dialog box, accessible when you create or edit an Easysoft ODBC-SQL Server Driver data source in ODBC Data Source Administrator lets you configure your data source.

For information about the data source attribute fields the dialog box contains, refer to the table this topic.

Troubleshooting database connection problems

This section lists some common connection problems and their solutions.

Client unable to establish connection: OS Error: 'Failed to find host address 'myhost\myinstance'

Check the Server attribute in your data source specifies a valid computer name or IP address. Check that the computer name can be looked up by using DNS or is present in /etc/hosts. Check that you are on the same network as the target host by pinging the computer:

ping myhost

If ping times out or fails, then either the DNS lookup is not working properly or there is some other networking or routing issue that needs to be resolved. Contact your network administrator.

Client unable to establish connection: OS Error: 'Connection refused'

Check that the SQL Server instance that you are trying to connect to is running.

On the SQL Server computer, "SQL Server <instance>" will be listed in output of the net start command, if the SQL Server instance is running.

If SQL Server is listening on a fixed TCP port, check that you can use telnet to connect to the port that you have specified in the data source:

telnet hostname port

where hostname is the host name or IP address of the computer where SQL Server is running and port is the port number that you have specified with the Port attribute. If the SQL Server instance is listening on this port, you will get output similar to:

Connected to myserver
Escape character is '^]'

To exit from telnet, enter CTRL-] and then quit.

If you do not get this output or a "Connection refused" error displays, SQL Server is not listening on the specified port. Contact your database administrator for the correct SQL Server port.

If you’re using the correct port but are unable to connect with telnet, the SQL Server instance may not allow remote TCP/IP connections. Refer to Client unable to establish connection: Server not configured for TCP connection.

Client unable to establish connection: Server not configured for TCP connection

The TCP/IP protocol must be enabled in the instance that you are trying to connect to.

In the SQL Server Configuration Manager, in the list of network protocols for the instance, the status for TCP/IP must be set to "Enabled."

By default, SQL Server do not allow remote connections, which means that the default setting for TCP/IP is "Disabled".

Client unable to establish connection: OS Error: 'Failed to get datagram from socket'

The Easysoft ODBC-SQL Server Driver uses the SQL Server Browser to find out what TCP port SQL Server is listening on. If the SQL Server Browser is not running and active, the Easysoft ODBC-SQL Server Driver will be unable to open a connection for this purpose and the "Failed to get datagram from socket" error displays.

On the SQL Server computer, "SQL Server Browser" will be listed in output of the net start command, if the SQL Server Browser is running. If net start shows that the SQL Server Browser service is running, the service may not be active. In the SQL Server Configuration Manager, the Active option must be set to "Yes" in the Advanced SQL Server Browser property tab. (The SQL Server Browser service must be restarted before any change to this setting takes effect.)

If you are connecting to SQL Server through a firewall, the firewall needs to allow connections through:

  • The SQL Browser UDP port, 1434.

  • The TCP port that the SQL Server instance is listening on.

  • If UDP port 1434 is not open, the firewall will block the connection when the Easysoft ODBC-SQL Server Driver attempts to discover the SQL Server port and the 'Failed to get datagram from socket' error displays.

Because the SQL Server Browser or listener accepts unauthenticated UDP requests, it may have been turned off as a security measure, and your database administrator will have configured each SQL Server instance to listen on a specific TCP port. You need to specify this port number with the Port setting. For example, if SQL Server is listening on port 1500, add this line to the data source in odbc.ini:

Port = 1500

The "Failed to get datagram from socket" error also displays if you try to connect to a hidden SQL Server instance. You need to specify the port that the hidden instance is listening even though the SQL Server Browser or listener may be running.

Login failed for user ''. The user is not associated with a trusted connection

Check that the User and Password attributes for the data source in odbc.ini specify a valid Windows user name and password.

This error also displays if you try to connect to SQL Server with a SQL Server user name and password but SQL Server’s authentication mode is set to Windows Authentication only. To connect by using a SQL Server account, the security mode for the SQL Server instance must be changed to mixed (both SQL Server and Windows authentication are enabled).

To enable mixed mode, your database administrator must set the SQL Server security property Server Authentication to SQL Server and Windows Authentication mode. Note that Microsoft recommend that Windows authentication is used to connect to SQL Server whenever possible.

Login failed for user 'myuser'.

Check that the User and Password attributes for the data source in the odbc.ini specify a valid SQL Server user name and password.

This error also displays if you try to connect to SQL Server with a valid Windows user name and password but no corresponding SQL Server login exists. For example, SQL Server Setup creates a login named BUILTIN\Administrators that allows members of the local Administrators Windows group to access SQL Server. As a security measure, the database administrator may delete this login and members of this group will then need individual SQL Server login accounts to access SQL Server.

Ask your database administrator to create a SQL Server login for you that uses Windows authentication to validate your connection details.

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-SQL Server Driver connection string for Linux and UNIX:

DRIVER=Easysoft ODBC-SQL Server;Server=myhost\\SQLEXPRESS;UID=mydomain\\myuser;PWD=mypassword;Port=1500;Database=Sales;

Here’s an example Easysoft ODBC-SQL Server Driver connection string for Windows:

DRIVER={Easysoft ODBC-SQL Server Driver};Server=myhost\SQLEXPRESS;UID=sa;PWD=mypassword;Database=Sales;

Logging

If you report an issue to us, we may ask you to turn on ODBC Driver Manager or Easysoft ODBC-SQL Server 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-SQL Server 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-SQL Server Driver logging is specific to the Easysoft driver and is of most use when making a support call.

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

[SQLSERVER_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.

ODBC Driver Manager logging on Windows

  1. In the Windows Taskbar Search box, enter “Run”.

  2. Do one of the following:

    • If your application is 64-bit, in the Run dialog box, enter:

      odbcad32.exe

      -Or-

    • If your application is 32-bit, in the Run dialog box, enter:

      %windir%\syswow64\odbcad32.exe
      If you’re not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit). For example, the process name for the 32-bit version of Excel is Microsoft Excel (32-bit); the process name for the 64-bit version of Excel is Microsoft Excel. On older versions of Windows, 32-bit applications contain *32 in the process name rather than (32-bit).
      For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
      If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the .exe file for the programming language. For example, run perl, php, python, or node. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains (32-bit).

  3. Choose the Tracing tab.

  4. Select Machine-Wide tracing for all identities.

  5. Enter a log file name and path in the space provided. For example:

    C:\Windows\Temp\SQL.log

  6. Choose Start Tracing Now.

With SQL Server, you may get two Driver Manager log files, we need both. The first log file is in the folder that you specify in ODBC Data Source Administrator. The second file’s location is defined by SQL Server. Two possible locations are the top-level folder (for example, C:\SQL.log) or the SQL Server temporary folder (for example, C:\Users\MSSQL$SQLEXPRESS\AppData\Local\Temp\SQL.log). If the Driver Manager log file isn’t in these folders, search for it on the drive where SQL Server is installed.

Easysoft ODBC-SQL Server Driver logging on Windows

  1. In the Windows Taskbar Search box, enter “Run”.

  2. Do one of the following:

    • If your application is 64-bit, in the Run dialog box, enter:

      odbcad32.exe

      -Or-

    • If your application is 32-bit, in the Run dialog box, enter:

      %windir%\syswow64\odbcad32.exe
      If you’re not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit). For example, the process name for the 32-bit version of Excel is Microsoft Excel (32-bit); the process name for the 64-bit version of Excel is Microsoft Excel. On older versions of Windows, 32-bit applications contain *32 in the process name rather than (32-bit).
      For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
      If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the .exe file for the programming language. For example, run perl, php, python, or node. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains (32-bit).

  3. Do one of the following:

    • If you configured a system data source, choose the System DSN tab.
      -Or-

    • If you configured a system data source, choose the System DSN tab.

  4. Choose your Easysoft ODBC-SQL Server Driver data source from the list, and then choose Configure.

  5. In the Easysoft ODBC-SQL Server Driver data source configuration dialog box, turn on Driver Logging.

  6. Enter a log file name and path in the space provided. For example:

    C:\Windows\Temp\Easysoft.log

Finding out what product version you have on Windows

If you have an issue with the Easysoft ODBC-SQL Server Driver, we may ask you to tell us what your product version is. To find this out:

  1. In the Windows Taskbar, enter “Add or remove programs” in the Windows Search box.

  2. Select Easysoft ODBC-SQL Server Driver in the list.

    The product version displays below.