k42 Installation Guide

This document contains instructions for installing and uninstalling k42 on supported platforms.

Introduction

This document contains the installaton guides for k42 v1.1 on Windows 2000/ME, Solaris and Linux. It also includes the pre-requistite lists of hardware and software for k42 and troubleshooting guide.

For details on configuring k42, please consult the k42 Developers Guide.

Who should read this document?

This document should be read by users who wish to use k42 on their systems, or system administrators who wish to deploy k42 for several users.

Pre-requisites

k42 requires a 100% compliant Java™ 2 platform. For minimum hardware requirements, please consult the documentation for the Java runtime environment used. Exceeding these requirements will, of course, increase k42 performance which may become relevant when serving large numbers of concurrent users.

k42 has been successfully tested on all the platforms listed in this document.

For all installations we assume that the reader has already acquired the k42 software. The k42 software consists of two files:

k42.zip is a ZIP archive containing the core k42 functionality and documentation. There is also ak42.jar for users who cannot process Info-ZIP archives. The contents of these archives are identical.
k42.war is a Web Application archive, conforming to the Servlet v2.2 specification, ready to be deployed in a compatible servlet container. This archive contains the WebAuthor (WA) and TopicMap View (TMV) applications.

Software Pre-requisites

The following software is required to take advantage of all the k42 components:

Java™ 2 Runtime Environment (JRE). This is available from http://java.sun.com.
Jakarta-Tomcat v3.2.2. This is part of the Jakarta-Apache project and is a fully compliant Servlet v2.2 container and web server. It is available from here in ZIP format via HTTP and here in GNU-Zip TAR format. This document only provides basic installation instructions for Jakarta-Tomcat.
To access the k42 web applications it is recommended that clients use Internet Explorer 5.5 or higher.
Client's accessing the k42 web applications using Internet Explorer 5.5 will require the MSXML Parser 4.0 Technology Preview, available from MSDN downloads. k42 has been tested with the version 3 release, but for better compatibility we recommend the latest version. Installation instructions may be found on MSDN.

Installing k42

What are the k42 components?

Within k42.zip are three major components:

k42 application server
k42 developer JAR archives
k42 documentation and Javadoc API documentation

The k42 application server is a long-lived application which processes client requests, received via TCP/IP. Scripts are provided to control the server. The second component is a collection of Java JAR files which may be used to develop k42 programs of your own. This document contains instructions on how to configure the k42 Server. For instructions on how to write k42 programs, see the k42 Developer Guide.

Solaris 2.x/Linux

Unpack the k42.zip archive to a desired directory. For example /opt/k42. If you do not have tools for processing Info-ZIP archives, then unpackk42.jar instead, using the following command line:

jar xvf k42.jar

The jar utility is included with any Java 2 SDK distribution. When unpacked correctly, the target directory will contain the directory structure:

For clarity, the expansion of theapidoc and docs directories are not shown here.

k42 requires a single environment variable to be set in order to run: K42_HOME. This should be set to be the directory into which k42 was installed, with no trailing slash. For example, if you have installed k42 into /opt/k42, setK42_HOME to /opt/k42 It is recommended that you set this as a permantent environment variable. Consult your operating system documentation for instructions on how to do this.

To verify that k42 is now installed correctly on your system, from a shell prompt (change directory to $K42_HOME/binif not on the path) and execute

./k42.sh start

which will start the k42 application server as a background task and start printing logging messages to the console. When you see a line reading:

1342 [main] RMIService - GDO application Started.

(Note the number 1342 may be different), k42 is now active and ready for clients. To stop k42, simply execute:

./k42.sh stop

from the shell and k42 will shut down.

Warning: Always close the k42 via ak42.sh stop command. Killing the task or closing the application window may cause loss of data and/or data corruption.

Windows 2000 (All editions)

Unpack the k42.zip archive to a desired directory. For example, C:\k42. There are many ZIP utilities available for the Windows platform; for example WinZip v8.0, available from http://www.winzip.com. When unpacked correctly, the target directory will contain the directory structure:

For clarity, the expansion of theapidoc and docs directories are not shown here.

k42 requires a single environment variable to be set in order to run: K42_HOME. This should be set to be the directory into which k42 was installed, with no trailing backslash. For example, if you have installed k42 into c:\apps\k42, then the following command would set K42_HOME correctly:

set K42_HOME=c:\apps\k42

It is recommended that you set this as a system environment variable. Consult your Windows 2000 documentation for instructions on how to do this.

You may also wish to add the%K42_HOME%\bin directory to the system path. This will allow you to run k42 from any directory in the filesystem.

To verify that k42 is now installed correctly on your system, open up a command prompt (change directory to%K42_HOME%\bin if not on the system path) and execute

k42 start

