webMethods Integration Server Service Profiler (ISSPROF) v1.3
================================================================================

Wrightia (c) 2006-2012 (README file for Windows 2K, XP & 2003 Server)

1. Introduction
2. Installation
   2.1 Instructions for webMethods versions prior to v8.2
       2.1.1 IS running as Windows Service
   2.2 Instructions for webMethods versions from v8.2 onwards
       2.2.1 Installation common steps
       2.2.2 IS running as Windows Service
       2.2.3 Installation completion
3. Uninstall
4. Upgrading
5. Further Reading


1. Introduction
    The ISSPROF is a tool to collect and analyze runtime information about IS
    Services.
    It is intended to have a small footprint while running, be easy and fast to
    install and uninstall, and to require no configuration over the Services
    being profiled.


2. Installation
    Install the profiler by installing the following IS Packages, in the order
    they are presented:
        - WiaRoot.zip
        - WiaUtilities.zip
        - WiaServiceProfiler.zip

    The presented ZIP filenames may have a version suffix appended to its name.
    These suffixes are not indicated to have this readme file version
    independent.

    Depending on the version of the IS where you are installing this tool,
    follow the instructions in the corresponding sub-section.

2.1 Instructions for webMethods versions prior to v8.2
    After installing the IS Packages the installation must be completed by
    configuring the Integration Server. Perform the following steps:
        a) Shutdown the IS;
           If the IS is running as an NT Service you *must* unregister it
           before the next step.

        b) Edit the startup script;
           Save a copy of the file 'server.bat' as 'server.org.bat';

           Edit the script file 'server.bat' and insert a call to a 'setenv.bat'
           script at the point shown below with '---->' and as indicated.

            ...
      ----> Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" %1

            set CLASSPATH=%PREPEND_SYSTEM_CLASSPATH%;%CLASSPATH%;%APPEND_SYSTEM_CLASSPATH%
            set PATH=%PATH%;%IS_DIR%\support\win32;%IS_DIR%\jvm\bin\classic;%IS_DIR%\lib;

            rem
            rem Run as an NT service ? If so, save program arguments to Registry
            rem
            if "1%1"=="1-service" (
            ...

        c) Start the Integration Server;
           If the IS is to be run as an NT Service you have register it (again).

        d) Set the tool License Key.
           Access the Service Profiler licensing page and set the License Key.

    The IS can be prevented from starting with the Service Profiler, without
    the need to uninstall it, by means of putting a file named ISSPROF_VOID in
    the '<wm_dir>\IntegrationServer' folder. The presence of this file skips
    the loading sequence. A direct result is having the functionality links in
    the tool menu disabled.

    IMPORTANT:  When installing webMethods upgrades (i.e., Service Packs) the
                server.bat script may be overwritten thus disabling the
                Service Profiler start-up.
                When this happens, just repeat the script edit step described
                above.

2.1.1 IS running as Windows Service
    There is no additional setting needed for using the Service Profiler on an
    IS running as a Windows (NT, W2K, XP) Service.

    If the IS is already running as a Windows Service you need to unregister
    it and register it again.
    The same is valid when uninstalling the tool. As required and documented
    by Software AG, all actions that change the Java command line require the
    Windows Service to be unregistered and be registered again. You must,
    however, unregister the service *before* doing any changes to the startup
    or shutdown scripts.

2.2 Instructions for webMethods versions from v8.2 onwards
    The webMethods v8.2 shell scripts introduce the segregation of starting
    the JVM into a specific script: '<wm_dir>\profiles\IS\bin\runtime.bat'.

2.2.1 Installation common steps
    a) Save a copy of the file 'runtime.bat' as 'runtime.org.bat';
       If the IS is running as an NT Service you *must* unregister it
       before the next step.

    b) To continue using the 'server.bat' to start the IS, all there is to do is
       to add the line...

            Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" %1

    ... right before the Java command line in 'runtime.bat', like this:

            ...
            title %WINDOW_TITLE%
            if "%USE_WRAPPER%"=="yes" (
              goto use_wrapper
            )
            Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" %1
            echo Starting as an application using Java.
            %JAVA_RUN% %JAVA_OPTS% %JAVA_SYSPROPS% -jar %OSGI_FRAMEWORK_JAR% -debug -configuration %OSGI_CONFIGURATION_AREA% %2 %3 %4 %5 %6 %7 %8 %9
            ...

    c) If the IS is running as an NT Service, continue installation at section
       2.2.2, otherwise skip to section 2.2.3.

