Installing ContactCenters on Windows

The installation is a three-steps process: install a Java Virtual Machine, unpack ContactCenters, and set up the environment. We will show these steps in more details.

If ContactCenters is already installed, an update can be performed simply by unpacking the new version at the same location as the old version. There is no need to redo the Java installation and environment setup.

Installing a Java Virtual Machine

Before using ContactCenters, one should install a Java Virtual Machine (JVM) which is needed to execute any Java program. The recommended JVM is Sun's Java Runtime Environment, and can be found on the Sun's Java SE downloads page. It is sufficient to download and install JRE for using the precompiled simulator, but JDK is necessary for programming using the ContactCenters library, which was used to build the generic simulator.

Testing if Java is already installed

One might test the installation of Java using the DOS prompt. For Windows 2000/XP/Vista, the DOS prompt can be accessed by Start menu, All programs, Accessories, DOS Prompt. On older versions of Windows, the DOS prompt is accessible in the Programs submenu of the Start menu. This opens a black window in which the user can type text.

See How to get to a MS-DOS prompt if the DOS prompt cannot be reached from the Start menu.

The DOS prompt accepts commands corresponding to program names with arguments, separated by spaces. After writing any command on the DOS prompt, the user needs to press the Enter key to execute it. The command java -version may be used to verify that the Java Virtual Machine is properly installed. Here, the program name is java while -version is an argument passed to the java program. The above command should produce an information message similar to the following one.

java version "1.6.0"
Java(TM) SE Runtime Environment (build 1.6.0-b105)
Java HotSpot(TM) Client VM (build 1.6.0-b105, mixed mode, sharing)

The displayed version should at least be 1.6.0. Java is not properly installed on the system if the above command produces an error message indicating that java is not a recognized command.

The exit command can be used to leave the DOS prompt.

Installing or updating Java

The following steps summarizes the installation process for the Sun's JVM. The Web site Installation Notes provides detailed instructions for installing Java on Windows.

Go to Sun's Java SE downloads page.
Click on the Download button next to JDK.
This should correspond to the first Download button on the page.
Select Windows as the Platform.
If a 64-bits version of Windows XP or Windows Vista is used, one should instead select Windows x64 as the platform.
Click on the check box to accept the license agreement.
Click on the Continue button.
Click on the link corresponding to the Windows offline installation.
Save the downloaded file on the hard disk, and execute it.
Follow the on-screen instructions for installation.

simul@iro.umontreal.ca

Unpacking

If the Windows installer was downloaded, the only remaining step is to execute it and follow the on-screen instructions. The user can then skip to Testing the installation.

If the ZIP file was downloaded, the installation must be performed manually. First, by using WinZip or any equivalent program, the user needs to unpack the ZIP file contactcenters-<DATE>.zip to any location; this will create a contactcenters subdirectory containing all files of the distribution. For example, if the files are unzipped in C:\Program Files\java, the base directory of ContactCenters will be C:\Program Files\java\contactcenters.

Note: Under Windows 2000/XP, a system administrator installing ContactCenters for every user on a machine or a network might need to alter permissions to make the ContactCenters directory and its files readable by everyone.

Setting up the environment

When using ContactCenters or any other third-party Java library, the user needs to tell Java how to locate the classes forming the library by configuring the CLASSPATH environment variable. Moreover, for convenience scripts to be used to call the simulator, the PATH environment variable must also be altered. Environment variables are properties passed implicitly to any executed program, including the Java Virtual Machine. The procedure to set these variables depends on the operating system used, and the privileges of the user.

Windows 2000/XP/Vista

Under Windows 2000/XP/Vista, the environment variables must be set manually because there is no startup file.

The System Properties must be accessed by right-clicking on the My Computer icon and selecting Properties. This pops up a dialog box with multiple tabs and caption System Properties.
The properties may also be accessed by pressing the Windows and Pause keys simultaneously, or double-clicking on the System icon in the Control Panel (in classic view).
From this dialog box named System Properties, the user can access the environment variables by selecting the Advanced tab and clicking on the Environment Variables button that comes up.
Under Windows Vista, these advanced options can be accessed by clicking on the Advanced system parameters menu item, in the left part of the System Properties dialog box. If a dialog box asking user's authorization pops up, the user must click on the Continue button. The Environment Variables button is then accessible.

This creates a new window with two lists. The upper list shows the user variables, while the lower list displays the system variables. A user having the Administrator privilege (most home users) can modify the system variables to install ContactCenters for everyone on the machine while a user with a limited account (most users in a business or a university) can only modify his user variables to install ContactCenters for himself.