which should create a new console window and start printing logging messages. When you see a line reading:

1302 [main] K42RMIService - k42 ready

(Note the number 1302 may be different), k42 is now active and ready for clients. To stop k42, simply execute:

k42 stop

from a command prompt window and k42 will shut down.

Warning: Always close the k42 via ak42 stop command. Killing the task or closing the application window may cause loss of data and/or data corruption.

Installing the k42 Web Application

The k42 web application archive:k42.waris a Servlet v2.2 compliant web application for use in Tomcat or any other compliant servlet container. k42 has been tested with Tomcat v3.2.1, v3.2.2 and v4.0beta1 successfully.

If you do not have an existing Tomcat installation and want to get up and running as quickly as possible, consult the quick-start guide below. Once Tomcat is installed, simply copy the k42.war in to the%TOMCAT_HOME%\webapps directory and restart Tomcat. Tomcat will automatically detect the new application.

Note: that you must not shut down k42 once a web client has connected to k42. This is because the servlets within the k42 web application keep persistent TCP/IP connections open to the k42 server. To shut down the system, shut down Tomcat first, then the k42 server to avoid errors.

Windows 98/ME

Please follow the installation instructions for installing under Windows 2000, with the following points taken into account:

Environment variables
K42_HOMEandTOMCAT_HOME environment variables maynot contain long filenames. Due to the limit on command line length within Windows 98/ME, we recommend using top-level directories ofk42 and TOMCAT, respectively.
Environment size
Windows 98/ME by default does not create MS-DOS sessions with enough environment space to deal with either Tomcat or k42's requirements. To fix this, edit the properties of the MS-DOS session and change the environment size to 4096 bytes. Restart the MS-DOS session to allow changes to take effect. If you are unsure how to do this, consult your operating system documentation.

Tomcat Quick-Start Guide

This section contains a quick-start guide to installing Tomcat. Please consult the Tomcat documentation for more detailed information.

Download Tomcat v3.2.2 from the Jakarta-Apache website.

Unpack this archive to a directory on your hard disk, for example unpacking to C:\ would produce a directoryc:\jakarta-tomcat-3.2.2. If you are using Windows 98/ME, you will need to rename this directory to a MS-DOS 8.3 filename (for examplec:\tomcat).

Set up a new environment variableTOMCAT_HOME to point to the top level directory of the Tomcat installation. Eg.
```
set TOMCAT_HOME=c:\tomcat
```

You may want to add the%TOMCAT_HOME%\bin directory to the system path, so you can launch Tomcat from any directory on the command line.

Starting and Stopping Tomcat

Starting Tomcat

To start Tomcat, issue the command:

tomcat.bat start

which is located in the %TOMCAT_HOME%\bin directory. This works in the same way as

k42
start

command.

To stop Tomcat, issue the command:

tomcat.bat stop

which is located in the %TOMCAT_HOME%\bin directory. This works in the same way as

k42
stop

command.

Troubleshooting

Error	Reason	Solution
k42 fails to start. Error is: "You must set JAVA_HOME to point at your Java Development Kit installation".	k42 could not find a Java runtime installation. k42 needs a Java 2 v1.3 compliant runtime (or better) to run.	If you have such a runtime installed, then ensure that the JAVA_HOME environment variable is set correctly. If you do not, then you must install one to run k42.
k42 fails to start. Error is: "Unable to locate topicmaps.jar, check the value of K42_HOME."	k42 requires the K42_HOME environment variable to be set to point to the top-level directory of k42. For example, if k42 was installed to C:\APPS\k42 then K42_HOME must equal "C:\APPS\k42".	Set up the K42_HOME environment variable correctly. Alternatively, run k42 while the current working directory is the bin directory within k42. To check the value of K42_HOME issue: echo %K42_HOME% on Windows platforms for echo $K42_HOME on UNIX platforms.
When I unpacked k42.ZIP, hundreds of files appeared in the directory I selected, but no subdirectories were created.	You've unpacked the k42.ZIP without preserving the archive directory structure.	Consult your ZIP application documentation for instructions on how to preserve archive directory structures when unpacking archives.
k42 refuses to start, a window appears for a fraction of a second and then disappears too quickly to see any error message.	k42 is not configured correctly.	To see the error message, rather than issue "`k42 start`", instead issue "`k42 run`" from a command prompt. This will cause k42 to run in the current command prompt session, rather than create a new one. You will then be able to see the error that is stopping k42 from running correctly.
I've tried to shut down k42, but it doesn't seem to affect the k42 window.	The k42 shutdown routine cannot find k42 running.
k42 refuses to start, the error in the k42 window contains the phrase:`Option unsupported by protocol: create`	TCP/IP is not installed on the machine.	Install TCP/IP drivers on your machine. Consult your operating system documentation for instructions on how to do this.