HIS 2006 Tutorial: Implementing the Basic Application Integration Scenarios

Application Integration is the name given to the set of Microsoft Host Integration Server (HIS) technologies that allow you to integrate a Windows-based application with a host mainframe application. The following tutorial describes several of the basic programming techniques involved when using Application Integration. To show different ways of performing the basic scenarios, the associated sample application, located in the samples directory of your installation of Host Integration Server or BizTalk Adapter For Host Systems, is written in Visual Basic .NET, Visual C# .NET, and unmanaged C++.

The samples directory of Host Integration Server and BizTalk Adapter for Host Systems contains several applications, written in Visual Basic .NET, Visual C# .NET, and unmanaged C++, that describe these techniques. This tutorial provides expanded instructions for compiling and running those samples. In addition, this tutorial describes how to rebuild the C# solution manually. Once you have completed this tutorial, you will be able to do the following:

  • Create a remote environment
  • Create a Transaction Integrator (TI) assembly
  • Use TI Manager to manage a TI assembly
  • Create a simple application that accesses a remote host to retrieve data

Before you start the 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 compile and run the Basic Scenarios sample, you must first create a COM+ application and import the host application definition. You can then start SimHost, which acts as a simulated host for this sample. You can then compile and run the sample.

To create a COM+ application
  1. Click Start, point to Programs, point to Microsoft BizTalk Adapters for Host Systems, and then click TI Manager.

  2. In TI Manager, expand Component Services, expand Computers, expand My Computer, and then expand the COM+ Applications node.

  3. Right-click the COM+ Applications node, and then click New, Application.

  4. On the Welcome to the COM+ Application Install Wizard page, click Next.

  5. Click Create an empty application.

  6. Enter Transaction Integrator Tutorials as the name for the new application, verify that the Server application option is selected, and then click Next.

  7. On the Set Application Identity page, select This user, enter a user account that is a member of the HIS Administrators group, and then click Next.

  8. On the Add Users to Roles page, click Next.

  9. On the Add Application Roles page, click Next, and then click Finish.

To import the Basic Scenarios sample
  1. In TI Manager, expand the Transaction Integrator node.

  2. Right-click the Window-Initiated Processing node, and then click Import.

  3. On the Welcome to the Import WIP Definitions Wizard page, click Next.

  4. On the Define Import Characteristics page, confirm that the Use Original Definitions option button is selected.

  5. Use Browse to locate the TIHostApplicationDef folder, and then click Next.

    The TIHostApplicationDef folder contains all of the relevant files for describing the host environment for this tutorial. The folder is located in <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\BasicScenarios\TIHostApplicationDef.

  6. On the Importing WIP Definitions page, wait for the import to complete, and then click Next.

  7. On the Completing the Import WIP Definitions Wizard page, click Finish.

  8. In TI Manager, expand the Objects node under the Window-Initiated Processing node.

  9. Right-click the TINetBasic.Accounts.1 object, and then click Properties.

  10. In the TINetBasic.Accounts.1 Properties dialog box, click the Remote Environment tab.

  11. Select SimHost ELM Link in the Remote environment drop-down list, and then click OK.

  12. Repeat steps 9 through 11 for the TIComBasic.Accounts.1 object.

To start SimHost for the Basic Scenarios sample
  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 sample and tutorial, you will use it to act as a remote host operating over a TCP/IP CICS connection.

  4. Click Options, and then click Reset to default values.

  5. Click Start TCP.

To build and execute the Basic Scenarios sample
  1. In Visual Studio, on the File menu, click Open, and then click Project/Solution.

  2. In the Open Project dialog box, locate the folder that contains the sample solution file.

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

  3. Click TIBasic.sln, and then click Open.

  4. Click Build, and then click Build Solution.

  5. Click Debug, and then click Start Debugging.

    A console window appears and displays the output of the application.

  6. End the debugging session by closing the console window.

  7. By default, the TIBasic solution runs the C#.NET client application; to run the Visual Basic .NET or the unmanaged C++ projects, change the Startup project for the TIBasic solution to either VBNetClient or CPlusPlusClient and repeat steps 5 and 6.

After you have run and compiled the sample, you may choose to manually re-create the application. This tutorial takes you through the process of creating the sample application.

After creating a new project, you add a .NET client object to contain the interface to the host system. You then import the host definition file into the client object and define the host system interface. After saving and deploying the interface, you can write code against the host system interface, and then create the sample application.

Step 1: Start SimHost

Start SimHost, which acts as a simulated host for this sample.

To start SimHost
  1. Note that you do not need to start SimHost if it is still running as a result of completing the first Basic Scenarios sample.

  2. Right-click Start, and then click Explore.

  3. Locate the SimHost folder.

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

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

  5. Click Start TCP.

Step 2: Create a Remote Environment

After starting SimHost, create a remote environment in TI Manager to act as an endpoint for the Transaction Integrator .NET Client Library used in this sample.

To create an CICS ELM Link remote environment
  1. Note that you do not need to create a remote environment if you have already completed the first Basic Scenarios sample.

  2. Click Start, point to Programs, then point to Microsoft BizTalk Adapters for Host Systems, and then click TI Manager.

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

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

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

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

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

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

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

  10. Click Next, and then click Finish.

Step 3: Create a New Project

After creating a COM+ application, you can create a new project to hold the Basic Scenarios sample. After you create the project, you can add a .NET Client object, which will expose the remote programming API to your application.

