HIS 2006 Tutorial: Creating a Web Service that Uses a Return Value

Microsoft Host Integration Server 2006 (HIS) has the ability to use a Web service as an interface to communicate with a host mainframe. This tutorial shows how to provide access to Customer Information Control System (CICS) transactions exposed as a .NET Web service hosted in Internet Information Services (IIS).

The samples directory of Host Integration Server and BizTalk Adapter for Host Systems contains a sample application that creates a Web service. This tutorial provides expanded instructions for compiling and running that sample. Once you have completed this tutorial, you will be able to do the following:

  • Create a Web service virtual directory
  • Create a remote environment
  • Register and execute the Web service

Before you start this tutorial, make sure to perform the following actions:

  1. Install Microsoft® Visual Studio® 2005.
  2. Install Microsoft BizTalk Adapters for Host Systems or Host Integration Server.
    For this tutorial, BizTalk Adapters for Host Systems was installed. To use this tutorial with HIS, simply replace any mention of BizTalk Adapters for Host Systems with HIS.
  3. Ensure that the account you are using is part of the HIS Administrators group.

To run the Web service sample you must first create the virtual directory for the Web service and then create the remote environment. You can then start SimHost, which acts as a simulated host for this tutorial. You can then access the Web service through a browser and also compile and run a sample that accesses the Web service programmatically.

Step 1: Ensure IIS is installed and Create the Web Service Virtual Directory

To ensure IIS is installed and to create the Web service virtual directory
  1. Click Start, point to Settings, click Control Panel, and click Add or Remove Programs, and then click Add/Remove Windows Components.

  2. On the Windows Component Wizard, double-click Application Server, and confirm that Internet Information Services (IIS) is selected.

    If IIS is not selected, select IIS and continue with the installation process.

  3. Click Start, point to Settings, click Control Panel, click Administrative Tools, and then click Computer Management.

  4. In the Computer Management screen, expand the Services and Applications node, expand the Web Sites node, right-click Default Web Site, point to New, and then click Virtual Directory to start the Virtual Directory Creation Wizard.

  5. On the Welcome to Virtual Directory Creation Wizard screen, click Next.

  6. On the Virtual Directory Alias screen, in the Alias field, type TIWSBanking, and then click Next.

  7. On the Web Site Content Directory screen, in the Path field, type the path of the Web Site content directory you want to use.

    For this tutorial, the directory used is <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\WindowsInitiated\WebServiceUsingReturnValue\TIHostApplicationDef.

  8. On the Virtual Directory Access Permissions screen, confirm that the Read, Execute, and Browse buttons are checked, click Next, and then click Finish.

  9. On the Computer Management screen, right-click the TIWSBanking virtual directory, and then click Properties.

  10. Do one of the following:

    • For Windows Server 2003, click the ASP.NET tab.
      Confirm that the ASP.NET version drop-down list has 2.0.50727 or higher selected, and then click OK.
      Also ensure that the user associated with the application pool that is used by the default Web site is a member of either the HIS Administrators or HIS Runtime Users groups, and that this user is not a member of the Guests group.
    • For Windows XP, click the Virtual Directory tab, and then click Configuration.
    1. In the Application extensions box, confirm that .rem is included as an extension, and then click OK.
    2. If .rem is not included as an extension, you must enable ASP.NET. To do this, open the command line and change the directory to %windows%\Microsoft.NET\Framework\v2.0.50215. Then, enter the following command:
      aspnet_regiis.exe -i
    3. Finally, add the ASPNET account to the HIS Local User and Groups.
  11. Click OK to exit the TIWSBanking Properties dialog box.

Step 2: Create a Remote Environment

To create a CICS ELM Link remote environment
  1. Click Start, point to Programs, point to Microsoft BizTalk Adapters for Host Systems, and then click TI Manager.

  2. Under the Console Root, expand the Windows-Initiated Processing node, right-click Remote Environments, click New, and then click Remote Environment.

  3. On the New Remote Environment Wizard, click Next.

  4. On the Configure a New Remote Environment page, in the Name field, type SimHost ELM Link, and then click Next.

    Bb418746.note(en-US,BTS.10).gifNote
    It is possible that a remote environment with this name already exists as a result of completing other tutorials. If a remote environment with this name already exists then delete the existing remote environment before completing this step.

  5. On the Configure Host Environment and Programming Model page, in the Target host drop-down box, select CICS.

  6. In the Programming model drop-down list, select ELM Link, and then click Next.

  7. On the Configure Endpoint TCP/IP page, in the IP/DNS address field, type localhost.

  8. Click Edit, and in the in the New port field, type 7511, click Add, and then click OK.

  9. Click Next, and then click Finish.

Step 3: Start SimHost

To start SimHost
  1. Right-click Start, and then click Explore.

  2. Locate the SimHost folder.

    For this tutorial, the SimHost folder is located in <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\system.

  3. Double-click SimHost.exe.

    This starts the Microsoft Transaction Integrator Host Simulator. You can use the Host Simulator to simulate a Host Environment. For this tutorial, you will use it to act as a remote Host operating over a TCP/IP CICS connection.

  4. Click Start TCP.

Step 4: Register and Execute the Web Service

To register the Web service using a return value TI assembly
  1. In TI Manager, expand the Windows-Initiated Processing node, right-click Objects, point to New, and then click Object.

  2. On the New Object Wizard, click Next.

  3. On the Specify Or Locate An Object page, click Browse, and confirm that the Files of type field is set to TI Metadata File for .NET (*.dll).

  4. Use the Open dialog box to select the TI Metadata file "WSBanking.dll", click Open, and then click Next.

    For this sample, the TI Metadata is located in <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\WindowsInitiated\WebServiceUsingReturnValue\TIHostApplicationDef.

  5. On the Define Environment Characteristics For the .NET Object page, click the ASP .NET worker process radio button.

  6. In the Virtual directories drop-down list, click Default Web Site/TIWSBanking.

  7. In the Service drop-down list, click Web Service only, and then click Next.

  8. On the Define Remote Environment page, in the Remote environments drop-down list, confirm that SimHost ELM Link is selected, and then click Next.

  9. On the Creation of WIP Object page, click Next, and then click Finish.

To execute the Web service
  1. Click Start, point to Programs, and then click Internet Explorer.

  2. In Internet Explorer, browse to , click WSBanking.Accounts.asmx, and then click GetBalance.

  3. On the Accounts page, type Kim Akers in the name field, 123456 in the ACCNUM field, and then click Invoke.

    Once you have clicked Invoke, you may view the responses from the Web service in a separate Internet Explorer window.

    Note that if you receive an error indicating that "The type initializer for 'WSBanking.Accounts' threw an exception. ---> That assembly does not allow partially trusted callers," then add the following line of code to the Web.config file for the Web service, restart IIS, and then invoke the Web service again:

    <trust level="Full" originUrl=""/>
    

    For this sample, the Web.config file is located in <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\WindowsInitiated\WebServiceUsingReturnValue\TIHostApplicationDef.

Step 5: Execute the Web Service from a Console Application

To execute the Web Service from a C# console application
  1. In Windows Explorer, locate and double-click the WebServiceUsingReturnValue solution file.

    For this tutorial, WebServiceUsingReturnValue.sln is located at <Installation directory>Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\WindowsInitiated\WebServiceUsingReturnValue

  2. In Solution Explorer, expand the WebServiceUsingReturnValue node, expand the References node, right-click WSBanking, and then click Remove.

    Bb418746.note(en-US,BTS.10).gifNote
    WSBanking is the actual TI assembly; this was originally in the project reference for the solution to build. For a successful execution, the solution must reference the Web service proxy.

  3. Right-click Reference, and then click Add Web Reference.

  4. In the Add Web Reference dialog box, click Web services on the localcomputer, and then click WSBanking.Accounts.

  5. In the Web reference name field, change the name to WSBanking, and then click Add Reference.

  6. In Visual Studio, click Build, and then click Build Solution.

To execute the tutorial
  1. In Visual Studio, click Debug, and then click Start Debugging.

    A command window appears and displays the relevant success or error messages.

Show: