Easysoft SQI-Sage Tetra CS/3 Driver User Guide - Installation

Installing the Easysoft SQI-Sage Tetra CS/3 Driver

This section explains how to install, license and remove the Easysoft SQI-Sage Tetra CS/3 Driver on supported Unix platforms.

The installation assumes you are, or have available for consultation, a system administrator.

Chapter Guide

Obtaining the Easysoft SQI-Sage Tetra CS/3 Driver

There are three ways to obtain the Easysoft SQI-Sage Tetra CS/3 Driver:

The Easysoft web site is available 24 hours a day at http://www.easysoft.com for downloads of definitive releases and documentation.

Select Download from the Easysoft SQI-Sage Tetra CS/3 Driver section of the website and then choose the platform release that you require.

First time visitors must complete the new user form and click Register. Note that your personal Internet options may require you to login and click Continue if you have previously registered.

The Easysoft FTP server is available 24 hours a day at ftp://ftp.easysoft.com, containing free patches, upgrades, documentation and beta releases of Easysoft products, as well as definitive releases.

Change to the pub/tetra_sqi directory and then choose the platform release that you require.

You can order Easysoft software on CD by email, telephone or post (see Contact Details).

What to install

The selection of components that you require to download in order to configure the Easysoft SQI-Sage Tetra CS/3 Driver varies depending on the platforms on which you wish to run.

All installations must download the Easysoft SQI-Sage Tetra CS/3 Driver software itself.

The name of the Easysoft SQI-Sage Tetra CS/3 Driver install file varies from platform to platform, but is of the form:

eda-tetra-x.y.z-platform.tar

where "x" is the major version number, "y" is the minor version number and "z" is the build index, which is incremented when minor changes are made.

"platform" will vary depending on the operating system distribution you require and you may come across files of the form:

eda-tetra-x.y.z-platform-variation.tar

within specific Unix platforms, where "platform-variation" refers to alternative versions available for a single platform.

NB	Select the highest release available for your platform within your licensed major version number (installing software of a different major version number requires a new Easysoft license).

Unix filenames may also be suffixed with .gz for a "gzipped" archive, .bz2 for a "bzip2ed" archive, or .Z for a "compressed" archive.

NB	If you download a Unix file using Windows, the browser may corrupt the filename. For example, if you download a `.gz` file and Windows corrupts the filename, it may not be obvious that the file is "`gzipped`". Use "`file`filename" to find out the file type of the downloaded file.

You can now download a file and begin the installation process.

Caution!

As long as you stop all running applications (under Windows), or any software either from Easysoft or using Easysoft drivers (under Unix), it is safe to reinstall or upgrade the Easysoft SQI-Sage Tetra CS/3 Driver without uninstalling.

If you do uninstall, you should first back up any configuration data that you still need, as uninstalling some Easysoft products will result in this information being deleted (license details remain in place).

Cross-platform data access

