HIS 2006 Tutorial: Connecting to an Application Using IMS Connect
IMS Connect is a programming model that provides access to information management system (IMS) transactions using TCP/IP.
The samples directory of Microsoft Host Integration Server (HIS) and BizTalk Adapters for Host Systems contains a sample application that connects to a host mainframe using IMS Connect. 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 file definition
-
Create a simple IMS transaction from a Windows-based environment to a host mainframe using TCP/IP
Before you start this tutorial, make sure to perform the following actions:
-
Install Microsoft® Visual Studio® 2005.
-
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.
-
Ensure that the account you are using is part of the HIS Administrators group.
To compile and run the IMS Connect sample, you must first 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 import the IMS Connect sample-
Click Start, point to Programs, point to Microsoft BizTalk Adapters for Host Systems, and then click TI Manager.
-
In TI Manager, expand the Transaction Integrator node.
-
Right-click the Window-Initiated Processing node, and then click Import.
-
On the Welcome to the Import WIP Definitions Wizard page, click Next.
-
On the Define Import Characteristics page, confirm that the Use Original Definitions option button is selected.
-
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\IMSConnect\TIHostApplicationDef.
-
On the Importing WIP Definitions page, wait for the import to complete, and then click Next.
-
On the Completing the Import WIP Definitions Wizard page, click Finish.
-
Right-click Start, and then click Explore.
-
Locate the SimHost folder.
For this sample, the SimHost folder is located in <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\System.
-
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 IMS connection.
-
Click Options, and then click Reset to default values.
-
In the IMS Connect dialog box, in the GetBal TranID field, enter GETBAL.
-
Click Start TCP.
-
In Visual Studio, on the File menu, click Open, and then click Project/Solution.
-
In the Open Project dialog box, locate the folder that contains the sample solution file.
For this sample, the sample solution file is located in <Installation directory>\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\WindowsInitiated\IMSConnect.
-
Click IMSConnect.sln, and then click Open.
-
Click Build, and then click Build Solution.
-
Click Debug, and then click Start Debugging.
A console window appears and displays the output of the application.
-
End the debugging session 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 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 application.
Step 1: Start SimHost
Start SimHost, which acts as a simulated host for this application.
To start SimHost-
Note that you do not need to start SimHost if it is still running as a result of completing the first IMS Connect sample.
-
Right-click Start, and then click Explore.
-
Locate the SimHost folder.
For this tutorial, the SimHost folder is located in <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\System.
-
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 IMS connection.
-
Click Options, and then click Reset to default values.
-
In the IMS Connect dialog box, in the GetBal TranID field, enter GETBAL.
-
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 tutorial.
To create an IMS Connect remote environment-
Note that you do not need to create a remote environment if you have already completed the first IMS Connect sample.
-
Click Start, point to Programs, point to Microsoft BizTalk Adapters for Host Systems, and then click TI Manager.
-
Under the Console Root, expand the Windows-Initiated Processing node, right-click Remote Environments, click New, and then click Remote Environment.
-
On the New Remote Environment Wizard, click Next.
-
On the Configure a New Remote Environment page, in the Name field, type SimHost IMSConnect, and then click Next.
-
On the Configure Host Environment and Programming Model page, in the Target host drop-down list, select IMS.
-
In the Programming model drop-down list, select IMS Connect, and then click Next.
-
On the Configure Endpoint TCP/IP page, in the IP/DNS address field, type localhost.
-
Click Edit, and in the In the New port field, type 9998, and then click Add.
-
In the IMS system ID field, type IVP1.
-
Click Next, and then click Finish.
Step 3: Create a New Project
The next step in the tutorial is to create a new project to hold the IMS Connect application. 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 IMS Connect application-
In Visual Studio, on the File menu, point to New, and then click Project.
-
In the New Project dialog box, in the Project Types pane, select Host Integration Projects.
-
In the Templates pane, select Transaction Integrator Project.
-
In the Name field, type IMSConnectTutorial.
-
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-
In Solution Explorer, right-click IMSConnectTutorial, point to Add, and then click Add .NET Client Library.
-
In the Add New Item dialog box, confirm that .NET Client Library is selected in the Templates pane.
-
In the Name field, type IMSBanking, and then click Add.
-
On the .NET Client Library page, click Next.
-
On the Library page, in the Interface Name field, type Accounts, and then click Next.
-
On the Remote Environment page, in the Target environment list, select IMS.
-
In the Programming Model list, select IMS Connect, and then click Next.
-
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 file, you can deploy the interface.
To import the host definition file-
On the menu bar in Visual Studio, click View, and then click Properties Window.
-
On the IMSBanking.dll tab, right-click the IMSBanking node, point to Import, and then click Host Definition.
-
On the Welcome to the Import COBOL Wizard page, click Next.
-
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\WindowsInitiated\IMSConnect\TIHostApplicationDef.
-
Click the GetBalance.cbl file, click Open, and then click Next.
-
On the Items Options page, type GETBAL for the Transaction ID field, and then click Next.
-
On the Input Area page, click to expand 01 INPUT-AREA, select the check box next to 05 NAME and 05 ACCNUM, and then click Next.
-
On the Output Area page, click to expand 01 OUTPUT-AREA, select the check box next to 05 ACCBAL, and then click Next.
-
On the Return Value page, click Next.
-
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-
On the IMSBanking.dll tab, click the GetBalance node.
-
In the Properties window, click the Include Context Parameter field, and then click False in the list.
-
On the File menu, click Save All.
-
Click Start, point to Programs, point to Microsoft BizTalk Adapters for Host Systems, and then click TI Manager.
-
Click to expand Transaction Integrator, click to expand Windows-Initiated Processing, and then click to expand Objects.
-
If IMSBanking.Accounts.1 exists in the list of Objects, right-click IMSBanking.Accounts.1 and then click either Force Undeployment or Delete (only one of these options will be available). Click Yes when prompted.
-
Right-click Objects and then click New, Object.
-
Click Next in Welcome to the New Object Wizard.
-
Click Browse and then locate the IMSBanking.dll file.
For this tutorial, the location of the IMSBanking.dll file will be <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\IMSConnectTutorial\IMSConnectTutorial\.
-
Click the IMSBanking.dll file, click Open, and then click Next.
-
On the Define Environment Characteristics for the .NET Object page, verify that the Self-Hosted option is enabled, and then click Next.
-
Select SimHost IMSConnect in the Remote environments drop-down list, and then click Next.
-
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 tutorial-
In Visual Studio, on the File menu, point to Add, and then click New Project.
-
In the Add New Project dialog box, in the Project Types pane, click Visual C#.
-
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 IMS Connect application-
In Solution Explorer, expand the ConsoleApplication1 node.
-
Right-click References, and then click Add Reference.
-
In the Add Reference dialog box, click the Browse tab, and then locate the IMSConnect folder.
For this tutorial, the IMSConnectTutorial folder is located at <Installation directory>\Program Files\Microsoft BizTalk Adapters for Host Systems\SDK\Samples\ApplicationIntegration\IMSConnectTutorial\IMSConnectTutorial.
-
Click IMSBanking.dll, and then click OK.
-
Add the following code to your Program.cs file:
using System; using System.Collections.Generic; using System.Text; using IMSBanking; namespace IMSConnect { class Program { static void Main(string[] args) { IMSBanking.Accounts MyBankObj = new IMSBanking.Accounts(); Decimal AccBal = 0.0m; MyBankObj.GetBalance("Kim Akers", "123456", out AccBal); Console.WriteLine("Account Balance = {0,9:C2}", AccBal); Console.WriteLine("\nPress any key to continue..."); Console.Read(); } } } -
On the File menu, click Save All.
-
Click Build, and then click Build ConsoleApplication1.
-
Click Debug, and then click Start Debugging.
-
End the debugging session by pressing a key on the keyboard or by closing the console window.