

•	Hanson Brothers Interoperability Sample: Overview

•	Hanson Brothers Interoperability Sample: Setup

Hanson Brothers Interoperability Sample: Setup

Clarity Consulting, Inc.
May 2000

Summary: Demonstrates the use of SOAP and the SOAP Toolkit for Visual Studio 6.0 to integrate COM+ components running on Windows 2000 and CORBA components running on a Solaris server. This document describes how to install the HBInterop sample application components on both platforms. Total estimated setup time: 30 minutes.

Download the sample code for this article

Requirements for Installing HBInterop
Stand-Alone Windows 2000 Server Setup
Installing the Product Inventory Web Service on a Separate Server
UNIX Server Setup
Detailed Windows 2000 Server Setup Instructions
Testing the Setup
Uninstalling HBInterop
About the Authors

Requirements for Installing HBInterop

It is highly recommended that you read the Hanson Brothers Interoperability Sample: Overview prior to following the setup steps below.

Windows 2000 Requirements

The HBInterop sample requires Microsoft® Windows® 2000 Server with Internet Information Server (IIS) 5.0, Microsoft SQL Server™ 7.0 or SQL Server 2000, and the Microsoft SOAP Toolkit for Visual Studio 6.0. The setup program by default will install the database, business components, and Web server on the same machine.

To work with the source code, you'll need Visual Studio® 6.0 (or Visual Basic® 6.0 and Visual InterDev® 6.0) with Service Pack 3 running on Windows 2000.

UNIX Server Requirements

The UNIX server components were developed and tested against Sun Solaris 2.6, Oracle 8i version 8.1.6, Visibroker version 4.0, and Sun's Java API for XML Parsing (JAXP) version 1.0. The code may compile and run on later versions of the OS, but these versions have not been tested.

To compile the C++ Common Object Request Broker Architecture (CORBA) components, you'll need Sun's Visual Workshop for C++ version 5.0, Personal Edition. To compile the Java listener, you will need version 1.2.2 of Sun's Java Development Kit and the Aurora ORB that accompanies Oracle 8i.

Windows 2000 Server Setup

The HBInterop sample application consists of three primary groups of components:

The HBRetail Web site, HBInterop COM+ component, and HBInterop SQL Server database.
The Inventory Management components, database, and Web Service.
The HBInterop Web Service.

This document describes three configurations for deploying the components. First, we will start out by installing and running all of the components on a single Windows 2000 server. Second, we'll point to a remote implementation of the Inventory Web Service. Third, we'll configure and point to a local UNIX implementation of the Inventory Web Service.

If the recommended setup requirements described below are not compatible with your setup, please see the detailed step-by-step process included later in this document.

Simple Setup Requirements:

The Setup batch files were written with the following assumptions:

The SQL Server 2000 "sa" account password must be empty for database scripts to work.
The Default Web Site must be running for the setup to work.

If your computer doesn't meet all of these requirements, please follow the steps described in the Detailed Windows 2000 Server Setup Instructions section.

Stand-Alone Windows 2000 Server Setup

This section of the document describes the steps necessary to install the three component groupings on a single Windows 2000 server and test the installation.

Set up the database, COM+ application, and Web sites. Double-click Setup.cmd in the \Program Files\HBInterop directory. This batch file calls three other batch files to set up the server components used by the HBInterop sample. The individual batch files will be created in separate command windows and prompt you to press any key when they finish. Any errors that occur during the process will be printed to the corresponding command window. The three batch files called by Setup.cmd are:
- Setupdb, which uses OSQL to create the HBInterop and HBProduct databases. It also populates the databases with data for two customers and sample products.
- Setupcomponents, which uses a Microsoft Windows Installer (MSI) package to install the COM+ application.
- Seutpweb, which creates three new virtual directories (HBRetail, HBInterop and ProdInv).
Copy the SOAP Toolkit for Visual Studio 6.0 Listener.asp into the HBInterop site. The HBInterop site, located in the \Program Files\HBInterop\InteropSite directory, uses the ASP listener from the SOAP Toolkit for Visual Studio 6.0 to expose the order information to external partner organizations. You need to copy the Listener.asp file that ships with the SOAP Toolkit into the HBInterop Web site.
Implement the SOAP ISAPI DLL. The HBInterop site uses the ISAPI listener from the SOAP Toolkit for Visual Studio 6.0 to expose the product information to external partner organizations. For detailed instructions on installing the ISAPI listener, follow the steps detailed in the SOAP Toolkit documentation.
Open the Internet Services Manager. Click on the Start button, then click on Programs, then Administrative Tools. Select Internet Service Manager and expand the Default Web Site.
Once the Default Web Site is expanded:
1. Select the HBInterop virtual directory and right-click to display the HBInterop Properties dialog box.
2. From the Virtual Directory tab, choose Create under the Application Settings area.
3. Click on the Configuration button to add the SOAP application mapping.
4. In the Add/Edit Application Extension Mapping dialog box, enter the following information:
  - Enter the path to the SoapIsapi.dll as the Executable.
  - Enter sod as the Extension.
  - In the Verbs box, select Limit to: and enter POST.
  - Make sure the Script engine check box is selected.
Repeat the steps above using the ProdInv Web site.

You are now finished with the Windows 2000 server setup. At this point, you can:

Move the Product Web Service to a separate Windows 2000 server.
Begin the Unix Server setup.
Test the setup.

Installing the Product Inventory Web Service on a Separate Server

In this section, we'll review the steps necessary to install the components that make up the Inventory Management system and its Web Service on a separate Windows 2000 server. This configuration allows you to test the concepts behind implementing a Web Service without installing and configuring the UNIX/CORBA components.

This section of the document assumes that you've already followed the steps outlined in the previous section. Steps 1, 2, and 3 are performed on the server that will host the Product Inventory Web Services. Step 4 is performed on the server that was set up in the previous section and will continue to host the HBRetail and HBInterop Web sites.

Set up the Product Inventory database, COM+ application, and Web Service. Double-click SetupProdInvWS.cmd, found in the \Program Files\HBInterop directory. This batch file calls three other batch files to set up the server components used by the HBInterop Product Inventory Web Service sample. The individual batch files will be created in separate command windows and prompt you to press any key when they finish. Any errors that occur during the process will be printed to the corresponding command window. The three batch files called are:
- SetupInvdb, which uses OSQL to create the HBProduct database. It also populates the databases with sample product data.
- SetupInvcomponents, which uses an MSI package to install the COM+ application.
- SetupProdInvWS, which creates a new virtual directory (ProdInv) to host the Web Service.
Implement the SOAP ISAPI DLL. The ProdInv site uses the ISAPI listener from the SOAP Toolkit for Visual Studio 6.0 to expose the product information to external partner organizations. For detailed instructions on installing the ISAPI listener, follow the steps detailed in the SOAP Toolkit documentation.
1. Open the Internet Services Manager by clicking on the Start button, then click on Programs, then Administrative Tools. Select Internet Service Manager and expand the Default Web Site.
2. Select the ProdInv virtual directory and right click to display the ProdInv Properties dialog box.
3. On the Virtual Directory tab, choose Create under the Application Settings section.
4. Click on the Configuration button to add the SOAP application mapping.
5. In the Add/Edit Application Extension Mapping dialog box, enter the following information:
  - Enter the path to the SoapIsapi.dll as the Executable.
  - Enter sod as the Extension.
  - In the Verbs box, select Limit to: and enter POST.
  - Make sure the Script engine check box is selected.
Edit the SDL file on the HBRetail server. The default Service Description Language (SDL) file that is installed points to the local machine (localhost) and needs to be changed to reflect the name of the new server. Open the Inventory.xml and Category.xml files using Notepad and replace the references to LocalHost to the name of your server.
Update the COM+ Initialization string. The product class of HBProduct implements IObjectConstruct. HBInterop will check the constructor string for a custom URL and will use it over the internal default.
On the machine running the HBInterop COM+ components, open the Component Services Explorer by clicking on the Start button and selecting Programs, Administrative Tools, and then Component Services. Expand the explorer so that the components in HBInterop package are visible. Right click on HBProduct.Product and select Properties. In the Properties dialog box, select the Activation tab. Then select the Enable Object Construction check box. Add your custom URL string in the Constructor String text box. Below is an example constructor string.
```
CORBA_ServiceURI=http://UnixListener/,CORBA_TimeOut=60000
```

You are finished configuring the Inventory components to run on a separate server. Now when you run the HBRetail site you will retrieve the product information from the new server.

UNIX Server Setup

The UNIX server setup involves the unpacking of files, establishment of an Oracle database, and compilation of the Java HBInterop Listener and C++ HBInterop server.

