Getting Started with Agent Controller - Windows

Install the Java runtime (JRE) or Java development kit (JDK) 1.5 or 1.4.x
Remove or uninstall all prior versions of Agent Controller.
If installing on a system running Windows XP with SP2 or Windows Vista for remote data collection, the default firewall settings will have the ports used by the Agent Controller blocked. You will need to re-configure the firewall to open ports 10002, 10003, 10005, and 10006 to allow full functionality. These port numbers are defined in the Agent Controller’s serviceconfig.xml file.

Additional Windows Vista requirements:

If the Agent controller is run as an application, it must be started with "Run As Administrator". See details in Starting as an Application.
If you plan to use the Manual Test Type in TPTP, or if you have agents that need to create UI, Windows Vista requires that you start the Agent Controller as an application. Specifically, Windows Vista security prohibits interaction between services and the user desktop. Therefore, when the Agent Controller is started as a Windows service, processes that are launched by the Agent Controller are unable to create a user interface on the desktop, even if the service checkbox "Allow service to interact with desktop" is checked.

Notation

<install-dir> = The absolute directory path where the Agent Controller has been unzipped. For example, C:\tptpAC.
<service_name> = A unique Windows service name.

Install Agent Controller

Download one of the Windows Agent Controller Runtime packages from the TPTP Downloads area. Complete the installation steps before trying to set up Agent Controller.

Setting Up Agent Controller

After a normal installation, you still need to configure the Agent Controller before you can start it. Perform the following procedures:

Configure Agent Controller

Run SetConfig.bat script from a command shell in the <install-dir>\bin directory to generate the configuration file for the Agent Controller. The script requires that a Java Virtual Machine (JVM) be present in the PATH environment variable. Follow the prompts and enter the required parameters as appropriate. The configuration file <install-dir>\config\serviceconfig.xml will be generated based on your inputs.
Add <install-dir>\bin directory to the PATH environment variable when running applications with TPTP agents (such as Profiling or Logging agents) from the command line.

Note: Do not encase the environment variable's value in double quotes even if there are spaces in the <install-dir> path.

If you want to make changes to the configuration file that was generated in step 1, you may run the SetConfig.bat script again or you may manually edit the file according to the rules outlined in the document Agent Controller configuration files. The Agent Controller must be restarted for the changes to take effect.

For guidance on administering the Agent Controller, refer to the Windows - Working with the Agent Controller document.

Start Agent Controller

The Agent Controller can be started as an Application or as a Windows Service.

Note: For Windows Server 2003 and Windows Vista systems, you will need to be Administrator to start the ACServer.

Starting as an Application

Start the Agent Controller by changing your working directory to <install-dir>\bin and running ACServer.exe.

Note: The Agent Controller may also be started up under the name "RAServer".

Note: (For Windows Vista systems) In order to run the Agent Controller as an application on Windows Vista, you must run ACServer as Administrator. There are several ways to do this:

1) Each time you launch ACServer, right click on the file in the explorer and choose "Run As Administrator".

2) Each time you launch ACServer, create an administrator command prompt (by right clicking on cmd.exe and choosing "Run As Administrator") and then launch ACServer from that command prompt.

3) Once only, right click on ACServer and select "Properties". On the "Compatibility" tab, check the box labeled "Run As Administrator" and click Apply. All subsequent executions of ACServer (whether launched from a command prompt or from Windows Explorer) will be automatically run as Administrator.

Note: (For Windows Vista systems) There are several different options that control the behavior when an application attempts to run at an elevated privilege level. Depending on how your Windows Vista system is configured, you may 1) be prompted for an administrator username and password, 2) simply be prompted for permission to elevate privileges, or 3) not prompted at all. See the Microsoft Windows Vista documentation for more information.

Starting as a Service

Run the <install-dir>\bin\manageservice.exe application to create the Windows service. The syntax is:

    manageservice add "<service_name>" "<install-dir>"
For example:
    manageservice add "Agent Controller"  "C:\tptpAC"
    
You can now start the server using the Windows' Services panel.

Note: (For Windows Vista systems) You must run the above command from an administrator command prompt (by right clicking on cmd.exe and selecting "Run As Administrator").

Stop Agent Controller

If Agent Controller is an Application

Stop the Agent Controller service by terminating the ACServer.exe process (e.g. closing the command shell). Alternatively you can stop the service by entering:

ACServer -shutdown

If Agent Controller is a Service

To uninstall the Windows service, stop the server using the Windows' Services panel (or the Windows "net" command) and then run the <install-dir>\bin\manageservice.exe application to delete the Windows' service.
For example:

    	net stop "Agent Controller"
	manageservice remove "Agent Controller"

Querying Agent Controller Version Information

To display the version of Agent Controller, simply type:

ACServer -v
or
ACServer -version

The Agent Controller will display its version and terminate.

Checking Agent Controller Installation

If desired, you can verify proper operation of your Agent Controller installation by executing the SampleClient application provided with the runtime package.

Perform the following steps:

Start the Agent Controller.
Open a command prompt window
Go to the <install-dir>/bin directory
Enter the following at the command prompt:

SampleClient
Observe the console output for SampleClient. It should be similar to the following example:

------------------- SampleClient Console Output --------------------------------

Connected to the Agent Controller on "localhost" at port number #####

The Time Collector Agent ID: ###

Established a data channel with the agent.

Sending 5 Hello messages over data channel to TimeCollector ...

Start the TimeCollector ...

Incoming data: Hello from Time Collector Agent - Count 0

Incoming data: Hello from Time Collector Agent - Count 1

Incoming data: Hello from Time Collector Agent - Count 2

Incoming data: Hello from Time Collector Agent - Count 3

Incoming data: Hello from Time Collector Agent - Count 4

Stop the TimeCollector ...

Incoming data: Hello from Time Collector Agent - Count 5

Incoming data: Hello from Time Collector Agent - Count 6

Incoming data: Hello from Time Collector Agent - Count 7

Incoming data: Hello from Time Collector Agent - Count 8

Incoming data: Hello from Time Collector Agent - Count 9

Incoming data: Hello from Time Collector Agent - Count 10

All finished
Press any key to exit...

Note: The above port number and Agent ID values will typically be 10006 and 103 respectively, depending on Agent Controller configuration settings and the number of times that the SampleClient application runs.

Refer to the Agent Controller build readme.txt file for detailed information on the SampleClient functionality.

Server Logging

All server log entries will be placed in <install-dir>\config\servicelog.log .

Running the Java Profiler

The Java Profiler consists of a Profiling Agent packaged as a library (DLL). This profiling agent is started by the JVM when the JVM is started with the -Xrun option described below. The profiling agent interacts with the JVM to capture and record the Java application's behavior. The output from the profiling agent is in the form of XML fragments. The format of this fragment is described in this document titled "Event Specification for the Java Profiler".

You can profile a Java application by using the Eclipse workbench or manually by invoking the profiler from the command line.

Invocation from the Eclipse Workbench

The Java Profiler can be launched from the Eclipse workbench. From the Profiling and Logging Perspective of the Eclipse workbench you can launch applications using the Run > Profile menu or the toolbar button. A wizard will come up. Simply follow the wizard to profile an application. Applications in the current Eclipse workbench's workspace can be launched and profiled. External Java applications located in the file system can also be launched and profiled.

Invocation of the Java Profiler from the Command Line

Note that another step in starting Agent Controller is required for invoking 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]*

where agent_parm may be:

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_<version>\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 .;<install-dir>\lib\hcframe.jar TestClass
```
filters=filename

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.

Note: This parameter is only used when server=standalone is specified.

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.trcxml in the current directory.

help
Displays a list of available agent options to standard out.

Uninstalling Agent Controller

To uninstall the agent controller:

Stop the agent controller:
If the agent controller was installed as a service, run the <install-dir>\bin\manageservice.exe application to delete the Windows' service. For example:
```
manageservice remove "Agent Controller"
```
Remove the <install-dir>.
Remove the <install-dir>\bin directory from the PATH environment variable, if necessary.

Getting Started with Agent Controller - Windows

Contents

Querying Agent Controller Version Information

Checking Agent Controller Installation

Server Logging

Running the Java Profiler