If you intend to implement cross-platform data access, you also need to install either the Easysoft ODBC-ODBC Bridge (see http://www.easysoft.com/products/2002/main.phtml) for remote ODBC access or the Easysoft JDBC-ODBC Bridge (see http://www.easysoft.com/products/2003/main.phtml) for remote JDBC access from Java applications.

The Easysoft ODBC-ODBC Bridge consists of two separate client and server components and the Easysoft JDBC-ODBC Bridge consists of a single server component.

NB	You cannot 'mix and match' server and client components of the Easysoft ODBC-ODBC Bridge and Easysoft JDBC-ODBC Bridge.

The following components are required for remote ODBC access to Sage Tetra CS/3 data:

the Easysoft SQI-Sage Tetra CS/3 Driver on the server platform
the Easysoft ODBC-ODBC Bridge server component on the server platform

the Easysoft ODBC-ODBC Bridge client component on the client platform

The first two digits of the version number must match when the Easysoft ODBC-ODBC Bridge client and server components are installed (see the Easysoft ODBC-ODBC Bridge manual for more information). This does not apply to the Easysoft JDBC-ODBC Bridge, where no specific client installation is required.

The following components are required for remote JDBC access to Sage Tetra CS/3 data:

the Easysoft SQI-Sage Tetra CS/3 Driver on the server platform

the Easysoft JDBC-ODBC Bridge on the server platform

Win 9x

If you are using Windows 9x with either the Easysoft ODBC-ODBC Bridge or the Easysoft JDBC-ODBC Bridge you will need Winsock2, which can be downloaded from http://www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/.

Cross-platform data access software can be obtained as follows:

1. From the Easysoft Web site at http://www.easysoft.com:

For the Easysoft ODBC-ODBC Bridge:

Obtain your required platform version for both client and server from the Multiple Platforms option on the Easysoft SQI-Sage Tetra CS/3 Driver Download page.
Install the Client Download on your client machine (on both Unix and Windows, you need to accept the Install ODBC-ODBC Bridge Client option and reject the Install ODBC-ODBC Bridge Server option).

This provides the Easysoft ODBC-ODBC Bridge Client.

Install the Server Download on your server machine (you need to accept both the remote ODBC access and Install ODBC-ODBC Bridge Server options).

This provides the Easysoft ODBC-ODBC Bridge Server, the Easysoft ODBC-SQI SQL Engine and the Easysoft SQI-Sage Tetra CS/3 Driver.

For the Easysoft JDBC-ODBC Bridge:

Obtain your required platform version from the Single Platform option on the Easysoft SQI-Sage Tetra CS/3 Driver Download page and install it on your server machine (you need to reject the Install OOB Server option).

This provides the Easysoft ODBC-SQI SQL Engine and the Easysoft SQI-Sage Tetra CS/3 Driver.

Obtain your required platform version from the Easysoft JDBC-ODBC Bridge Download page and install it on your server machine.

This provides you with the Easysoft JDBC-ODBC Bridge.

2. From the Easysoft FTP site:

On Windows:

for the Easysoft ODBC-ODBC Bridge both client and server components are contained in the same Easysoft ODBC-ODBC Bridge executable file held in the ftp://ftp.easysoft.com/pub/tetra_sqi/ directory.
the Easysoft JDBC-ODBC Bridge server component is contained in the Easysoft JDBC-ODBC Bridge executable file held in the ftp://ftp.easysoft.com/pub/jdbc-odbc-bridge/ directory. There is no client component to install.

On Unix:

the Easysoft ODBC-ODBC Bridge server component is bundled within the Easysoft SQI-Sage Tetra CS/3 Driver archive file held in the ftp://ftp.easysoft.com/pub/tetra_sqi/ directory.
the Easysoft ODBC-ODBC Bridge client component is contained in the Easysoft ODBC-ODBC Bridge archive file held in the ftp://ftp.easysoft.com/pub/odbc-odbc-bridge/ directory.

the Easysoft JDBC-ODBC Bridge server component is contained in the Easysoft JDBC-ODBC Bridge archive file held in the ftp://ftp.easysoft.com/pub/jdbc-odbc-bridge/ directory.

NB	Both client and server components are held in the same executable installation file for the Easysoft ODBC-ODBC Bridge. There is no specific client installation for the Easysoft JDBC-ODBC Bridge.

Installing the Easysoft SQI-Sage Tetra CS/3 Driver

Although this section covers a range of platforms and the precise output may vary from system to system, the installation process is essentially the same.

Installation requirements

The installation routine has the following requirements:

The Bourne shell (or BASH) must either be named (or linked to) /bin/sh or the first line of the install file updated to the correct location.
Various common Unix commands such as grep, awk, cut, ps, sed, cat, wc, uname, tr and find.

If any of these commands are missing they can be obtained from the Free Software Foundation (http://www.fsf.org).

Depending on the platform, you will need up to 10Mb of free disk space for the installed programs and up to 10Mb of temporary disk space for the installation files themselves.
You must know the location of your existing Sage Tetra CS/3 installation (e.g. /u/cs3).

Preparation

1. Log on to your Unix machine as the root user.

2. Download the Easysoft SQI-Sage Tetra CS/3 Driver (see Obtaining the Easysoft SQI-Sage Tetra CS/3 Driver).

3. Place the distribution file in a temporary directory on your Unix machine.

Extracting the installation files

4. Change to the directory in which the distribution file resides.

5. Extract the installation files from the distribution file:

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

gunzip eda-tetra-x.y.z-platform.tar.gz

¯ OR ¯

If the distribution file has been bzip2ed (i.e. the filename ends in .bz2), then use:

bunzip2 eda-tetra-x.y.z-platform.tar.bz2

¯ OR ¯

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

uncompress eda-tetra-x.y.z-platform.tar.Z

6. If the distribution file has not been compacted at all (i.e. the filename ends in .tar), then it is ready for extraction:

tar -xvf eda-tetra-x.y.z-platform.tar

The tar program creates a directory of the same name as the tar file (without the final .tar) containing further archives, checksum files, a script called install and a text file called INSTALL.

It also contains a versioned directory to ensure that any shared components already installed by other Easysoft products are only overwritten if those included in this distribution are newer.

NB	If you do not wish to keep the original downloaded distribution file you can now delete it safely.

7. Change into the newly-created eda-tetra-x.y.z-platform directory.

Caution!

Check through the INSTALL file before continuing. It gives full installation instructions for the Unix-literate, and if you are confident in the use and administration of your system, you can follow the instructions in the INSTALL file instead of working through the remainder of this section.

Beginning the Installation

8. Type:

./install

During the installation, you are asked to answer some questions. The default reponse is displayed in square brackets [], which you can press <Enter> to accept or you can choose any of the alternative responses shown in round brackets () by typing the required response and then pressing <Enter>.

Occasionally, the install program pauses to give you time to read the information displayed on screen. Press <Enter> to continue when you have read the current screen of information.

9. If you have read and agree to the Easysoft License Agreement, type yes and then press <Enter> to continue.

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

10. Specify the directory into which you want to install the Easysoft SQI-Sage Tetra CS/3 Driver.

If you accept the default base directory, the files are installed into a subdirectory called /easysoft within the specified path.

For example, if you accept the default path of /usr/local, the files are installed into /usr/local/easysoft.

If you specify an alternative directory, the files are installed into that directory but a symbolic link is created from /usr/local/easysoft pointing to the install directory. This link is necessary for licensing to work.

11. Depending on the server platform, there may be more than one configuration of the Easysoft SQI-Sage Tetra CS/3 Driver in the distribution file. If this is the case, you will be asked to choose the configuration that best suits your system.

12. The Easysoft SQI-Sage Tetra CS/3 Driver requires unixODBC to be installed. If you do not already have unixODBC installed, it is installed now.

Licensing the Easysoft SQI-Sage Tetra CS/3 Driver

13. You are now asked if you want to obtain a license. Accept the default [y] to start the licensing procedure.

A menu of options is displayed.

14. Choose the option to license the Easysoft SQI-Sage Tetra CS/3 Driver.

NB	By licensing the Easysoft SQI-Sage Tetra CS/3 Driver, you also license the Easysoft ODBC-ODBC Bridge.

You will then be asked to provide some contact information.

15. Enter your Name.

16. Enter your Company Name.

17. Enter at least one of Email, Phone and Fax (preferably all three).

18. At the Ref prompt, do either of the following:

If you want a trial license, leave it blank and press <Enter>.
If you want a purchased license, enter your authorization code then press <Enter>.

19. The License Manager displays a menu of options for acquiring your license.

If you have an internet connection you should select 1, Automatic. This is the quickest and easiest method unless your firewall or other network obstacles prevent the message from getting through.

¯ OR ¯

If you do not have an internet connection, or the Automatic option fails, select option 2 to write the required information to a text file in the current working directory called license_request.txt, which you will then need to view to obtain a license.

20. The License Manager displays the menu again. Select 0 to exit.

NB	The View Existing Licenses option will not display any license you obtained during this License Manager session. You must quit the License Manager and allow the install script to finish applying the license.

If you chose the automatic licensing method, any licenses that are retrieved are output to a file called licenses.out and the install script will ask whether you want to add any possible new licenses it detects in this file to the license database.

21. If you obtained licenses and you want to add them now, enter y.

¯ OR ¯

If you did not obtain licenses, enter n.

¯ OR ¯

If you do not see this message, then read on. You will need to complete the offline licensing procedure as explained in Completing the offline licensing procedure.

22. After the licensing is complete, the install program asks for the location of your Sage Tetra CS/3 installation.

23. After specifying the location of your Sage Tetra CS/3 installation, the install program sets up a data source for your Sage Tetra CS/3 data.

Once the Easysoft SQI-Sage Tetra CS/3 Driver is installed and licensed, you can start the Web Administrator program to enable users and grant them access to the Sage Tetra CS/3 tables, as explained in Administration.

Completing the offline licensing procedure

If at step 19 you chose to write the licensing information to a file, you still need to complete the licensing procedure before the Easysoft SQI-Sage Tetra CS/3 Driver can be activated.

The licensing information is written to the license_request.txtfile, which contains information including a machine number (a number unique to your machine) which Easysoft require before a license key can be issued.

1. Do any one of the following:

Display the license_request.txt file (e.g. using cat license_request.txt) and note the machine number. Now run a web browser and go to http://www.easysoft.com/sales/autolicense.phtml. Log in to Easysoft's web site. On the License Generator screen, choose the type of license you want, then enter your machine number and click Continue. You can now close the web browser. You will shortly receive your license key(s) via email.
Email the file license_request.txt to autolicense@easysoft.com. Your license key(s) will be emailed to you automatically.
Email the file license_request.txt to license@easysoft.com. A member of the Licensing Department will email the license keys(s) to you.

2. When you receive your license key(s), append them to the file /usr/local/easysoft/license/licenses, removing any LIC: prefixes.

NB	The Easysoft license responder puts an attachment in its outgoing emails that allows Windows users to activate their licenses with a double-click. If you read your email in Windows, this attachment will be visible but it will not work for licensing Unix versions of the software.

The Easysoft SQI-Sage Tetra CS/3 Driver is now licensed and you can begin using it.

If you need further information about licensing, please refer to the Licensing Guide.

Uninstalling the Easysoft SQI-Sage Tetra CS/3 Driver

To uninstall the Easysoft SQI-Sage Tetra CS/3 Driver, you need to:

stop the Web Administrator if it is running (the Web Administrator is explained fully in Administration).
remove the usr/local/easysoft/sqi/tetra directory.

To stop the Web Administrator:

1. Log onto the server machine as the root user.

2. Change into the /usr/local/easysoft/sqi/tetra directory.

3. You can check if the Web Administrator is running by typing

cat /etc/services

A list of the ports currently in use is displayed. By default the Web Administrator listens at port 8450.

4. Type

./stop_http.sh

5. When asked if you want to stop all http administration servers, type

y

If you do not stop the Web Administrator and then later perform another installation of the Easysoft SQI-Sage Tetra CS/3 Driver, the installation may not be successful.

To remove the usr/local/easysoft/sqi/tetra directory:

6. Change into the /usr/local/easysoft/sqi/tetra directory.

7. Type

rm -rf *

to delete all the files and directories underneath the current directory.

8. Type

cd ..

to move back up one level in the directory structure.

9. Type

rmdir tetra

to remove the tetrasubdirectory.

For details of uninstalling the Easysoft ODBC-ODBC Bridge server and client components, please refer to the Easysoft ODBC-ODBC Bridge manual.

For details of uninstalling the Easysoft JDBC-ODBC Bridge server and client components, please refer to the Easysoft JDBC-ODBC Bridge manual.