Getting started with Agent Controller - Windows

This guide contains the following information:

• Prerequisites
• Configuring and starting Agent Controller
• Querying Agent Controller version information
• Server logging
• Invoking the Java Profiler
• Uninstalling the Agent Controller

Prerequisites

• Install the TPTP 4.0.0 Runtime.

Configuring and starting Agent Controller

1. Generate the configuration file that provides the rules for the applications that can be executed by the server. This can be accomplished by running the <unzip directory>\bin\SetConfig.bat script. Run this script from a command shell in the <unzip directory>\bin directory. This step will require that a Java Virtual Machine (JVM) be present in the system's PATH. Follow the prompts and the output will be the <unzip directory>\config\serviceconfig.xml file.
2. Add the <unzip directory>\bin directory to the system's PATH environment variable.
   Note: Do not encase the environment variable's value in double quotes despite spaces in <unzip directory>.
3. The Agent Controller can be started as an Application or as a Windows Service.

If you want to make a change to the configuration file that was generated in step 1, the file can be manually edited using the rules outlined in the document Agent Controller configuration files. The server must be restarted to load changes.

Running the Server as an Application

1. Set the RASERVER_HOME environment variable to point to <unzip directory>. The server will use this environment variable to locate the configuration file.
   NOTE: Do NOT encase the environment variable's value in double quotes despite spaces in <unzip directory>.
2. Start the server by running the <unzip directory>\bin\RAServer.exe application.
3. Stop the server by terminating the RAServer.exe process (e.g. closing the command shell).

Running the Server as a Windows Service

1. Remove and/or uninstall all existing installations of Agent Controller.
2. Run the <unzip directory>\bin\manageservice.exe application to create the Windows service. The syntax is:

       manageservice add "<service name>" "<unzip directory>"
   

   For example:

       manageservice add "Agent Controller"  "C:\agentcontroller"
       

   You can now start and stop the server using the Windows' Services panel or with the Windows' 'net' command.
3. To uninstall the server Windows service, run the <unzip directory>\bin\manageservice.exe application to delete the Windows' service.
   For example:

       manageservice remove "Agent Controller"
   

Querying Agent Controller version information

To display the version of Agent Controller, simply type:
RAServer -v
or
RAServer -version

The Agent Controller will display its version and terminate.

Server Logging

The Java Profiler

The Java Profiler is a library that attaches to a JVM to capture and record the Java application's behavior. The output from the profiling agent is in the form of XML fragments.

Documentation on the composition of these XML fragments is located at: http://www.eclipse.org/tptp/platform/documents/resources/profilingspec/XML4Profiling.htm

Invocation of the Java Profiler from the Eclipse Workbench

The Java Profiler can be launched from the Eclipse workbench. From the Profiling and Logging Perspective of Eclipse workbench you can launch applications using the Run > Profile menu or the toolbar button. Applications in the current Eclipse workbench's workspace or external Java applications located in the file system can be launched and profiled.

Invocation of the Java Profiler from the Command Line

The Java Profiler is invoked from a command line using the -Xrun JVM option as follows:

    -XrunpiAgent[:agent_parm[,agent_parm]*

• server=[standalone | enabled | controlled | applicationControlled]

  standalone

  The Java Profiler is manually attached to a JVM instance and generates a stand-alone trace to a specified file based on the options and filters given on the command line. When this option is selected, the Java Profiler produces the enclosing traceRoot element to form a complete and valid XML document.

  enabled

  The Java Profiler is loaded, allows the application to run normally, but produces no trace until a Eclipse workbench attaches to the agent to give it instructions. When this option is selected, the Java Profiler only produces XML fragments instead of a complete XML document.

  controlled

  The Java Profiler is loaded, and the application is blocked from running until a client gives it instructions to continue. When this option is selected, the Java Profiler only produces XML fragments instead of a complete XML document.

  applicationControlled

  Profiling operations are controlled by the TPTP "Profiler" java class. The pluginconfig.xml file must be modified to use this mode. The pluginconfig.xml is located in the following directory:

  <agent_controller_home>\plugins\org.eclipse.tptp.platform.collection.framework_4.0.0\config\pluginconfig.xml

  The following modification is required:

  <Agent client="DYNAMIC" configuration="default" dataChannelSize="64M" name="Java Profiling Agent" type="Profiler"/>

  should be modified to

  <Agent client="HEADLESS" configuration="default" dataChannelSize="64M" name="Java Profiling Agent" type="Profiler" logFile="C:\profile.trcxml"/>

  Note that the Agent client attribute has been changed to "HEADLESS" and that the "logFile" attribute has been added.
  The hcframe.jar file should also be included in the user's class path when profiling an application under this mode. For example:

   java -XrunpiAgent:server=applicationControlled -classpath "C:\AgentController\lib\hcframe.jar";. TestClass

• filters=filename
  NOTE: This parameter is only used when server=standalone is specified.
  Specifies the name of the file that contains the initial class filter definitions to be used during the trace. The default is filters.txt in the current directory. The format of the file is as follows:

          classpattern methodpattern mode , where:
  

  classpattern

  is a string with no embedded blanks. The string may contain a single "*" either at the beginning of the string or at the end of the string. The "*" will match zero or more characters, thus making the pattern a generic prefix or suffix pattern. A single "*" can also be specified to represent all strings.

  methodpattern

  is a string with no embedded blanks. The string may contain a single "*" either at the beginning of the string or at the end of the string. The "*" will match zero or more characters, thus making the pattern a generic prefix or suffix pattern. A single "*" can also be specified to represent all strings.

  mode

  is one of INCLUDE or EXCLUDE.

  Filter patterns are processed in the order that they are specified until the first pattern match succeeds. If the class name does not match any of the specified filter patterns, the default is to INCLUDE the class.

• file=filename
  NOTE: This parameter is only used when server=standalone is specified.
  Specifies the name of a file where the trace will be written. The default is trace.xml in the current directory.
• help
  Displays a list of available agent options to standard out.

Uninstalling the Agent Controller

To uninstall the agent controller:

1. Stop the agent controller:
   • If the agent controller is running as an application, stop the application by terminating the RAServer.exe. (See instructions above.
   • If the agent controller is running as a service, stop the service by running the following:

     net stop <service_name>

2. If the agent controller was installed as a service, run the <unzip directory>\bin\manageservice.exe application to delete the Windows' service. For example:

   manageservice remove "Agent Controller"

3. Remove the <unzip directory>.
4. Remove the <unzip directory>\bin directory from the system's PATH environment variable