HIS 2006 Tutorial: Creating a Persistent Connection

One of the main features of Microsoft Host Integration Server (HIS) is the ability to connect a Windows application to a host mainframe application. In doing so, HIS translates Windows commands into commands appropriate to the mainframe programming model. A common mainframe programming model involves the Customer Information Control System (CICS) over TCP/IP. For many programming models, this connection can be made persistent, so that HIS does not need to re-establish the connection for each method call.

The samples directory of Host Integration Server and BizTalk Adapter for Host Systems contains a sample application that creates a persistent connection. 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:

  • Create a remote environment
  • Import a host definition file
  • Deploy an interface
  • Create an application that uses a persistent connection

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.

The following procedures describe how to compile and run the Persistent Connection 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 application definition
  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 page of the Import WIP Definitions Wizard, click Next.

  4. On the Define Import characteristics page, confirm that the Use Original Definitions radio 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\WindowsInitiated\PersistentConnections\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. Click to expand the Window-Initiated Processing node.

  9. Click to expand Objects.

  10. Right-click PCBanking.Accounts.1, and then click Properties.

  11. Click the Remote Environment tab.

  12. Click to select SimHost ELM Link in the Remote environment drop-down list, and then click OK.

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.

To build and execute the Persistent Connection 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\PersistentConnections\.

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

  4. Click Build, and then click Build Solution.

  5. Click Debug, and then click Start Debugging.

    A console window will open that demonstrates using the TI client context to provide persistent connection Open, Use, and Close calls.

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

To simulate a persistent connection error
  1. In Visual Studio, in Solution Explorer, double-click Program.cs.

  2. Set a breakpoint at line 47, just prior to the persistent Close call.

  3. Click Debug, and then click Start Debugging.

    The application will run until it reaches your breakpoint, and then it will pause.

  4. In SimHost, click Stop TCP.

  5. In Visual Studio, click Debug, and then click Continue.

    The call will fail, at which point the application cleans the persistent connection.

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 Persistent Connection 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 a CICS ELM Link remote environment
  1. Note that you do not need to create a remote environment if you have already completed the first Persistent Connection sample.

  2. Click Start, point to Programs, then point to Host Integration Server, 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 box, 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 Visual Studio Project

After creating the remote environment, you can create a new project to hold the Persistent Connections sample. After you create the project, you can add a .NET client object, which will represent the remote programming API to your application.

To create a new project for the Persistent Connection sample
  1. In Visual Studio, on the File menu, select 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 PersistentConnTutorial.

  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 add a .NET client object
  1. In Solution Explorer, right-click PersistentConnTutorial, 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 PCBanking2, 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 PCBanking2.dll tab, right-click the PCBanking2 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\PersistentConnections\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 PCBanking2.dll tab, click the GetBalance node.

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

  3. On the PCBanking2.dll tab, click the PCBanking2 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, then point to Host Integration Server, 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 PCBanking2.Accounts.1 exists in the list of Objects, right-click PCBanking2.Accounts.1, and then click Force Undeployment. 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 PCBanking2.dll file.

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

  12. Click the PCBanking2.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
  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 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 Persistent Connection 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 PersistentConnTutorial folder.

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

  4. Click PCBanking2.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 <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\system\ folder.

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

  8. Add the following statement(s) at the top of the program file:

    using Microsoft.HostIntegration.TI;
    using PCBanking2;
    
  9. Define an object as an array that will contain the TI context information that is passed between the client and the TI Runtime using the following line of C# code, and then enter this code and subsequent lines of code into the Main() method of the console application:

    object[] contextArray = null;
    
  10. Define the TI Client Context utility object using the following line of code:

    ClientContext TIClientContext = new ClientContext();
    
  11. Create a decimal variable to store the output of the GetBalance() method using the following line of code:

    decimal Balance = 0.0m;
    
  12. Create an instance of the TI PCBanking Object using the following line:

    PCBanking2.Accounts MyBankObj = new PCBanking2.Accounts();
    
  13. Set the Client Context to indicate that a call is about to be made that will be the first ("Open") of possibly many calls on a connection and then execute the mainframe program using the following line of C# code (note that this call will establish the connection and the connection will remain open):

    TIClientContext.WriteContext("CONNTYPE", "OPEN", ref contextArray);
    MyBankObj.GetBalance("Kim Akers", "111111", out Balance, ref contextArray);
    
  14. Re-use of the existing connection occurs when additional calls are made. The TI Client Context information is automatically updated to reflect a connection state of "USE":

    MyBankObj.GetBalance("Kim Akers", "111111", out Balance, ref contextArray);
    Console.WriteLine("Account balance for Kim Akers account #111111 {0,9:C2}\n", Balance);
    
  15. Set the Client Context to indicate that a call is about to be made that will be the last ("Close") call on a connection and then Execute the mainframe program using the following line of C# code (note that when this call occurs the connection will be shut down):

    TIClientContext.WriteContext("CONNTYPE", "CLOSE", ref contextArray);
    Console.WriteLine("\nPress any key to continue...");
    Console.Read();
    
  16. On the File menu, click Save All.

  17. Click Build, and then click Build ConsoleApplication1.

  18. Click Debug, and then click Start Debugging.

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

Show: