Reference Manual

| Table of Contents |

Agency Viewer

The Agency Viewer tool is used to run a set of agents belonging to an agency. The Agency Viewer provides a pane for viewing the icons that represent the agents. You are able to drag the icons to a new position, or change the agent's icon. Once the agency is running, you can view agent communications in two ways. First, notice that when two agents are communicating, a line is drawn between the two agents with a small ball moving along this line. The line represents the connection being made between agents, and the ball represents the message being delivered to the agent. You can also examine agent messages in a text area at the bottom of the panel. The message text area displays the sender and receiver of the message, as well as for the content of the message. Figure 32 shows the Agency Viewer .

Figure 32. Agency Viewer

Overview

The Agency Viewer contains a menu bar with six items: File , Edit , Exec , Options , Windows , and Help . The File menu allows you to save an agency, create a message log, and save/open runtime messages. The Edit menu gives you access to the agency properties and the agent properties dialogs. The Exec menu allows you to start, pause, stop, and reset the agents. The Options menu allows you to turn on or off message text area, display the agent status window, and specify the message buffer size.

During each run, agents switch to different states: Stop, Registering, Registered, Running, and Paused. The agent's icon label changes colors according to the state it is in. The red label signifies the agent is stopped. The pink label means the agent is in the process of registering with the agency. The yellow label means the agent successfully registered with the agency. The green label means the agent is currently running. The cyan label indicates that the agent is paused.

Operation: Running an Agency

Setting Agency in Register Mode

In order to run agents in the Agency Viewer, the agents must first register with the agency. In order for the agency to register agents, the Agency Viewer needs to be set to Register Mode . You can do this by selecting Exec < Register Mode menu item from the Agency Viewer's menu bar.

Registering the Agents

Once the Agency Viewer is in register mode, you must start the agents in agency-mode. There are several ways to start running an agent. The agents can be started individually by right clicking on an agent's icon and selecting Run from the resulting pop-up menu. You can also start all agents at once using the Agency Viewer by selecting the Run All menu item from the Exec menu bar. If you select the Run All menu item, the Agency Viewer will run only the agents that are set to run in the current host. If an agent has been set to run on a different host, the Agency Viewer will not run it and will display a warning message. You can start this agent from the Agent Engine; make sure the -agency-mode flag is turned on so that it registers with the agency. (See Run-Time System.). If any JVM groups are specified for the agency, it will use it to run multiple agents in the same Java Virtual Manchine. This will only occur when you select the Run All menu item from the Agency Viewer. If the agents are started within the Agency Viewer tool, the agency-mode flag is set automatically. When the agent's label changes to the color yellow, it means it has registered successfully.

Running and Resetting agents

Once the agents have registered, you can start running the agents from the Agency Viewer by selecting the Exec < Begin menu item. The Agency Viewer will then start the engines for each registered agent. The agency can still register agents when it is running (i.e., in run mode). The agent's label will change to green when the agent starts running.

Agents can only be reset if they are either running or paused. To reset an agent, right-click on the agent's icon and select the Reset menu item. If you want to reset the entire agency, select the Exec < Reset menu item from the Agency Viewer's menu bar.

Pausing and Unpausing the agents

Whenever the agents are running in agency-mode, you can pause and unpause them. There are two ways of pausing the agents. You can pause an individual agents by right-clicking on the agent and selecting Pause from the pop-up menu. You can also select the Pause menu item from the Exec menu bar. If you select Pause from the menu bar, it will cause all running agents to pause. You can use the same method to unpause the agents. Selecting Unpause from the menu bar will unpause any agents that have been paused. Any agent with a cyan color label is in pause mode.

Displaying the Agent's Message History Dialog

You can view the messages that each agent has sent or received by displaying the Message History dialog (Figure 33). To view the Message History dialog, you need to right-click on an agent and select the Message History menu item. With this dialog, you can see two lists and a description area. The top list displays the name of the agents that have sent messages to this agent. The bottom list displays the names of the agents that this agent has sent messages. Clicking on any of the agent names will display the message in the description area. You can display the Message History dialog for more than one agent. To close the dialog, simply click on the OK button.

Figure 33. Message History Dialog

Displaying the Agent's Status Window

The agent status window provides you with a list of agents along with their current state. You can access the window by selecting Options < Agent Status from the Agency Viewer menu bar. Figure 34 shows the Agent Status dialog.

Figure 34. Agent Status Dialog

Opening and Saving Runtime Messages

At the end of each run, you can save the runtime messages for later examination. There are two ways to save these messages. You can select File < Save Run and save the message to a file. (A default name has been provided with the following format: date AgencyName RunNumber. e.g. 11_11_98 NewAgency Run0 ). You can also specify the file name by selecting File < Save Run As from the Agency Viewer menu bar.

Specifying Message Buffer Size

You can set the number of messages that are saved when running an agency by selecting the Options < Message Buffer Size menu item from the Agency Viewer menu bar. You can enter any number between 0 and 100,000. The default value for all the agencies is 1000. When the buffer size has reached its limit and a new message arrives, the oldest message will be discarded and the new one will be kept.

Creating a Runtime Message log

If you wish to log all messages sent to a text file when running the agency, select the Message Log menu item from the File menu bar. This will bring up the Save File dialog where you can enter the location and filename of the log file. Once you have selected the name of the file, click on the Save button. A check mark will appear in the Message Log menu item showing that all messages are currently being logged.

Handling High Volumes of Communication

If the agency you are building is creating a high volume of messages you may wish to speed up the AgencyViewer. There are several changes you can make to speed up the rate at which the tool handles messages. The first is to set the message buffer size to 0, see previous section for details. The second requires turning off the message trace at the bottom of the AgencyViewer window. To accomplish this, toggle the Show Messages menu item on the Options menu. You may also want to consider turning off all logging since logging generates a large amount of overhead that should be avoided when handling high message volumes.

Viewing and Altering the Properties of the Agency

You can view and modify the properties of the agency by selecting the Properties menu item in the Edit menu bar. The only restriction is that the agency name cannot be modified from the Agency Viewer tool, but the description, author, company, and communications can be modified. The only tool that allows you to change the agency name is the Project Manager .

Viewing and Altering the Properties of the Agent

To display the agent's properties, you can either click on the agent and select Agent Properties menu item from the Edit menu bar, or simply double-click on the agent's icon. The Agent Properties dialog will be displayed along with the current information for the selected agent. In order for your changes to be applied, you must click on the OK button. Clicking on the Cancel button will cause the system to ignore any changes that have been made. The agency will be saved if the name of an agent is modified.

Changing the Agent's Icon

To change the agent's icon, you will need to use the agent's Properties Dialog (See previous section for a description of opening the Agent Properties dialog). From the Agent Properties dialog, click on the Browse button to display the Icon Dialog . The Icon Dialog allows you to select an icon for the agent by clicking on an icon. The selected icon will be highlighted with a red border. Once you have selected the desired icon for the agent, click on the OK button. The Cancel button will close the Icon dialog without changing the agent's icon file. Figure 35 shows the Icon Dialog.

Figure 35. Icon Dialog

Saving Agency Properties

You can save the agency by selecting Save in the File menu. The save action will save the agents properties and agency properties, which include the current location in the panel and the message buffer size.

Switching Windows

The Windows menu is a dynamic menu that contains a list of all AgentBuilder tools that are currently open. This menu facilitates switching between the tools when multiple tools are active. To switch to the desired tool, select the tool from the Windows menu. The selected tool will then be brought to the top of the window stack.

Accessing Help

The help system con be accessed using the Help menu item. The About menu item allows you to read the help information for the current tool. The Index menu item displays an index of the help system's contents. The Tutorial menu item displays the Quick Tour of the AgentBuilder toolkit. The About AgentBuilder menu item displays the AgentBuilder logo along with the version number and copyright information. Selecting the AgentBuilder Home Page menu item will display the home page for the AgentBuilder product.

Closing the Agency Viewer

You close the Agency Viewer by selecting the Close item in the File menu. If necessary, AgentBuilder will query whether to save the changes made to the agency.

Exiting AgentBuilder

To exit AgentBuilder, select the Exit in the File menu. AgentBuilder will display a dialog asking whether you are sure you want to exit. If so, then click on Yes button; if you do not wish to exit, click on the No button.

| Table of Contents |


AgentBuilder is a registered trademark of Reticular Systems, Inc.
Copyright © 1998-2001 Reticular Systems, Inc.