To create a new project for the Basic Scenarios sample
  1. In Visual Studio, on the File menu, point to New, and then click Project.

  2. In the New Project dialog box, in the Project Types pane, select Host Integration Projects.

  3. In the Templates pane, select Transaction Integrator Project.

  4. In the Name field, type BasicScenarios.

  5. In the Location field, type the location where you want to save the tutorial, and then click OK.

    For this tutorial, the location of the project will be <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration.

Step 4: Add a .NET Client Object

Once you have created the project, you can add a .NET client object. This object will contain the interface that you program your application against.

To create the .NET client object
  1. In Solution Explorer, right-click BasicScenarios, point to Add, and then click Add .NET Client Library.

  2. In the Add New Item dialog box, confirm that .NET Client Library is selected in the Templates pane.

  3. In the Name field, type BasicBanking, and then click Add.

  4. On the Welcome to the.NET Client Library Wizard page, click Next.

  5. On the Library page, in the Interface Name field, type Accounts, and then click Next.

  6. On the Remote Environment page, in the Target Environment drop-down list, select CICS.

  7. In the Programming Model dropdown, select ELM Link, and then click Next.

  8. Click Create.

Step 5: Import the Host Definition File

Once you have added the .NET client object, you can define the interface to the object by importing a host definition file. This file describes the programming interface on the remote system that you will be writing your application against. After you import the host definition, you can deploy the interface.

To import the host definition file
  1. On the menu bar in Visual Studio, click View, and then click Properties Window.

  2. On the BasicBanking.dll tab, right-click the BasicBanking node, point to Import, and then click Host Definition.

  3. On the Welcome to the Import COBOL Wizard page, click Next.

  4. On the Import COBOL Source File page, click Browse, and then locate the TIHostApplicationDef folder.

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

  5. Click the GetBalance.cbl file, click Open, and then click Next.

  6. On the Item Options page change the Link-to-Program name from GETBALAN to GETBAL and then click Next.

  7. On the 01 DFHCOMMAREA page, select the check box next to the DFHCOMMAREA node, and then click Next.

  8. Expand the DFHCOMMAREA node.

  9. Click the arrows next to the NAME field, and then click In.

  10. Click the arrows next to the ACCNUM field, and then click In.

  11. Click the arrows next to the ACCBAL field, and then click Out.

  12. Click Next.

  13. On the Data Tables, Structures and Unions page, click Next.

  14. On the Completing the Import COBOL Wizard page, click Modify.

Step 6: Save and Deploy the Interface

Once you have created the interface for the remote programming environment, you need to deploy the interface. Then, you can create an application that uses the interface.

To save and deploy the Accounts interface
  1. On the BasicBanking.dll tab, click the GetBalance node.

  2. In the Properties window, click the Include Context Parameter field, and then click False in the list.

  3. On the BasicBanking.dll tab, click the BasicBanking node.

  4. In the Properties window, click the Remote Environment field, and then select SimHost ELM Link.

  5. On the File menu, click Save All.

  6. Click Start, point to Programs, point to Microsoft BizTalk Adapters for Host Systems, and then click TI Manager.

  7. Click to expand Transaction Integrator, click to expand Windows-Initiated Processing, and then click to expand Objects.

  8. If BasicBanking.Accounts.1 exists in the list of Objects, right click BasicBanking.Accounts.1 and then click either Force Undeployment or Delete (only one of these options will be available). Click Yes when prompted.

  9. Right-click Objects and then click New, Object.

  10. Click Next in Welcome to the New Object Wizard.

  11. Click Browse and then locate the BasicBanking.dll file.

    For this tutorial, the location of the BasicBanking.dll file will be <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\BasicScenarios\BasicScenarios\.

  12. Click the BasicBanking.dll file, click Open, and then click Next.

  13. On the Define Environment Characteristics for the .NET Object page, verify that the Self-Hosted option is enabled, and then click Next.

  14. Select SimHost ELM Link in the Remote environments drop-down list, and then click Next.

  15. Click Next and then click Finish to close the New Object Wizard.

Step 7: Create a Visual C# Project

Once you have deployed the interface, you need to create an application that uses the interface. The first step in creating the application is to create a project to hold the application.

To create a Visual C# project for the Basic Scenarios sample
  1. In Visual Studio, on the File menu, point to Add, and then click New Project.

  2. In the Add New Project dialog box, in the Project Types pane, click Visual C#.

  3. In the Templates pane, click Console Application, and then click OK.

Step 8: Code and Run the Client Application

After creating a project to hold the application, you can code and execute the application.

To code the Visual C# application for the Basic Scenarios sample
  1. In Solution Explorer, expand the ConsoleApplication1 node.

  2. Right-click References, and then click Add Reference.

  3. In the Add Reference dialog box, click the Browse tab, and locate the BasicScenarios folder.

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

  4. Click BasicBanking.DLL, and then click OK.

  5. Add the following code to your Program.cs file:

    using System;
    using System.Collections.Generic;
    using System.Text;
    using BasicBanking;
    
    namespace ConsoleApplication1
    {
        class Program
        {
            static void Main(string[] args)
            {
                decimal Balance = 0.0m;
    
                BasicBanking.Accounts MyBankObj = new BasicBanking.Accounts();
                MyBankObj.GetBalance("Kim Akers", "123456", out Balance);
    
                Console.WriteLine("Basic Scenarios: Account Balance = {0,9:C2}", Balance);
                Console.WriteLine("\nPress any key to continue...");
                Console.Read();
            }
        }
    }
    
  6. On the File menu, click Save All.

  7. Click Build, and then click Build ConsoleApplication1.

  8. Click Debug, and then click Start Debugging.

  9. End the debugging session by pressing a key on the keyboard or by closing the console window.

Show: