README

Brahms Agent Environment version 1.3.2

9/29/2009
Copyright (c) 1998-2009 NASA Ames Research Center. All Rights Reserved.

I. Welcome!

Welcome to NASA's Brahms Agent Environment 1.3.2 for Windows 2000, Windows XP, Vista, Linux, Sparc/Solaris and Mac OS X. Please take a few minutes to read this file, which contains the latest information regarding this release.

II. Installation Notes

In order to use the software you will need a license file (brahms.lic). Without the license file you will be able to install the software but you will not be able to use the Brahms virtual machine. If you have registered before to download previous versions of Brahms you can request a license file by sending an e-mail to register@agentisolutions.com. Include your name in the e-mail and we will send you a license file. If you registered to download this current version of Brahms then you will have received a user name and password to download this software as well as a license key. Place the license key in the AgentEnvironment directory.

If you have a previous version of Brahms installed you must first uninstall that version. Before uninstalling the version or upgrading the Brahms Agent Environment to this latest version make sure you copy your configuration files in case you want to use the same settings with the new version. You can copy the configuration files to the new version of Brahms once the new version is installed. The new version installs new configuration files and note that new configuration properties are supported in the virtual machine's configuration file. So make sure to check out the newly installed vm.cfg file before overwriting it with your own.

Start the setup program. It will start an installation program that will guide you through the steps to install the Brahms Agent Environment. The installation will install a minimum of six scripts/executables in the bin directory, one for the compiler (bc), one for the virtual machine (bvm), one for the Brahms Hosting Environment (HostingEnvironment), one for the Brahms Integrated Development Environment (Composer), and one to generate an encrypted password for use with SSL (encpwd). On certain platforms also a process manager and wrapper script/executable are installed. The hosting environment, process manager, and password encryption scripts are used for the server component of Brahms to run Brahms models in distributed mode. For more information on running Brahms in distributed mode see the ReadmeDistributedVM file.

In the bc batch/script file two values have to be passed at a minimum, the first one being the library path, the second one being the source file to be compiled, it is highly recommended to also pass the DTD referencing the local file system for efficiency.

The installation software will automatically install the appropriate version of Sun's JRE 6, except on Mac OS X where the appropriate version of Java must already be installed (JSE 5.0) and be the default Java virtual machine. The virtual machine requires at a minimum JRE 5.

The various components use some configuration files. These files are generated during the installation and contain the appropriate default settings. The configuration files generated by the installation program are (depending on the chosen installation):

vm.cfg
vmLogger.cfg
favservice.cfg
teservice.cfg

The configuration files contain comments on how to use or set their properties. Make sure to verify the vm.cfg, you might have to change your library path and/or working directory.

In order to use the compiler and virtual machine from other places on your machine, make sure to add the Brahms Agent Environment directory to your system PATH environment variable.

III. What's New

Added support for language specification 2.18 which includes enhancements for the types of detectable conditions and transfer definitions that can be written in Brahms. It is now possible to use class variables in both the left and right hand side of detectable conditions and transfer definitions and it is possible to use a wildcard ('?'). The use of the known and knownval modifiers in preconditions is now also optional.

IV. Known Problems

Compiler: All brahms files need to have the extension '.b'. The Brahms Compiler will not be able to find imported files that have other extensions like for example '.txt'.
Virtual Machine: The distributed virtual machine does not yet distribute the areas. All areas must therefore remain local on each virtual machine they are references. This will also result in agents running in different virtual machines not being able to automatically detect one another when in the same area.
When installing Brahms in the default location on Vista with User Account Control (UAC) turned on Brahms will not be able to generate the history files, event information, and log files. The solution is either to turn off UAC or to install Brahms in a location other then Program Files or Program Files (x86) or to change the config/favservice.cfg, config/teservice.cfg, and config/vmLogger.cfg to specify a directory other then a directory in Program Files or Program Files (x86). The Proram Files directories are restricted by Vista.

V. Revision History

The revision history for the Brahms Composer, Agent Monitor, Agent Viewer, Compiler and Virtual Machine can be found in the file named Changes.

VI. Important Notes

To run the Brahms Agent Environment installer and the Agent Environment components on Mac OS X you must install JSE 5.0 or 6.0 from Apple and make it the default Java virtual machine for your OS X. The installer will not function correctly and the components will not function at all if JSE 5.0 or 6.0 is not installed and is not the default Java virtual machine.
This new version can cause problems when compiling models that use a non-approved base library with custom added attributes. These models are required to be updated in order to use them with this version. The best way to update those models is to create model specific base classes that will automatically inherit from the base classes and in which the model builder specifies any customizations that were made to the base classes. The base library is included in the installation and can be found in the Models directory. Make sure to have this base library available in your library path when compiling your models.
If you use external activities or external agents as part of your Brahms models, make sure to package them up as jar files using Sun's jar tool and place the jar files in the AgentEnvironment\deploy directory. The compiler and virtual machine will in that case be able to find those external activities and agents, not placing them in that directory will cause the compiler and virtual machine to generate errors that they are unable to find the appropriate class files. If you wish to place these jar files into a different directory make sure to update the bc and bvm scripts to include them in the classpath/extensions directories.
The Composer is able to reload Java classes from Java archives for external activities and external agents when running the compiler multiple times, allowing you to drop updates of these archives in the Agents directory and recompile the model with the updates. However the virtual machine is not yet capable of doing this. So if you need to rerun your model with updated Java archives you must restart the Composer if you want to run the virtual machine from the Composer.

VII. Contacting the Brahms project team for Technical Support

In case you have problems with the installation or questions and problems with the use of the Brahms Composer, Agent Viewer, Compiler or Virtual Machine you can reach Technical Support at:

E-mail: support@agentisolutions.com
www: http://www.agentisolutions.com/support/support.htm

Thank you for trying the Brahms Agent Environment. We hope you find it useful in your modeling and agent development efforts.

Sincerely,

The Brahms Development Team