Web Services Integration Toolkit for OpenVMS

Web Services Integration Toolkit for OpenVMS

Developer’s Guide

April 2008

This document contains information that will help you use the development tools in this release of WSIT for OpenVMS.

Software Version

Web Services Integration Toolkit
Version 3.0 Field Test

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.

C O N T E N T S

INTRODUCTORY INFORMATION – FOR ALL USERS

1. USING THE WEB SERVICES INTEGRATION TOOLKIT FOR OPENVMS

1.1 Overview

1.2 Preparing the Original (Legacy) Application

1.3 Exposing an OpenVMS 3GL Application: Typical Development Steps

1.4 Wrapping a 3GL Application: C Sample

1.4.1 Server/Application Build Procedure

1.4.2 Customizing the Build Environment

1.5 Wrapping an ACMS Application: ACMS Sample

1.6 Generating Sample Clients

1.7 Using ANT with the Web Services Integration Toolkit

1.7.1 Ant Setup

1.7.2 Configuring the wsit-ant-user.properties File

1.7.3 Using the wsit-ant-userbuild.xml Build File

1.7.4 Ant Property Descriptions

1.7.5 Ant Target Descriptions

1.7.6 Custom Ant Tasks

1.8 Using Distributed NetBeans with the Web Services Integration Toolkit

1.8.1 WSIT Build Templates

1.8.2 Using the WSIT-Supplied Ant Version

1.9 Security Considerations

1.9.1 Server Process Security

1.9.2 Per User Security

1.10 WSIT Tools and Parameters

1.10.1 In-Process/Out-of-Process Parameters

1.10.2 POJO/JSP Sample Client Parameters

1.11 OBJ2JAVA.COM

2. DEPLOYMENT CONSIDERATIONS

2.1 Types of OpenVMS Applications

2.2 In-Process Deployment

2.3 Out-of-Process Deployment

2.3.1 Sessions

2.3.2 Application Reusability

2.3.3 Using Multiple Processes to Scale Applications

2.3.4 Specifying Out-of-Process Deployment Options

2.3.4.1 Out-of-Process Account Preparation and Requirements

2.4 Web Services Integration Toolkit Interfaces

2.4.1 Application Interfaces (User Supplied)

2.4.2 OpenVMS Datatypes Supported by WSIT

2.4.3 Passing Mechanisms

2.4.4 JavaBean Interface (Generated by WSIT)

2.4.5 Datatype Mapping

2.4.5.1 String Datatype

2.4.6 Parameter Usages

2.5 Design Restrictions for Wrapped Applications
2.5.1 Stack Size Not Automatically Increased Based on Demand
2.5.2 Bit Data Types

2.5.3 Pointer Types Not Supported

2.5.4 Single Instantiated WSIT JavaBean Cannot Be Shared Among Multiple Threads

2.5.5 Languages Tested with the OBJ2IDL Tool

2.5.6 Tips and Hints for Supported Languages
2.5.7 Tips and Hints for OpenVMS Alpha Users

2.5.8 Programming with Nested Structures

ADVANCED INFORMATION – FOR EXPERIENCED USERS

3. ADVANCED OUT-OF-PROCESS CONFIGURATION

3.1 Case A: Not Reusable

3.2 Case B: Sequentially Reusable

3.3 Case C: Concurrently Reusable

3.4 Case D: Concurrently Reusable with Multiple Threads

3.5 Single Threaded Applications –- Automatic Stack Expansion

3.6   Example: Using the Debugger
3.7   Generating Tracing for Application Interface
3.8   Creating a Log File

4. MAPPING BLOBS AND OTHER UNFORMATTED DATA

5. USING TEMPLATES TO GENERATE CODE

5.1 Modifying Velocity Templates

5.2 Generating Code with IDL2CODE.JAR

5.3 Example 1: Writing a New Template

5.4 Example 2: Modifying an Existing Template
5.5 Example 3: Generating Helper Routines for the Original Application

6. MODIFYING IDL FILES

6.1 OpenVMS Interface Block

6.2 Enumeration Block

6.3 Enumerator Block

6.4 Typedef Block

6.5 Primitive Block

6.6 Structure Block

6.7 Field Block

6.7.1 Field Array Tag

6.8 Routine Block

6.9 Parameter Block

6.9.1 Parameter Array Tag

6.10 Example WSIT IDL File

APPENDIX

A. Program Listing - STOCK.C

B. Program Listing - STOCK.XML

C. Program Listing - StockCaller.Java

D. Program Listing - MATH.C

E. Program Listing - MATH.XML

F. Program Listing - mathcaller.java

About Web Services Integration Toolkit for OpenVMS Documentation

This 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.

The 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.

For the latest release information, refer to the Web Services Toolkit for OpenVMS web site at

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

1 U S I N G W E B S E R V I C E S I N T E G R A T I O N T O O L K I T

1.1 Overview

The Web Service Integration Toolkit for OpenVMS (WSIT) contains a collection of integration tools. These tools are easy to use, highly extensible, based on standards and built on open source technology. The toolkit can be used to call OpenVMS applications written in 3GL languages, such as C, BASIC, COBOL, FORTRAN, and ACMS from newer technologies and languages such as Java, Microsoft .NET, Java -RMI, JMS, and web services.

The Web Service Integration Toolkit is focused on integrating at the API level. It generates a JavaBean wrapper for a supplied OpenVMS application interface (API). At runtime, you can specify if the application will be run in the process of the caller (in-process) or in separate processes (out-of-process) managed by the WSIT runtime.

1.2 Preparing the Original (Legacy) Application

Using the Web Services Integration Toolkit for OpenVMS, as with all programmatic integration, requires some upfront development work before you can begin performing the integration. Your existing application is likely to have been written long ago and will benefit from having a wrapper expose a new and clean interface. The new interface will expose the legacy implementation. Separating the interface from the implementation provides encapsulation and the ability to easily extend and reuse the implementation.

Before you use the Web Services Integration Toolkit or any other integration technology, you must evaluate the original application and design one or more interface classes to expose different features of the business logic. These new interfaces should be tested with a simple client before you use the Web Services Integration Toolkit. When you know that the interface classes are working properly, you can use WSIT to extend the use of the new interface to the Java environment.

After you have prepared the application, WSIT can extend the features of the new interface to Java as shown in the following diagram.

1.3 Exposing an OpenVMS 3GL Application: Typical Development Steps

Following are the development steps required to use the Web Services Integration Toolkit to expose an OpenVMS 3GL or ACMS application. Note that these steps are only required for the development phase. It is expected that the application has been prepared as discussed in the previous section.

Note: These tools were renamed in a pre-V1.0 field test kit. See Chapter 3 in the Installation Guide and Release Notes for a table containing the old and new file names.

1. Create XML IDL file (on I64)

Create an XML interface definition file (IDL) that describes the interface to be exposed. You create an XML IDL file using the tool named OBJ2IDL.EXE (for 3GL languages) or STDL2IDL.JAR (for ACMS). Note: OBJ2IDL.EXE runs on OpenVMS I64 only. If you are using WSIT on OpenVMS Alpha, see Section 2.5.5 for information about the HP TestDrive program.

2. Validate XML IDL file

Verify that the XML IDL file correctly describes the interface being exposed. If it does not, manually update the XML IDL file until the interface definition is correct. VALIDATE.JAR allows you to verify that an XML IDL file conforms to the openvms-integration.xsd schema.

3. Generate components

For the interface being exposed, generate one WSIT server interface wrapper and one WSIT Java Bean using IDL2CODE.JAR. The generated source code must be built on the OpenVMS system that hosts the application.

4. Use the generated code

Call the generated WSIT JavaBean from the technology of your choice, including BEA WLS, Apache Axis, JMS, Java RMI, J2EE or another JavaBean.

1.4 Wrapping a 3GL Application: C Sample

The following steps demonstrate how to wrap a 3GL application using the math sample program found in WSI$ROOT:[SAMPLES.C]. Other 3GL sample programs can be found in WSI$ROOT:[SAMPLES.COBOL] and WSI$ROOT:[SAMPLES.BASIC]. (See Section 1.5 for information about a sample program that wraps an ACMS application.)

The information in this section is also included in WSI$ROOT:[SAMPLES.C]MATH-SAMPLE.README.

Note: For demonstration purposes only, the steps below use the wsi$root:[samples.c] directory

as the default directory. HP recommends that you copy the contents of this directory into

your own local directory before performing these steps.

Step 1: Generate an Interface Definition with OBJ2IDL

The tool OBJ2IDL.EXE is used to generate an XML interface definition file (IDL). (For information about manually reading or modifying an IDL, see Chapter 5.)

Establish a foreign command:

$ obj2idl = "$WSI$ROOT:[tools]obj2idl.exe"

Compile the wrapper that exposes the new interface:

$ set def WSI$ROOT:[samples.c]

$ cc/debug/noopt math.c

Note: Your code must be compiled with the /DEBUG option for the OBJ2IDL parser to work properly.

Use OBJ2IDL to generate an XML file with the interface definition:

$ obj2idl -f WSI$ROOT:[samples.c]math.obj

The tool OBJ2IDL creates the file math.xml. See the Appendix for a full listing of math.xml.

You should become familiar with the XML description of OpenVMS applications. Review the math.xml file and notice the overall structure of the file. Following are the level 1 tags used to define an interface. These tags contain lower level tags and more information.

<Primitives></Primitives> Define the fundamental types referenced in the interface.

<Routines></Routines> Define the callable routines of the interface.

<Structures></Structures> Define the structures of the interface.

<Typedefs></Typedefs> Define the type definitions of the interface.

</OpenVMSInterface>

Note: To view the XML file with coloring and a collapsible outline, use Internet Explorer.

Step 2: Validate the Generated XML File

The OBJ2IDL tool is sometimes unable to extract a complete interface definition from the supplied object file. When the tool is missing data or has made assumptions, a comment is placed in the XML file below the line of concern.

The file math.log is also generated from OBJ2IDL. Use this file to conveniently see an overview of the comments within the XML file. (ACMS does not create a .log file.)

$ ty math.log

Generated IDL file: WSI$ROOT:[samples.c]math.xml

Tue Apr 5 11:22:37 2005

In this case the tool did not report any issues. However, even in cases where the log file has not generated any error or warning, you should always review the XML file to ensure that the interface definition is exactly correct. It is very important that the XML IDL describe the interface accurately to generate correct code in Step 3.

The validate.jar tool is provided to allow you to verify that an XML IDL file conforms to the openvms-integration.xsd schema. Use this tool to validate all XML IDL files before they are passed to the IDL2CODE tool. The IDL2CODE tool does not validate the XML IDL file.

The validate tool is an executable JAR file. To run the tool, you must supply two parameters: an XML IDL file and the openvms-integration schema. For example:

$ java -jar wsi$root:[tools]validate.jar -x wsi$root:[samples.c]math.xml

–s wsi$root:[tools]openvms-integration.xsd

Step 3: Generate WSIT Components with IDL2CODE

Use the tool IDL2CODE.JAR (also called the Generator) to create a server wrapper for the application and a JavaBean client. This tool requires certain JAR files to be in the Java classpath. A command procedure is supplied to add these files to the java$classpath logical. (The java$classpath logical lets you define a class path using OpenVMS file specification syntax. Defining this logical overrides the classpath logical, if set.)

$ @WSI$ROOT:[tools]wsi-setenv - wsi$dev

The New JAVA$CLASSPATH is:

"JAVA$CLASSPATH" = "WSI$ROOT:[LIB]WSIRTL.JAR" (LNM$JOB_86F82E00)

= "[]"

= "WSI$ROOT:[LIB]VELOCITY-DEP-1_4.JAR"

= "WSI$ROOT:[TOOLS]IDL2CODE.JAR"

To generate files for the math demo, use the following command. In this case, the tool is passed the math.xml file and the application is named math. All generated files for the application are placed in a subdirectory named generated.

$ create/dir [.generated]

$ java "com.hp.wsi.Generator" -i math.xml -a math -o [.generated]

File: ./generated/mathServer/build-math-server.com generated.

File: ./generated/mathServer/methIds.h generated.

File: ./generated/mathServer/structkeys.h generated.

File: ./generated/mathServer/math.wsi generated.

File: ./generated/mathServer/math.opt generated.

File: ./generated/mathServer/math-server.h generated.

File: ./generated/mathServer/math-server.c generated.

File: ./generated/math/build-math-jb.com generated.

File: ./generated/math/Imath.java generated.

File: ./generated/math/mathImpl.java generated.

HP OpenVMS Systems