Getting started with Agent Controller - OS/400

This guide contains the following information:

• Prerequisites
• Configuring and starting Agent Controller
• Agent Controller logging
• Invoking the Java Profiler
• Uninstalling Agent Controller

Prerequisites

• Install the Java runtime (JRE) or Java development kit (JDK) 1.5 or 1.4.x
• Remove or uninstall all existing installations of Agent Controller.

Configuring and starting Agent Controller

<ifs restore directory> = The absolute directory path where the IFS portion of Agent Controller has been restored.

1. In the HYADESDC library, create an empty save file called HYADESDC.SAVF by typing: CRTSAVF HYADESDC/HYADESDC
   
2. Under iSeries QShell, create the IFS directory /opt/hyadesdc if it does not exist. If this directory exists, delete everything under it by typing rm -rf /opt/hyadesdc/*
3. Transfer the downloaded HYADESDC.SAVF to the iSeries library HYADESDC, overwriting the save file created above.
4. Restore the save file HYADESDC.SAVF located to the library HYADESDC, by typing:
   RSTOBJ OBJ(*ALL) SAVLIB(HYADESDC) DEV(*SAVF) SAVF(HYADESDC/HYADESDC)
   
5. Restore the save file HYADESIFS.SAVF in HYADESDC to the IFS directory /opt/hyadesdc. For example,
   RST DEV('/QSYS.LIB/HYADESDC.LIB/HYADESIFS.FILE') OBJ('/opt/hyadesdc/*')
   
6. Run SetConfig.sh script from a QShell (launched via STRQSH) in the <ifs restore directory>/bin directory to generate the configuration file for the Agent Controller. This step will require 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 <ifs restore directory>/config/serviceconfig.xml will be generated based on your inputs.
7. Add the HYADESDC library to the library list entry by running: ADDLIBLE HYADESDC
   
8. Start the Agent Controller by running: SBMJOB CMD(CALL RASERVER) JOBD(RASTART)
   
9. Alternatively, the Agent Controller can be started from QShell by running the RAStart.sh script under the /opt/hyadesdc/bin directory
10. Stop the Agent Controller by running: ENDJOB JOB(RASTART) OPTION(*IMMED)
11. Alternatively, the Agent Controller can be stopped from QShell by running the RAStop.sh script under the /opt/hyadesdc/bin directory

You can verify the version of the installed Agent Controller by running the QShell script version.sh under the /opt/hyadesdc/bin directory. This requires step 7 to be executed before entering QShell.

If you want to make changes to the configuration file that was generated in step 5, you may run the SetConfig.sh 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.

Agent Controller Logging

Invoking the Java Profiler

The Java Profiler consists of a Profiling Agent packaged as a library.  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 the document entitled "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 of the Java Profiler from the Hyades 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, or external Java applications located in the file system, can be launched and profiled.

Invocation of the Java Profiler from the Command Line

Note: Step 7 in Configuring and starting Agent Controller is required for invoking the Java Profiler from the command line. Also, multithread capability must be enabled to profile a java application from the command line. Under QShell, the environment variable QIBM_MULTI_THREADED must be set to Y by the command: export QIBM_MULTI_THREADED=Y. 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 an 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:

  <ifs restore directory>/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="<some_dir>/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 .:<rac_dir>/plugins/org.eclipse.tptp.platform.collection.framework_<version>/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.trcxml in the current directory.
• help
  Displays a list of available agent options to standard out.

Uninstalling Agent Controller

To uninstall the Agent Controller:

1. Stop the Agent Controller by running the following command:

   ENDJOB JOB(RASTART) OPTION(*IMMED)

2. Remove the Agent Controller library HYADESDC and its contents.
3. Remove the IFS directory /opt/hyadesdc (including all subdirectories and files) with the following command from a QShell:

   rm -r /opt/hyadesdc/*