Getting started with Agent Controller - OS/400

This guide contains the following information:

Prerequisites

Install the TPTP 3.3.0 Runtime.
Agent Controller for OS/400-ISERIES requires the IBM XML Toolkit (5733-XT1) to be installed. Please contact your iSeries vendor for a copy of the IBM XML Toolkit. Alternatively, if you have a copy of the Enterprise edition of iSeries, you may already have a copy of the Toolkit on your CD of optional programs. For the latest information about iSeries related XML technologies, see the following Web site: http://publib.boulder.ibm.com/iseries/v5r1/ic2924/index.htm?info/rzamj/rzamjtoolkit.htm.

Configuring and starting Agent Controller

Notation

<ifs restore directory> = The absolute directory path where the IFS portion of Agent Controller has been restored.
<RAServer PID> = The process identifier for the server process.

Create a library called HYADESDC by typing:
```
CRTLIB HYADESDC
```
In the HYADESDC library, create an empty save file called HYADESDC.SAVF by typing:
```
CRTSAVF HYADESDC/HYADESDC
```
Add the server's HYADESDC.SAVF file to the library HYADESDC. Open a FTP connection to the target AS/400 machine from a location that has hyadesdc.savf. Type the following commands to add the file:
```
bin 
cd HYADESDC
put HYADESDC.SAVF
bye
```

Restore the save file HYADESDC.SAVF located to the library HYADESDC, by typing:

   RSTOBJ OBJ(*ALL) SAVLIB(HYADESDC) DEV(*SAVF) SAVF(HYADESDC/HYADESDC)

Create the <ifs restore directory>, /opt/hyadesdc, on the integrated file system (IFS). Make sure there is no file or directory inside this directory.
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/*')
   
```
Generate the configuration file that provides the rules for which applications that can be executed with the server. This can be accomplished by running the
```
<ifs restore directory>/bin/SetConfig.sh
```
script. Run this script from a qshell (launched via STRQSH) in the <ifs restore directory>/bin directory. This step will require that a Java Virtual Machine (JVM) be present in the system's PATH. Follow the prompts and the output will be the <ifs restore directory>/config/serviceconfig.xml file. This is a sample of the configuration file that will be used by the server when it is started. You may edit this file manually using the rules as outlined in the document Agent Controller configuration files. To load any changes, restart the server.
Add the HYADESDC library to the library list entry by running:
```
   ADDLIBLE HYADESDC
   
```

Start the server by running:

   SBMJOB CMD(CALL RASERVER) JOBD(RASTART)

Stop the server by running:

   ENDJOB JOB(RASTART) OPTION(*IMMED)

Querying Agent Controller version information

To display the version of Agent Controller, simply type:
RAServer -v
or
RAServer -version

The Agent Controller will display its version and terminate.

Server Logging

All server log entries will be placed in <unzip directory>/config/servicelog.log.

The Java Profiler is a library that attaches to a JVM to capture and record the Java application's behavior. The output from the profiling agent is in the form of XML fragments.

Documentation on the composition of these XML fragments is located at: http://www.eclipse.org/tptp/platform/documents/resources/profilingspec/XML4Profiling.htm

Invocation of the Java Profiler from the Hyades Workbench

The Java Profiler can be launched from the Hyades workbench. Open the Profiling Perspective and you can launch applications using the 'Profile' menu contribution or the toolbar button. Applications can be run either using code within the current Hyades workbench's workspace or binaries that are on the file system.

Invocation of the Java Profiler from the Command Line

The Java Profiler is invoked using the -Xrun JVM option as follows:

    -XrunpiAgent[:agent_parm[,agent_parm]*

where agent_parm may be:

server=[standalone | enabled | controlled]

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 Hyades 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, blocks the application 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.
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 imbedded 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 imbedded 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.xml in the current directory.
help
Displays a list of available agent options to standard out.

Uninstalling the Agent Controller

To uninstall the agent controller:

Stop the agent controller by running the following command:
```
ENDJOB JOB(RASTART) OPTION(*IMMED)
```
Remove the Agent Controller library HYADESDC and its contents.