This document contains installation instructions for ubTools Web Package. The procedures in this document can also be used for users upgrading existing ubTools applications.

Documentation Updates

Documentation Version	ubTools Web Package Version	Date
2.2.2	2.2.2	February-12, 2008
2.2.1	2.2.1	February-11, 2008
2.2.0	2.2.0	February-07, 2008
2.1.2	2.1.2	September-08, 2007
2.1.1	2.1.1	October-03, 2005
2.1.0	2.1.0	March-09, 2005
2.0.0	2.0.0	December-08, 2004
1.0.3	1.0.3	April-13, 2004
1.0.2	1.0.2	April-12, 2004
1.0.0	1.0.0	April-05, 2004

Documentation Accessibility

The latest version of this document is available at:

URL: http://www.ubtools.com/web/public/resources

Welcome to ubTools

ubTools brings high-quality softwares and consultancy. We believe that you will find that the result with ubTools is truly more than before.

What is ubTools

ubTools, a subsidiary of Unal Bilisim founded in 2001, is a company develops and hosts web based Oracle database products.

What is itrprof SQL Analyzer

itrprof SQL Analyzer is a web based tool which analyzes SQL_TRACE and Event 10046 trace files of Oracle; finds bottlenecks and offers information on how to tune them.

URL: http://www.ubtools.com/web/public/products/itrprof

What is iStatsPackAnalyzer

iStatsPackAnalyzer is a web based tool which analyzes STATSPACK files of Oracle; finds bottlenecks and offers information on how to tune them.

URL: http://www.ubtools.com/web/public/products/istatspackanalyzer

Downloading ubTools Web Package

ubTools Web Package consists of 2 products:

itrprof SQL Analyzer
iStatsPackAnalyzer

URL: http://www.ubtools.com/web/public/downloads

The products are available as downloadable compressed file which has the following file name:

ubtools-a.b.c.zip

This file includes the following files:

ubtools_web_package_installation.html: This manual.
ubtools-a.b.c.war: Applications.

The definition of ubtools-a.b.c.war is as below:

ubtools: Web package name.
a: Major additions.
b: Minor additions.
c: Fixes.
war: File extension in packed web application format.

ubTools Web Package Contents

The following table includes the contents of ubTools Web Package:

ubTools Web Package	itrprof SQL Analyzer	iStatsPackAnalyzer
2.2.2	6.2.4	1.3.1
2.2.1	6.2.3	1.3.1
2.2.0	6.2.2	1.3.1
2.1.2	6.1.2	1.3.1
2.1.1	6.1.1	1.3.0
2.1.0	6.1.0	1.3.0
2.0.0	6.0.0	1.2.2
1.0.3	5.1.5	1.2.2
1.0.2	5.1.5	1.2.2
1.0.0	5.1.4	1.2.1

Support

If you encounter a problem during the installation, go to the following address at:

URL: http://www.ubtools.com/web/public/support

System Requirements

Hardware and Operating Systems

Since ubTools Web Package is Java based, it's platform independent. They run on any platforms in which a certified java version is installed.

Memory and Disk Space Requirements

Because of the efficient design, ubTools Web Package is not resource intensive.

iStatsPackAnalyzer allocates memory less than 1MB.

The size of memory allocated by itrprof SQL Analyzer depends on the sizes of statements text in trace files. There is no direct releation to trace file size.

Total unpacked size of ubTools Web Package on disk is around 1.30MB.

Pre-Installation

Backing Up Existing Installations

If there is existing ubTools Web Package installations, new installations will not overwrite the existing installations by default. You can remove existing installations without any problems. But, keep the parameter files named *.properties of existing installations. Because, you may need your specific parameters(especially for LICENSE_KEY parameter) for the next installations.

As of ubTools Suite 2.1.0.2, the configuration files are no longer configured manually. They are configured by a web interface named ubAdmin.

Certification

The following table gives the certification table of ubTools Web Package against Java and Servlet Specification:

ubTools Web Package Version	Java Version	Servlet Specification
2.2.2	1.4.2	2.3
2.2.1	1.4.2	2.3
2.2.0	1.4.2	2.3
2.1.2	1.4.2	2.3
2.1.1	1.4.2	2.3
2.1.0	1.4.2	2.3
2.0.0	1.4.2	2.3
1.0.3	1.4.2	2.3
1.0.2	1.4.2	2.3
1.0.0	1.4.2	2.3

