"AntWorld" (Apr 2000) Release: Client Installation Instructions

Contents

• What software is required to use the AntWorld?

• Do I need to download anything?

• What platforms can I run Antscape on?

• Install on a UNIX machine

• Install on a Microsoft Windows 95/98 machine

• Install on a Microsoft Windows NT machine, as a regular user

• Install on a Microsoft Windows NT machine, as the system administrator

• Where do I get Java virtual machine?

For configuration options, upgrading, and troubleshooting, please see our FAQ

What software is required to use the AntWorld?

1. To use AntWorld, you need the Netscape Navigator web browser, preferably version 4.07 or more recent 4.* versions. For Windows XP operating system, version 4.77 is recommended. (Older versions seem to crash on our code fairly often; we have not had a chance to test much with NN 5.* or 6.*). Here is the page for obtaining the "approved" versions of Netscape.

   The Netscape browser, for whatever platform you are using (Solaris, IRIX, LINUX, MS Windows 95, Mac OS, etc.), can be downloaded free of charge from Netscape Communication Corporation. Unfortunately, this release of the AntWorld cannot be conveniently used with other web browsers. This is because the JavaScript language interpreters built into browsers are not fully standardized yet, and we had to use browser-specific code to accomplish some important operations.

2. Besides Netscape, you don't have to install any special software to use AntWorld. However, you can also download and install the AntWorld client (Antscape), in order to use the AntWorld ant marking feature. Antscape is a Java program that will work with your browser while you are browsing the World Wide Web and insert small ant icons marking useful links in the pages you are viewing.

3. AntWorld can also be used with Microsoft Internet Explorer, but in a much less reliable way than with Netscape. If you want to use AntWorld with MSIE, you must install Antscape. You also need to follow special instructions for MSIE, which involves installing some additional third-party software. Antscape has not been validated for Microsoft Windows XP.

4. If you want or need to install Antscape, you will also need a Java Virtual Machine (a Java interpreter). If you are using the installation package for Microsoft Windows, it will automatically check whether it is already installed on your computer. On any platform, you can also check if you have one on your computer simply by typing

        java
   

   on the command-line prompt. If you don't have a Java virtual machine, download it from Sun.

Do I need to download anything?

There is also the AntWorld client, called Antscape. You can download and install it in order to access some the complete functionality of AntWorld. Currently (Spring 2000), the main difference between using AntWorld with and without AntScape is that with AntScape you get the so-called "ant marking": in any document you view, links to pages suggested by AntWorld are marked with a small ant icon. Antscape has not been validated for Microsoft Windows XP.

Antscape is a Java program that will run on your computer ("the client side") when you use the AntWorld. Although it is written in Java, it has some operating-system-specific code, since it has to figure where on your computer Netscape configuration files reside and to modify them, and then to start Netscape.

Downloading the AntWorld client (Antscape)

On a UNIX machine

1. Make sure you have the Netscape web browser installed on your computer, and can actually browse the Web using it from your personal account.

   (Usually, Netscape works right out of the box, but on some sites a bit of configuring may be required. For example, if you are separated from the outside world by a firewall, you may have set the proxy server parameters correctly in the Netscape's Edit -> Preferences -> Advanced -> Proxies menu.)

2. Download file antworld.tar.gz (62 kB; also available via ftp) to a suitable directory on your machine. (Your home directory is fine).

3. Uncompress and untar it with the following commands:

   gunzip antworld.tar.gz
   tar xvf antworld.tar
   

   This will create a subdirectory named antworld, which will contain a Java archive file (local.jar) and a shell script (antscape.sh).

4. Every time you want to use the AntWorld, exit Netscape (if you are using it at the time) and run the script

   antworld/antscape.sh
   

   This script starts the Local Ant Proxy Server, modifies your Netscape preference file (see details here if you care), and starts Netscape at the AntWorld starting page.

5. As you are running your first AntWorld quest, Netscape will ask you several times whether you are allowing this or that JavaScript script to perform this or that operation. You have to check the "Remember this decision" box and then grant the permission. (Doing this will allow AntWorld to resize and move Netscape windows, and to keep track of the documents you are looking at, so that your itinerary can be recorded.)

6. After you finish browsing and quit Netscape, the program will automatically shut down LAPS and re-set the preference file to the normal values (no proxy server, no codebase principal permissions). It won't try to reset other values, so if you made any changes to the Netscape preferences during your AntWorld browsing, they will be preserved!

Note: Don't move the AntWorld startup script, anstcape.sh to another directory unless you move local.jar along with it, and don't soft link to antscape.sh. (If you do either, the script may not be able to find local.jar.) For example, if you are the system administrator and want everybody on your system to run Antscape, just copy both anstcape.sh and local.jar to a directory like /usr/local/bin.

(If you really want to keep the two files in different directories, or to soft-link, you'll have to modify anstcape.sh so that the -classpath option to java points to the correct current location of local.jar. But why bother? If you want antscape.sh to be in some directory in your $PATH, but don't want to take local.jar along, just write a wrapper script!)

You can also download local.jar (also available via ftp) separately, if you have any need for it. (Note that Netscape on some MS Windows machines may try to download it in "text", not "binary" mode. Apparently, there is no "choose download mode" checkbox on Netscape's "download file" dialog box...)

On a Microsoft Windows 95/98 machine

1. On a Microsoft Windows machine several Netscape profiles may exist, so that each users can use his own preferences. Before installing AntWorld you must create a new profile named antworld, using Netscape's User Profile Manager. To do it, exit Netscape, and run the Profile Manager.

   (One way to run the Profile Manager is by going to Start menu->Programs->Netscape Communicator->Utilities-> User Profile Manager. Another way is to type

   netscape -new_profile
   

   on the MS DOS command line, or in the Start menu->Run box.)

   When the Profile Manager asks for the profile name, enter antworld. The Profile Manager also asks you for the name of the directory where the preference files etc. for this profile are stored; make sure that it is

   C:\Program Files\Netscape\Users\antworld 

2. Once the new profile exists, make sure that it is possible to actually browse the Web using this profile. To test this, start Netscape. It will show you the profile selection screen. Choose antworld, go to some web pages, and see if everything works right.

   Normally, when a new profile is created, no special preparation is needed to make it usable; however, on some sites additional configuring is required. For example, if your site accesses the Internet via a proxy server (a gateway in a firewall), you may have to make sure that the proxy server parameters are set correctly (that is, according to your site administrator's instructions) in the Netscape's Edit -> Preferences -> Advanced -> Proxies menu.

3. Download file antworld.exe (420+ kB; also available via ftp) to a suitable directory on your machine. (C:\TEMP or C:\TMP is fine).

   If you prefer to use a java installation, you can download setup.class (350+ kB; also available via ftp) instead.

4. Execute antworld.exe. (You can do it in Windows Explorer, by navigating to the directory where antworld.exe is, and double-clicking on it). This will start installation process. The installation program will check if you have a Java Virtual Machine (JVM) installed on your computer. If it finds several JVMs, it will let you choose one (does not matter which, probably).

   If you have downloaded setup.class instead of the executable, just go to the directory where it is and type

       java setup.class
   

   If the installation program doesn't find a JVM, it will quit and start Netscape so that you could download one from Sun's site. Once you've downloaded and installed the Java software, you have to run antworld.exe again to finally proceed with installing AntWorld.

   During the installation, the installation program will also ask you what directory to install the AntWorld client in. Normally, you can just use the default directory (C:\Program Files\AntWorld).

5. The setup program will install an "AntWorld" or "antscape" icon in the "Programs" menu. Every time you want to use the AntWorld, exit Netscape, and then click on the "antscape" icon. This will start the "antscape" script that starts the Local Ant Proxy Server, modifies your Netscape preference file (see details here if you care), and starts Netscape at the AntWorld starting page.

   You can also start "antscape" from the Windows Explorer, by clicking on the icon for C:\Program Files\AntWorld\antscape.bat. An advantage of this technique is that you get an extra "MS DOS" window to see antscape's error messages and diagnostics.

6. As you are running your first AntWorld quest, Netscape will ask you several times whether you are allowing this or that JavaScript script to perform this or that operation. You have to check the "Remember this decision box" and then GRANT the permission. (Doing this will allow AntWorld to resize and move Netscape windows, and to keep track of the documents you are looking at, so that your itinerary can be recorded.)

On a Microsoft Windows NT machine (as a regular user)

• When prompted by the installation program for the name of the directory where the AntWorld client is to be installed, choose some location under your own directory. eg. c:\winnt\profile\your usrname\ or c:\your usrname\ .
  During installation,there might be one error message about unable to create an entry for the antworld application in the control panel Add/Remove property list and you need administrator privileges to perform this operation. Please ignore the error and continue. Or you can ask your system administrator to install antworld particularly for you.
• If you cannot successfully create the antworld profile in the User Profile Manager, it means that you don't have the permission to create new netscape profiles. You will have to ask your system administrator for help.

On a Microsoft Windows NT machine (as the system administrator)

• If you fail to install antworld under default installation directory c:\program files\antworld, please try another installation directory, eg. c:\antworld.
• The installation program will create a shortcut file in C:\winnt\profile\usrname\start menu\program\antworld. For the first option (AntWorld for one user), move the antworld shortcut file to the particular user's profile, C:\winnt\profile\usrname\start menu\program\antworld. For the second option (AntWorld for all users), move the antworld shortcut file to C:\winnt\profile\all users\start menu\program\antworld.

Where do I get Java Virtual Machine?

Written by: Vladimir Menkov and Qin Shi. April 1999 --April 2000.