Prerequisites for the MQSeries Workflow Web Client

If you want to use the MQSeries Workflow Web Client, install the following prerequisite products or product components:

This servlet has been developed and tested using Windows NT V4, SP6a running Apache's Tomcat V3.2. Tests have been carried out using IBM HTTPServer V1.3.12 with IBM WebSphere Application Server V3.5.2 Advanced Edition. For client tests, mainly Microsoft Internet Explorer V5.5 was used and Netscape Navigator V4.6 was also used in tests.

Directory structure

After having extracted the file wa81.zip to your MQSeries Workflow installation directory, <MQWFDir>, the following new directories exist, containing these files:

Installing and setting up the MQSeries Workflow Web Client

If you are using a Unix platform, run the <MQWFDir>/WebClient/chaccess shell script to make sure the correct file ownerships and permissions are set for the Web Client's files. You may need to switch to the root account to be able to execute this shell script. Note that Java AWT which is used to create the process monitor images requires the DISPLAY variable to be set. This variable must point to an X11 server, preferably (for performance reasons) the local host.

Before you start installing the Web Client, read the section about prerequisites, then choose your environment from the following list:

The following versions are no longer supported, please upgrade to IBM WebSphere Application Server V3.5 if you want to use the Web Client:

If your environment is not listed above, see the generic installation instructions.

Instructions for installing over an earlier version of the Web Client precede the installation instructions for each of the environments. You may also want to check the change log before you continue.

After having installed, using your Web browser click http://localhost/MQWFClient/RTC.html.

In addition to the above, you might want to define an alias '/MQWFDoc' in your Web Server for the <MQWFDir>/doc directory. This allows you to access the documentation for the Web Client as http://localhost/MQWFDoc/WebClient/index.html. The Java API documentation is then located at http://localhost/MQWFDoc/javaapi/index.html.

Generic installation instructions

Installing over the previous version of the Web Client

If you already have the previous version of the Web Client installed on your machine, and are installing the new version in the same location, you only need to check step 3 of the installation instructions below. The servlet settings are now defined in the WebClient.properties (formerly Servlet.properties). You may also want to check the change log before you continue.

Installation steps

Setup for IBM WebSphere Application Server V3.0.2/V3.5

Installing over the previous version of the Web Client

If you already have the previous version of the Web Client installed on your machine, and you are installing the Web Client in the same location as the previous version, you only need to do the following:

In addition, it may be necessary to clean up the compiled JSP files from the previous version. Go to the <WASDir>/temp/default_host/MQWFClient directory and delete all files and subdirectories in it.

You may also want to check the change log before you continue.

Otherwise, go to Installation using the XML configuration GUI or Manual installation.

Installation using the XML configuration GUI for IBM WebSphere Application Server V3.0.2/V3.5

The Web Client contains a configuration GUI to be used with the XML configuration technology preview of WebSphere Application Server V3.0.2 and the XML configuration technology of WebSphere Application Server V3.5.

  1. Make sure you installed the Web Client in the <MQWFDir>/WebClient directory, because the skeleton files which will be filled in and imported into WebSphere depend on that name. If you chose another name, please follow the instructions for manual installation below.
  2. Edit the <MQWFDir>\WebClient\was3cfg.bat (for Windows) or <MQWFDir>/WebClient/was3cfg.sh (for Unix platforms) file and make the adaptations for your environment as documented in that file.
  3. Make sure the current directory is <MQWFDir>/WebClient, and the WebSphere Administration Server is running, before you run the script.
  4. In the dialog that appears, enter the directories where MQSeries Workflow and MQSeries are installed. Then, enter the MQSeries Workflow subdirectory of the version of the Java API you want to use. Last, select the MQSeries Workflow configuration to be used by the Web Client.
  5. Make sure the correct version of the XML skeleton file is listed in the 'Skeleton file' field. There are different skeleton files for WebSphere releases up to V3.0.2 fix pack 1, for WebSphere V3.0.2 fix pack 2, and for WebSphere V3.5 and subsequent release levels.
  6. In the field 'Web Application node', enter the name of the node, where you wish to install the Web Client exactly as it appears in the 'Topology' pane of the WebSphere Adminstrative Console. Finally, select 'Configure'.
  7. After the configuration utility has finished, click 'Refresh' on the Web Application node in the 'Topology' pane of the WebSphere Administrative Console to see the new 'MQSeries Workflow WebClient' Application Server.
  8. Finally, select the 'MQSeries Workflow WebClient' server from the Topology Tree and click the green Start Button.

Note that there is a problem on AIX with setting the LIBPATH variable for the 'MQSeries Workflow WebClient' Application Server in the WebSphere Administrative Console. If you try this, you will get an error message like:

java.lang.UnsatisfiedLinkError: Can't find library libfmcojprf.so in LIBPATH
LIBPATH=/usr/jdk_base/lib/aix/native_threads:...TH=/usr/lpp/fmc/lib:$LIBPATH:TH=/usr/jdk_base/lib/aix/native_threads:...
at java.lang.Runtime.loadLibrary(Compiled Code)
:
When using WebSphere V3.0.2, the workaround for this problem is setting export LIBPATH=/usr/lpp/fmc/lib:$LIBPATH on the command line before starting the WebSphere Application Server. For WebSphere V3.5, you must set LD_LIBRARY_PATH instead of LIBPATH. Note that the XML configuration GUI neither sets LIBPATH nor LD_LIBRARY_PATH on AIX. You have to do this manually.

Manual installation for IBM WebSphere Application Server V3.0.2/V3.5

If you cannot use the XML configuration, follow these instructions instead:

  1. Make sure the WebSphere Administration Server is running on your server machine.
  2. Open the WebSphere Administrator's Console.
  3. WebSphere V3.0.2: Select the Tasks tab.
    WebSphere V3.5: In the Administrator's Console menu select 'Console' then 'Tasks' and finally 'Create Application Server'.
    1. WebSphere V3.0.2: In the 'Configuration' branch of the tasks tree, click 'Configure an application server'.
    2. WebSphere V3.0.2: Click the green start button.
    3. WebSphere V3.0.2: In the resource types dialog, choose the following:
      WebSphere V3.5: In the Create Application Server Wizard, choose the following:
      • Uncheck 'Enterprise Beans' (not available in the standard edition).
      • Check 'Web Applications'.
    4. Click 'Next'.
    5. In 'Application Server Properties' - 'General' enter the following:
      • Application Server Name: MQSeries Workflow WebClient
      • Windows NT: Command line arguments: add -classpath <MQWFDir>\WebClient\fmcohcli.jar;<MQWFDir>\bin\java<VRMS>\fmcojagt.jar
      • Unix platforms: Command line arguments: add -classpath <MQWFDir>/WebClient/fmcohcli.jar:<MQWFDir>/bin/java<VRMS>/fmcojagt.jar
      • Windows NT: Click the 'Environment...' field
        • Add PATH=<MQWFDir>\bin;<MQWFDir>\bin\mqserver;<MQSeriesDir>\bin;
        • Add LOCPATH=<MQWFDir>\bin\locale
        • Add NLSPATH=<MQWFDir>\bin\%N
        • Click OK.
    6. Click 'Next'.
    7. In the Start server dialog, check 'Do not start the server automatically after creating it'.
    8. Click 'Next'.
    9. In the 'Nodes' dialog, open the tree and select your hostname as node.
    10. Click 'Next'.
    11. In the 'Virtual Hosts' dialog, open the tree and select 'default_host'.
    12. Click 'Next'.
    13. In the servlet engine 'General' dialog, enter:
      • Servlet Engine Name: 'Servlet Container'
    14. Click 'Next'.
    15. In the Web application 'General' dialog, enter the following:
      • Web Application Name: 'MQWFClient'
      • Virtual Host: 'default_host'
      • Web Application Path: '/MQWFClient'
    16. In the Web application 'Advanced' dialog, choose the following:
      • Enter DocumentRoot: '<MQWFDir>\WebClient\webpages'.
      • Delete the predefined Classpath from the listbox.
    17. Click 'Next'.
    18. In the servlet/JSP dialog, choose the following:
      • Check 'Enable File Servlet'.
      • Uncheck 'Serve Servlets by Classname'.
      • Select 'Enable JSP 1.0'.
    19. Click 'Finished'.
  4. Select the Topology tab.
    1. Open the tree and locate the 'MQSeries Workflow WebClient' Server.
    2. Open the server node and then the 'Servlet Container' branch of the tree.
    3. Right-click and hold the mouse button on the 'MQWFClient' Web application and select 'Create' - 'Servlet'.
    4. In 'Create Servlet' - 'General', enter the following:
      • Servlet Name: 'Main'
      • Web Application: 'MQWFClient'
      • Servlet Class Name: 'com.ibm.workflow.servlet.client.Main'
      • In the 'Servlet Web Path List' select the 'Add' button.
        • Enter the following Servlet Path: '/MQWFClient/servlet/Main'
        • Click 'OK'.
    5. In 'Create Servlet' - 'Advanced', choose the 'Init Parameters' list box and enter:
      • ConfigurationFile: <MQWFDir>/WebClient/WebClient.properties
        (this is optional)
    6. On the same page set 'Load at Startup:' to 'False'.
    7. Click 'Create'.
    8. Select the 'MQSeries Workflow WebClient' server from the Topology Tree and click the green Start Button.