Here, we assume that the user is Administrator, and installs ContactCenters for every user of his machine. See below for a procedure that can be applied to users with limited accounts.
The user should create the CCHOME variable by using the New button below the list of system variables. This pops up a new window prompting the user to enter a variable name along with its value. The text CCHOME must be entered as the variable name while the value of the variable must be the base directory of the ContactCenters distribution, e.g., C:\Program Files\java\contactcenters. The Ok button must be used to close the dialog box, and create the variable. The CCHOME variable now appears in the list of system variables.
Tip: the directory name might be copy/pasted from an open Explorer window to avoid error-prone typing.
The CLASSPATH variable must then be edited or created. This variable is a semicolon-separated list of paths being searched by the Java Virtual Machine for classes.
- If the CLASSPATH variable already exists, the user must edit it by selecting it in the list of system variables and clicking on the Edit button; this results in a dialog box asking the new value of the variable. One should unselect the highlighted text of the value, and append the following text to the existing value:
```
;%CCHOME%\lib\contactcenters.jar;%CCHOME%\lib\ssj.jar;%CCHOME%\lib\colt.jar
```
- If CLASSPATH does not exist, i.e., it cannot be found in the list of system and user variables, it can be created the same way as CCHOME, by clicking on the New button below the list of system variables. The class path should contain at least
```
.;%CCHOME%\lib\contactcenters.jar;%CCHOME%\lib\ssj.jar;%CCHOME%\lib\colt.jar
```
The PATH variable must then be edited. This variable is a semicolon-separated list of paths being searched by Windows when a program or shared library is loaded.
After the PATH variable is selected in the list of system variables, the user must click on the Edit button, unselect the contents of the value, and append the string ;%CCHOME%\bin to the value.
Every dialog box opened for this procedure can be closed with their Ok button to validate the performed changes.

Changes to the environment variables apply to newly-launched programs only. As a result, if a DOS prompt was active during the setup, it will have to be closed and reopened to access ContactCenters classes.

Users without administrative privileges

Users without administrative privileges cannot create or edit system environment variables. However, they can create user variables that override system variables when they log on. The only exception to this rule is the PATH variable whose contents is composed of the system and user variables, separated by a semicolon. Consequently, a user with a limited account may apply the following variants to the above procedure.

The CCHOME variable is created by using the New button below the list of user variables rather than the list of system variables.
If a CLASSPATH is not present in the list of system variables, the user can create a new user variable named CLASSPATH and set its contents as above.
If a CLASSPATH is already present in the list of system variables, a new CLASSPATH user variable can be created; it will simply override the system CLASSPATH.

It is possible to refer to the system variable in the user variable by using %CLASSPATH%. For example, a user's CLASSPATH might have the value
```
.;%CCHOME%\lib\contactcenters.jar;%CCHOME%\lib\ssj.jar;%CCHOME%\lib\colt.jar;%CLASSPATH%
```
This can be useful if other libraries are installed system-wide, and needed by the user.
The user creates a PATH user environment variable, and sets its value to %CCHOME%\bin. The contents of the system and user variables are automatically concatenated by Windows.

Windows 95/98/Me

For Windows 95/98/Me, batch files are available to setup the environment for the user. The CCHOME environment variable must be set to the full path of ContactCenters prior to calling the setup batch file.

Commands for Windows 9x/Me:

   set CCHOME=<path to ContactCenters>
   call %CCHOME%\Contactcenters.bat

Here, <path to ContactCenters> must be replaced by the absolute path to the unpacked contactcenters subdirectory, for example C:\Program Files\java\contactcenters. For ContactCenters to be always available, the above command lines should be added to the C:\autoexec.bat file. The computer will have to be restarted for changes in this configuration file to take effect.

Note on Java IDEs

Note: Some Java Integrated Development Environments (IDEs) such as Eclipse and NetBeans do not use the standard CLASSPATH environment variable. These environments must be notified about the location of colt.jar, ssj.jar and contactcenters.jar manually. The procedure used to set these parameters can be found in the documentation of the specific Java IDE. If the archives cannot be located, the ContactCenters programs will not compile or not execute properly.

Testing the installation

If Java 6 is properly installed as tested above, the command mskcallcentersim may be entered on the DOS prompt to test the installation of ContactCenters. After pressing Enter for validating the command, the user receives an information message similar to this:

Usage: java umontreal.iro.lecuyer.contactcenters.msk.CallCenterSim
           <call center data file name> <experiment parameter file>
           [<output file name>]

If this message appears, the installation is finished. Otherwise, the user needs to verify if the Java Virtual Machine is properly installed, and the environment variables are set.

The command cd /d %CCHOME%\msk can be used to switch to the ContactCenters directory in order to load sample parameter files.

Here are the most common errors.

The java command cannot be found.

The Java Virtual Machine is not installed properly.

The command cd /d %CCHOME% displays an error message or does nothing.

The CCHOME environment variable is not set up properly.

The mskcallcentersim command cannot be found.

The PATH environment variable is not set up properly. One can try

set PATH=%PATH%;%CCHOME%\bin

to set up the variable temporarily.

The mskcallcentersim shows NoClassDefFoundError errors.

The CLASSPATH environment variable is not set up properly. One can try

set CLASSPATH=.;%CCHOME%\lib\contactcenters.jar

to set up the variable temporarily to run the simulator. The error can also appear if Java 5 is used instead of Java 6.

At any moment, the exit command can be used to close the DOS prompt.