Installing Zim 8

This document details all steps needed to install the latest version of Zim 8 on Windows and Unix and provides additional steps to be checked after ZimWeb installation.

You should also refer to the Release Notes of all versions up to the current one for details about what is new in Zim 8.

Windows Installation

Unix Installation

Additional Instructions for IBM AIX 4.x and 5.x

Additional Instructions for HP-UX 11

Additional Instructions for Linux

Additional Instructions for Solaris

Additional Instructions for Unixware

Remarks on ZimWeb Installation

Note: If you are installing ZimWeb . it will install the Java environment and Tomcat. However, this installation will not interfere with previous installations of any Java environment or Tomcat.

Windows Installation

For a successful installation, you must have full administrator privileges on the local machine. If you are not sure, contact your system administrator.

1. Increase Virtual Memory

Virtual Memory must be increased to accommodate Zim Server and handle shared memory segments across multiple databases. Choose the appropriate value below based on the desired implementation.

Client Implementation – available disk space: 500 MB

Server Implementation – available disk space: 2 GB

Note: These values represent the suggested minimum, and should not exceed half the amount of free disk space.

Windows XP: (Client/Server)

a) Open the Windows Control Panel and select the ”System” component.

b) Select the ”Advanced” tab.

c) Select the ”Performance Settings” button.

d) Select the ”Advanced” tab.

e) Select the virtual memory ”Change” button.

f) Select the drive which you installed on from the drive box.

g) Choose ”Custom Size”.

h) Set the ”Initial Size” and ”Maximum Size” to the recommended values.

i) Select the ”Set” button to apply the changes.

j) Select the ”OK” button. You may have to reboot your machine.

Windows 2000: (Client/Server)

a) Open the Windows Control Panel.

b) Select the ”System” component.

c) Select the ”Advanced” tab.

d) Select the ”Performance Options” button.

e) Select the virtual memory ”Change” button.

f) Select the drive which you installed on from the drive box.

g) Choose ”Custom Size”.

h) Set the ”Initial Size” and ”Maximum Size” to the recommended values.

i) Select the ”Set” button to apply the changes.

j) Select the ”OK” button. You may have to reboot your machine.

Windows NT 4 (SP6a): (Client Only)

a) Open the Windows Control Panel and select the ”System” component.

b) Select the ”Performance” tab.

c) Select the virtual memory ”Change” button.

d) Select the drive which you installed on from the drive box.

e) Choose ”Custom Size”.

f) Set the ”Initial Size” and ”Maximum Size” to the recommended values.

g) Select the ”Set” button to apply the changes.

h) Select the ”OK” button. You may have to reboot your machine.

Windows 98SE2/ME: (Client Only)

a) Open the Windows Control Panel.

b) Select the ”System” component.

c) Select the ”Performance” tab.

d) Select the ”Virtual Memory” button.

e) Select the ”Specify my own virtual memory settings” option.

f) Set the ”Minimum” and ”Maximum” to the recommended values.

g) Select the ”OK” button. You may have to reboot your machine.

2. Install Zim

1. Insert the Zim 8 software CD into your CD-ROM drive.

2. Zim 8 Setup automatically launches the Setup Wizard. If the Setup does not launch automatically, choose ”Run” from the Windows Start menu and execute the zim8setup.exe program in the CD Directory called Windows.

3. Follow the instructions as provided on the screen.

3. Install .NET Framework 1.1

In order to run ZimExplore, you need the run-time part of .Net called Framework 1.1. If you don't have this software installed, ZimExplore will not work. To install it, just go to Microsoft .NET Framework Version 1.1 Redistributable Package and click in "Download".

3. Additional Steps to Check ZimWeb

If you installed ZimWeb on Windows, you can check that ZimWeb is running correctly by going through the following procedure:

1. Make sure that Zim Server is running with the example application database that was installed with ZimWeb . This database is located in ZimWeb\exampledb where your Zim software was installed;

2. Verify that the file ZimWeb tomcat\webapps\ZII\WEB-INF\web.xml, located in the directory where your Zim software has been installed, contains the text "[ZIMWEB]". If so, change this text to the address of the directory where Zim software was installed. Example:

            <param-value>[ZIMWEB]\conf\zimweb.cfg</param-value>

change it to the following:

            <param-value>C:\Program Files\Zim Corporation\Zim\8.10\Zim\ZimWeb\conf\zimweb.cfg</param-value>

if you installed the Zim software in "c:\Program Files\Zim Corporation\Zim\8.10\Zim" (the default).

Similarly, change a second entry for "zimweb.log" as well, right below the above entry.

3. Start Tomcat by selecting Start | Programs | ZimWeb | Start Tomcat. You should see the database agents start on the Zim Integrated Server console.

4. Browse to the Tomcat Homepage by selecting Start | Programs | ZimWeb | Tomcat Homepage. If you see the Tomcat Homepage then Tomcat is functioning correctly.

5. Browse to ZimWeb Administration by selecting Start | Programs | ZimWeb | ZimWeb Administration. When requested for the username and password, enter "zimwebadmin" and "zimweb" (the default values) respectively. The ZimWeb Administration Tool should appear, and should be indicating that the Database Connections are running.