Unpack files. Download HBInterop.tar to $HOME, then type the following statement in the command line:
```
tar xvf $HOME/HBInterop.tar
```
The following files will be place in $HOME/HBInterop:
- Create.sql, which is SQL Script to create an Oracle user account, tablespace, and table.
- Corba.idl, which specifies category and inventory interfaces.
- Server.pc, a Pro*C pre-compiled C++ source code that produces the HBInterop server.
- Makefile, which creates server.pc.
- Listener.java, Java source code that produces the HBInterop listener.
- Inventory.xml, from the SOAP Toolkit for Visual Studio 6.0 SDL used for specifying the inventory interface.
- Category.xml, from the SOAP Toolkit for Visual Studio 6.0 SDL used for specifying the category interface.
Create environment variables. The HBInterop server and HBInterop listener do not require environment variables themselves, but Oracle, Visual Workshop, JDK, JAXP, and Visibroker require several environment variables. You will want to verify that the environment variables below are set to the correct values for your server configuration. Check your command shell user manual to learn how to view and set the following environment variables.
- CLASSPATH
- ORACLE_SID
- PATH
- SINGLE_THREADED
- VBROKERDIR
- VBROKER_ADM
Edit Create.sql script used to create database. Open the $HOME/HBInterop/create.sql file in your favorite text editor and change the following line:
```
create tablespace prodinv datafile '$HOME/hbinteorp/prodinv.dbf'
size 10m autoextend on next 500k maxsize 100m;
```
Replace $HOME/HBInterop/prodinv.dbf with a fully-qualified path pointing to where you would like the Oracle tablespace file to reside. It is recommended that you keep this file with the other HBInterop files.
Execute SQL script to create database. In the command line, type:
```
svrmgrl < $HOME/HBInterop/create.sql 
```
Compile server. To compile the HBInterop server, change to the directory where the Server.pc file exists and type the following in the command line:
```
Make
```
As the make file is processed, the IDL is converted to skeleton classes, the Pro*C C++ source code is pre-compiled, and an executable called "server" is created.
Compile listener. First, you need to convert the IDL into skeleton classes. Change to the directory where the Corba.idl file exists, and then type the following in the command line:
```
idl2java CORBA.idl
```
Next, you need to compile the listener class code with a Java compiler that is Visibroker-aware. Change to the directory where Listener.java exists and type the following in the command line:
```
vbjc Listener.java
```
Edit service location in Category.xml and Inventory.xml. You will need to update the URL attribute of the location element that can be found between the service tags. See the XML fragment below:
```
<service>
 <addresses>
 <location url='http://192.168.1.1/'/>
 </addresses>
 <implements name='Category'/>
</service>
```
Open Category.xml in your favorite text editor and change the URL attribute of the location element so that it points to the listener on the UNIX server. For example, if the host name of the UNIX box where listener is running is "productserver," then the URL attribute might be:
```
url='http://product server/' 
```
Keep in mind that the listener responds to all POST submissions the same way regardless of the path following the host name or IP address. Repeat this step for Inventory.xml. You will need to open Inventory.xml in a text editor and update the URL attribute of the location element.
Test the component.
1. Execute ORB. Open a new terminal window and type the following in the command line:
```
osagent
```
2. Execute server. Open a new terminal window and type the following in the command line:
```
$HOME/HBInterop/server
```
3. Execute listener. Open a new terminal window and type the following in the command line:
```
cd $HOME/HBInterop
vbj Listener
```
4. Browse Category.xml. You can verify the configuration by opening Category.xml in Internet Explorer on your Windows server. For example, if the UNIX server's IP address is 192.168.1.1, you can type http://192.168.1.1/Category.xml in your browser.
Update the COM+ Initialization string. On the Windows 2000 server, update the COM+ initialization string for the HBProduct component to point to the new UNIX listener. Open the Component Services Explorer by clicking on the Start button and selecting Programs, Administrative Tools, then Component Services. Expand the window so that the components in the HBInterop package are visible. Right click on the HBProduct.Product and select Properties. In the Properties dialog box, select the Activation tab. Then select the Enable Object Construction check box. Add your custom URL string in the Constructor String text box. Below is an example constructor string.
```
CORBA_ServiceURI=http://UnixListener/,CORBA_TimeOut=60000
```

You are finished configuring the Inventory components to run on a UNIX server. When you run the HBRetail site, you will now retrieve the product information from the Oracle database using the CORBA components.

