TOC Previous Next Index   Easysoft Homepage
       

Installation


Installing the Easysoft ODBC-ODBC Bridge

Installing the Easysoft ODBC-ODBC Bridge allows you to access ODBC data sources from other computers across the network running any supported Windows or Unix variant. This chapter covers the tasks necessary to install and remove the Easysoft ODBC-ODBC Bridge.

The Windows installation can be carried out by anyone. The Unix installation assumes you are, or have available for consultation, a system administrator.


Chapter Guide


What to Install (Windows and Unix)

The Easysoft ODBC-ODBC Bridge (OOB) consists of two main components, the OOB Client and the OOB Server. There are shared components which are needed to install either of these, and there are documentation files which you may leave out of the installation if you are comfortable with the OOB and want to save disk space. The Unix installation also offers a third-party driver manager . Windows already has one.

Installation of the OOB is more complicated than most software because the client and the server will typically be installed on different machines with different operating systems. Because of this, you will need to perform the basic installation procedure twice, probably in different environments.

Another important consideration is this: from time to time the protocol -- the language spoken between the Client and Server -- may change. For this reason you should try to ensure the client and server version numbers match in the first three fields, for example:


Obtaining The Software (Windows and Unix)

The Easysoft web site and FTP site are available 24 hours a day, offering Easysoft products for download, beta releases, free patches, upgrades, and documentation for Easysoft products. The web site can be found at http://www.easysoft.com/. Click products to go to the download area for definitive releases. If the browser asks you whether to open or save the file, save it to a temporary directory.

If you prefer to use the FTP protocol, the server is ftp.easysoft.com. This is a more efficient use of network and client resources and does not require a web browser. Change to the pub/product directory, switch to binary mode and get the file.

If you have an extremely slow connection, or no internet access at all, you can obtain the software on CD by writing to Easysoft at the address given in This Appendix. When you have the CD, the product can be found in the folder \Products\OOB.

The name of the install file varies from platform to platform, but you can expect something of the form:

... where v is the major version number, and w and x are minor version numbers. z is build index, which is incremented when minor changes are made which do not affect the client/server protocol.

Within your licensed major version number, you should go for the highest release available for your platform. To install software of a different major number requires a new license.

Whichever medium you choose, you should now download the file and begin the installation process. The exact installation process depends on your operating system. You should refer to the section relevant to your platform to continue.


Installation Under Windows

For Windows, the Easysoft ODBC-ODBC Bridge installation comes as an executable named EasysoftODBC-ODBCBridgev_w_x_y.exe, where v is the major version number, w and x are the minor version numbers, and y is the build number. If there is a choice of files then you should download the file with the highest version number.

1. From the web, click to download the installation file
– OR –

In your FTP client, switch to binary mode and get the installation file

– OR –

If you have a CD, navigate to the folder with the installation file in it.

Caution!
Please shut down other Windows programs before installing.
If you are upgrading you must remove any previously installed version before continuing. Refer to Uninstalling Under Windows for more details about this procedure.
If there is already an OOB Server running when you install a new version of the OOB, it will be stopped and all connections to it will be broken.

2. Execute the file EasysoftODBC-ODBCBridgev_w_x_y.exe. There will be a short delay while setup prepares the wizard to guide you through the rest of the install procedure, then you are presented with the Welcome screen.

Figure 2.1: Welcome Dialog.
3. Click Next when you have read the welcome screen. A window appears containing notes specific to that release.

Figure 2.2: Release Information Dialog.
4. Once you have read the release information, click the Next button.

The User Information dialog appears.

Figure 2.3: The User Information Dialog.
5. Enter your name and the name of your company. Click Next.

The next window allows you to choose where to install the files.

Figure 2.4: Destination Selection Dialog.
6. Click the Next button to install the application into the default directory location:

C:\Program Files\Easysoft\Easysoft ODBC-ODBC Bridge.

– OR –

Click the Browse button and select an alternative directory location for the installation, before clicking the Next button.

The next screen offers you a choice of three setup types: Typical, Compact and Custom.

