Instructions for installing and using ACP3, version 1.1 ------------------------------------------------------- Updated: Wed Mar 15 02:15:41 2000 by Jeff Dalton ACP3 is distributed as a gzipped tar file. The current version is available from http://www.aiai.ed.ac.uk/~arpi/ACP3/1.2/ There you will find links to a README file, and INSTALL file, and a tar file. The INSTALL file is the same as the instructions you are now reading. The name of the tar file, when you get it, should be acp3-1.2-15Mar00.tar.gz ACP3 requires JDK 1.2 or later, and it's assumed that the corresponding "java" command is in the PATH of anyone using ACP3. The system has been tested only with JDK 1.2 and only on Suns running SunOS 5.6 (Solaris). To install ACP3: 1. Make a new, empty directory to contain the system. 2. Get a copy of the file acp3-1.2-15Mar00.tar.gz and place it in the directory created in step 1. 3. Unpack the release tar file there, e.g. as follows: zcat acp3-1.2-15Mar00.tar.g | tar xpf - 4. Make sure the subdirectory "acp3-logs" is writable by everyone who will be running ACP3. (The "p" in the "tar" command above should ensure this, but it's still a good idea to check.) The directory you created above must be your current directory when you run ACP3. When you are in that directory, the script bin/acp3 will start ACP3. When ACP3 is run as a process monitor (as opposed to just for testing), it must register itself with a KQML ANS (name server) so that it can be sent KQML messages. ACP3 registers itself as a Kqml agent called "ACP3". ACP3 assumes that the Unix environment variable ANS_HOST contains the name of the host that is running the ANS. The bin/acp3 script uses the current host as a default. You can set a different value before running bin/acp3, or you can edit bin/acp3 to change the default. There is a comment that indicates which line to edit. It is possible to temporarily set the variable and run ACP3 in one command by using the "env" command: env ANS_HOST=somehost.somewhere bin/acp3-with-watcher Note that ANS_HOST can be used to specify only the host, not the port on which the server is listening. The port is fixed at 5500. ACP3 understands a number of command-line arguments that let you set the font size, window positions, etc. See doc/command-line-arguments. To test the installation: 1. Make sure you are in the right directory and that the subdirectory "acp3-logs" is writable by anyone who will be running ACP3. 2. Type: bin/acp3 -no kqml If you forget the "-no kqml", you may see some error messages at the start (if there is no KQML ANS running on your machine), but everything in this test should still work. When ACP3 starts up, two new windows will appear, and some debugging output will be printed as the system runs. Some window managers may not automatically place the windows at their intended locations, in which case they may need to be placed manually. Here is the suggested layout: +--------------------------------+ +------------------+ | ACP3 Main Frame | | ACP3 Information | | | | | | | | | | | | | | | | | | | | | | | +------------------+ | | | | | | | | +--------------------------------+ The upper part of the main window contains a graph of the process. The status colors of process steps in the graph will change as ACP3 discovers that steps have started, or completed, execution. The lower part of the main window contains similar information in tabular ("matrix") form. The "Test" menu contains a "Demonstration states" submenu. If you wish, you can step through a brief demonstration by selecting the states in order. An explanation of each state will appear in the Information window. If you do this, select "Monitor" from the menu when you're done. The buttons in the information window can be used at any time. 3. Ask ACP3 to run a simulation. Select "Breach COA 1" from the "Test" "Replay log file" menu. This will cause ACP3 to send itself a series of messages of the sort it would receive in normal use, to interpret those messages, and to display the resulting status changes as it determines that actions have started, or finished, execution. When you run this simulation, the effects should be similar to those described in steps 7 and 8 in the TESTING-KQML file (except for those parts that mention the "SendKqml" program). The "Freeze" button can be used to freeze the display. When the display is frozen, the label on the button changes to "Unfreeze". Note that ACP3 will continue to monitor the process state while the display is frozen. The boxes in the graph that cast shadows represent process steps that can be expanded into subactions. To see the expansion of such a step, click on the corresponding box. The "Graph" menu provides another way to change what is displayed. There is one submenu that lists expandable process steps and another, with entries such as "Overall", "COA-1", "COA-2", and "COA-3", that determines which column of the matrix is shown in the graph. The simulation tests everything except the code that would receive actual KQML messages, and it can be run even when no KQML ANS server is available. 4. Click on the "Quit" button to exit. So far, everything has been tested except the KQML message-handling code. If you'd like to test that, there are further instructions in the file TESTING-KQML in this directory. When ACP3 is being used as a process monitor that is observing KQML traffic, it displays the results of monitoring unless one of the "demonstration states" has been selected from the "Test" menu. In that case, select "Monitor" from the "Show demonstration state" menu so that ACP3 will again show the results of monitoring. This affects only what is displayed. Monitoring happens automatically even when one of the demonstration states has been selected. This allows the user to choose whether to display the monitoring results or one of the numbered demonstration screens, and to switch back and forth between the two cases without losing information. The "Test" "Replay log file" menu can be used to run a simulation in which ACP3 processes messages recorded during an earlier run. The messages are treated as if they were actual Kqml messages. The menu entry "Create finished COA 1" can be used to quickly create a completely developed COA-1 in cases where COA-1 was produced before ACP3 started running, and where ACP3 will see only messages about later COA. The "Reset" button can be used to discard the status information derived from monitoring, in case the ARPI TIE 97-1 process that is being monitored is restarted from the beginning, or to remove the effects of a simulation. It will also stop a simulation that has already begun. Running a new simulation does not automatically clear out the effects of earlier simulations (or of KQML monitoring). To clear those effects, press "Reset".