Detailed Windows 2000 Server Setup Instructions

If you didn't meet the requirements for the simple setup or want to learn how to deploy the Web application by hand, the instructions below will walk you through the steps to create the HBInterop application.

Create the Database

The following steps create the SQL Server HBInterop database and populate it with customer data.

Load the database scripts. Use the Query Analyzer to connect to your database using the "sa" account. Load the database/schema.sql script into the query window and run it by pressing F5. The script will create a database named HBInterop using the model database as a template.
Load the customer data into the database. Load the database/schema.sql script into the query window and run it by pressing F5. Close the query window (Ctrl+F4).

Register the Components with COM+

There is one COM+ application to set up that will contain two COM+ components.

Create the HBInterop application. Open the Component Services Explorer by clicking on the Start button and selecting Programs, Administrative Tools, then Component Services. Create an empty application called HBInterop by expanding the tree on the left window down to My Computer\COM+ Applications. Right-click on COM+ Applications and select Application from the New menu.
The new application dialog box should now be on the screen. Click the Empty Application button and name it HBInterop. Leave the Application Identity option set to Interactive User. This means that you must be logged into the application server in order to use these components.

Note Running in Server Application mode as the Interactive User may cause problems. If there is no one logged into the console, then the Web pages will fail when trying to create any of those objects. You may want to set the identity to a specific user context.

Click the Finish button. Expand the HBInterop/Components icons on the right side of the window. Finally, drag the HBInterop.dll and FMSProduct.dll components from Components/Source/Distribution into the empty components window to register them.
Customize database connection string (optional). Perform this step if you want to supply a custom database connection string.
The HBInterop classes implement IobjectConstruct, which allows an administrator to pass a string to components every time they are created. HBInterop classes use a custom ConnectionString supplied in a constructor over the internal default.

Open the Component Services Explorer by clicking on the Start button and selecting Programs, Administrative Tools, then Component Services. Expand the window so that the components in HBInterop package are visible. Right click on HBInterop.Cart and select Properties. Then select the Activation tab from the Properties dialog box. Then select the Enable Object Construction check box. Add your custom connection string in the Constructor String text box. Below is an example constructor string.
```
ConnectionString=Data Provider=SQLOLEDB;Driver={SQL Server};
Server=MyComputer;Database=HBINTEROP;Uid=sa;Pwd=
```
You will need to provide a custom database connection in the Cart, Order, Product, and Session components
Customize URL used to access the UNIX listener (optional). The product class of HBProduct implements IObjectConstruct. HBInterop will check the constructor string for a custom URL and will use it over the internal default.
Open the Component Services Explorer by clicking on the Start button and selecting Programs, Administrative Tools, then Component Services. Expand the window so that the components in the HBInterop package are visible. Right click on HBProduct.Product and select Properties. In the Properties dialog box, select the Activation tab. Then select the Enable Object Construction check box. Add your custom URL string in the Constructor String text box. Below is an example constructor string.
```
CORBA_ServiceURI=http://UnixListener/,CORBA_TimeOut=60000
```
Test the component and database setup. Double-click on the Test HBInterop Installation.vbs script that is located in the HBInterop folder. This simple VBScript creates an instance of the HBInterop.Session object and uses the Login and Logout methods to verify the component and database implementations.
If the VBS test script was able to login to the HBInterop application, you should see a dialog stating that the session was successfully created.

Create the Web Applications

The final steps to create the Web application are listed below.

Deploy the HBRetail application directory. Now that you have the plumbing and architecture in place for your application, the final addition is the presentation layer. IIS provides several ways to deploy a new Web site or add functionality to an existing Web site. In this case, all you need to do is create a new Virtual Directory for the existing Default Web Site. This operation will tell IIS that there is a new keyword or virtual directory to listen for on the Web server port. Whenever IIS receives a request for any file in that virtual directory, it will map that request to the application directory.
Launch the Computer Management Administrator tool by right-clicking on My Computer and selecting Manage. Create a new virtual directory by expanding out the tree to show Services and Applications/Internet Information Services/Default Web Site. Right-click on the Default Web Site and select Virtual Directory from the New menu.

A dialog box appears and requests the Virtual Directory Alias. Enter HBRetail and press Next. The dialog prompts you for the path to the directory that contains the Web content. Point it to c:\Program Files\HBInterop\RetailSite and select Next.
Deploy the HBInterop application directory. Launch the Computer Management Administrator tool by right-clicking on My Computer and selecting Manage. Create a new virtual directory by expanding out the tree to show Services and Applications/Internet Information Services/ Default Web Site. Right-click on the Default Web Site and select Virtual Directory from the New menu.
A dialog box appears and asks you for the Virtual Directory Alias. Type HBInterop and click Next. The dialog prompts you for the path to the directory that contains the Web content. Point it to c:\Program Files\HBInterop\InteropSite and press Next.
Copy the Listener.asp into the HBInterop site. The HBInterop site uses the ASP listener from the SOAP Toolkit for Visual Studio 6.0 to expose the order information to external partner organizations. You need to copy the Listener.asp page that ships with the Toolkit into the HBInterop Web site.
Implement the SOAPISAPI DLL. The HBInterop site uses the ISAPI listener from the SOAP Toolkit for Visual Studio 6.0 to expose the product information to external partner organizations. To install the ISAPI listener, follow the steps detailed in the Toolkit documentation using the HBInterop site.

Testing the Setup

Test the HBRetail site. Connect to the Web site using Internet Explorer 5.0 or later. You can test the application by logging in as Intetop1 with the password Interop1. To check the functionality of the HBRetail, browse for products, fill your shopping cart, and then submit your order. Most configuration problems stem from having a bad database connection string for your database or from a bad URL for the UNIX server.
Test the HBInterop site. Open and run the Visual Basic InteropDemo project that is located in the \Components\Source\InteropDemo\ directory. The HBInterop site can use this to test services that are made available. The HBInterop site exposes the following specific COM object methods:
- BrowseCategories. Press the BrowseCategories button on the Product tab. The SOAPISAPI DLL will process a request and a call will be made to the BrowseCategory method on the product object in the HBProduct component.
- BrowseByCategory. Press the BrowseByCategory button on the Product tab. The SOAPISAPI DLL will process a request and a call will be made to the BrowseByCategory method on product object in the HBProduct component.
- Save. Press the Save Order button on the Order tab. A request will be processed by the Order.asp page and a call will be made to the Save method on the order object in the HBInterop component.

Most problems stem from having an incorrect path or URL in SDL or SOD files. If you have problems, you'll want to check the contents of the Product.XML, Product.SOD, and the Order.XML files that are located in the InteropSite directory.

Uninstalling HBInterop

Follow the steps below to remove HBInterop from your Windows 2000 server.

Drop the database. Use the Query Analyzer to log into the database as the "sa" account. Delete the HBInterop database and associated account using the four lines shown below.
```
 drop database HBInterop
 go
 sp_droplogin "HBInterop_login"
 go
```
Remove the COM+ applications. Launch the Component Services application from the Administrative Tools program group. Delete the four HBInterop groups. You might need to shut down each group if the groups were recently used.
Remove the HBInterop virtual root. Locate the HBInterop virtual root entry under the Default Web Site entry in the Computer Management snap-in. Use the context menu to delete the entry.
Remove the HBRetail virtual root. Locate the HBRetail virtual root entry under the Default Web Site entry in the Computer Management snap-in. Use the context menu to delete the entry.
Delete the local files. You should now be able to delete the source files installed under C:\Program Files\HBInterop by default.

Follow the steps below to remove HBInterop from your UNIX server.

Stop the HBInterop listener. Press Ctrl-C in the terminal window where the HBInterop listener is executing.
Stop the HBInterop server. Press Ctrl-C in the terminal window where the HBInterop server is executing.
Stop the ORB. Press Ctrl-C in the terminal window where osagent is executing.

Drop the database. Enter the following commands in the command line:

svrmgrl
connect system/manager
drop user iop cascade;
drop tablespace prodinv;
quit

Remove HBInterop local files. Enter the following commands in the command line:
```
rm $HOME/HBInterop/product/*
rmdir $HOME/HBInterop/product
rm $HOME/HBInterop/*
rmdir $HOME/HBInterop
```
Note If you placed Prodinv.dbf in a directory other than $HOME/HBInterop, you will need to remove this data file as well.

About the Authors

Jay Schmelzer is a consultant and partner with Clarity Consulting, Inc.

Chris Helzerman and Garrison Brinkmann are consultants with Clarity Consulting, Inc. They can be reached at HBInterop@ClarityCon.com.