Figure 2.5: Select Installation Type Dialog.
7. Select Typical to install all components, documentation and examples. This is recommended for developers and administrators.
– OR –

Select Compact to install the client and server but no documentation or examples. This is recommended for users' machines and servers, if your administrator already has a `typical' installation of the bridge elsewhere.

– OR –

Select Custom to choose what components to install. This is useful if disk space is at a premium, or you wish to restrict a machine to being either a client or a server.

8. Click Next to proceed. If you selected a Typical or Compact installation, skip to step 10.

If you selected Custom, then you will be presented with a checklist of items to install. Note that the Common System Files box must be checked if either Client or Server is checked.

Figure 2.6: Custom Installation Dialog.
9. Select the items to install and click Next to proceed.
10. A License Agreement dialog appears. Different license text appears depending on whether or not you elected to install the server.

Figure 2.7: License Agreement Dialog.
11. If you agree to the License Agreement then click Yes to continue with the installation.
– OR –

If you do not agree with the license agreement click No and refer to the license agreement in This Appendix for more information. Please do not hesitate to contact Easysoft with any questions. Easysoft contact information is given in This Appendix.

If you elected not to install the Server, then skip to step 15 Otherwise, a server configuration dialog box will appear.

Figure 2.8: The Server Configuration Dialog.
12. The server configuration box contains three settings;

Unless you think you will have a port conflict, or have some reason to change the timeout (See Choosing another Port or Service Name for more information,) you should keep the default values and click Next. You are asked for a Server Administrator user name.

Figure 2.9: Server Administrator's Username Dialog.

This should be the login name of an existing Windows user account. Only this user will be able to use the online configuration tool to modify server parameters (See The HTTP Configuration Interface), so it may be worth creating a specific "OOB Admin" user for the purpose.

13. Enter your chosen administrator's user name and click Next.
14. A summary screen is displayed.

Figure 2.10: Summary Dialog.
15. Click Next. There is now a short wait while the relevant bridge components are copied and configured.

Licensing Under Windows

16. If you selected the Custom installation, and elected not to install the server, then you do not need a license. Skip to step 29.
– OR –

The install program starts the Easysoft License Manager (For full information on the License Manager, refer to This Appendix). It is possible to complete the installation without licensing the product, but you will not be able to use the server until a license is obtained. A time-limited trial license can be obtained for free, or if you have already purchased a full license you will have an Authorisation Code, which you should have to hand.

Figure 2.11: License Manager Window.
17. Enter your contact details. You should include at least your name, email and company name. The telephone and facsimile fields are important if you want us to contact you by those methods. Click Request License. You are asked for a license type.

Figure 2.12: License Type Dialog.

The next step depends on the type of license you want.

18. If you are installing the software on an evaluation basis you should click Trial, followed by Next. Skip to step 20.
– OR –

If you have purchased the software and obtained an authorisation code, you should select Purchase and click Next.

The License Manager requests your authorisation number.

Figure 2.13: Authorisation Number Dialog.
19. Enter the authorisation code you received when you completed your purchase, and click Next. Skip to step 21.
20. The License Manager asks what software you are licensing.

Check that Easysoft ODBC-ODBC Bridge is selected in the drop-down list, and click Next.

21. The license manager displays a summary of the information you entered and allows you to choose the method of applying for your license.

Figure 2.14: License Application Dialog.

Four options are offered here:

22. If you choose On-line request, then click On-line Request now. The license transaction is complete and you can skip to step 27.
– OR –

To use email, fax or phone, click E-mail Request, Print Request or View Request now.

23. Read the information window and close it. You are returned to the license manager window, where you should wait until you receive a reply in order to proceed with the next step.
– OR –

If you wish, you can continue with the installation process and return later to license the product, referring to This Appendix for instructions.

24. When you receive your License Key(s), click Enter License. The following dialog appears:

Figure 2.15: License Key Dialog.
25. Enter your license key or keys in the box. If you received the license in an email, you can use Windows' Copy and Paste functions. You do not have to be very precise with the mouse, as this dialog will be quite tolerant of spurious characters before and after the license keys.
26. Click Apply.
27. Click OK in the dialog that pops up to confirm that the licenses have been added.
28. Click Finish in the License Manager window to return to the install program.
29. Click Finish again -- the installation is complete.

Easysoft provide a small demonstration client program which can demonstrate the OOB client in action by connecting across the internet to the server demo.easysoft.com. Refer to The Demo.exe Client for more details.


Uninstalling Under Windows

This section explains how to remove the Easysoft ODBC-ODBC Bridge from your system. This is necessary if you are planning to install a more recent release of the OOB. This does not include service packs.

1. Select Start > Settings > Control Panel and then double-click the Add/Remove Programs icon.

You will then be presented with a list of applications that can be automatically removed.

2. Select Easysoft ODBC-ODBC Bridge and click the Add/Remove button.
3. Click Yes to confirm that you wish to remove the Easysoft ODBC-ODBC Bridge and all its components.

The system will then begin to remove all the components. If shared components seem no longer to be required, then you will be prompted to decide whether or not to delete them.

NB
Windows' install/uninstall procedures incorporate a mechanism in the registry to determine whether or not shared files are still required by other programs. Sometimes this database can become out-of-date, for instance if the user deleted an application directly, without using Add/Remove Programs, or the registry was `repaired' after a system crash.

4. If you feel confident with the registry (i.e. your system has had relatively few programs installed and removed) you should click the Yes or Yes to all button to proceed.
– OR –

If you have any doubts (e.g. uninstall procedures have failed in the past) you should click the No or No to All buttons.

The uninstall process removes the Easysoft ODBC-ODBC Bridge components from your system.

NB
If files have been created in any of the installation directories then these directories will not be removed. In this case, the uninstall program will issue a warning and you can click Details to find out what directories remain.

5. On completion, click OK to go back to the Control Panel Install/Uninstall window.
6. The uninstall process is complete.

Installation Under Unix

Preparation

Because this section covers a range of platforms, there are many possible paths through the install process. It is worth having a notepad to hand, as information may be given during the install process which is of vital importance to successfully completing the installation. For example, if you are not logged in as the root user whilst installing, then there may be some manual configuration work for the root user to do later.

If you have not already done so, refer to Obtaining The Software (Windows and Unix), to get the installation archive onto your system.

For Unix systems, the filename is of the following form:

odbc-odbc-bridge-v.w.x.y.platform.tar

This filename may be suffixed with .gz for a "gzipped" archive, or .Z for a "compressed" archive. platform may be aix, sunos, linux-libc5, linux-glibc, or any other supported platform.

NB
If you downloaded a Unix file using Windows, then there is a good chance that the browser has broken the filename. You can normally work out what is wrong by experimenting with gunzip, uncompress and tar.

1. If you have not already done so, consult What to Install (Windows and Unix) and Obtaining The Software (Windows and Unix), and copy or download the file into a working directory.

You must have write access to this directory, but it need not be the install directory -- in fact, it is better if it is not. It is a good idea to put the archive in a temporary directory which can be removed after installation.

2. Determine whether or not you need root (superuser) access.

If you are installing the server end of the Easysoft ODBC-ODBC Bridge then root access is required, as the installation script needs to modify the services and inetd configuration files.

If you are installing only the client end then root access should not be required unless:

3. Start a terminal session, as root if necessary, and change to the directory the archive file resides in. The next step is to extract the installation files from the archive.

Extracting the installation files

4. If the archive has been gzipped (i.e. the filename ends in .gz), then use:

$ gunzip odbc-odbc-bridge-v.x.y.z.platform.tar.gz

– OR –

If the archive has been compressed (i.e. the filename ends in .Z), then use:

$ uncompress odbc-odbc-bridge-v.x.y.z.platform.tar.Z

– OR –

If the archive has not been compacted at all (i.e. the filename ends in .tar), then the archive is ready for extraction.

5. Extract the files from the archive:

$ tar -xvf odbc-odbc-bridge-v.x.y.z.platform.tar

The tar program creates a directory of the same name as the tar file (without .tar), containing further archives, checksum files, a script called install and a text file called INSTALL. If you do not wish to keep the original downloaded archive you can now safely delete it.

6. Skim through the INSTALL file before continuing. It gives full installation instructions for the Unix-literate. If you are confident in the use and administration of your system, you can skip the rest of this section and rely on the INSTALL file.

Caution!
Be sure to remove any old version of the Easysoft ODBC-ODBC Bridge before proceeding, or there may be conflicts after installation which will prove difficult to resolve.
You will need approximately 5MB of free space for the Easysoft ODBC-ODBC Bridge, plus an additional 3MB for temporary files which can be deleted after installation.


7. There are two license files provided in the archive; one applies if you are installing only the client side, the other if you are installing the server or both the client and the server.

Caution!
You must read and accept the terms of the applicable license to use the software. The license texts can be found in the files Client-License.txt and Server-Client-License.txt, respectively. Determine which applies to you, and be sure to understand its terms before continuing.


Beginning the Installation

The illustrations in the following section are taken from a session installing the pre-release (version 0.8.0.0) as the root user on a linux/libc5 system. Although the precise output will differ for other platforms, the installation process is essentially the same.

8. Once you have taken care of any matters arising from the INSTALL text file, begin the installation:

Figure 2.16: Starting the Installation under Unix.
9. If you have read and agree to the License Agreement, Enter yes to continue.

NB
You must type yes, not y, to continue.


10. The script pauses to allow you to read its output so far. Up to this point it has merely checked the following;
11. Hit <Enter> to continue.

The script checks the archive package.

Figure 2.17: The Script Checks the Archives.

There are three possible outcomes to this check:

12. If the check failed because of missing components, enter y to continue regardless, or n to quit and investigate the missing components.
– OR –

If the check was carried out and the files failed then the files have been damaged. Return to Obtaining The Software (Windows and Unix) and download the install archive again.

– OR –

If the files passed the check then read on.

13. Hit <Enter> to continue.

The install script then explains the situation regarding root privileges, i.e. if you are not root then:

14. If you are not root then you will be asked whether you want to continue. Enter y and read on, or enter n to quit.
– OR –

If you are root, read on.

The script then asks for a directory in which to place the easysoft installation directory tree. The default is /usr/local, which would be the normal location to install software for system-wide use. If you do not have root access, or you wish to install the software in another directory, you will need to specify a directory name here.

NB
The installation script will create a directory easysoft under the directory you specify here. All the Easysoft ODBC-ODBC Bridge files will be placed in the easysoft directory.
The installation script can accept a path to a directory that does not exist, provided its parent exists. For example, if the directory /usr/local exists on your machine, the script can accept the non-existent directory /usr/local/odbc and will create it, but will not create /usr/local/odbc/oob.

15. If you have root permission and want a typical system-wide installation, hit <Enter> to place the easysoft directory in /usr/local/.
– OR –

If you do not have root privileges, or have other reasons for a custom installation directory, type the desired directory and hit <Enter>.

16. The script now creates the easysoft directory under the directory you specified. If your chosen directory does not exist, you will be asked whether or not the script should create it. Enter y or n.
17. If the chosen directory already contains an easysoft directory, then the script warns you that you may be installing over a previous installation of the ODBC-ODBC bridge. It asks you whether or not you wish to continue with the installation. Enter y or n.
18. If you chose a directory other than /usr/local, then the script creates a symbolic link /usr/local/easysoft, pointing to the easysoft directory in the directory you specified.
19. Hit <Enter> to continue.

Installing unixODBC and Common Files

Next, if your platform allows, the script offers to install the unixODBC driver manager. You should normally do this if you are installing the server. You may wish to skip this step if:

20. If you do not wish to install unixODBC, enter n and skip to Installing the Client Side.
– OR –

If you wish to install unixODBC, enter y at the prompt.

21. The script pauses at this point. Hit <Enter> to continue.

The script extracts the unixODBC files.

22. The script pauses again. Hit <Enter> to continue.

The parts of the OOB installation common to both client and server are extracted.

Installing the Client Side

The script asks you whether you want to install the client side of the bridge. This is required if you want to connect an ODBC client application on the local machine to a remote datasource.

23. Enter n to skip the client. Skip to Installing the Server.
– OR –

Enter y to install the client. Read on.

24. Press <Enter> to continue.

The script extracts the client files.

25. Press <Enter> to continue.

The script displays important information regarding the dynamic library locations at this point.

Linux
The script sets up the dynamic linker with the paths to the client shared objects.
If you are not the root user then you will need to configure the dynamic linker manually. Make a note of any paths you are given as you will need to get a root user to set it up for you.
If you have the file /etc/ld.so.conf, then you need to insert the paths you were given in here, then run /sbin/ldconfig to re-read the changes.

26. Press <Enter> to continue.

Configuring the Client in unixODBC

The script offers you the chance to set up the client under unixODBC. Doing this permits ODBC applications on the local machine to choose a datasource on the fly. The driver manager loads the required driver (such as the OOB client). This is particularly useful if you intend to run local ODBC datasources as well as connect across the OOB.

27. If you do not want to set the OOB up under unixODBC or you do not have unixODBC, enter n and skip to Installing the Server
– OR –

If you have unixODBC installed on your system, and wish to use it with your bridge client, enter y.

The script attempts to run odbcinst, the command for installing data sources under unixODBC.

28. If the odbcinst program is not in its expected location, you are asked to provide the directory into which unixODBC was installed.

Enter q to abandon the attempt to configure unixODBC, and skip to Installing the Server.

– OR –

If known, supply the unixODBC install path.

The script checks for the OOB being already set up under unixODBC.

29. If the unixODBC driver manager is already configured for the ODBC-ODBC bridge, then a warning is given. Make a note of this warning.

Caution!
If unixODBC has been previously configured with the ODBC-ODBC Bridge then it will continue to pick up the OOB software from the directory in which it was originally installed. If the current install directory is different, then unixODBC will pick up the old version of the bridge, resulting in incorrect behaviour.


30. The script now calls odbcinst with the relevant details for the OOB client. Should this part of the installation fail, you will need to resort to the unixODBC documentation and manually reconfigure the Driver Manager.

REF
Comprehensive unixODBC documentation can be found at http://www.unixodbc.org/.
The settings that the install script attempted to set can be found in the file unixODBC.template.


Installing the Server

The script asks you whether you wish to install the server. This allows you to make datasources on the local machine available to remote ODBC clients.

31. If you wish to skip the server install, enter n and skip to the end, checking the list on This Link.
– OR –

Enter y, and read on.

32. Hit <Enter> to continue.

The necessary files for the server end of the bridge are extracted.

33. Hit <Enter> to continue.
34. If you are not root, then the installation terminates. Skip to step 40
– OR –

If you are root user, the script now begins to install the server.

It only remains to modify your system's configuration to register the bridge as a service. The script asks whether you would like to install the services and inetd entries.

35. Enter n and the installation terminates. Skip to step 40.
– OR –

Hit <Enter> to continue.

The script now amends the /etc/services and /etc/inetd.conf files.

36. If either of these files is missing or protected against writing, then you must supply their locations as prompted.

NB
You must specify the actual name of the file, not just the location, so if your inetd.conf file is in the /etc/net directory then you must enter:
/etc/net/inetd.conf


The script looks for an existing entry in the services file for the OOB server's default service name. If one already exists then you are prompted for a decision.

37. If there is no service name conflict, then skip to step 38.
– OR –

If there is a conflict and you wish to define a new service name for the server, then type d, hit <Enter>, then enter your chosen new name for the server service.

– OR –

If there is a conflict and you wish to overwrite the existing service entry, then enter r.

The script creates backups of both the services and inetd.conf files to services.pre_OOB and inetd.conf.pre_OOB.

38. The script looks for an existing entry in the services file for the OOB server's default port. If an entry already exists then you are asked to choose another port. Enter another four-digit port number -- the script checks whether the new value conflicts with any other services.
39. If the script cannot determine what shell to use for the inetd.conf file, then you must enter one at the prompt.