6. Stop and Start the database connections by pressing the appropriate button on the ZimWeb Administration page. Make sure that the connections are running for the next test.

7. Browse to ZimWeb Example Application by selecting Start | Programs | ZimWeb | ZimWeb Example Application. The ZimWeb Example Application page should appear. Check that each example runs correctly.

8. You can shutdown Tomcat by selecting Start | Programs | ZimWeb | Shutdown Tomcat. You should see the database agents terminated on the Zim Integrated Server console.

UNIX Installation

For a successful installation, you must have full administrator privileges on the local machine. If you are not sure, contact your system administrator.

1. Install Zim

1.  Insert the Zim 8 software CD into your CD-ROM drive.

2.  Change directories to the CD mounted directory and run the shell script "./Zim-8.xx.sh" where "xx" is the latest version of Zim 8.

3.  Follow the instructions as provided on the screen.

2. Setting the UNIX Environment Variables

To execute the Zim software, you first must set the UNIX environment variables. The commands used to set these variables vary depending on the shell being used.

Under the Korn Shell, Bourne Shell, or any POSIX Shell

Note: To make the settings consistent on a per-user basis, place these commands in the file ”$HOME/.profile”.

1.  Set the ZIM environment variable to indicate where Zim was installed (for example, /opt/zim8):

ZIM=/opt/zim8

export ZIM

2.  Set the ZIMTERM environment variable to indicate the name of your terminal. (The example ”build.ztcap” is installed with the software to give a starting point for configuring this file using the name ZIMTCAP):

ZIMTERM=build

export ZIMTERM

3.  Add the directory where the Zim files are located to your default search PATH:

PATH=$PATH:$ZIM

export PATH

Under the C Shell

Note: To make the settings consistent on a per-user basis, place these commands in the file ”$HOME/.cshrc”.

1. Set the ZIM environment variable to indicate where Zim was installed (for example, /opt/zim8):

setenv ZIM /opt/zim8

2. Set the ZIMTERM environment variable to indicate the name of your terminal (The example named ”build.ztcap” is installed with the software to give a starting point for configuring this file using the name ZIMTCAP):

setenv ZIMTERM build

3. Add the directory where the Zim files are located to your default search PATH:

setenv PATH $PATH:$ZIM

3. Configuring the Terminal

1. At the OS prompt, type $ZIM/zimtcap and press Enter.

2. Follow the instructions as provided on the screen.

Additional Instructions for IBM AIX 4.x and 5.x

1. Check the GCC package

You should also install the gcc package to run Zim. If you already have this package installed in our machine, disregard the following instructions.

To install gcc, go to www.bullfreeware.com and choose your operating system version. There, select the most recent gcc package (usually gcc-3.3.x) and download it. Next, follow the instructions in the item "install" found in the same page.

Additional Instructions for HP-UX 11

1. Apply Recent Patches

In order to run Zim 8, you need to apply all the most recent patches supplied by HP to your running environment.

2. Increase Shared Memory

The size of the Shared Memory needed will depend on the particular configuration used by Zim Server. If not enough memory is available, Zim Server will produce an error telling what is the shared memory needed.

To increase the shared memory, use the System Administrator Manager (SAM) to set the appropriate value of the parameter "shmmax".

Additional Instructions for Linux

1. Increase Shared Memory

The size of the Shared Memory needed will depend on the particular configuration used by Zim Server. If not enough memory is available, Zim Server will produce an error telling what is the shared memory needed.

To check the current shared memory, type command:

ipcs -lm

If it is needed to increase it, type the following command:

echo "NNN" > /proc/sys/kernel/shmmax

where "NNN" is the memory needed in bytes.

2. Increase Message Queues

Each Zim session requires two message queues. To check the existing queues, type the command:

ipcs -lq

If it is needed to increase it, edit the file /etc/sysctl.conf and add the following line:

kernel.msgmni=QQQ

where "QQQ" is the number of message queues needed (that is, 2 * number of users).

Then, run the following command to force the operating system to accept this new setting:

/sbin/sysctl -p

3. Check ZimWeb ./h3>

If you installed ZimWeb on Linux (not available on other UNIX platforms), you can check that ZimWeb is running correctly by going through the following procedure:

1. Make sure that Zim Server is running with the example application database that was installed with ZimWeb . This database is located in $ZIM/ZimWeb/exampledb;

2. Go to the $ZIM/ZimWeb/bin directory;  

3. Start Tomcat by executing  tomcat_startup.sh;

4. Browse to the Tomcat Homepage openning the Linux Web Browser and accessing http://localhost:8080. If you see the Tomcat Homepage then Tomcat is functioning correctly.

5. Browse to ZimWeb Administration openning the Linux Web Browser and accessing http://localhost:8080/ZII/servlet/ZIIAdmin . When requested for the username and password, enter "zimwebadmin" and "zimweb" (the default values) respectively. The ZimWeb Administration Tool should appear, and should be indicating that the Database Connections are running.

