
Licensed Materials - Property of IBM
Copyright IBM Corp. 2004  All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

PRODUCT     : IBM Tivoli Monitoring for Transaction Performance
INTERIM FIX : 5.3.0.0-TIV-WTP-IF002
RELEASE     : ITMTP v5.3
DATE        : 2004/11/21
LAST UPDATE : 2004/11/21


You should print and read this document and all associated references 
before applying this maintenance package. The online page where this 
package was downloaded is the most up to date information and supersedes 
all other versions of this document.  

I.   INTERIM FIX.
  5.3.0.0-TIV-WTP-IF002

II.  DESCRIPTION:
  This package enables the coexistence of the Management Agent J2EE Monitoring component 
  of ITMTP v5.3 with the following products:
     IBM WebSphere Studio Application Monitor (WSAM v2.1.4)
     IBM Tivoli Monitoring for Web Infrastructure (ITMWI 5.1.2 fp1) 

III. PREREQUISITES:
      ITMTP v5.3
	Please refer to the ITMTP software requirements for supported versions
    	of WebSphere Application Server.

	COEXISTENCE PREREQUISITES:
    	WSAM 2.1.4
    	Please refer to the IBM WSAM software requirements for supported versions
    	of WebSphere Application Server.

    	ITMWI 5.1.2 fp1
    	ITM 4.1.1

IV. INSTALLATION INSTRUCTIONS:
  For ITMTP J2EE Management Agents to be deployed in a zOS machine, refer to the 
  section "V. zOS INSTALLATION INSTRUCTIONS".

  This Interim Fix is applied directly to the ITMTP Management Server.

  The installer contains a bundled JVM that will be used to launch 
  the installation program.

  Download the Interim Fix. Execute the 5.3.0.0-TIV-WTP-IF002 Executable that corresponds 
  to the platform of your ITMTP Management Server machine as follows:
      AIX:         5.3.0.0-TIV-WTP-IF002_aix.bin    (See DB2 ENVIRONMENT below)
      Solaris:     5.3.0.0-TIV-WTP-IF002_sol.bin    (See DB2 ENVIRONMENT below)
      Linux:       5.3.0.0-TIV-WTP-IF002_lin.bin    (See DB2 ENVIRONMENT below)
      Linux s390:  5.3.0.0-TIV-WTP-IF002_lin390.bin (See DB2 ENVIRONMENT below)
      Linux ppc:   5.3.0.0-TIV-WTP-IF002_ppc.bin    (See DB2 ENVIRONMENT below)
      Windows:     5.3.0.0-TIV-WTP-IF002_w32.exe

  DB2 ENVIRONMENT:  
     When applying this package to ITMTP Management Servers running in a supported
     Unix platform (AIX, Solaris, Linux, Linux s390, Linux ppc) that is making 
     use of a DB2 server, it is necessary to prepare the DB2 environment for the session 
     that will invoke the installation program, by executing the db2profile script of the 
     DB2 client installation as in the following example:
          # .  /usr/db2inst1/sqllib/db2profile
     *Note the (.) dot before the command.
     Then proceed to execute the installer binary, for example:
          # /usr/download/5.3.0.0-TIV-WTP-IF002_aix.bin

V. INSTALLATION INSTRUCTIONS FOR zOS.
   Download and apply PTF found in APAR OA09008
   Order the PTF and apply it to your box.
   Run script /usr/lpp/tmtp/V5R3M0/MA/config1/prepConfig.sh
   Now follow instructions in section VI.

