For Rational Application Developer, Version 6.0.1 / Rational Web Developer, Version 6.0.1 / Rational Software Architect, Version 6.0.1 / Rational Performance Tester 6.1.1
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.
This file is available in the following national languages:
| Brazilian Portuguese | Chinese - Traditional | Japanese |
Agent Controller is a daemon that allows client applications to launch and manage local or remote applications and provides information about running applications to other applications. You must install Agent Controller separately before you can use the following tools:
Notes:
Use the following commands:
In all other cases you must uninstall the previous version of Agent Controller using the instructions provided below before installing Agent Controller version 6.0.1.
Refer to the instructions below for more information on silently installing Agent Controller.
Note for Linux: The Hyades Data Collection Engine feature of Agent Controller is compiled using libstdc++-libc6.2-2.so.3 shared library. Ensure that this shared library exists under the /usr/lib directory. If it does not exist, you have to install the RPM package compat-libstdc++ that comes with the operating system installation media.
Note for OS/400: Agent Controller for OS/400 (iSeries) requires that you install the IBM XML Toolkit for iSeries (5733-XT1). Contact your iSeries vendor to obtain a copy of the IBM XML Toolkit for iSeries.
Note for z/OS: Agent Controller for z/OS (zSeries) requires that you install the XML C++ Parser 1.4 for z/OS, available at www.ibm.com/servers/eserver/zseries/software/xml/download/cparser_download.html.
Agent Controller has been tested on the following platforms:
Agent Controller has not been tested on the following platforms, but it is expected to run on these platforms:
In general, Agent Controller works with JVM version 1.4 and above. Here are the JVM versions (java -fullversion) that Agent Controller has been tested on:
The Agent Controller installation files that you extracted to a temporary directory are located in the directories listed below:
If you installed either the Agent Controller provided with your version 6.0 Rational software development product or version 6.0.0.1 Agent Controller, it will be automatically uninstalled when you install the version 6.0.1 Agent Controller. In all other cases you must uninstall the previous version of Agent Controller, or any software derived from the Hyades Data Collection Engine, before installing Agent Controller version 6.0.1.
You can silently install the version 6.0.1 Agent Controller and without first uninstalling the version 6.0 or version 6.0.0.1 Agent Controller by using the parameter -P hyadesdc_product.patch=True. By using this method, your previous installation configuration gets migrated; all of the previous installation parameters are preserved. Use the following commands:
Refer to the instructions below for more information on silently installing Agent Controller.
If you have a previous version of Agent Controller or any software derived from the Hyades Data Collection Engine, stop it, uninstall it, and clean up any left-over files before installing this version of Agent Controller. The following files may be left behind after uninstalling:
Windows:
%RASERVER_HOME%\*.* (directory where Agent Controller is installed) %SystemRoot%\system32\piAgent.dll (Windows' system32 directory) %SystemRoot%\system32\LogAgent.dll %SystemRoot%\system32\hcbnd.dll %SystemRoot%\system32\hcclco.dll %SystemRoot%\system32\hccldt.dll %SystemRoot%\system32\hccls.dll %SystemRoot%\system32\hcclserc.dll %SystemRoot%\system32\hcclsert.dll %SystemRoot%\system32\hcclsm.dll %SystemRoot%\system32\hcjbnd.dll %SystemRoot%\system32\hclaunch.dll %SystemRoot%\system32\hcthread.dll %SystemRoot%\system32\piAgent.dll %SystemRoot%\system32\rac.dll %SystemRoot%\system32\sysperf.dllLinux, AIX, HP-UX, Solaris:
$RASERVER_HOME/* (directory where Agent Controller is installed /usr/lib/libpiAgent.so (or .sl on HP-UX) /usr/lib/libLogAgent.so /usr/lib/libhcbnd.so /usr/lib/libhcclco.so /usr/lib/libhccldt.so /usr/lib/libhccls.so /usr/lib/libhcclserc.so /usr/lib/libhcclsert.so /usr/lib/libhcclsm.so /usr/lib/libhcjbnd.so /usr/lib/libhclaunch.so /usr/lib/libhcthread.so
Click Next to proceed.
Click Next to proceed.
Click Next to proceed.
If Enable is selected, click Next and under Security type a comma-separated list of users that can connect to Agent Controller. These users will be required to authenticate to use the tool.
Click Next to proceed.
You can run the installation process silently using the following parameters with the setup command:
| Parameter | Description |
|---|---|
| Required Parameters | |
-silent | tells the installer to run silently |
-P installLocation | specify the installation path |
-W javaHome_win.path | (Windows) specify the fully-qualified path of the java.exe executable |
-W javaHome_unix.path | (non-Windows)specify the fully-qualified path of the java executable |
-W hostList.type | specify how clients can connect to Agent Controller (ALL, LOCAL, CUSTOM)
|
-W securityCustom.type | (Use if hostList.type="CUSTOM") specify whether security should be
turned on (true, false)
|
-W securityLocal.type | (Use if hostList.type="LOCAL") specify whether security should be
turned on (true, false)
|
| Optional Parameters | |
-W wasHome_win.was510path | (Windows) specify the installed location of IBM WebSphere Application Server 5.1 |
-W wasHome_unix.was510path | (non-Windows) specify the installed location of IBM WebSphere Application Server 5.1 |
-W wasHome_win.was500path | (Windows) specify the installed location of IBM WebSphere Application Server 5.0 |
-W wasHome_unix.was500path | (non-Windows) specify the installed location of IBM WebSphere Application Server 5.0 |
-W hostListCustom.hosts | specify the client hostnames, separated by commas (if hostList.type="CUSTOM") |
-W securityAllList.users | (Use if hostList.type="ALL") specify which users can connect to Agent Controller |
-W securityCustomList.users | (Use if hostList.type="CUSTOM") specify which users can connect to Agent Controller (if securityCustom.type = "true") |
-W securityLocalList.users | (Use if hostList.type="LOCAL") specify which users can connect to Agent Controller (if securityLocal.type = "true") |
-P hyadesdc_ibm_runtimeAnalysis_feature.active=false | specify to not install the Runtime Analysis feature (by default it is installed during silent install) |
Windows example:
setup.exe -silent -P installLocation="D:\IBM\AgentController" -W javaHome_win.path="D:\jdk1.4.1\jre\bin\java.exe" -W wasHome_win.was510path="D:\WebSphere5.1\AppServer" -W wasHome_win.was500path="D:\WebSphere5.0\AppServer" -W hostList.type="CUSTOM" -W hostListCustom.hosts="host1,host2" -W securityCustom.type="true" -W securityCustomList.users="user1,user2"
Non-Windows example:
setup.bin -silent -P installLocation="/opt/IBM/AgentController" -W javaHome_unix.path="/opt/java1.4.1/jre/bin/java" -W wasHome_unix.was510path="/opt/WebSphere5.1/AppServer" -W wasHome_unix.was500path="/opt/WebSphere5.0/AppServer" -W hostList.type="CUSTOM" -W hostListCustom.hosts="host1,host2" -W securityCustom.type="true" -W securityCustomList.users="user1,user2"
Using a response file
You can create a response file (for example, setup.rsp) to store all the above parameters, instead of specifying them on the command line:
# Start of response file -P installLocation="D:\IBM\AgentController" -W javaHome_win.path="D:\ibm-sdk-n142p\jre\bin\java.exe" -W wasHome_win.was510path="D:\WebSphere5.1\AppServer" -W wasHome_win.was500path="D:\WebSphere5.0\AppServer" -W hostList.type="CUSTOM" -W hostListCustom.hosts="host1,host2" -W securityCustom.type="true" -W securityCustomList.users="user1,user2" # End of response file
# Start of response file -P installLocation="D:\IBM\AgentController" -W javaHome_win.path="D:\ibm-sdk-n142p\jre\bin\java.exe" -W wasHome_win.was510path="D:\WebSphere5.1\AppServer" -W wasHome_win.was500path="D:\WebSphere5.0\AppServer" -W hostList.type="LOCAL" -W securityLocal.type="true" -W securityLocalList.users="user1,user2" # End of response file
# Start of response file -P installLocation="D:\IBM\AgentController" -W javaHome_win.path="D:\ibm-sdk-n142p\jre\bin\java.exe" -W wasHome_win.was510path="D:\WebSphere5.1\AppServer" -W wasHome_win.was500path="D:\WebSphere5.0\AppServer" -W hostList.type="ALL" -W securityAllList.users="user1,user2" # End of response file
To install using the response file:
Windows: setup.exe -silent -options d:\temp\setup.rsp
Non-Windows: setup.bin -silent -options /tmp/setup.rsp
PATH=/usr/sbin:$PATH export PATH
| Platform | Library path setting |
|---|---|
| AIX |
LIBPATH=/usr/java14/jre/bin:/usr/java14/jre/bin/classic:$LIBPATH export LIBPATH |
| HP-UX |
SHLIB_PATH=/opt/java1.4/jre/lib/PA_RISC/server:/opt/java1.4/jre/lib/PA_RISC:$SHLIB_PATH export SHLIB_PATH |
| Linux/IA32 |
LD_LIBRARY_PATH=/opt/IBMJava2-141/jre/bin/classic:/opt/IBMJava2-141/jre/bin:$LD_LIBRARY_PATH export LD_LIBRARY_PATH |
| Linux/PPC64 |
LD_LIBRARY_PATH=/opt/IBMJava2-ppc64-142/jre/bin:/opt/IBMJava2-ppc64-142/jre/bin/classic:$LD_LIBRARY_PATH export LD_LIBRARY_PATH |
| Linux/390 |
LD_LIBRARY_PATH=/opt/IBMJava2-s390-141/jre/bin/classic:/opt/IBMJava2-s390-141/jre/bin:$LD_LIBRARY_PATH export LD_LIBRARY_PATH |
| Solaris |
LD_LIBRARY_PATH=/usr/j2sdk1.4.2_04/jre/lib/sparc/server:/usr/j2sdk1.4.2_04/jre/lib/sparc:$LD_LIBRARY_PATH export LD_LIBRARY_PATH |
| z/OS |
LIBPATH=/usr/lpp/java/IBM/J1.4/bin/classic:/usr/lpp/java/IBM/J1.4/bin:$LIBPATH export LIBPATH |
./RAStart.sh
./RAStop.sh
Agent Controller v6.0.1 prevents mutliple instances of the product from being installed on a single workstation. When additional installations are peformed, either by stand-alone install or as an embedded install inside a product, Agent Controller records a reference to the name of the product that is initiating the new installation.
If Agent Controller has been installed multiple times - in other words, there are multiple reference counts - either by stand-alone install or as an embedded install inside a product, it can be uninstalled only when the last referencing product is uninstalled; the last referencing product still requires Agent Controller.
If you attempt to uninstall Agent Controller while it is still required by another product, the uninstallation will not proceed and you will receive a message "This product cannot be uninstalled as it is required by another product."
If you have a previous version of Agent Controller or any software derived from the Hyades Data Collection Engine, stop it and uninstall it before installing this version.
Important: Agent Controller for OS/400 (iSeries) requires that you install the IBM XML Toolkit for iSeries (5733-XT1). Contact your iSeries vendor to obtain a copy of the IBM XML Toolkit for iSeries.
CRTLIB HYADESDC CRTLIB IBMRAC
CRTSAVF HYADESDC/HYADESDC
CRTSAVF IBMRAC/IBMRAC
CRTSAVF IBMRAC/IBMRTA
RSTOBJ OBJ(*ALL) SAVLIB(HYADESDC) DEV(*SAVF) SAVF(HYADESDC/HYADESDC)
RSTOBJ OBJ(*ALL) SAVLIB(IBMRAC) DEV(*SAVF) SAVF(IBMRAC/IBMRAC)
RSTOBJ OBJ(*ALL) SAVLIB(IBMRAC) DEV(*SAVF) SAVF(IBMRAC/IBMRTA)
RST DEV('/QSYS.LIB/HYADESDC.LIB/HYADESIFS.FILE') OBJ('/opt/hyadesdc/*')
RST DEV('/QSYS.LIB/IBMRAC.LIB/IBMRACIFS.FILE') OBJ('/opt/hyadesdc/*') ALWOBJDIF(*ALL)
RST DEV('/QSYS.LIB/IBMRAC.LIB/IBMRTAIFS.FILE') OBJ('/opt/hyadesdc/*') ALWOBJDIF(*ALL)
./SetConfig.sh
ADDLIBLE HYADESDC ADDLIBLE IBMRAC
SBMJOB CMD(CALL RASERVER) JOBD(RASTART)
ENDJOB JOB(RASTART)
If you have a previous version of Agent Controller or any software derived from the Hyades Data Collection Engine, stop it and uninstall it before installing this version.
Important: Agent Controller for z/OS (zSeries) requires that you install the XML C++ Parser 1.4 for z/OS, available at www.ibm.com/servers/eserver/zseries/software/xml/download/cparser_download.html.
pax -ppx -rf ibmrac.os390.pax
pax -ppx -rf ../../tptpdc.os390.pax
pax -ppx -rf ../../ibmrta.os390.pax
./createLinks.sh
extattr +p /usr/lpp/IBM/AgentController/lib/*.so
extattr +p /usr/lpp/IBM/AgentController/plugins/com.ibm.rational.pd.probekit/lib/*.so
./SetConfig.sh
Data Channel usage on z/OS:
In order to set a large dataChannelSize in the serviceconfig.xml file you may need to increase the maximum shared memory segment size setting on your machine. To do this, increase the IPCSHMMPAGES value in the BPXPRMxx parmlib member. This value is the maximum number of 4K pages that your data channel can be. For example, if you want to set dataChannelSize to 32M, you must set IPCSHMMPAGES to a value greater than 8192.
To allow Agent Controller to communicate with a large number of agents simultaneously, you must set the IPCSHMNSEGS value in the BPXPRMxx parmlib member to an appropriate value. This value specifies the maximum number of attached shared memory segments for each address space. The default value is 10 so you should increase this to 50.
For more information about the data channels used by Agent Controller, refer to the online help information for Agent Controller.
For more information about z/OS BPXPRMXX parmlib members and how to update them, refer to IBM z/OS MVS(TM) Initialization and Tuning Reference.
Note: RAServer requires the directories of the JRE that contain executable libraries such as libjvm.so to be added to the LIBPATH environment variable. For example, if you are using the IBM JRE 1.4.1, the LIBPATH variable would be set as follows:
export LIBPATH=/usr/lpp/java/IBM/J1.4/bin/classic:/usr/lpp/java/IBM/J1.4/bin:$LIBPATH
./RAStart.sh
./RAStop.sh
./removeLinks.sh
rm -rf /usr/lpp/IBM/AgentController
The following list contains hints and tips for using the Agent Controller security feature on all platforms:
This section covers known problems and limitations related to installing and uninstalling Agent Controller. Except where otherwise noted, the following information applies to all operating systems that are supported for Agent Controller.
Agent Controller may fail to start on non-Windows platforms with the following message:
RAServer failed to start.
This failure is usually caused when TCP/IP port 10002 is not free. Agent Controller listens on this port by default. Another process running on the system may be using this port when Agent Controller is started or perhaps Agent Controller was just stopped and then restarted before the port could be released.
If Agent Controller failed to start, you can start it as follows:
If you encounter errors during installation or uninstallation, this may be due to the fact that the object files of Agent Controller are loaded by running processes. To ensure the object files can be modified, do the following:
For product news, events, support, and other information, visit your product home page:
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this documentation in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this documentation. The furnishing of this documentation does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the
IBM Intellectual Property Department in your country or send inquiries, in
writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any
other country where such provisions are inconsistent with local
law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical
errors. Changes are periodically made to the information herein;
these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the
program(s) described in this publication at any time without notice.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the
purpose of enabling: (i) the exchange of information between
independently created programs and other programs (including this one) and
(ii) the mutual use of the information which has been exchanged, should
contact:
Intellectual Property Dept. for Rational Software
IBM Corporation
3600 Steeles Avenue East
Markham, Ontario
Canada L3R 9Z7
Such information may be available, subject to appropriate terms and
conditions, including in some cases, payment of a fee.
The licensed program described in this documentation and all licensed
material available for it are provided by IBM under terms of the IBM Customer
Agreement, IBM International Program License Agreement or any equivalent
agreement between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating
environments may vary significantly. Some measurements may have been
made on development-level systems and there is no guarantee that these
measurements will be the same on generally available systems.
Furthermore, some measurements may have been estimated through
extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available
sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be
addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject
to change or withdrawal without notice, and represent goals and objectives
only.
This information contains examples of data and reports used in daily
business operations. To illustrate them as completely as possible, the
examples may include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the
names and addresses used by an actual business enterprise is entirely
coincidental.
Programming interface information is intended to help you create application software using this program.
General-use programming interfaces allow you to write application software that obtain the services of this program's tools.
However, this information may also contain diagnosis, modification, and tuning information. Diagnosis, modification and tuning information is provided to help you debug your application software.
Warning: Do not use this diagnosis, modification, and tuning information as a programming interface because it is subject to change.
The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both:
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Windows and Windows NT are trademarks of Microsoft(R) Corporation in the United States, other countries, or both.
Intel and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Other company, product or service names, may be trademarks or service marks of others.