Installation Guide and Release Notes

April 2006

 

This document contains information that will help you install and use this release of WSIT for OpenVMS.

 

 

 

 

 

 

 

 

 

Software Version
Web Services Integration Toolkit Version 1.1

 

 

 

Hewlett-Packard Company
Palo Alto, Calif.

 

Intel, Intel Inside, and Itanium are trademarks of Intel Corporation in the U.S. and/or other countries.

 

Microsoft, Windows, Windows XP, Visual Basic, Visual C++, and Win32 are trademarks of Microsoft Corporation in the U.S. and/or other countries.

 

Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

 

All other product names mentioned herein may be trademarks of their respective companies.

 

Confidential computer software. Valid license from HP and/or its subsidiaries required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license.

 

Neither HP nor any of its subsidiaries shall be liable for technical or editorial errors or omissions contained herein. The information in this document is provided “as is” without warranty of any kind and is subject to change without notice. The warranties for HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

 

1.     REQUIREMENTS

                 1.1 Hardware Requirements

                 1.2 Software Installation, Development, and Runtime Requirements

 

 

2. INSTALLATION

 

                 2.1  Installing the Web Services Integration Toolkit for OpenVMS

                 2.2 After Installing the Web Services Integration Toolkit for OpenVMS

                 2.3 Starting and Stopping the Web Services Integration Toolkit

                 2.4 Uninstalling the Web Services Integration Toolkit

                 2.5 Web Services Integration Toolkit Directory Structure

                 2.6 Performance Recommendations

 

 

3. RELEASE NOTES

 

                3.1  Large STDL File Problem on OpenVMS Alpha
                3.2  Copy WSIRTL.JAR to Server Classpath and Restart Server (If Required)           
                3.3 Support for Web Services Integration Toolkit Version 1.1                

                3.4 Tools and Files Renamed in Field Test Kit

 

4. CONTACT AND SUPPORT INFORMATION

 

APPENDIX

 

                 A.  Sample FTP File Transfer

                 B.  Sample OpenVMS Installation Log
                 C.  Directories and Files in the Web Services Integration Toolkit

 

About Web Services Integration Toolkit for OpenVMS Documentation

This Installation Guide and Release Notes includes system requirements and installation instructions for OpenVMS, as well as release notes for the current release of the Web Services Integration Toolkit for OpenVMS.

 

The Developer’s Guide contains information about how to use the tools in the Web Services Integration Toolkit for OpenVMS, and things to consider as you prepare your legacy application.

 

For the latest release information, refer to the Web Services Toolkit for OpenVMS web site at http://www.hp.com/products/openvms/webservices/. 

 

The Web Services Integration Toolkit-generated server component is a native OpenVMS image installed on the system running the wrapped application.  The generated source code must be built on the OpenVMS system that hosts the application using command-line driven development tools. 

1.1        Hardware Requirements

The Web Services Toolkit for OpenVMS is available on OpenVMS I64 and OpenVMS Alpha.

 

The Web Services Toolkit for OpenVMS I64 EXE file requires approximately 55,500 blocks of disk space. Expanding the EXE file requires an additional 80,000 blocks.

 

The Web Services Toolkit for OpenVMS Alpha EXE file requires approximately 33,000 blocks of disk space. Expanding the EXE file requires an additional 35,000 blocks.

 

1.2         Software Installation, Development, and Runtime Requirements

Following are the minimum system requirements needed to install the Web Services Integration Toolkit and to build and run the generated components. Optional requirements represent requirements that are not needed for every type of application. However, several such requirements will apply to your particular platform/component selection.

 

Make sure you have the latest MUPs, ECOs, and patches for your configuration. Search for these on the Patch Download page at:

http://www2.itrc.hp.com/service/patch/mainPage.do

 

Always Check Cross-Product Requirements!

Always check for cross-product software requirements, which can change with new releases. These product requirements may be greater than for the Web Services Integration Toolkit itself.

 

For example, to run a Web Services Integration Toolkit-generated JavaBean component requires OpenVMS Version 8.2 or higher and a Java 2 Runtime Environment 1.4.2-1 or higher. Each Java SDK and RTE has specific ECO requirements. 

 

Installation Requirements

 

·         OpenVMS I64 Version 8.2 or higher  - or -

·         OpenVMS Alpha Version 7.3-2 or higher

·         ODS-5 disk

 

Development Requirements

 

The C Compiler is required to build all server components.

 