Java

To learn Java version, run the following in the command line of your host as below:

$ java -version
java version "1.4.2_04"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_04-b05)
Java HotSpot(TM) Client VM (build 1.4.2_04-b05, mixed mode)

If it doesn't return any thing or a certified version, be sure that correct java executable is available in your environment.

If you don't have a certified Java version in your host, download at:

URL: http://java.sun.com/j2se/1.4.2/download.html

Servlet Container

Install a servlet container which is certified with ubTools Web Package. If There is no servlet container installed in your server, Tomcat is recommended. Download Tomcat at:

URL: http://tomcat.apache.org/download-41.cgi

Test Servlet

Be sure that at least one sample servlet or JSP application works fine. If sample servlet/JSP applications don't work, it means that your servlet container setup is not correct. In that case, don't continue to install ubTools Web Package.

Installation

Deploy ubTools Web Package

If there is a web admin, give ubtools-a.b.c.war to your web admin. It is very easy for a web admin to deploy ubTools Web Package. If there is no web admin, deployment may be different in the different servlet containers. But, the basic concept is as below:

Go to the directory of your servlet container in which servlet applications reside. This is typically named webapps directory.

Copy ubtools-a.b.c.war to webapps directory. Note that ubtools-a.b.c.war is a BINARY file.

Re-start your servlet container. This will unpack ubtools-a.b.c.war automatically. If it doesn't unpack, do it manually in webapps directory as below:

jar -xvf ubtools-a.b.c.war

Directory Tree

After ubTools Web Package is deployed, the following directory structure will be created:

ubtools-a.b.c
	/images
		...
	/META-INF
		...
	/products
		/istatspackanalyzer
			istatspackanalyzer.html
			...
		/itrprof
			itrprof.html
			...
		/ubadmin
			ubadmin.html
			...
		...
	/WEB-INF
		/classes
			/com
				/ubTools
					/servlet
						/itrprof
							AuthorizedClients.properties
							itrprof.properties
						/iStatsPackAnalyzer
							AuthorizedClients.properties
							iStatsPackAnalyzer.properties
							IdleWaits.ini
							...
						/ubAdmin
							ubAdmin.properties
					/ubSharedClasses
						IllegalXMLCharactersMap.properties
		/lib
			...
		web.xml
	ubtools_index.html

Post-installation

Verifying installation

If your servlet container is not open, open it.
Point your browser to the products home page of ubTools Web Package at
http://yourHostName:<portNumber>/ubtools-a.b.c

yourHostName: Name of the host in which ubTools Web Package has been installed.
portNumber : Port number assigned to ubTools Web Package. It's typically 8080 for Resin/Tomcat servlet container. If your web admin assigned different port number, contact your web admin.

If you can see the product home page of ubTools Web Package on your browser, it means your installation is successful.

Generating License Key

To run ubTools Web Package, you have to generate license keys. There are 2 types of license keys:

Evaluation license keys: Expires after some time. It's free and generated by users.

Production license keys: Never expires. It's generated for the customers by ubTools staff only.

Do the following steps to generate license key:

Point your browser to the product home page of ubTools Web Package at
http://yourHostName:<portNumber>/ubtools-a.b.c

Click the product link for which you want to generate license key.

After you point your browser to the home page of the product, click "Analyze" button.

You will get a message as below:

500 Servlet Exception
java.lang.UnsupportedOperationException: ppf-03 [0] : Initialization parameters
error. Cause : java.lang.UnsupportedOperationException: License key not
entered for the host <yourHostName>. Action : Contact support.

It means you did not entered a license key. To generate evaluation license key, go to:

URL: http://www.ubtools.com/web/public/downloads

Please note that you have to use <yourHostName> value in the message given above while generating license key. It's case sensitive.

To get production license key, contact ubTools with the required information used at the URL of evaluation license key generation.

Configuring ubTools Web Package

Confuguration of ubTools Web Package is done by a web interface named ubAdmin.

