HIS 2006 Tutorial: Creating an RE Override

Transaction Integrator (TI) is the primary technology that Microsoft Host Integration Server (HIS) uses to connect a Windows-based application to a host mainframe. Part of the process of using TI is describing the default mainframe, or remote environment (RE), that your application will connect to. However, if you want to communicate with multiple mainframes, you must be able to switch the default RE with a different RE.

The samples directory of Host Integration Server and BizTalk Adapters for Host Systems contains a sample application that can switch, or override, an RE. This tutorial provides expanded instructions for compiling and running that sample. In addition, this tutorial describes how to rebuild the solution manually. Once you have completed this tutorial, you will be able to do the following:

  • Set up SimHost
  • Import a host application definition
  • Create and deploy a host application interface
  • Create an application that performs an RE override

Before you start the RE Override 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.

The following procedures describe how to compile and run the RE Override sample application. After you have run the application once, you may choose to go back and rebuild the solution manually by following the tutorial steps.

To import the host application definitions for the RE Override 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\Application Integration\WindowsInitiated\REOverride\TIHostApplicationDef.

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

    Bb418742.note(en-US,BTS.10).gifNote
    The RE0Banking.Accounts.1 file is registered to the "SimHost ELM Link" host, and not to the "SimHost ELM Link Secondary" host.

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

To start the primary instance of SimHost for the RE Override 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 tutorial, you will use it to act as a remote host operating over a TCP/IP Customer Information Control System (CICS) connection.

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

  5. Click Start TCP.

To start the secondary instance of SimHost for the RE Override sample
  1. Double-click SimHost.exe.

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

  3. Enter the following port values into the Microsoft Transaction Integrator Host Simulator so that there are no duplicate port numbers being used by the Host Simulator:

    • In the TCP/IP CICS TRM section, in the Port field, enter 6510.
    • In the OS/400 DPC section, in the Port field, enter 8474.
    • In the TCP/IP CICS ELM section, in the Link Port field, enter 6511.
    • In the TCP/IP CICS ELM section, in the GetBal Port field, enter 6512.
    • In the TCP/IP CICS ELM section, in the Getaccts Port field, enter 6513.
    • In the IMS Connect section, in the Port field, enter 9997.
  4. Click Start TCP.

To build and execute the RE Override 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 tutorial solution file.

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

  3. Click REOverride.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. You should see one message for the primary host simulator, and one for the secondary host simulator.

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

To cause the RE Override sample to fail
  1. Click Stop TCP on the secondary instance of SimHost.

  2. Build and execute the RE Override sample again.

    The call to the primary SimHost will succeed, while the call with the RE Override will fail.

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. You do not need to start SimHost if it is still running as a result of completing the first RE Override sample.

To start the primary instance of SimHost for the RE Override 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 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 start the secondary instance of SimHost for the RE Override sample
  1. Double-click SimHost.exe.

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

  3. Enter the following port values into the Microsoft Transaction Integrator Host Simulator so that there are no duplicate port numbers being used by the Host Simulator:

    • In the TCP/IP CICS TRM section, in the Port field, enter 6510.
    • In the OS/400 DPC section, in the Port field, enter 8474.
    • In the TCP/IP CICS ELM section, in the Link Port field, enter 6511.
    • In the TCP/IP CICS ELM section, in the GetBal Port field, enter 6512.
    • In the TCP/IP CICS ELM section, in the Getaccts Port field, enter 6513.
    • In the IMS Connect section, in the Port field, enter 9997.
  4. Click Start TCP.

Step 2: Create Remote Environments

After starting SimHost, create remote environments in TI Manager to act as endpoints for the Transaction Integrator .NET Client Library used in this sample. You do not need to create remote environments if you have already completed the first RE Override sample.

To create primary and secondary CICS ELM Link remote environments
  1. Click Start, point to Programs, then 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.

  5. On the Configure Host Environment and Programming Model page, in the Target host drop-down list, 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.

  10. Right-click Remote Environments, click New, and then click Remote Environment.

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

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

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

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

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

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

  17. Click Next, and then click Finish.

Step 3: Create a New Project

After creating remote environments, you can create a new project to hold the RE Override 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 RE Override 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 REOverrideTutorial.

  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 REOverrideTutorial, 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 REOBanking, and then click Add.

  4. On the .NET Client Library 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 Programming Model list, select ELM Link, and then click Next.

  7. 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 REOBanking.dll tab, right-click the REOBanking 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\REOverride\TIHostApplicationDef.

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

  6. On the Item Options page, 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 REOBanking.dll tab, click the GetBalance node.

  2. In the Properties window, click the Include Context Parameters field, and then click True in the list.

  3. On the File menu, click Save All.

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

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

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

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

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

  9. Click Browse and then locate the REOBanking.dll file.

    For this tutorial, the location of the REOBanking.dll file is <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\REOverrideTutorial\REOverrideTutorial\.

  10. Click the REOBanking.dll file, click Open, and then click Next.

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

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

  13. 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 REO Override 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 RE Override 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 REOBanking.dll file.

    For this tutorial, the REOBanking.dll file is located in <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\WindowsInitiated\REOverride\bin\Debug.

  4. Click REOBanking.dll, and then click OK.

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

  6. In the Add Reference dialog box, click the Browse tab, and locate the Microsoft.HostIntegration.TI.ClientContext.dll file.

    The Microsoft.HostIntegration.TI.ClientContext.dll file is located in <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\system.

  7. Click Microsoft.HostIntegration.TI.ClientContext.dll, and then click OK.

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

    using System;
    using System.Collections.Generic;
    using System.Text;
    using Microsoft.HostIntegration.TI;
    using REOBanking;
    
    namespace REOverride
    {
        class Program
        {
            static void Main(string[] args)
            {
                object[] contextArray = null;
                decimal Balance = 0.0m;
                ClientContext TIClientContext = new ClientContext();
                REOBanking.Accounts MyBankObj = new REOBanking.Accounts();
                try
                {
                    MyBankObj.GetBalance("Kim Akers", "123456", out Balance, ref contextArray);
                    Console.WriteLine("Account balance from the primary RE {0,9:C2}\n", Balance);
                    TIClientContext.WriteContext("REOverride", "SimHost ELM Link Secondary", ref contextArray);
                    MyBankObj.GetBalance("Kim Akers", "123456", out Balance, ref contextArray);
                    Console.WriteLine("Account balance from the Secondary RE {0,9:C2}\n", Balance);
                }
    
                catch (Microsoft.HostIntegration.TI.CustomTIException Ex)
                {
                    Console.WriteLine("Exception: TI Runtime Error {0}", Ex.Message);
                }
                catch (Exception Ex)
                {
                    Console.WriteLine("Exception: {0}", Ex.Message);
                    if (Ex.Message.StartsWith("ClassFactory cannot supply requested class", StringComparison.CurrentCultureIgnoreCase))
                    {
                        Console.WriteLine("Error: REOBanking object could not be created. Use TI Manager to ensure it is registered");
                    }
                }
    
                Console.WriteLine("\nPress any key to continue...");
                Console.Read();
            }
        }
    }
    
  9. On the File menu, click Save All.

  10. Click Build, and then click Build ConsoleApplication1.

  11. Click Debug, and then click Start Debugging.

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

Show: