/******************************************************************************* * Copyright (c) 2005 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 * * Contributors: * Vishnu K. Naikawadi, Intel - Description about 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. * *******************************************************************************/ New Technology Agent Controller (AC) in TPTP 4.1 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 TPTP 4.1 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 release is not yet completely equivalent to the agent controller found in TPTP 4.1 (henceforth referred to as the "RAC" to distinguish it from the new technology AC), nor does it have all of the compatibility libraries that will be needed to allow 4.1 agents to be used with the RAC. Thus, it cannot be used in place of the existing RAC controller in the TPTP 4.1 release. This agent controller should be installed in its own directory (not the same directory as the 4.1 RAC) to prevent overwriting the RAC's serviceconfig.xml file. See the TPTP web site for documentation on "Getting Started with the New Technology Agent Controller" for details on what's in the new serviceconfig.xml file. 2. Installing a Package ----------------------- To install the binary 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 this bin directory path to the LD_LIBRARY_PATH environment variable as well. NOTE: For all that follows, 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 binary package to allow easy testing of the success of your install. Step A. Edit Configuration Files -------------------------------- 1. Edit /config/serviceconfig.xml a. Make the value for the "Agent path" tag point to "/agents" b. On Linux, modify the value for the "ProcessController" tag, to be "./tptpProcessController" (delete the .exe suffix) 2. Edit agents/org.eclipse.tptp.TimeCollector/agent.xml a. On Linux, make the value for the "Application executable" tag be "./TimeCollector" (drop the .exe suffix and change the '\' to '/') b. Do not remove the ConfigFile line from this file. 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 /bin directory 3. Enter the following at the command prompt: tptpAgentCtlr NOTE: On many Linux systems, you will need to preceed the name with "./" in order for the executable to be found. This will start the new technology Agent Controller (AC) at its configured port number. The AC does not take any command line arguments at this time. The AC reads the 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 documentation on "Getting Started with the New Technology Agent Controller" for details. The AC starts the ProcessController agent (which, on Windows, will pop up in a new console window) 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 /bin directory 3. Enter the following at the command prompt: SampleClient NOTE: On many Linux systems, you will need to preceed 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 start the "TimeCollector" agent if it is not running already, causing (f) below), (c) establishes a data channel with the agent (through the AC) (d) sends 5 "Hello" messages to the agent (which can be seen echoed as received data over in the "TimeCollector" agent console window in between start and stop time and date stamps), (e) and waits for the user to press a key to indicate completion; (f) Meanwhile, after step (b), and in parallel with the remaining steps, the incoming data from the "TimeCollector" agent is echoed out by a separate listener thread. Actual output for the SampleClient and the TimeCollector is shown at the bottom of this file. 4. Available Packages --------------------- A. Windows binary package (agntctrl.win_ia32-TPTP-4.1.0-TIMESTAMP.zip) \bin\AgentBase.dll CommonBaseEvent.dll+ hcclco.dll hccls.dll hcclsm.dll javaBaseAgent.dll NamedPipeTL.dll ProcessControlUtil.dll readme.txt [this file] SampleClient.exe SharedMemTL.dll SocketTL.dll TimeCollector.exe tptpACTL.dll tptpAgentCtlr.exe tptpBaseTL.dll tptpClient.dll tptpCmdExtr.dll TPTPConfig.dll TPTPConfigBinding.dll tptpFileTransferAgent.exe TPTPLogUtils.dll TPTPProcessController.exe tptpUtils.dll TransportSupport.dll xerces-c_2_4_0.dll \config\serviceconfig.xml \Release_Note.txt \agents\org.eclipse.tptp.FileTransferAgent\agent.xml \agents\org.eclipse.tptp.TimeCollector\agent.xml B. Linux binary package (agntctrl.linux_ia32-TPTP-4.1.0-TIMESTAMP.zip) /bin/SampleClient TimeCollector libcbe.so libhcclco.so libhccls.so libhcclsm.so libjavaBaseAgent.so libnamedPipeTL.so libperflin.so libprocessControlUtil.so libresutils.a libsharedMemTL.so libsocketTL.so libtptpAgentBase.so libtptpClient.so libtptpCmdExtr.so libtptpConfig.so libtptpConfigBinding.so libLogUtils.so libtptpUtils.so libtransportSupport.so readme.txt [this file] tptpAgentCtlr tptpFileTransferAgent tptpProcessController libxerces-c.so.24.0 /config/serviceconfig.xml /agents/org.eclipse.tptp.FileTransferAgent/agent.xml /agents/org.eclipse.tptp.TimeCollector/agent.xml C. Windows SDK package, includes: binary pkg + libs + include files + samples + documentation (agntctrl.win_ia32.sdk-TPTP-4.1.0-TIMESTAMP.zip) \bin\AgentBase.dll CommonBaseEvent.dll hcclco.dll hccls.dll hcclsm.dll javaBaseAgent.dll NamedPipeTL.dll ProcessControlUtil.dll readme.txt [this file] SampleClient.exe SharedMemTL.dll SocketTL.dll TimeCollector.exe tptpACTL.dll tptpAgentCtlr.exe tptpBaseTL.dll tptpClient.dll tptpCmdExtr.dll TPTPConfig.dll TPTPConfigBinding.dll tptpFileTransferAgent.exe TPTPLogUtils.dll TPTPProcessController.exe tptpUtils.dll TransportSupport.dll xerces-c_2_4_0.dll \agents\org.eclipse.tptp.FileTransferAgent\agent.xml \agents\org.eclipse.tptp.TimeCollector\agent.xml \config\serviceconfig.xml \include\tptp - common include files \include\tptp\client - client-only include files \include\tptp\agents - agent-only include files \lib - libraries corresponding to .dlls in the bin directory \samples - contains sample programs like SampleClient and TimeCollector \Doc - contains C++ and Java API documentation D. Linux SDK package, includes: binary pkg + include files + samples + documentation (agntctrl.linux_ia32.sdk-TPTP-4.1.0-TIMESTAMP.zip) /bin/SampleClient TimeCollector libcbe.so libhcclco.so libhccls.so libhcclsm.so libjavaBaseAgent.so libnamedPipeTL.so libperflin.so libprocessControlUtil.so libresutils.a libsharedMemTL.so libsocketTL.so libtptpAgentBase.so libtptpClient.so libtptpCmdExtr.so libtptpConfig.so libtptpConfigBinding.so libtptpLogUtils.so libtptpUtils.so libtransportSupport.so readme.txt [this file] tptpAgentCtlr tptpFileTransferAgent tptpProcessController libxerces-c.so.24.0 /agents/org.eclipse.tptp.FileTransferAgent/agent.xml /agents/org.eclipse.tptp.TimeCollector/agent.xml /config/serviceconfig.xml /include/tptp - common include files /include/tptp/client - client-only include files /include/tptp/agents - agent-only include files /samples - contains sample programs like SampleClient and TimeCollector /Doc - contains C++ and Java API documentation 5. Building the New Technology Agent Controller and its Components from Source ------------------------------------------------------------------------------ The TPTP 4.1 AC 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. The build directory contains the top level make files which will build all of the component parts. tptp_ac.dsw - Windows workspace file for agent controller. Specifying the BuildALL project results in a complete build. tptp_samples.dsw - Windows workspace file for sample programs. Specifying the BuildAllSamples project results in a complete build of all included sample programs. tptp_javaagent.dsw - Windows 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 build script for agent controller. Executing this file will do a complete build. build_tptp_samples.script - Linux build script for sample programs. Executing this file will build all the included sample programs. A. Dependencies 1) Compilers: - Windows/IA32/EM64T/IPF(Itanium): Microsoft Visual C++ v6.0 - Linux/IA32/EM64T/IPF(Itanium): GNU gcc 2) Software: - Apache Xerces-C++ XML parser (http://xml.apache.org/xerces-c) v2.4.0 for IA32, v2.6.0 for EM64T and IPF (Itanium) - Java - J2SE v1.4.0 or above (http://java.sun.com/j2se/index.jsp) - TPTP Native Logging SDK (http://www.eclipse.org/tptp/home/downloads/downloads.html) B. Windows Build Instructions 1) Install the appropriate Xerces-C++ XML Parser (v2.4 for IA32, and v2.6 for EM64T or IPF [Itanium]]), and follow carefully the installation 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 source modification, in file $XERCESC_HOME\src\xercesc\util\Platforms\Win32\Win32PlatformUtils.cpp insert the following line at the beginning of the file: #undef WIN64 2) Copy CommonBaseEvent.h from the TPTP Native Logging SDK into the include\tptp directory. Use the 4.1 version of this file to correspond with the 4.1 version of the CBE library packaged with the SDK. Otherwise, copy the CommonBaseEvent.dll that corresponds with the include file into the AC's bin directory. 3) Open the agent controller MSVC++ workspace file, tptp_ac.dsw, located in the build directory. Under Project, Set Active Project to "BuildAll" and then under Build, select "BUild". The following projects get built: 1. TPTPUtil - Common Utility library 2. RACommon 3. RASocket 4. RASharedMemory 5. transportSupport - Common Transport library 6. namedPipeTL - Named Pipe Transport Layer library 7. sharedMemTL - Shared Memory Transport Layer library 8. tptpConfig 9. TPTPLogUtils 10. agentBase - Base Agent Class 11. processControlUtil 10. TPTPConfigBinding 11. CmdExtractor 12. socketTL - Socket Transport Layer library 13. BaseTransport 14. TPTPAgentCompTL 15. AgentController - Agent Controller 16. client - C++ Client library 17. tptpProcessController - Process Controller Agent (Used by AC to launch the applications and agents) 18. FileTransferAgent 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. 4) To build the C++ samples, open the MSVC++ workspace tptp_samples.dsw. Under Project, Set Active Project to "BuildAllSamples" and then under Build, select "Build". Note: The Agent Controller must be running prior to executing any of these samples in order for them to succeed. 5) To build the Java Base Agent, open the MSVC++ workspace tptp_javaagent.dsw. Under Project, Set Active Project to "javaBaseAgent" and then under Build, select "Build". Set the JAVA_HOME environment variable to point to the directory where java is installed. See the org.eclipse.tptp.platform.new.agentcontroller feature plugin for details on executing the java agent sample. NOTE: The samples builds will fail if the AC build is incomplete. C. Linux Build Instructions 1) Install the appropriate Xerces-C++ XML Parser (v2.4 for IA32, and v2.6 for EM64T or IPF [Itanium]]), and follow carefully the installation 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) 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. 3) Copy CommonBaseEvent.h from the TPTP Native Logging SDK into the include/tptp directory. Use the 4.1 version of this file to correspond with the 4.1 version of the CBE library packaged with the SDK. Otherwise, copy the CommonBaseEvent.dll that corresponds with the include file into the AC's bin directory. 4) Add the AC's bin 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 build_tptp_samples.script 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 ------------------------------------------- The Agent Controller and Process Controller are compiled so as not to produce any console output by default. Instead, log messages will be written to the AC's log file. See the serviceconfig.xml to configure logging options. ------------------- 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 -------------------------------- ---------------- TimeCollector Agent Console Output ---------------------------- Start Time is - ??? ??? ## ##:##:## #### Received data: Hello from Sample Client to Time Collector Agent - Count 0 ! Received data: Hello from Sample Client to Time Collector Agent - Count 1 ! Received data: Hello from Sample Client to Time Collector Agent - Count 2 ! Received data: Hello from Sample Client to Time Collector Agent - Count 3 ! Received data: Hello from Sample Client to Time Collector Agent - Count 4 ! End Time is - ??? ??? ## ##:##:## #### Press any key to exit ------------------ TimeCollector Agent Console Output END ----------------------