VI. ADDITIONAL INSTALLATION INSTRUCTIONS.
   For Installing WSAM coexistence refer to Section A.  
   For Installing ITMWI coexistence refer to Section B.

   A) Installing WSAM and J2EE:
      The ITMTP J2EE behavior must be deployed after WSAM is already installed.  You must 
      undeploy the J2EE behavior, install WSAM, then redeploy J2EE.  If you wish to
      install WSAM at a later time then you can refer to STEP 5 below. 

      Detailed instructions of this procedure follows:

      STEP 1 - Uninstall current J2EE behaviors:
        If J2EE is already deployed on the ITMTP Management Agent it is necessary to undeploy it.
        (If no J2EE behavior is deployed on the Management Agent, you can proceed to STEP 3.)
        
        1.1 Save Configuration (Optional)
        	Write down the J2EE behavior configuration information that will be used 
        	while deploying the new J2EE behavior in STEP 3. Log in into the ITMTP GUI 
		and go to "System Administration->Work with Agents" view.  Select the 
		J2EE Management Agent, choose "View Details" from the drop down list,
	  	and click "Go" to retrieve the current configuration values.
        
        1.2 Uninstalling J2EE : 
        	Log in into the ITMTP GUI and go to "System Administration->Work with Agents" view.
         	Select the J2EE Management Agent, choose "Remove Component" from the drop down list, 
	  	and click "Go".  Select J2EE server instance, choose "Remove" from the drop down list, 
	    	and click "Go".

	IMPORTANT: If there is more than one J2EE server instance installed on the Management Agent, 
	you must repeat STEP 1 until all J2EE server instances on that ITMTP Management Agent are removed.

      STEP 2 - Manually remove the old J2EE behaviors:
	You must stop WAS and delete some files manually because they might be locked or in use.
	On the Management Agent, perform these steps:
	
        2.1 Shutdown all WebSphere Server instances.
		- For WAS 4x, shutdown the Administrative server
            - For WAS 5x, shutdown all the server instances

        2.2 Stop the Management Agent.
		- On Windows: Stop "IBM Tivoli Monitoring for Transaction Performance" service.
	      - On Unix: Run $MA_HOME/bin/stop_tmtpd.sh

        2.3 Delete the $MA_HOME/app/instrument directory.
	  
	  2.4 Delete $WAS_HOME/bin/*jitipi_53.*
        
        2.5 Start the Management Agent:
		- On Windows: Start "IBM Tivoli Monitoring for Transaction Performance" service.
		- On Unix: Run $MA/bin/start_tmtpd.sh

	  2.6 Restart WebSphere.
        
      STEP 3 - Install WSAM using the WSAM documentation installation documentation.
	
      STEP 4 - Installing J2EE:
        In the ITMTP GUI, proceed to "System Administration -> Work with Agents" view,
        Select the Management Agent, choose "Deploy J2EE", and click "Go".
        Fill in the appropriate J2EE information, check "Automatically Restart the Application Server",
	  and click "OK".
    
      STEP 5 (Optional) - Installing WSAM at a later time:
        In the ITMTP GUI, proceed to "System Administration -> Work with Agents" view,
        Select the J2EE Management Agent, and choose "View Details" from the drop down 
	  list and click Go. If all J2EE instances are not at version 5.3.0.02,
	  you must redeploy J2EE following STEPS 1-4 outlined above, otherwise follow
	  the steps below:
	
		5.1 On the Management Agent that you want to install WSAM on, browse to 
        		$MA_HOME/app/instrument/bin
        		( default windows C:\Program Files\ibm\tivoli\MA\instrument\53\bin
                  		unix    /opt/ibm/tivoli/MA/instrument/53/bin )
	
		5.2 Disable J2EE from WAS by executing
			> enableprobes -disable -serverHome $WAS_HOME -serverName {serverInstance}
        
		5.2 Install WSAM using the WSAM installation documentation.

      	5.3 Enable J2EE to WAS by executing
			> enableprobes -enable -serverHome $WAS_HOME -serverName {serverInstance}
		
      	5.4 Restart WebSphere server instance on your Management Agent.

   B) Installing ITMWI and J2EE: Manual Workaround
        In order to enable JVMPI data reporting for IBM WebSphere Application Server you need to
	  modify the JVM parameters in your WebSphere configuration.
	
      B.1 - Backup the WebSphere configuration files
		For WebSphere 4:
		Create backup directories.
			mkdir /WASbackup
			mkdir /WASbackup/bin
			mkdir /WASbackup/properties
			mkdir /WASbackup/installApps
			mkdir /WASbackup/etc
		Backing up WebSphere configuration as XML
			$WAS_HOME/bin/XMLConfig -adminNodeName {Node Name} -export /WASbackup/wasexport.xml

		For WebSphere 5:
		Stop WebSphere.
		Backing up WebSphere configuration
			$WAS_HOME/bin/backupConfig.sh or backupConfig.bat

      B.2 - Log in to your WebSphere Administrative Console and browse to JVM Settings
		For single WAS 4 installation:
			Launch the Administrative console
				$WAS_HOME/bin/adminclient
			Select WebSphere Administrative Domain -> Nodes -> {Server Name)->
				Application Servers-> {server instances}.  
			On "JVM Settings" tab, click on "Advanced JVM Settings...", 
			edit field Command line arguments

		For Server Group WAS 4 installations:
			Launch the Administrative console
				$WAS_HOME/bin/adminclient
			Select WebSphere Administrative Domain -> Server Groups -> servergroup.
			On "JVM Settings" tab, click on "Advanced JVM Settings...", 
			edit field Command line arguments
			
		For WAS 5 installation:
			Connect to the WebSphere Administrative console for single installation or 
			to the Network Deployment Manager for Network Deployment 

			From the menu, select Server -> Application Servers

			Click on {Server Instance}-> Process Definition-> Java Virtual Machine

	B.3 - Edit the JVM Arguments, and replace the following entry	  

		  if -Xrunijitipi_53:${MA_INSTRUMENT}\lib\jiti.properties is found, change it to
		  	"-Xrunvirt:agent=ijitipi_53:${MA_INSTRUMENT}\lib\jiti.properties,agent=pmiJvmpiProfiler"
		  if -Xrunjitipi_53:${MA_INSTRUMENT}\lib\jiti.properties if found, change it to
		   	"-Xrunvirt:agent=jitipi_53:${MA_INSTRUMENT}\lib\jiti.properties,agent=pmiJvmpiProfiler"

	B.4 - Save the changes

      B.5 - Restart WebSphere.

VII) UNINSTALLATION INSTRUCTIONS:

  A) Uninstalling Interim Fix 5.3.0.0-TIV-WTP-IF02 
     To uninstall this Interim Fix package from the Management Server, execute
         <BASEDIR>\MS\5.3.0.0-TIV-WTP-IF002\uninstall.exe or uninstall.bin
     And follow the instructions of the uninstall program.

     The Uninstall procedure removes the files from the Management Server.
     Until you undeploy the J2EE behaviors from your Management Agents your 
     J2EE servers will still have the coexistence code.

     IMPORTANT:
     If you uninstall the Interim Fix then you must uninstall WSAM, J2EE,
     and ITMWI from all of your J2EE WebSphere environments.  You must 
     then install ONLY one application to reside on WebSphere, since you will 
     be losing coexistence support.     

  B) Uninstalling WSAM
     B.1) Undeploy the J2EE server instances that coexist with WSAM
     B.2) Uninstall WSAM, see WSAM documentation for instructions.
     B.3) Redeploy the J2EE server instances. 
     B.4) Restart WebSphere.

  C) Uninstalling ITMWI and J2EE: Manual Workaround
    C.1) Browse to your WebSphere server directory
        ex: $WAS_HOME/config/cells/{cell name}/nodes/{node name}/servers/{server name}
    C.2) Backup then edit the server.xml, edit this line
		if ijitipi_53
            "-Xrunvirt:agent=ijitipi_53:${MA_INSTRUMENT}\lib\jiti.properties,agent=pmiJvmpiProfiler"
            "-Xrunvirt:agent=ijitipi_53:${MA_INSTRUMENT}\lib\jiti.properties"
		if jitipi_53
            "-Xrunvirt:agent=jitipi_53:${MA_INSTRUMENT}\lib\jiti.properties,agent=pmiJvmpiProfiler"
            "-Xrunvirt:agent=jitipi_53:${MA_INSTRUMENT}\lib\jiti.properties"
    C.3) Restart WebSphere.

    Contact IBM Support for further assistance.

VIII. MODIFIED FILES:
     On the Management Server:
        <BASEDIR>/MS/lib/j2eeinst.jar 
        <BASEDIR>/MS/config/tmtpversion.properties

IX. ADDITIONAL INFORMATION:

  TARGET FIXPACK: 5.3.0.0-TIV-WTP-FP001

  KNOWN DEFECTS OR LIMITATIONS:  

    A)Problem: 
	enableprobes.sh fails to start with error
	"Exception in thread "main" java.lang.NoClassDefFoundError: com/ibm/tivoli/jiti/registry/IRegistry"
	
	Solution:
	Edit the enableprobes.sh file and above the line:
		CLASSPATH="$CLASSPATH:$INSTRUMENT_LIB_DIR/j2eeprereq.jar"
      add the line CLASSPATH="$CLASSPATH:$INSTRUMENT_LIB_DIR/jiti.jar".

    B)Problem:
	Installing bos.perf packages after the ITMTP Management Agent is installed will make J2EE stop working.

	Solution:
	You need to relink the libarm.a
	ln -sf /usr/lib/libarm.a <MA_INSTALL_DIR>/bin/aix4-r1/USRLIB/libarm.a
	

  IMPORTANT NOTES
	This patch has only been tested for WSAM and ITMWI coexistence.  
	If you need to uninstall WSAM or ITMWI you need to follow the section 
    	VII Uninstall Instructions.

	By enabling coexistence, ITMTP will lose support for gathering JNDI metrics.