If your servlet container is not open, open it.
Point your browser to the products home page of ubTools Web Package at
http://yourHostName:<portNumber>/ubtools-a.b.c
Click ubAdmin.
Select ubAdmin - Parameters in user interface.
Set UBTOOLS_HOME to the physical path in which ubTools Web Package has been deployed. For example:

UBTOOLS_HOME = /home/resin/resin-2.1.9/webapps/ubtools-2.2.0
Configure itrprof SQL Analyzer and iStatsPackAnalyzer as defined in ubAdmin Administrator Manual.

New URLs and previous installations

If users had saved the URLs of previous ubTools Web Package installations in their browser bookmarks, they will not be able to see the new pages if they still use their old URLs. In that case, do do followings:

Redirect older URLs to the new URLs in web server level.
Inform users that new URLs are available.

Image Generation

ubTools Web Package generates images in analysis reports. On Windows platforms, there is no problem in image generations. But, platforms in which no graphics environment installed, it's not possible to generate images. There are 2 different solutions:

Set java.awt.headless to true as a Java command line parameter. The following sample gives a sample from Resin startup/shutdown script:
- $RESIN_HOME/bin/httpd.sh -server-root $SERVER_ROOT \
  -conf $RESIN_HOME/conf/resin.conf -Djava.awt.headless=true \
  $*
UNIX platforms, you have to get GUI permission for UNIX user in which ubTools Web Package has been installed. In other words, you should be able to run GUI applications. This is basically done by xhost command and DISPLAY environment variables. For further assitance, contact your UNIX admin.

De-installation

It is very easy for a web admin to de-install ubTools Web Package. If there is no web admin, de-installation may be different in the different servlet containers. But, the basic concept is as below:

Stop your servlet container.
Go to the directory of your servlet container in which servlet applications reside. This is typically named webapps directory.

Remove ubtools-a.b.c.war.
Remove ubtools-a.b.c directory with its sub-directories.

Change log

2.2.2

Bug of itrprof SQL Analyzer:

Database version value in USER INTERFACE PARAMETERS changed
from 9i --- 10g to 9i --- 11g.

2.2.1

Bug of itrprof SQL Analyzer:

Top Statements Ordered by CPU Time header renamed to
Top Statements Ordered by Service Time.

2.2.0

New features of itrprof SQL Analyzer:

Overall Response Time Distribution section renamed to
Top Statements Ordered by Response Time.
Top Statements Ordered by Service Time section added.
Top Statements Ordered by Wait Time section added.
Top Statements Ordered by Logical IO section added.

The 4th number in the WebPackage version has been removed.

2.1.2.2

Internal modifications.

2.1.1.2

New feature:

itrprof SQL Analyzer - Oracle 10.2 certification.

2.1.0.2

New features:

Web based configurations by ubAdmin:

itrprof SQL Analyzer - Parameters
itrprof SQL Analyzer - Authorized Clients
itrprof SQL Analyzer - Tuning Advices
iStatsPackAnalyzer - Parameters
iStatsPackAnalyzer - Authorized Clients
ubAdmin - Parameters

Bug:

Bug#4: itp-10 [9] : Internal error.

2.0.0.1

New features of itrprof SQL Analyzer:

Comparison of 2 trace files.
Histograms.
Processing UN-KNOWN cursors.
Processing Remote Procedure Calls(RPC)
Processing WAIT calls is not optional.
Processing EXECUTION PLANs is not optional.
Reporting Statement Totals is optional.
Execution plan support for Oracle 10g.

1.0.3.1

Bug#3: setContentType("text/html") missed.

1.0.2.1

Bug#1: NullPointerException while reading conf. files.
Bug#2: Wrong servlet-mapping and servlet order

1.0.1.1

Initial release.

Copyright Notice

ubTools Web Package is available in 2 forms:

Evaluation releases: Works with evaluation license keys.
Production releases: Works with production license keys.

Both the evaluation and the production release have the same features.

You can use the evaluation releases for free of charge until they expire. You can not re-install the evaluation releases on the same host once the products are expired.

The production releases can not be distributed. The evaluation releases can be distributed.

No products can be modified except their configuration files.

ubTools Web Package Installation Manual 2.2.2

info@ubTools.com
http://www.ubTools.com