·         HP C Version 6.5 or higher for OpenVMS

·         HP C++ Version 6.5 or higher for OpenVMS

·         Java 2 SDK (“JDK”) Standard Edition 1.4.2-1 or higher

Java Technology for OpenVMS Download Page  
http://h18012.www1.hp.com/java/download/

Runtime Requirements

·         Java 2 RTE (JRE) Standard Edition 1.4.2-1 or higher

Java Technology for OpenVMS Download Page  
http://h18012.www1.hp.com/java/download/

·         Java Software Patches (ECOs) (if required)

Java Technology for OpenVMS v 1.4.2 Software Patch Page
            http://h18010.www1.hp.com/java/download/ovms/1.4.2/sdk1.4.2_patches.html

Out-of-Process Account Preparation and Requirements

If you are specifying an account in which to run out-of-process servers, you may want the account to have a minimal amount of privileges. 

 

You can specify an account to run out-of-process servers that has only the NETMBX and TMPMBX privileges.  To use an account with these privileges, perform the following steps:

 

1.       Create an identifier within the system UAF with the name WSI$SERVER.  (Perform this step one time only.)

2.       Grant the WSI$SERVER identifier to each account used to run a WSIT out-of-process server.

 

If you do not perform these steps, the privileges required by the account are as follows:

BYPASS

SYSNAM

SYSPRV

IMPERSONATE

DETACH

TMPMBX 

 

Installation involves installing and then starting the Web Services Integration Toolkit on OpenVMS.

 

2.1        Installing the Web Services Integration Toolkit for OpenVMS

Before You Begin

§         Log into the SYSTEM account.

§         If you have previously installed a field test version of the Web Services Toolkit, make sure the Web Services Toolkit is shut down by entering this command from the SYSTEM account:

      $ @SYS$STARTUP:WSI$SHUTDOWN.COM

§         HP recommends that you perform a system disk backup before proceeding.

Web Download Instructions

1.       Save the Web Services Toolkit self-extracting archive (WSIT-V0101-I64.EXE or WSIT-V0101-AXP.EXE) to a temporary location by choosing the option to save the program to your disk.

2.       If you are downloading to a Windows machine, move the downloaded file to your OpenVMS machine using either a shared network drive or FTP.  (See Appendix A: Sample FTP File Transfer.)

Installation Instructions

1.          Expand the Web Services Integration Toolkit compressed EXE file by entering one of the following command, depending on the platform on which you are installing the kit:

$ RUN WSIT-V0101-I64.EXE ! for OpenVMS I64
      $ RUN WSIT-V0101-AXP.EXE ! for OpenVMS Alpha

      The EXE file contains the file HP-IA64VMS-WSIT-V0101--1.PCSI$COMPRESSED
       (for OpenVMS I64) or HP-AXPVMS-WSIT-V0101--1.PCSI$COMPRESSED
       (for OpenVMS Alpha) and the WSIT documentation.

    2. Start the utility that installs the Web Services Toolkit component, by entering the following command.  (PCSI installs the
            PCSI$COMPRESSED file directly; you do not need to expand it.)

 

         $ PRODUCT INSTALL WSIT /DESTINATION=ods5disk:[directory]

              The Web Services Toolkit requires a destination directory to be specified on the PCSI install 
              command line. This location is used as the root directory for the WSIT product.
              The destination directory must be an ODS5 volume.

     3. Follow the on-screen installation instructions. (See Appendix B: Sample OpenVMS Installation Log.)

             To proceed with a default installation, press Enter/Return in response to any other installation
             questions.

2.2        After Installing the Web Services Integration Toolkit for OpenVMS

HP recommends that you restart J2EE environments, such as BEA WebLogic Server, or other Bean servers, such as Tomcat, after a Web Services Toolkit installation.  Such environments may not automatically refresh shareable images and libraries without being restarted.

1.       Modify your system startup command procedure (SYS$MANAGER:SYSTARTUP_VMS.COM) to include the Web Services Toolkit startup command:

@SYS$STARTUP:WSI$STARTUP.COM

2.       Modify your system shutdown command procedure (SYS$MANAGER:SYSHUTDWN.COM)  to include the Web Services Toolkit shutdown command:

@SYS$STARTUP:WSI$SHUTDOWN.COM

3.    Finally, start the Web Services Integration Toolkit with this command:

   $ @SYS$STARTUP:WSI$STARTUP.COM

This completes the Web Services Integration Toolkit for OpenVMS installation.

Note:  If you opt not to use the SYSTEM account
The Web Services Toolkit startup procedure must still be run every time your system starts. It can be run as part of your system startup or in another account.

Important: You are recommended to use the SYSTEM account. However, the account in which you run the Web Services Toolkit must have, minimally, the following authorized account privileges:

BYPASS
SYSPRV
TMPMBX
SYSNAM
CMKRNL
DETACH
LOG_IO

2.3        Starting and Stopping the Web Services Integration Toolkit for OpenVMS

Starting the Web Services Integration Toolkit

Use the following command to start the Web Services Integration Toolkit:

$ @SYS$STARTUP:WSI$STARTUP.COM

Stopping the Web Services Integration Toolkit

Stopping the Web Services Integration Toolkit requires the same privileges as starting it. Ensure that all client connections have been closed.

1.       Log into the SYSTEM account.

2.       Use the following command to stop the Web Services Integration Toolkit:

$ @SYS$STARTUP:WSI$SHUTDOWN.COM

2.4       Uninstalling the Web Services Integration Toolkit

To remove the Web Services Toolkit for OpenVMS from your system, enter the following command:

 

$ PRODUCT REMOVE WSIT

2.5        Web Services Integration Toolkit Directory Structure

After you install the Web Services Integration Toolkit, browse the WSIT directories to see the location of the tools and sample programs.  Appendix C contains a listing of all of the directories and files in the Web Services Integration Toolkit.

 

2.5.1        WSIT Root Directory

 

The root directory is represented by the logical WSI$ROOT. This logical is created when the WSI$STARTUP.COM procedure is executed.

 

$ dir wsi$root:[000000]

 

Directory wsi$root:[000000]

 

Apache_Software_License_V1_1.txt;1      Apache_Software_License_V2_0.txt;1

deploy.dir;1        docs.dir;1          lib.dir;1           samples.dir;1

src.dir;1           tools.dir;1         wsi-version.txt;1

Total of 7 files.

$

 

2.5.2        Deploy Subdirectory

 

The Deploy subdirectory contains the shareable image for the application’s server wrapper. The generated JavaBean calls the server wrapper’s shareable image at runtime.

 

2.5.3        Docs Subdirectory

 

The Docs directory contains Web Services Integration Toolkit documentation.

 

2.5.4 LIB Subdirectory

 

The LIB subdirectory is where the Web Services Integration Toolkit stores the files it uses internally; for example, Velocity template files.

 

2.5.5        Samples Subdirectory

 

The Samples subdirectory contains example programs.  This kit includes sample applications written in ACMS, C, COBOL, and FORTRAN.

 

The .C, .CBL and .FOR programs are the wrappers for the original application. The .JAVA files illustrate calling the WSIT-generated JavaBean for each wrapper. See the Developer’s Guide Appendix for the source files of the C sample.

 

2.5.6        Tools Subdirectory

 

The tools in this directory are used to develop code that wraps 3GL applications.

 

2.5.7        Source Subdirectory

 

The source subdirectory contains objects and classes used by the generated code, including Java exceptions and holder classes.  The files in this subdirectory are provided for your reference.

 

2.6        Performance Recommendations

2.6.1     Operating System Requirements

Increase the PRCLM quota to be high enough to run the maximum number of expected concurrent servers.

2.6.2     Java Requirements

The Java runtime environment was designed to perform optimally on UNIX systems, where each process is given large quotas by default. On OpenVMS, the default behavior gives each process lower quotas so that many processes can co-exist on a system.  To get the best Java performance on OpenVMS, you are recommended to set process quotas to match a typical UNIX system. These are also the recommended minimum quota settings (except where noted).

These are the recommended J2SDK for OpenVMS quotas:

UAF Fillm Channelcnt Wsdef   Wsquota Wsextent and Wsmax Pgfilquo bytlm biolm diolm tqelm

4096 4096 2048 4096 16384 2,097,152* 2,000,000 150 150 100

*A good number for Pgflquo is (2 x heap-size), for example, 128 MB (2*128*1024*1024)/512 = 524288. Recall that the recommended minimum Pgflquo is 96 MB when using the RTE. When you increase the Pgflquo parameter, you should always increase the system's page file size to accommodate the new Pgflquo parameter, if needed.

Note:  If you receive a WSIConnectException without a specific message attached to it, the most likely cause is a value for bytlm that is too low. HP recommends that you set this value to at least 2,000,000. 

There are many other optimizations you can make to your Java environment to improve performance, such as setting the compacting garbage collector with the Fast VM.

-Xgc:compacting

This will benefit some but not all Java applications. All such optimizations should be tested in a systematic fashion. You can try out the techniques and tips available from the following source.

Guide to Optimizing Java on OpenVMS
http://h71000.www7.hp.com/ebusiness/OptimizingSDKGuide/OptimizingSDKGuide.html

3.1        Large STDL File Problem on OpenVMS Alpha

In rare cases, when you attempt to import a very large STDL file using the stdl2idl utility on an OpenVMS Alpha system, the generated WSIT IDL file will not contain a valid application definition.  HP believes this is a resource problem.  (This does not seem to occur on OpenVMS I64 systems.)

If you encounter this problem, you can work around it by doing the following:

 

1.       Delete all WSIT generated temporary files from your SYS$LOGIN directory.  These files have names similar to WSI$IMPORT*.*, and BWX_*.TMP.

2.       Create a file in your SYS$LOGIN directory called WSI$IMPORT_TMP.LIS. This file will have a single line which is the name of the STDL file that you want to import.

$ CREATE WSI$IMPORT_TMP.LIS
MYSTDLFILE.STDL
^z
$

3.       Set default back to the directory containing the STDL file that you want to import, and run the stdl2idl tool.

 

3.2        Copy WSIRTL.JAR to Server Classpath and Restart Server (If Required)

If you plan to call a Web Services Integration Toolkit application from a web server or application server, the file wsi$root:[lib]wsirtl.jar must be in the server’s classpath.  The details on how to configure the server to include this jar file are specific to each server.

 

For example, if you are using CSWS_JAVA for OpenVMS (Apache Tomcat), you should copy the file wsi$root:[lib]wsirtl.jar to the common/lib directory.  To ensure that the server becomes aware of the file, a restart if often required.  However, this is also server specific.

3.3        Support for Web Services Integration Toolkit Version 1.1

Support for Version 1.1 of the Web Services Integration Toolkit is provided by HP Support. If you want to send technical feedback or comments to the Web Services for OpenVMS engineering team, please send mail to OpenVMS.WebServices@hp.com.

3.4        Tools and Files Renamed in Field Test Kit

The following tools and files were renamed in a pre-Version 1.0 field test kit, as shown in the following table.  The names used in Version 1.1 are in the New Name column.

 

Directory	Old Name	New Name
[wsit.tools]	idlgen.exe	obj2idl.jar
[wsit.tools]	wsigen.jar	idl2code.jar
[wsit.tools]	validateIDL.jar	validate.jar
[wsit.tools]	wsi$setenv.com	wsi-setenv.com
[wsit.tools]	OpenVMSbasetypes.xml	openvms-basetypes.xml
[wsit.tools.templates.javabean]	structure_java.vm	structure-java.vm
[wsit.tools.templates.javabean]	viewname_java.vm	interface-appname-java.vm
[wsit.tools.templates.javabean]	build_jb_com.vm	build-appname-jb-com.vm
[wsit.tools.templates.javabean]	viewnameImpl_java.vm	appname-impl-java.vm
[wsit.tools.templates.serverwrapper]	build_server_com.	build-appname-server-com.vm
[wsit.tools.templates.serverwrapper]	conn-name_opt.vm	appname-opt.vm
[wsit.tools.templates.serverwrapper]	conn-name_server_c.	appname-server-c.vm
[wsit.tools.templates.serverwrapper]	conn-name_server_h.	appname-server-h.vm
[wsit.tools.templates.serverwrapper]	conn-name_wsi.	appname-wsi.vm
[wsit.tools.templates.serverwrapper]	methIDs_h.vm	methIds-h.vm
[wsit.tools.templates.serverwrapper]	structkeys_h.vm	structkeys-h.vm
[wsit.deploy]	wsi$default.wsi	wsi-default.wsi

 

 

For OpenVMS Alpha

·         Support for customer release versions of the Web Services Integration Toolkit for OpenVMS is provided by HP under OpenVMS Alpha service agreements through standard support channels.

·         Download is an official distribution mechanism for the Web Services Integration Toolkit, including updates in addition to the OpenVMS Alpha media kit.

·         Source code kits are provided in the spirit of the open source community, but are not supported by HP.

For OpenVMS on Integrity Servers

·         Support for customer release versions of the Web Services Integration Toolkit for OpenVMS is provided by HP under OpenVMS I64 Foundation Operating Environment (FOE) service agreements through standard support channels.

·         Download is a courtesy distribution mechanism for the Web Services Integration Toolkit for OpenVMS. Kits or updates other than security patch kits obtained via download are unsupported.

·         The OpenVMS I64 Operating Environments media kit is the official distribution mechanism for the Web Services Integration Toolkit for OpenVMS. Supported kits and updates must be obtained from this mechanism or from software product update services.

A variety of service options are available from HP Support. For more information, contact your local HP account representative or distributor. Information is also available from Software Support Services.

You can informally exchange information with other users in the OpenVMS newsgroup comp.os.vms.

If you would like to provide comments about the Web Services Integration Toolkit for OpenVMS, please send mail to:

OpenVMS.WebServices@hp.com

If you would like to provide comments or general feedback about the e-Business offerings on OpenVMS, please send mail to:

OpenVMS.eBusiness@hp.com

Web Services Toolkit Home Page

http://www.hp.com/openvms/products/webservices/

A        Sample FTP File Transfer

If you downloaded the Web Services Integration Toolkit compressed EXE file to a Windows system, use commands similar to the following to move the kit to your OpenVMS system using command-line FTP (with user input in angle brackets):

C:\>cd temp

C:\TEMP>ftp <your.server.name.com>

Connected to your.server.name.com.

220 your.server.name.com FTP Server (Version 5.0) Ready.

User (your.server.name.com:(none)): <user>

331 Username Yourname requires a Password

Password: <password>

230 User logged in.

ftp> binary

200 TYPE set to IMAGE.

ftp> <put WSIT-V0101-I64.EXE>

200 PORT command successful.

150 Opening data connection for disk:[user]WSIT-V0101-I64.EXE; (16.28.0.58,4460)

226 Transfer complete.

335713 bytes sent in 0.40 seconds (837.19 Kbytes/sec)

ftp> <bye>

221 Goodbye.

C:\TEMP>

      

B        Sample OpenVMS Installation Log  (on OpenVMS I64)

Step 1: Extract the Kit

$ RUN WSIT-V0101-I64.EXE

UnZipSFX 5.51 of 22 May 2004, by Info-ZIP (http://www.info-zip.org).

  inflating: HP-IA64VMS-WSIT-V0101--1.PCSI$COMPRESSED

$

Step 2:  Run PCSI (POLYCenter Software Installation) Utility

$ PRODUCT INSTALL WSIT/source=dka100:[products.kits] /dest=dka100:[products]

The following product has been selected:

    HP IA64VMS WSIT V1.1                   Layered Product

 

Do you want to continue? [YES]

Configuration phase starting ...

 

You will be asked to choose options, if any, for each selected product and for

any products that may be installed to satisfy software dependency requirements.

 

HP IA64VMS WSIT V1.1: Web Services Integration Toolkit (WSIT) V1.1 for OpenVMS

    (C) 2005 Hewlett-Packard Development Company, L.P.

 

Do you want the defaults for all options? [YES]

Do you want to review the options? [NO]

Execution phase starting ...

 

The following product will be installed to destination:

    HP IA64VMS WSIT V1.1                   ODS5:[WSIT]

 

Portion done: 0%...20%...30%...40%...50%...60%...90%

***************************************************************

 

 Insert the following lines at the end of SYS$MANAGER:SYSTARTUP_VMS.COM:

@sys$startup:wsi$startup.com

 

 Insert the following lines in SYS$MANAGER:SYSHUTDWN.COM:

@sys$startup:wsi$shutdown.com

 

***************************************************************

 

  WSIT has detected that CSWS_JAVA (Apache Tomcat) is installed on this system.

  Some WSIT samples require WSIT runtime files to be in the common/lib directory.

 

  May this installation procedure copy the WSIT runtime to Tomcat?

 

Enter N to skip copying WSIT runtime to Tomcat : Y

...100%-COPIED, WSI$ROOT:[lib]wsirtl.jar;1 copied to SYS$COMMON:[APACHE.JAKARTA.TOMCAT.COMMON.LIB]wsirtl.jar;16 (209 blocks)

 

The following product has been installed:

    HP IA64VMS WSIT V1.1                   Layered Product

C        Directories and Files in the Web Services Integration Toolkit

$ set def wsi$root:[000000]
$ dir wsi$root:[000000…]