6. Stop and Start the database connections by pressing the appropriate button on the ZimWeb Administration page. Make sure that the connections are running for the next test.

7. Browse to ZimWeb Example Application openning the Linux Web Browser and accessing http://localhost:8080/ZII/example/index.htm .The ZimWeb Example Application page should appear. Check that each example runs correctly.

8. You can shutdown Tomcat by executing tomcat_shutdown.sh;

Additional Instructions for Solaris

1. Increase Shared Memory

The size of the Shared Memory needed will depend on the particular configuration used by Zim Server. If not enough memory is available, Zim Server will produce an error telling what is the shared memory needed.

If it is needed to increase it, edit the file /etc/system and add the following line:

set msgsys:shminfo_shmmax=NNN

where "NNN" is the memory needed in bytes.

Additional Instructions for Unixware

1. Increase Shared Memory

The size of the Shared Memory needed will depend on the particular configuration used by Zim Server. If not enough memory is available, Zim Server will produce an error telling what is the shared memory needed.

If it is needed to increase it, edit the file /etc/conf/cf.d/mtune and add the following line:

SHMMAX NNN

where "NNN" is the memory needed in bytes.

Next, you need to rebuild the kernel:

/etc/config/bin/idbuild

and reboot your machine.

Remarks on ZimWeb Installation

1. The ZimWeb Reference Platform

The ZimWeb installation includes not only ZimWeb . but also an Example Application, a Sun Java SDK and the Apache Tomcat Servlet Container. Together these are termed the "ZimWeb Reference Platform".

The "ZimWeb Reference Platform" is currently available for two environments: Windows and RedHat Linux.

The ZimWeb Reference Platform is straightforward to install on a Windows PC or on a redhat 7.x linux machine and is accomplished by the either Windows Installation or Unix Installation described above. It enables a Zim developer to start working with ZimWeb very quickly.

ZimWeb is a Java Servlet, which means that it can be executed on a variety of operating systems and Servlet Containers. ZimWeb has been tested successfully under various Java versions on various versions of Apache Tomcat on various platforms.

However, if you experience problems executing ZimWeb in another environment, then it is recommended that you attempt to reproduce the problem on one of the ZimWeb Reference Platform.

The ZimWeb Reference Platform consists of:

• Directory j2sdk - contains the Java environment: Java2 SDK Version 1.4.1_01 for Windows or redhat Linux (it depends on the environment that you receive ZimWeb ..

• Directory tomcat - contains the Servlet Container: Apache Tomcat V4.1.18 LE. In particular, note that ZimWeb itself is installed at tomcat/wepapps/ZII, and that by default the Tomcat logs for ZimWeb are in the files tomcat/logs/localhost_ZimWeb_log..

• Directory conf - contains the ZimWeb configuration file zimweb.cfg.

• Directory logs - contains the ZimWeb log file zimweb.log.<date>.txt

• Directory exampledb - A Zim database for the ZimWeb Example Application

• Directory WAR - contains the ZimWeb Web Application Archive file ZII.WAR, for installing ZimWeb in other Servlet Container Environments.

The Java environment is unmodified from the original Sun distribution.

2. Installing ZimWeb in other Servlet Container environments

Installing web applications into Servlet Containers is typically done using a Web Application Archive or WAR file. This is a JAR (Java Archive) image of the application root, file extension ".war" and with a name matching the application root directory name.

The file [ZIMWEB]/WAR/ZII.war is a Web Application Archive consisting of ZimWeb plus the web portion of the ZimWeb Example Application.

When installing it, you will need to adjust the ZimWeb configuration parameters config-file and log-file (in Tomcat these are found in the file [TOMCAT_ROOT]/webapps/ZII/web.xml) as appropriate.

3. Conflict with different XML parser and XSLT processors

ZimWeb requires JAXP 1.1 XML Parsing and XSLT Processing facilities. Tomcat itself, and other typical Servlet Containers, require XML Parsing facilities. ZimWeb includes recent versions of the Apache Xerces and Xalan APIs to provide these facilities in the directory [TOMCAT_ROOT]/webapps/ZII/WEB-INF/lib/jaxp.

However, if different versions of XML Parsing and XSLT Processing facilities are available at the same time then there can be conflicts between them, leading to the Servlet Container and/or ZimWeb malfunctioning.

There are several choices to make the required facilities available and function correctly, including:

• In the default installation environment, Java 1.4.x already includes these facilities. Hence the Tomcat 4.1.x LE version has been selected, which does not include these, and by default these facilities are not supplied in ZimWeb either, so there is no potential for conflict.

• If installing into an environment using a Java version 1.2.x or 1.3.x then the Java environment does not include these facilities, so XML Parsing will probably be included in the Servlet Container environment e.g. in Tomcat non-LE versions you would find these in the directory [TOMCAT_ROOT]/common/endorsed. So for Tomcat non-LE versions, we recommend that you replace the files in that directory (xerces.jar and xml-apis.jar) with the files in the directory [TOMCAT_ROOT]/webapps/ZII/WEB-INF/lib/jaxp.