Easysoft SQI-Zortec System Z Driver User Guide - Installation
Installing the Easysoft SQI-Zortec System Z Driver
This section explains how to install, license and remove the Easysoft SQI-Zortec System Z Driver on supported Windows and Unix platforms.
The Windows installation can be carried out by anyone with local administrator privileges for the target machine.
The Unix installation assumes you are, or have available for consultation, a system administrator.
Obtaining the Easysoft SQI-Zortec System Z Driver
There are three ways to obtain the Easysoft SQI-Zortec System Z 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-Zortec System Z 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/systemz_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-Zortec System Z Driver varies depending on the platforms on which you wish to run.
All installations must download the Easysoft SQI-Zortec System Z Driver software itself.
The name of the Easysoft SQI-Zortec System Z Driver install file varies from platform to platform, but is of the form:
- eda-systemz-x_y_z-platform.exe (Windows)
¯ OR ¯
- eda-systemz-x.y.z-platform.tar (Unix platforms)
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:
within specific Unix platforms, where "platform-variation" refers to alternative versions available for a single platform.
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.
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 "filefilename" to find out the file type of the downloaded file.
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.
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-Zortec System Z 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 Zortec System Z data:
- the Easysoft SQI-Zortec System Z Driver on the server platform
- the Easysoft JDBC-ODBC Bridge on the server platform
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-Zortec System Z Driver Download page.
- Install the Client Download onto 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:
On Unix you need to accept both the remote ODBC access and Install ODBC-ODBC Bridge Server options.
On Windows you also need to download the Easysoft ODBC-ODBC Bridge via the Multiple Platforms option, selecting your required server platform version, and install the Server Download on your server machine.
This provides the Easysoft ODBC-ODBC Bridge Server, the Easysoft ODBC-SQI SQL Engine and the Easysoft SQI-Zortec System Z Driver.
For the Easysoft JDBC-ODBC Bridge:
- Obtain your required platform version from the Single Platform option on the Easysoft SQI-Zortec System Z Driver Download page and install it on your server machine (on Unix you need to reject the Install OOB Server option).
This provides the Easysoft ODBC-SQI SQL Engine and the Easysoft SQI-Zortec System Z Driver.
- Obtain your required platform version from the Easysoft JDBC-ODBC Bridge Download page and install it on your server machine.
This provides the Easysoft JDBC-ODBC Bridge.
2. From the Easysoft FTP site:
- 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/systemz_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.
- the Easysoft ODBC-ODBC Bridge server component is bundled within the Easysoft SQI-Zortec System Z Driver archive file held in the ftp://ftp.easysoft.com/pub/systemz_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.
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.
You can now download a file and begin the installation process.
As long as you stop all running applications (on Windows), or any software either from Easysoft or using Easysoft drivers (on Unix), it is safe to reinstall or upgrade the Easysoft SQI-Zortec System Z 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).
Refer to the section relevant to your platform to continue:
Installing on Windows
1. Execute the file distribution that you downloaded in Obtaining the Easysoft SQI-Zortec System Z Driver.
Please shut down other Windows programs before installing. In particular, Microsoft Outlook can cause the installation routine to pause for several minutes when you start it.
There will be a short delay while setup prepares the wizard to guide you through the rest of the install procedure before the Welcome dialog box is displayed:
Figure 3: The Welcome dialog box
2. Click Next to continue.
The Software License Agreement dialog box displays more information about licensing and the components which are installed.
Figure 4: The Software License Agreement dialog box
3. If you do not agree to the License Agreement, click No to exit the installation.
¯ OR ¯
Click Yes to accept the License Agreement and continue with the installation.
The Information dialog box is displayed:
Figure 5: The Information dialog box
4. Click Next to continue.
The User Information dialog box is displayed:
Figure 6: The User Information dialog box
5. Enter your name and the name of your company. Then click Next to continue.
The name and company that you enter here will become the defaults in the License Manager later on.
You are then asked to choose where to install the Easysoft SQI-Zortec System Z Driver files in the Choose Destination Location dialog box:
Figure 7: The Choose Destination Location dialog box
6. Click Next to install the application into the default directory location:
C:\Program Files\Easysoft\Easysoft Data Access for Zortec System Z
¯ OR ¯
Click Browse and select an alternative directory location for the installation, before clicking Next.
The Easysoft Data Access for Zortec System Z DSN dialog box is displayed, pre-configured to set up a data source connecting to sample data.
Figure 8: The Easysoft Data Access for Zortec System Z DSN dialog box
7. Click OK to create the sample data source and continue.
Creating data sources connecting to your real System Z data is explained in "Creating additional data sources on Windows" on page 62.
Licensing on Windows
The install program now starts the Easysoft License Manager (explained fully in the Licensing Guide).
Licensing the Easysoft SQI-Zortec System Z Driver also obtains licenses for the Easysoft ODBC-ODBC Bridge and the Easysoft JDBC-ODBC Bridge.
The following types of license are available:
- a trial license which gives you free and unrestricted use of the product for a limited period (usually 28 days).
- a purchased license which gives you unrestricted use of the product. When you purchase the product, an authorization code is emailed to you.
8. Enter your contact details.
You MUST enter the Name, E-Mail Address and Company fields.
The Telephone and Facsimile fields are important if you require Easysoft to contact you by those methods.
Figure 9: The Windows License Manager screen
9. Click Request License.
You are asked for a license type:
Figure 10: The License Type dialog box
10. To obtain a trial license click Time Limited Trial and then click Next.
The License Manager asks what software you are licensing:
Figure 11: Select the product you are licensing
Select Easysoft SQI-Zortec System Z Driver from the drop-down list and then click Next.
¯ OR ¯
If you have obtained an authorization code for a purchased license, select Non-expiring License and then click Next.
The License Manager requests your authorization code.
Figure 12: The Authorization Number dialog box
Enter the authorization code and then click Next.
11. The License Manager displays a summary of your details and allows you to choose the method of applying for your license:
Figure 13: The License Application dialog box
Choose On-line Request if your machine has a connection to the internet.
The License Manager then transmits a network packet to the license server at Easysoft. The whole process is automatic and you can proceed to step 12.
Only your license request identifier and contact details as they are displayed in the main License Manager screen are sent to Easysoft.
The remaining three options (Email Request, Print Request and View Request) are all ways to obtain a license if your machine is offline (i.e. does not have a connection to the internet).
Each of these methods involves providing Easysoft with information including your machine number (a number unique to your machine) and then waiting to receive your license key.
Instead of emailing, faxing or telephoning your details to Easysoft, you can enter them directly onto Easysoft's web site and your license key will be emailed to you automatically.
To use this method, click View Request to display your machine number, then run a web browser and go to http://www.easysoft.com/sales/autolicense.phtml.
Choose the type of license you require, enter your machine number and then click Continue. Your license key will now be emailed to you.
When you receive the license key, you can activate it either by double-clicking the email attachment or by clicking Enter License on the License Manager main screen and pasting the license key into the dialog box.
A message is displayed, telling you how many licenses have been added.
If you use the Email Request option, the license key is emailed to the email address as displayed on the License Manager main screen, not the from: address of your email.
12. Click Finish in the License Manager to return to the install program.
The Setup Complete dialog box is displayed:
Figure 14: The Setup Complete dialog box
13. Click Finish.
The installation is complete.
See "Querying data sources" on page 59 for details of how to check if the installation has been successful.
Uninstalling on Windows
This section explains how to remove the Easysoft SQI-Zortec System Z Driver from your system.
You should uninstall this software before installing a more recent version.
1. Select Start > Settings > Control Panel and then double-click the Add/Remove Programs icon.
A list is displayed of applications that can be automatically removed.
2. Select Easysoft Data Access for System Z and click Add/Remove.
3. Click Yes to confirm that you wish to remove Easysoft Data Access for System Z and all its components.
The system begins to remove all the components. If shared components seem not to be required, you will be prompted to decide whether or not to delete them.
The Windows install/uninstall procedure incorporates 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 Yes or Yes to All to continue.
¯ OR ¯
If you have any doubts (e.g. uninstall procedures have failed in the past) you should click No or No to All.
The uninstall process removes the Easysoft Data Access for Zortec System Z components from your system.
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 return to the Control Panel Install/Uninstall window.
6. The uninstall process is complete.
Any licenses you obtained for the Easysoft SQI-Zortec System Z Driver and other Easysoft products are held 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.
Installing on Unix
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.
The Unix 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 temporary space for the installation files themselves.
- You must know the location of your System Z data dictionary (e.g. /z/DD.dat).
1. Log on to your Unix machine as the root user.
2. Download the Easysoft SQI-Zortec System Z Driver (see Obtaining the Easysoft SQI-Zortec System Z 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:
¯ OR ¯
If the distribution file has been bzip2ed (i.e. the filename ends in .bz2), then use:
¯ OR ¯
If the distribution file has been compressed (i.e. the filename ends in .Z), then use:
6. uncompress eda-systemz-x.y.z-platform.tar.Z
7. 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-systemz-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.
If you do not wish to keep the original downloaded distribution file you can now delete it safely.
8. Change into the newly-created eda-systemz-x.y.z-platform directory.
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
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.
10. If you have read and agree to the Easysoft License Agreement, type yes and then press <Enter> to continue.
You must type yes, not y, to continue.
11. Specify the directory into which you want to install the Easysoft SQI-Zortec System Z 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.
12. Depending on the server platform, there may be more than one configuration of the Easysoft SQI-Zortec System Z Driver in the distribution file. If this is the case, you will be asked to choose the configuration that best suits your system.
13. The Easysoft SQI-Zortec System Z Driver requires unixODBC to be installed. If you do not already have unixODBC installed, it is installed now.
The Easysoft product database now needs resetting. You should close down any Easysoft products that are currently running otherwise they may terminate unexpectedly and any applications using them will need to be restarted.
Licensing on Unix
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-Zortec System Z Driver.
By licensing the Easysoft SQI-Zortec System Z 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.
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 and licenses are retrieved, the licensing script outputs them to a file called licenses.out.
If the install script detects possible new licenses in the file licenses.out it asks whether you want to add them 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 certain System Z files, so that a data source can be set up to your data (by default this data source is named SYSTEMZ).
If you do not know the location of these files, press <Enter> to skip each prompt in turn.
You can specify these paths later by editing the data source directly.
- Enter the path of the data dictionary, e.g. /z/DD.dat. The DD.dat file defines the structure of your System Z application's data.
- Enter the path of the PN file, e.g. /z/PN. The PN file provides an alternative to using synonyms for file pointers; it lists the directory paths of filenames that begin with an asterisk (*).
- Enter the path of your SYNONYM.VAL file. This file lists the synonyms in your data.
- Enter the path of the data, e.g. /z/DATA. If your data cannot be located using the other references, the Easysoft SQI-Zortec System Z Driver checks this directory.
This information is written to <InstallDir>/easysoft/sqi/systemz/dsn_template, which is the temporary holding place for new data sources.
23. Choose whether to configure unixODBC for use with this [SYSTEMZ] data source.
odbcinst will then add the data source stored in dsn_template to odbc.ini which is placed in /etc by default.
24. Choose whether to create a data source to access sample data.
You are advised to accept this option, because the sample data source [SAMPLE_SYSTEMZ] is used as an example elsewhere in this manual.
The sample data is installed into <InstallDir>/easysoft/sqi/systemz/demo. Do not add any important information to the sample data, because it will be overwritten if you reinstall the Easysoft SQI-Zortec System Z Driver.
At the end of the install, information is displayed telling you which data sources have been set up and explaining how to test the installation by running the demosql SQL script provided with the Easysoft SQI-Zortec System Z Driver to query the sample data source (see "Querying a data source on Unix" on page 60).
If you choose to query the data source now, press <Enter> after you have finished to return to the system prompt.
You will not be able to query the sample data source if you have still to complete the offline licensing procedure.
Complete the licensing, as explained in Completing the offline licensing procedure and then try running demosql.
If, at step 22, you were unable to enter the locations of your System Z files, see "Unix odbc.ini settings" on page 69 for details of which settings you need to specify for the data source before you can access the data.
If you have more than one set of System Z data, you can create more data sources by manually editing <InstallDir>/easysoft/sqi/systemz/dsn_template and then running odbcinst to add them to odbc.ini.
See "Creating additional data sources on Unix" on page 68 for details of how to do this.
Once you have installed the Easysoft SQI-Zortec System Z Driver you can run the Web Administrator to create users and set up their access rights to restrict access to the System Z data. See "Using the Easysoft Web Administrator" on page 75 for details.
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-Zortec System Z Driver can be used.
The licensing information is written to the license_request.txtfile.
This file contains information including a machine number (a number unique to your machine) which Easysoft require before you can be issued with a license key.
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 the Easysoft 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 firstname.lastname@example.org. Your license key(s) will be emailed to you automatically.
- Email the file license_request.txt to email@example.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.
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-Zortec System Z Driver is now licensed and you can begin using it.
If you need further information about licensing, please refer to the Licensing Guide.
Uninstalling on Unix
To uninstall the Easysoft SQI-Zortec System Z Driver, you need to:
- stop the Web Administrator if it is running (the Web Administrator is explained fully in "Administration" on page 75).
- remove the <InstallDir>/easysoft/sqi/systemz directory.
To stop the Web Administrator:
1. Log onto your Unix machine as root.
2. Change into the <InstallDir>/easysoft/sqi/systemz directory.
3. You can check if the Web Administrator is running by typing
A list of the ports currently in use is displayed. By default the Web Administrator listens at port 8454.
5. When asked if you want to stop all http administration servers, type
If you do not stop the Web Administrator, then later perform another installation of the Easysoft SQI-Zortec System Z Driver, the installation may not be successful.
To remove the <InstallDir>/easysoft/sqi/systemz directory:
1. Change into the <InstallDir>/easysoft/sqi/systemz directory.
rm -rf *
to delete all the files and directories beneath the current directory.
to move back up one level in the directory structure.
to remove the systemz subdirectory.
If you have installed the Easysoft ODBC-ODBC Bridge or the Easysoft JDBC-ODBC Bridge and you wish to uninstall, please refer to the manual supplied with that product for details of its uninstall procedure.
Any licenses you obtain for the Easysoft SQI-Zortec System Z Driver and other Easysoft products are stored in the <InstallDir>/easysoft/license/licenses file.
After uninstalling the Easysoft SQI-Zortec System Z Driver, unless you have deleted this file, you will not need to relicense the product when you reinstall or upgrade.
However, for security purposes you may want to make a copy of <InstallDir>/easysoft/license/licenses before uninstalling.