2.2.2 IS running as Windows Service
    If the IS is running as an NT Service you *must* unregister it
    before continuing (if not done so yet). The (re)registration must be done
    only after the changes indicated below.
    The same is valid when uninstalling the tool. As required and documented
    by Software AG, all actions that change the Java command line require the
    Windows Service to be unregistered (before changes) and be registered again
    (after changes).

    To be able to use the Service Profiler with an IS running as an NT Service:
        a) Perform the changes at section 2.2.1 (above);

        b) Save a copy of the file 'server.bat' as 'server.org.bat';

        c) The same statement that was added to 'runtime.bat' needs to be added
           to the 'server.bat'. So, in 'server.bat' add the line...

            Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" %1

            ... right before the removal of the LOCKFILE statement, like this:

                    ...
                    rem
                    rem Run as an NT service ? If so, save program arguments to Registry
                    rem
                    rem Run as Server JVM
                    set SERVER_VM_OPT=-server
                    if "1%1"=="1-service" (
                        Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" %1
                        if exist LOCKFILE del LOCKFILE
                        "%JAVA_EXEC%" -classpath %IS_PROXY_JAR% com.wm.app.server.CustomServiceUpdater -isdir "%IS_DIR%" -wrapperdir "%IS_DIR%\..\profiles\IS\configuration" -binpath "%PATH%" -jvmargs "%SERVER_VM_OPT% %JAVA2_MEMSET% %JAVA_OPTS%" -progargs %3#%4#%5#%6#%7#%8#%9
                        goto :EOF
                    )
            ...

        d) Register the service;

        e) Complete the installation by following the steps in section 2.2.3.

    To use the Tanuki wrapper, nothing else needs to be done, because the
    preparation scripts already create the necessary configuration settings
    and add them to the '<wm_dir>\profiles\IS\configuration\wrapper.conf' file.
    A copy of the file is saved before the changes are made to the name
    'wrapper.conf.beforeissprof'.

2.2.3 Installation completion
    At this point the Service Profiler is already installed, but to have it up
    an running, please complete the steps that follow:

        a) Start the Integration Server;

        b) Set the tool License Key.
           Access the Service Profiler licensing page and set the License Key.


3. Uninstall
    To uninstall the tool:

        a) Shutdown the IS;
           If the IS is running as an NT Service you *must* unregister it
           before the next step.

        b) Revert the edited start-up scripts back to their saved originals,
           or just remove the lines inserted upon installation (refer to point
           2 in this document);
           Depending on the IS version, which files are these may vary.

        c) Delete the folder '<wm_dir>\IntegrationServer\serviceprofiler';

        d) Delete the folder for the package 'WiaServiceProfiler';

        e) If the IS is running as an NT Service, unregister the service and
           register it again;

        f) Start the IS.

    Optionally, you can remove the IS Packages 'WiaUtilities' and 'WiaRoot'.


4. Upgrading
    Due to the nature of the tool, its architecture and the runtime behavior,
    and also depending on the nature of the upgrade it may require steps beyond
    the simple (re)installation of an IS Package and/or patch.

    Due to the complexity of this subject, please refer to the User Guide for
    guidance.


5. Further Reading
    Reading the Profiling Whitepaper is recommended as the next reading document.
    This document is available for download from Wrightia's website. A direct
    link to it is provided in the installed 'WiaServiceProfiler' IS Package
    (see the Info package),

    The About page includes an Abstract of the Service Profiler, and links to
    Release Notes and Version History.
    The Online Help is useful to quickly check the way to use the tool.

    The User Guide is a more detailed documentation about using the Service
    Profiler, concerning all the aspects about using the tool.