Now inetd is restarted so that it takes on the changed configuration files, and the server startup script is installed.

Completing the installation

40. Hit <Enter> to return to the shell prompt.

Don't forget:


Uninstalling Under Unix

To remove the Easysoft ODBC-ODBC Bridge from your Unix system you must manually remove the entries for the server from services and inetd. This requires root access. If your system has a dynamic linker, such as linux's ld.so, then you must also remove the bridge directories from the dynamic linker search path. This may require root access, depending on the mechanism used on your platform. Finally you must remove the install directory tree. This requires the same privileges as the user who performed the installation (in practice, this will often be root too). A step-by-step guide follows.

1. Log in as root.
2. If you have the ld.so.conf file, make a backup copy, e.g.

# cp /etc/ld.so.conf /etc/ls.so.conf.safe

3. Copy the inetd and services configuration files to make backups:

# cp /etc/inetd.conf /etc/inetd.conf.safe

# cp /etc/services /etc/services.safe

Deregistering the Client and Server Ends

4. Open /etc/services using your favourite editor.

Look near the end of the file for a line like this:

esoobserver 8888/tcp # Easysoft ODBC-ODBC Bridge

Again, if you created more than one server then you will have more than one line like this in the file. Each such line should have a comment like that above.

If you have more than one Easysoft ODBC-ODBC Bridge server, then there will be more than one line in the services file. esoobserver is the default name for an OOB service, but additional OOB services will have different names. In place of esoobserver will appear whatever name you gave to the additional service: You should make a note of the names of all the services you remove at this stage.

If you do not intend to install a later release of the Easysoft ODBC-ODBC Bridge then you will have to remove all services that were configured for use with it.

5. If you do not intend to re-install the Easysoft ODBC-ODBC Bridge, delete all lines pertaining to all OOB servers and write the file.
– OR –

If you are going to upgrade the OOB software and you want the configuration to remain the same, leave the lines in place and close the file.

6. Open /etc/inetd.conf in your editor.

Look for a line in the file similar to the following:

esoobserver stream tcp nowait root /bin/sh /bin/sh /usr/local/easysoft/oob/server/SERVER

esoobserver is the name as specified in the services file; so there should be one entry in inetd.conf for every entry you saw in the services file.

7. If you do not intend to re-install the Easysoft ODBC-ODBC Bridge, remove the lines pertaining to all OOB servers and write the file.
– OR –

If you are going to replace the OOB software and you want the configuration to remain the same, leave the lines in place and close the file.

8. Use ps to find the Process ID (PID) of the inetd process, and send it a Hangup signal:

# kill -HUP pid

The next step is to notify the dynamic linker that the shared objects will no longer be available.

Linux
If you have the file /etc/ld.so.conf, then manually remove the paths to the OOB's shared objects. The lines will be of the following form:
install-dir/easysoft/oob/client,
install-dir/easysoft/oob/lib, and possibly also
install-dir/easysoft/unixODBC.

Removing the Software

The final task is to remove the software from your system's filestore.

9. Enter the following:

# cd install-directory/easysoft/

# pwd

The system displays the current directory. Double-check that this is the directory under which you installed the Easysoft ODBC-ODBC Bridge.

Caution!
Be very careful issuing the rm -r command as root. Normally rmdir will not remove directories that contain files, but rm -r will remove all subdirectories along with their contents. It is possible to effectively destroy your system and/or lose all user files by removing the wrong directory.

# ls

(Check that you are in the right directory)

# rm -r oob

The system may ask you to confirm deletion for some files -- you can confirm these as long as you are sure you are in the correct directory.

# cd ..

# ls

If you have no other Easysoft products on your system and you are not using any copy of unixODBC that may be in this directory, then you can delete the easysoft directory too.

# rm -r easysoft

If there are other files in there, i.e. you have another Easysoft product installed too, then you must leave them.

10. If you left the installation files on your system then you may wish to remove them at this point.

The uninstall process is complete.

[Top] | [Contents] | [Previous] | [Next] | [Index]

Easysoft Ltd. Easysoft - The Home of Data Access
Easysoft Ltd.