Setup for IBM WebSphere Application Server for OS/390 Version 3.5

Before installing WebSphere Application Server V3.5, complete your HTTP Server installation and customization (see the documentation IBM HTTP Server for OS/390 Planning, Installing, and Using Version 5.2, SC31-8690-04, or IBM HTTP Server for OS/390 Planning, Installing, and Using Version 5.3, SC31-8690-05).
It is recommended that you first customize and start the IBM HTTP Server without WebSphere Application Server to make sure that you can successfully serve HTML pages before you start customizing WebSphere Application Server.

It is recommended that you install the most recent available PTFs for Java, IBM HTTP Server and IBM WebSphere Application Server.

Before installing the Web Client, make sure that the MQSeries Workflow environment is correctly installed, where the MQSeries Workflow Java API support can be exploited from the OS/390 Unix System Services.

Optionally, create your own HFS file system for MQSeries Workflow and mount it for example on /usr/lpp/fmc (see also the IBM MQSeries Workflow for z/OS Customization and Administration - Customize the Web Client).

It is assumed that MQSeries Workflow Java API support is installed as follows: It is assumed that the IBM HTTP Server and IBM WebSphere Application Server V3.5 for OS/390 have been successfully installed, the Application Server installation has been verified. For details on the WebSphere Application Server Customization see the documentation WebSphere Application Server for OS/390 - Planning, Installing and Using, Version 3.5, GC34-4835.


Note: Throughout this installation and customization description the following placeholders are used:

<CustHLQ> refers to the qualifier that has been used during the installation of MQSeries Workflow (MQSeries Workflow for z/OS Customization and Administration)

<MQWFDir> is the directory where MQSeries Workflow has been installed, e.g. /usr/lpp/fmc

<MQWFCfgDir> is the directory specified (to the fmczwcfg shell script; see below) as configuration root directory

<applicationserver_root> is the name of the mounted install-image of an individual execution system of IBM WebSphere Application Server. The default applicationserver_root is /usr/lpp/WebSphere

Installation

All files belonging to Web Client should already be available on your system if you followed the instructions, given in IBM MQSeries Workflow for z/OS Customization and Administration - Customize the Web Client).

Shell script fmczwcfg

In <MQWFDir>/bin you will find a shell script named fmczwcfg. If necessary, execute command chmod a+x fmczwcfg against it.

Either edit the script and make adaptations to the "customization area" to specify user IDs and directories, or specify the appropriate values as invocation parameters (fmczwcfg -help gives a list of the supported parameters).

Customization

To configure the Web Client follow the steps below:

Process Monitor

Note that Java AWT which is used to create the process monitor images requires the DISPLAY variable to be set. This variable must point to an X11 server, preferably (for performance reasons) the local host.

This variable can be set in the httpd.envvars configuration file.

Diagnostic messages (optional)

For additional diagnostic messages, you can set various trace settings in was.conf:

appserver.loglevel=
objectleveltrace.enabled=true

For details on these settings, refer to the was.conf template file, or to the WebSphere Application Server Planning, Installing, and Using documentation.

Error prevention (optional)

Servlets are inherently multi-threaded, which means that you have to make sure that the Unix System Services and the MQSeries Queue Manager are configured properly to support a high number of threads. (See below for BPXPRMxx).

If you encounter errors, such as, "java.lang.OutOfMemoryError: cannot create any more threads", possible fixes are:

If errors in MQSeries occur, such as Reason code=2025, (which means MQRC_MAX_CONNS_LIMIT_REACHED, Maximum number of connections reached), this suggests that the MQCONN or MQCONNX call was rejected, because the maximum number of concurrent connections was exceeded. On OS/390, connection limits are applicable only to TSO and batch requests. The limits are determined by the customer using the following parameters of the CSQ6SYSP macro:

Corrective Action: Increase the size of the appropriate install parameter value or reduce the number of concurrent connections.

Performance (optional)

To improve performance, you can enable the JIT compiler in appserver.jvmpropertiesfile (defined in was.conf) by setting appserver.product.java.jvmconfig.jit=on. Problems can occur with the JIT compiler, therefore, check a new application without the JIT compiler first.

Also refer to the topic "Performance Hints and Tips" in The WebSphere Troubleshooter for OS/390 on the Web.

Additional information


© Copyright IBM Corporation 1999, 2001. All Rights Reserved.