HIS 2006 Tutorial: Using Discriminated Unions

A discriminated union is a data structure whose value can be considered as one of several fixed data types. For example, a discriminated union could hold a value that could be considered an integer, a real number, or a character, depending on how the application interprets that value. To program with a discriminated union, you must set up a discriminant value table (DVT). A DVT contains the logic for determining which possible value a discriminated union should return.

The samples directory of Microsoft Host Integration Server (HIS) and BizTalk Adapters for Host Systems contains a sample application that uses discriminated unions. 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
  • Modify a discriminant value table
  • Create an application that uses a discriminated union

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.

This section provides a simple walkthrough on how to build a project that uses discriminated unions. It also sets up environmental parameters that you can use in the step-by-step tutorial.

To import the Discriminated Unions sample
  1. Click Start, point to Programs, point to Microsoft BizTalk Adapters for Host Systems, and then click TI Manager.

  2. In TI Manager, expand the Transaction Integrator node.

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

  4. On the Welcome page of the Import WIP Definitions Wizard, click Next.

  5. On the Define Import characteristics page, confirm that the Use Original Definitions radio button is selected.

  6. 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\DiscriminatedUnions\TIHostApplicationDef.

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

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

  9. Click to expand the Window-Initiated Processing node.

  10. Click to expand Objects.

  11. Right-click Banking.Accounts.1, and then click Properties.

  12. Click the Remote Environment tab.

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

To start SimHost for the Discriminated Unions 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 Start TCP.

To build and execute the Discriminated Unions 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\DiscriminatedUnions.

  3. Right-click DiscriminatedUnions.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 pressing a key on the keyboard or by closing the console window.

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 for the Discriminated Unions sample
  1. Note that you do not need to start SimHost if it is still running as a result of completing the first Discriminated Unions 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 Discriminated Unions sample.

  2. Click Start, point to Programs, 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, click CICS.

  7. In the Programming model drop-down list, click 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 remote environment, you can create a new project to hold the Discriminated Unions 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 Discriminated Unions 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 DiscrUnionTutorial.

  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 DiscrUnionTutorial, point to Add, and then click Add .NET Client Library.

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

  3. In the Name field, type Banking, 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 Target Environment drop-down list, select CICS.

  7. In the Programming Model drop-down list, 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 Banking.DLL tab, right-click the Banking node, point to Import, and then click Host Definition.

  3. On the Welcome page of the Import COBOL wizard, 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\DiscriminatedUnions\TIHostApplicationDef.

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

  6. On the Item Options page, click Next.

  7. On the 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 05 SSN field, and then click In.

  10. Click the arrows next to the 05 ACCT-ARRAY OCCURS 2 TIMES field, and then click In\Out.

  11. Click Next.

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

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

Step 6: Modify the Discriminant Value Table

Once you have imported the host definition file, you can modify the discriminant value table.

To modify the discriminant value table
  1. On the Banking.DLL tab, expand the Banking node, expand the Accounts node, expand the GetAInfo node, and then expand the ACCT_ARRAY node.

  2. Right-click the UNION1 node, and then click Properties.

  3. In the Properties window, in the Discriminant field, click the drop-down button, and then click the ACCT_ARRAY.ACCT_TYPE value.

  4. Click the DVT field, and then click the ellipsis (…) button.

  5. In the Discriminant Value Table dialog box, click the drop-down button under the Union Member field, and then click CHECKING.

  6. Double-click the field in the Condition column, and then type C.

  7. In the Union Member column, click the drop-down button under the CHECKING field, and then click SAVINGS.

  8. In the Condition column, type S under the C condition.

  9. Click OK.

Step 7: Save and Deploy the Interface

Once you have modified the discriminant value table, you need to deploy the interface. Then, you can create an application that uses the interface.

To save and deploy the Accounts interface
  1. In the Banking.DLL tab, click the GetAInfo node.

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

  3. In the Banking.DLL tab, click the Banking 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 Banking.Accounts.1 exists in the list of Objects, right-click cBanking.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\DiscrUnionTutorial\DiscrUnionTutorial\.

  12. Click the Banking.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 8: 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 Discriminated Unions sample
  1. In Visual Studio, on the File menu, select 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 9: 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 Discriminated Unions 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, select the Browse tab, and locate the DiscrUnionTutorial folder.

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

  4. Click Banking.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 Banking;
    
    namespace ConsoleApplication1
    {
        class Program
        {
            static void Main(string[] args)
            {
                Banking.Accounts MyBankObj = new Banking.Accounts();
                Banking.ACCT_ARRAY[] accountInfoArray = new Banking.ACCT_ARRAY[2];
                Banking.SAVINGS MySavInfo = new Banking.SAVINGS();
                Banking.CHECKING MyChkInfo = new Banking.CHECKING();
    
                accountInfoArray[0].ACCT_NUM = "SAV1234567";
                accountInfoArray[0].ACCT_TYPE = "S";
                accountInfoArray[0].UNION1 = MySavInfo;
    
                accountInfoArray[1].ACCT_NUM = "CHK4566112";
                accountInfoArray[1].ACCT_TYPE = "C";
                accountInfoArray[1].UNION1 = MyChkInfo;
    
                MyBankObj.GetAInfo("11223333", ref accountInfoArray);
    
                foreach (ACCT_ARRAY aa in accountInfoArray)
                {
                    switch (aa.ACCT_TYPE)
                    {
                        case "C":
                            Banking.CHECKING ChkInfo = (Banking.CHECKING)aa.UNION1;
                            
                            Console.WriteLine("Checking account number: {0}", aa.ACCT_NUM);
                            Console.WriteLine("\tOverdraft charge:\t {0,10:C2}", ChkInfo.CHK_OD_CHG);
                            Console.WriteLine("\tOverdraft limit:\t {0,10:C2}", ChkInfo.CHK_OD_LIMIT);
                            Console.WriteLine("\tLinked account:\t {0,18}", ChkInfo.CHK_OD_LINK_ACCT);
                            Console.WriteLine("\tLast Statement:\t {0,18}", ChkInfo.CHK_LAST_STMT);
                            Console.WriteLine("\tDetail Items:\t {0,18:F0}", ChkInfo.CHK_DETAIL_ITEMS);
                            Console.WriteLine("\tBalance:\t {0,18:C2}\n", ChkInfo.CHK_BAL);
                        break;
    
                        case "S":
                            Banking.SAVINGS SavInfo = (Banking.SAVINGS)aa.UNION1;
                            
                            Console.WriteLine("Savings account number: {0}", aa.ACCT_NUM);
                            Console.WriteLine("\tInterest rate:\t {0,20:P}", SavInfo.SAV_INT_RATE / 100);
                            Console.WriteLine("\tService charge:\t {0,18:C2}", SavInfo.SAV_SVC_CHRG);
                            Console.WriteLine("\tLast Statement:\t {0,18}", SavInfo.SAV_LAST_STMT);
                            Console.WriteLine("\tDetail Items:\t {0,18:F0}", SavInfo.SAV_DETAIL_ITEMS);
                            Console.WriteLine("\tBalance:\t {0,18:C2}\n", SavInfo.SAV_BAL);
                        break;
    
                    default:
                        break;
                    }
                }
                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: