/****************************************************************************
 * Copyright (c) 2005, 2007 Intel Corporation.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * $Id: readme.txt,v 1.18 2007/03/20 13:30:14 jkubasta Exp $
 ****************************************************************************/

Contributors:
Vishnu K. Naikawadi, Intel
    (Description of the directory structure and steps on how to run the
     AgentController, SampleClient and TimeCollector)
Randy D. Smith, Intel
    (Upgraded for TPTP 4.0 technology preview)
Karla Callaghan, Intel
    (Further refinements for technology preview 4.0)
Randy D. Smith, Intel
    (Updated for TPTP 4.1 new agent controller technology.)
Randy D. Smith, Intel
    (Updated for TPTP 4.2 new tech AC w/BC [agent controller with backward
     compatibility]; new build structure; real 64-bit ports to Windows 2003.)


New Technology Agent Controller (AC) in TPTP 4.2



1. Introduction
---------------

This release includes the agent controller, several service agents (e.g.,
process controller and file transfer agent), client libraries for accessing the
services of the agent controller and its agents, and a sample client/agent
application illustrating the use of the client and agent libraries. The SDK
package includes several additional sample applications. This readme.txt file
serves to chronicle the dependencies, environments, and procedures necessary to
compile the new technology Agent Controller (AC) on Windows and Linux platforms
and run the primary Sample Client as a means of testing an AC installation.
Note that there are platform-specific procedures required for building this
software.

This version of the release contains compatibility layers to make it useable in
place of the agent controller found in TPTP 4.1 (henceforth referred to as the
"RAC" to distinguish it from the new technology AC). The SSL/authentication
support and dynamic discovery of other agent controller support are new to this
version. Note that these AC/BC functionalities are only operative for the
Windows packages for IA32, IPF, and EM64T in 4.2.

This agent controller should be installed in its own directory (not the same
directory as a RAC install) to prevent overwriting the RAC's serviceconfig.xml
file. See the TPTP web site for documentation of details on what's in the new
serviceconfig.xml file. The RAC and the new AC cannot be run simultaneously
unless care is taken in assigning different port numbers and pipe names for
each using each's serviceconfig.xml file.



2. Installing a Package
-----------------------

To install the runtime or SDK package, simply create a directory and unzip the
contents of the file downloaded from the TPTP web site. Add the path of the
resulting bin directory to the PATH environment variable. On Linux, add the lib
directory path to the LD_LIBRARY_PATH environment variable as well.

NOTE: For all that follows, <INSTALL-HOME> is this directory where the new
technology AC was unzipped.



3. Running the New Technology AC and SampleClient
-------------------------------------------------

One of the samples (SampleClient) is built and included in the runtime package
to allow easy testing of the success of your install.


Step A. Generate Configuration Files
--------------------------------

1. Run <INSTALL-HOME>/bin/SetConfig.{bat|sh} (Windows|Linux) (FROM THE
   <INSTALL-HOME>/bin DIRECTORY!)
2. Edit agents/org.eclipse.tptp.TimeCollector/agent.xml if on Linux
   a. For Linux, make the value for the "Application executable" tag be
      "TimeCollector" (drop the '.\' prefix and '.exe' suffix)
   b. Do not remove the ConfigFile line from this file on any platform! Even
      though the file referenced does not exist, the line must be here or else
      the AC will not function properly.


Step B. Start the New Technology Agent Controller
-------------------------------------------------

1. Open a command prompt window
2. Go to <INSTALL-HOME>/bin directory
3. Enter the following at the command prompt: ACServer

NOTE: On many Linux systems, you will need to precede the name with "./" in
order for the executable to be found. Alternatively on Linux, the
<INSTALL-HOME>/bin/ACStart.sh command may be used to start the agent
controller.

NOTE: For ease of use in a backward compatibility environment, the AC may also
be started up under the name "RAServer".

NOTE: For Windows systems, the ACServer can be started as a Windows service.

NOTE: For Windows Server 2003 systems, you will need to be Administator to
start the ACServer.

This will start the new technology Agent Controller (AC) at its configured port
number. The AC reads the <INSTALL-HOME>/config/serviceconfig.xml file to
determine the location of the Process Controller agent (used to launch
processes) and the location of other agent configuration files. See the TPTP
web site for more detailed documentation.

The AC starts the ProcessController agent then waits, listening for connection
requests from clients and agents.


Step C. Execute the Sample Client
---------------------------------

1. Open another command prompt window
2. Go to <INSTALL-HOME>/bin directory
3. Enter the following at the command prompt: SampleClient

NOTE: On many Linux systems, you will need to precede the name with "./" in
order for the executable to be found.

This will start the SampleClient application, which:
(a) connects to the Agent Controller at the designated port number,
(b) gets the "org.eclipse.tptp.TimeCollector" agentID (causing the AC to launch
    the TimeCollector executable if it is not running already),
(c) establishes a data channel with the agent (through the AC)
(d) sends 5 "Hello" messages to the agent
(e) sends a start message to tell the collector to start collecting
(f) sends a stop message to tell the collector to stop collecting
(g) and waits for the user to press a key to indicate completion;
(h) Meanwhile, after step (b), and in parallel with the remaining steps, the
    TimeCollector agent initializes itself and waits for a request from the
    client. Upon receiving the start message (step e) it starts its
    "collection" activity, which is to simply collect a timestamp and then send
    data to the client until it receives a stop message.
(i) Each message sent over the data channel to the client is displayed (usually
    around 8 messages)on the client's console window
(j) Pressing return will cause the client to terminate the agent and exit.

Actual output for the SampleClient and the TimeCollector is shown at the bottom
of this file.


Step D. Troubleshooting with a Debug Log
----------------------------------------

If things don't appear to be working properly, include a log file of debug info
when asking for help. The Agent Controller and agents print their debug
messages to a common log file. Edit the file
<INSTALL-HOME>/config/serviceconfig.xml, changing the Logging level from
INFORMATION to DEBUG. The output will go into the file
<INSTALL-HOME>/config/servicelog.log (by default; this too is configurable in
the serviceconfig.xml file).



4. Available Packages
---------------------

Both runtime and SDK packages are available. The SDK packages include the
libraries, header files, and sample code for those writing new agents or
clients. The APIs supported are for the new AC and are not supported by the
older agent controller (RAC) technology.



5. Building the New Technology Agent Controller and its Components from Source
------------------------------------------------------------------------------

The agent controller code is located in the
dev.eclipse.org/cvsroot/tptp/platform/org.eclipse.tptp.platform.agentcontroller
TPTP CVS module, with the new technology component being found in the
src-native-new subdirectory. (With the 4.2 release, there are dependencies on
source code found in the src-native subdirectory as well, though these are
abstracted out into usage of the RAC's SDK package via an environment variable
setting.)

The build directory contains the top level make files which will build all of
the component parts.

tptp_ac.dsw
    Windows-IA32 workspace file for agent controller. Specifying the BuildMost
    project results in a complete build.

BuildAll.mak64
    Windows-{IPF|EM64T} NMAKE makefile for agent controller.

tptp_samples.dsw
    Windows-IA32 workspace file for sample programs. Specifying the
    BuildAllSamples project results in a complete build of all included sample
    programs.

BuildAllSamples.mak64
    Windows-{IPF|EM64T} NMAKE makefile for sample programs.

tptp_javaagent.dsw
    Windows-IA32 workspace file for Java base agent. Specifying the BuildAll
    project results in a complete build of the native library required for
    executing an agent written in the Java programming language.

build_tptp_ac.script
    Linux-IA32 build script for agent controller. Executing this file will do a
    complete build, after some preliminary adaptations to the file are made;
    see below.

build_tptp_ac.script64
    Linux-{IPF|EM64T} build script for agent controller. Executing this file
    will do a complete build, after some preliminary adaptations to the file are
    made; see below.

build_tptp_samples.script
    Linux build script for sample programs. Executing this file after
    successfully building with build_tptp_ac.script[64], and after similar
    adaptations are made, will build all the included sample programs.


A. Dependencies

1) Compilers:

 - Windows-IA32:  Microsoft Visual C++ v6.0

 - Windows-IPF:  Microsoft Windows Server 2003 SP1 Platform SDK

 - Windows-EM64T:  Microsoft Windows Server 2003 R2 Platform SDK

 - Linux-{IA32|EM64T|IPF}:  GNU gcc

2) Software:

 - Apache Xerces-C++ XML parser (http://xml.apache.org/xerces-c) v2.6.0

 - Java, J2SE v1.4.2 or above (http://java.sun.com/j2se/index.jsp)


B. Windows Build Instructions

1) Build/install the Xerces-C++ XML Parser v2.6, following the instructions on
the http://xml.apache.org/xerces-c website.

Set the environment variable XERCESC_HOME to point to the directory containing
the Xerces include and lib directories.

NOTE For EM64T and IPF Platforms:
The standard 2.6 xerces from the apache web site will not compile without the
following makefile modifications:
   (a) Remove "/machine:IX86" from the "XercesLib -Win64 {Debug|Release}"
       configurations LINK32_FLAGS specifications.
   (b) Add bufferoverflowU.lib to those same LINK32_FLAGS specifications.
   (c) [EM64T only:] Change /machine:IA64 to /machine:AMD64 for those same
       LINK32_FLAGS specifications.

2) Download the current CBE SDK from the from the download site at
http://www.eclipse.org/tptp/home/downloads/downloads.php
(i.e., cbe.win_<platform>.sdk-<timestamp>.zip) and unzip that package into a
directory, then set the environment variable CBE_SDK_HOME to point to that
directory.

3) Install Java - J2SE 1.4.0 or above and follow the install intructions on
http://java.sun.com/j2se/index.jsp website.

Set the environment variable JAVA_HOME to point to the directory containing the
Java include and lib directories.

4) For Windows-IA32, open the agent controller MSVC++ workspace file,
tptp_ac.dsw, located in the build directory. Under Project, Set Active Project
to "BuildMost" and then under Build, select "Build".

NOTE: Prior to running the resulting executables from within MSVC++, go to
Project => Settings... and set the Working directory to point to the AC's bin
directory. When running from a command line, execute the binaries from within
the bin directory.

For Windows-IPF and EM64T, open the appropriate Platform SDK command prompt
windows (All Programs => Microsoft Platform SDK for Windows Server 2003 =>
Open Build Environment Windows => Windows Server 2003 64-bit Build Environment
=> Set Win Svr 2003 {IA64 for IPF | x64 for EM64T} Build Env), change directory
to your installation build directory, and invoke "NMAKE BuildAll.mak64".

5) To build the C++ samples on Windows-IA32, open the MSVC++ workspace
tptp_samples.dsw. Under Project, Set Active Project to "BuildAllSamples" and
then under Build, select "Build".

For Windows-IPF and EM64T, see step 2, replacing the makefile with
BuildAllSamples.mak64.

NOTE: The samples builds will fail if the AC build is incomplete.

NOTE: The Agent Controller must be running prior to executing any of these
samples in order for them to succeed.

6) To build the Java Base Agent, open the MSVC++ workspace tptp_javaagent.dsw.
Set the JAVA_HOME environment variable to point to the directory where java is
installed. Under Project, Set Active Project to "javaBaseAgent" and then under
Build, select "Build".

See the org.eclipse.tptp.platform.new.agentcontroller feature plugin for
details on executing the java agent sample.


C. Linux Build Instructions

1) Build/install the Xerces-C++ XML Parser v2.6, following the instructions on
the http://xml.apache.org/xerces-c website.

Set the environment variable XERCESC_HOME to point to the directory containing
the Xerces include and lib directories.

2) Download the current CBE SDK from the from the download site at
http://www.eclipse.org/tptp/home/downloads/downloads.php
(i.e., cbe.linux_<platform>.sdk-<timestamp>.zip) and unzip that package into a
directory, then set the environment variable CBE_SDK_HOME to point to that
directory.

3) Install Java - J2SE 1.4.0 or above and follow the install intructions on
http://java.sun.com/j2se/index.jsp website.

Set the environment variable JAVA_HOME to point to the directory containing the
Java include and lib directories.

4) Add the AC's lib directory and $XERCESC_HOME/lib to the LD_LIBRARY_PATH
environment variable.

5) Run the following build script files located in the build directory. You may
need to run dos2unix if they were checked out in DOS format and add execute
permissions (chmod a+x) on these files before executing them:
   build_tptp_ac.script[64] (add the 64 extension for IPF and EM64T)
   build_tptp_samples.script

NOTE: By default the build scripts are set up to compile the files optimized.
If instead you want a "DEBUG build", edit the files, comment out the
OPTIMIZABLE line, and uncomment out the DEBUGABLE line so that it takes effect.

NOTE: Execute the resulting binaries from within the bin directory.

NOTE: See the org.eclipse.tptp.platform.new.agentcontroller feature plugin for
details on executing the Java agent sample.



6. Expected Console Output for SampleClient
-------------------------------------------


------------------- 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...


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