Implementing Gateway with Host Integration Server 2004

 

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Integration Patterns

Contents

Context

Background

Implementation Strategy

Example

Resulting Context

Tests

Context

Most medium-sized to large-sized organizations rely on a distributed environment where business logic operates on many different computing technologies. To the dismay of the software developers in these organizations, two of the most commonly used technologies can be difficult to integrate. These technologies are the Microsoft .NET Framework and the IBM Customer Information Control System (CICS) application subsystem. Implementing the Gatewaypattern allows developers to overcome incompatibility issues by integrating existing mainframe business logic into .NET Framework applications without having to redevelop the code that already exists in CICS.

You have decided to implement the Gateway pattern by using Microsoft Host Integration Server 2004 and its Transaction Integrator (TI) feature to enable .NET Framework applications to invoke mainframe transactions, to pass the proper input parameters to the transactions, and to finally receive the output parameters that are returned from the executing transactions.

Background

The Global Bank infrastructure integrates applications that run on several platforms. The account management system runs on a mainframe. Account management operations such as Create Account, Check Balance and Debit, Credit Account, Delete Account, and Get Account Information are implemented as CICS transactions. The integration solution must be capable of executing these transactions from the Microsoft Windows operating system. Global Bank decided to use Microsoft Host Integration Server 2004 and its Transaction Integrator (TI) feature as a Gateway implementation to invoke the individual CICS transactions included in the mainframe account management system. Using TI to call mainframe programs from a .NET Framework application is known as Windows-initiated processing.

Figure 1 depicts a high-level view of this configuration.

Figure 1. Global Bank implementation of Gateway

Although it does not apply in the case of Global Bank, a mainframe application developer can also use TI to access .NET Framework applications from a mainframe application. Using TI in this manner is known as host-initiated processing.

Note   The TI feature of Host Integration Server 2004 was named COM Transaction Integrator for CICS and IMS (COMTI) in previous releases of Microsoft Host Integration Server.

Implementation Strategy

Using Host Integration Server 2004 to implement Gateway typically requires the expertise of many different people, including a .NET Framework developer, a Microsoft network infrastructure engineer, a mainframe CICS developer, and a mainframe systems administrator, just to name a few. It is important for all personnel involved to clearly understand the Host Integration Server 2004 components and the implementation steps that are required to successfully deploy this Gateway implementation.

Host Integration Server 2004 includes the following components that are required to access mainframe CICS transactions:

• TI Manager. TI Manager is the administrative component that allows developers to configure TI options. In a Windows-initiated processing scenario, these options include configuring the mainframe transaction's operating environment. This operating environment is known as the remote environment. These options also include configuring Windows-initiated processing objects that are used to associate the metadata file with the remote environment. The metadata file is addressed later in this pattern.
• TI Designer. TI Designer is a Microsoft Visual Studio .NET plug-in that developers can use to build TI client objects. TI client objects are used to specify the methods to invoke on the mainframe transactions and to specify the input and output parameters to use with those methods.
• TI run-time component. The TI run-time component intercepts the method calls to and from the mainframe and uses the information in the TI metadata file to perform the actual conversion and formatting of the method parameters.

Because the implementation strategy relies primarily on the TI feature of Host Integration Server 2004, most of the strategy involves configuring TI. To properly configure TI, follow these steps:

1. Select the TI programming model. A TI programming model determines the method used to access and to integrate host transactions. You must determine which of the eleven available programming models you need to use to access the transactions.
2. Configure the mainframe environment. Ensure that the mainframe environment is properly configured to allow access by TI.
3. Configure the TI metadata file. The TI metadata file defines the methods, parameters, and data type mappings that are used when mainframe transactions are invoked.
4. Configure network protocol connectivity. You must implement the appropriate network protocol to provide network communications between TI and the mainframe. You can use Systems Network Architecture (SNA) Logical Unit 6.2 (LU 6.2) or Transmission Control Protocol/Internet Protocol (TCP/IP).
5. Configure a TI remote environment. A remote environment is a collection of properties that describes a region on the mainframe. You must configure a remote environment.
6. Add a Microsoft Internet Information Services (IIS) virtual directory. This virtual directory is the virtual directory where the TI request is processed. The virtual directory is used to store the Windows-initiated processing object that you configure in the next step.
7. Configure a Windows-initiated processing object. A Windows-initiated processing object establishes a relationship between the metadata file, the IIS virtual directory, and the remote environment. You must configure a Windows-initiated processing object.
8. Implement a .NET Framework client application to invoke the TI client interfaces. Finally, after all the TI-specific configuration is finished, you must implement the .NET Framework applications that use TI to invoke the mainframe transactions.

The following paragraphs describe these implementation steps in greater detail.

Step 1: Select the Programming Model

A TI programming model determines the method used to access host transactions and the TI configuration requirements. You must coordinate with the mainframe CICS developer and with the mainframe systems administrator to select the appropriate programming model.

The first decision to make when selecting a TI programming model is to determine which of the three supported transactions—CICS, Information Management System (IMS), or AS/400—is being accessed. TI supports eleven programming models. Six of these models are used to access the CICS mainframe transactions that are the subject of this implementation. The six programming models used to access CICS transactions are the following:

• LU 6.2 Link
• LU 6.2 User Data
• TCP/IP Enhanced Listener Mode (ELM) Link
• TCP/IP ELM User Data
• TCP/IP Transaction Request Message (TRM) Link
• TCP/IP TRM User Data

The other five models are used for accessing IMS transactions or OS/400 transactions. They are not discussed here.

The next critical decision in selecting the programming model is to choose the network protocol to use. TI can use either the TCP/IP network protocol or the LU 6.2 network protocol to communicate between the mainframe environment and the .NET Framework environment. LU 6.2 is the recommended protocol to use with TI for the following reasons:

• CICS transactions run more efficiently in an LU 6.2 environment than they do in a TCP/IP environment. CICS transactions run more efficiently because of the costly task-swapping techniques that CICS employs for executing transaction programs initiated by TCP/IP.
• It is easier to configure LU 6.2 on the mainframe than it is to configure TCP/IP.
• The LU 6.2 protocol supports two-phase commit transactions; the two-phase commit protocol is required to allow transactions to execute in a distributed environment across multiple systems. Two-phase commit transactions are only supported when the TI metadata file (addressed later in this pattern) is configured to use a Component Object Model (COM) type library.
• LU 6.2 supports the IBM Parallel Sysplex technology for network redundancy. Parallel Sysplex provides a mechanism that allows mainframe sessions to be reestablished automatically across a different route when an established route is interrupted.
• You can use LU 6.2 over an existing TCP/IP network as long as the Enterprise Extender is deployed on the mainframe. The Enterprise Extender is a feature of IBM mainframes that supports running LU 6.2 over the TCP/IP protocol. This configuration also supports two-phase commit transactions when using COM type libraries.

The two programming models that support the LU 6.2 protocol are LU 6.2 Link and LU 6.2 User Data. The key difference between these two programming models is how each handles data communications between TI and the CICS transactions. The LU 6.2 Link is the only one of the two models that uses the COMMAREA. The COMMAREA is a feature of CICS that allows COBOL transactions to pass data between them without requiring developers to incorporate the data communication logic into their code. Input and output parameters are easily passed in and out of the COMMAREA. When the COMMAREA is not in use, all data exchanged between transactions must be explicitly handled in the transaction code. Because many of the existing CICS transactions that are deployed in mainframe production environments are already coded to use the COMMAREA, using the COMMAREA is the simplest way for a TI developer to access CICS transactions. Therefore, LU 6.2 Link is the recommended programming model for using TI to access CICS transactions.

Note   If the existing CICS transactions are not coded to use the COMMAREA, or if they contain code that is used for something other than for processing business logic, the CICS developer must modify the transaction code to use the COMMAREA. The COMMAREA limits the amount of data that can be passed in and out of invoked transactions to 32 kilobytes (KB).

LU 6.2 Link Model: Components

The LU 6.2 Link model relies on a number of critical run-time components that support its functionality. Figure 2 depicts the TI run-time environment and components for the LU 6.2 Link programming model. Following the figure are descriptions of each of these components.

Figure 2. TI run-time environment for the LU 6.2 Link model

The LU 6.2 Link model uses the following components, as shown in Figure 2, to access mainframe transactions:

• .NET Framework application. The .NET Framework application invokes the TI client object for access to mainframe transactions.
• TI client object. The TI client object contains the necessary data and logic required to communicate with the CICS transactions.
• TI run-time proxy. The TI run-time component is used to establish the connection between the TI client object and the CICS mainframe transaction at run time.
• TI remote environment. The TI remote environment component is used to specify host connection parameters such as the network address, the security settings, and the communications model to use for accessing host transactions.
• Distributed Program Link (DPL) LU 6.2. DPL is the protocol that TI uses to communicate with CSMI.
• Mirror TP CSMI. The mirror CICS transaction is a special CICS transaction that acts as a gateway between transactions running in different CICS regions. The mirror transaction allows the transactions in the different regions to exchange data through the COMMAREA. TI takes advantage of this standard method of communication between CICS transactions to access mainframe transactions. The CICS transaction ID for the mirror transaction is CSMI. CSMI handles all LU 6.2 and transactional properties required on the communication.
• COMMAREA. The COMMAREA is an area of the mainframe transaction code that many CICS transactions that are written in COBOL use to exchange data. When using this model, TI appears to the mainframe transaction as a CICS transaction that exchanges data through the COMMAREA.
• CICS link-to-program. The CICS link-to-program is the CICS transaction that TI invokes on behalf of the client application. It contains the business logic being executed and is identified by its link-to-program name in the TI method call.
• DB2/VSAM. CICS usually uses the IBM SQL database that is named DB2 or the older Virtual Storage Access Method (VSAM) as the data storage mechanism for storing the data that is used by CICS transactions.

Using a Model Other Than LU 6.2 Link

If you cannot use the recommended LU 6.2 Link model because your existing environment does not allow you to use it, you can select one of the other five models to access CICS transactions:

• LU 6.2 User Data. Although this model uses the efficient LU 6.2 protocol, it does not use the COMMAREA. It therefore is more complex to implement. This model is best for situations where the mainframe transactions are not coded to use the COMMAREA and where the transaction code does contain communication handling data and business logic data. Because this model does not use the COMMAREA, it is not subject to the 32-KB COMMAREA limit. Instead, it supports an unlimited amount of data.
• TCP/IP Enhanced Listener Mode Link. This model is similar to the LU 6.2 Link model because it uses the COMMAREA. However, it uses TCP/IP instead of LU 6.2. The model also employs the mainframe's Enhanced Listener Mode (ELM). You would use this model when LU 6.2 is not configured for access to the mainframe and when CICS transactions are coded to use the COMMAREA.
• TCP/IP Transaction Request Message Link. This model is similar to the TCP/IP ELM Link model. The only difference is that it does not implement the ELM. ELM is preferred over Transaction Request Message (TRM); however, the newer ELM functionality may not be implemented in older versions of CICS.
• TCP/IP ELM User Data. This model is similar to the LU 6.2 User Data model because it does not use the COMMAREA. It therefore is more complex to implement. This model is best for situations where mainframe transactions are not coded to use the COBOL COMMAREA and where the mainframe only supports TCP/IP access.
• TCP/IP TRM User Data. This model is similar to the TCP/IP ELM User Data model. The difference is that it does not implement the Enhanced Listener Mode.

The remainder of this implementation focuses on the LU 6.2 Link model when programming models are mentioned. For more information about other programming models, see the Host Integration Server 2004 product documentation.

Step 2: Configure the Mainframe Environment

Mainframes are often already configured with everything that TI requires to gain access to the transactions, because most of what TI requires is used for internal integration between mainframe programs. The mainframe systems programmer and the CICS developer must make any changes that are required. .NET Framework developers are rarely capable of performing such configurations themselves. The following are the minimum CICS versions that must be installed on the mainframe to support TI in specific mainframe operating system environments:

• IBM CICS for MVS version 3 release 3, or later, to support an SNA LU 6.2 network connection
• IBM CICS Transaction Server for VSE/ESA version 2 release 1, or later, to support an SNA LU 6.2 network connection
• IBM CICS Transaction Server for OS/390 version 1, or later, to support an SNA LU 6.2 or TCP/IP network connection
• IBM CICS Transaction Server for z/OS version 2, or later, to support an SNA LU 6.2 or TCP/IP network connection
• IBM CICS Transaction Server for z/OS version 2 release 2, or later, to support Enhanced Listener Mode for a TCP/IP network connection

For more information about how to properly configure the mainframe for this or other programming models, see the Host Integration Server 2004 documentation.

Determine If Changes Are Required to the Existing Transactions

In some cases, CICS transactions may require some modification before you can use TI to access them. In the case of the LU 6.2 Link model, transactions that are not coded to use the COMMAREA must be modified by the CICS developer. Additionally, any embedded terminal-handling code must be removed before using TI with LU 6.2 Link.

Step 3: Configure the TI Metadata File

The TI metadata file is used to specify the methods, parameters, and data type mappings that are used when mainframe transactions are invoked. You must gather the pertinent information that is required to configure the file. This information is typically provided by the mainframe systems programmer, the mainframe CICS developer, and the .NET Framework developers who invoke the mainframe transactions.

The metadata file can be configured as a Component Object Model (COM) component library or as a .NET Framework client library by using the TI Designer plug-in for Visual Studio .NET.

To configure the TI metadata file

1. Create a Visual Studio .NET project. When you create the Visual Studio .NET project, choose HIS as the project type and TI Project as the template.
2. Add a .NET Framework client library or a COM client library. You use either the Add .NET Client Library Wizard or the Add COM Client Library Wizard to add the client library. When using a wizard to add either a .NET Framework client library or a COM client library, you must specify the following properties for the remote environment that this library will be associated with:
   • Vendor. Specify the vendor for this remote environment. In the Global Bank scenario, the vendor is Microsoft.
   • Protocol. Specify the protocol used to access the remote environment. This could be either TCP/IP or LU 6.2. In this scenario, the protocol is LU 6.2.
   • Target Environment. Specify whether the target environment is CICS, IMS, or AS/400. In this scenario, the target environment is CICS.
   • Programming Model. Specify the programming model to use. In this scenario, the programming model is LU 6.2 Link.
3. Develop the interface methods. A method in the TI metadata file has a direct correlation to a CICS transaction program on the mainframe. You must define a number of method properties. One important method property is Return Type. The Return Type property enables you to specify whether the method has a return value and, if so, to specify the data type for the value. Whether a method has a return value or not depends on the existing COBOL program and on how you want to handle the output data. Another important method property is Tran ID. The Tran ID method property enables you to specify the link-to-program name of the mainframe transaction. The link-to-program name is how CICS identifies this transaction in its tables. CICS uses this name to invoke the transaction for execution.
4. Configure method parameters. You must configure the parameters for the method. The parameters are the input and output values that the method uses when communicating with the mainframe transaction. Before configuring the parameters, you must identify the input and output parameters in the existing COBOL source code. You must then determine the data type to use for each parameter.

Determining the Transaction's Link-to-Program Name

CICS transactions are usually invoked using their link-to-program name. You must consult with the mainframe developer to obtain the names of the transactions that you want to invoke.

Importing COBOL by Using the COBOL Import Wizard in TI Designer

You can use the COBOL Import Wizard in the TI Designer to import COBOL source code to configure a method. As you move through the pages of the wizard, you extract the data declarations specified in the COMMAREA. The data declarations describe the input that is sent to the mainframe transaction and the output that is received from the mainframe transaction. The wizard uses the parameters specified in the COMMAREA and ignores all other content in the source file. When the wizard finishes, a new method is added to your client library. The method uses the parameters specified in the source file's COMMAREA.

Step 4: Configure Network Protocol Connectivity

Assuming that the physical network that connects the server running Host Integration Server 2004 TI and the mainframe is in place, the first step to establish connectivity is to configure the protocol you are using to access the mainframe. You can use either LU 6.2 or TCP/IP.

Configuring LU 6.2 Access

The LU 6.2 protocol is based on IBM Systems Network Architecture (SNA) - Advanced Program-to-Program Communications (APPC) protocol for network communications. When using LU 6.2 to access the host applications, you must configure Host Integration Server 2004 for LU 6.2 access to the proper CICS region. Although a full description of how to configure Host Integration Server 2004 for LU 6.2 access to the CICS region is not part of this pattern, it is important to know the following when configuring LU 6.2 access:

• The name of the local APPC LU that is configured on Host Integration Server 2004 for access to the CICS region corresponds to the independent LU 6.2 configured on the Virtual Telecommunications Access Method (VTAM) PU definition for that Host Integration Server 2004 connection.
• The name of the remote APPC LU configured on the Host Integration Server 2004 connection to the mainframe corresponds to the APPLID as configured on the VTAM APPL definition for the CICS region.
• The APPC mode configured for the LU 6.2 communications must correspond to the mode configured on the VTAM LU definition for the local APPC LU and on the mode used by the APPL definition in VTAM. The APPC mode typically specifies parameters such as the number of parallel sessions supported and the communication partner that is the contention winner.

Note    For more information about the steps to configure Host Integration Server 2004 for LU 6.2 access to a mainframe computer, see the Host Integration Server 2004 product documentation.

Configuring TCP/IP Access to Mainframe Transactions

If you are using TCP/IP, you must determine the TCP/IP address and the port number to use to access the proper CICS region. You must specify the TCP/IP address of the mainframe you want to access and the port number of the CICS region you want to access. A TCP/IP port number is associated with a CICS region on the mainframe. The port statement is used to define this relationship. The IBM-supplied Concurrent Listener (program EZACIC02, transaction ID CSKL) binds a socket to the port specified for a given CICS region and then waits for a client request on that port. When a client makes a request on a port associated with that CICS region, TCP/IP forwards the connection request to the Concurrent Listener in that CICS region.

Step 5: Configure a Remote Environment

A remote environment is a collection of properties that describes a region on the mainframe. You must configure a remote environment to specify the programming model to use with a TI component, to specify the protocol used to access the mainframe, and to specify other connectivity properties. You use the Remote Environment Wizard in TI Manager to create a remote environment.

The wizard allows you to specify values for the following properties:

• Remote environment name. Specify a name for this remote environment.
• Network protocol to use. Specify LU 6.2 or TCP/IP. In this scenario, the protocol is LU 6.2.
• Target host. Specify whether this remote environment is used to access CICS, IMS, or OS/400 transactions. The target host is the name of the Global Bank mainframe.
• Programming model. Specify one of the eleven programming models to use with this remote environment. In this scenario, the programming model is LU 6.2 Link.
• Local LU alias. Specify the name of the local APPC LU that corresponds to the independent LU 6.2 configured on the VTAM PU definition for the Host Integration Server 2004 connection.
• Remote APPC LU alias. The remote APPC LU corresponds to the APPLID as configured on the VTAM APPL definition for the CICS region.
• Mode name. The APPC mode configured for LU 6.2 communications must correspond to the mode configured on the VTAM LU definition for the local APPC LU, and it must correspond to the mode used by the APPL definition in VTAM.

Note   For specific instructions on how to create a remote environment, see the Host Integration Server 2004 product documentation.

Step 6: Add an IIS Virtual Directory

The IIS virtual directory is used to store the Windows-initiated processing object configured in the following step. This IIS virtual directory is associated with Windows-initiated processing and with the remote environment. The IIS virtual directory is then made available to .NET Framework applications that use this TI configuration to access mainframe transactions.

Step 7: Configure a Windows-Initiated Processing Object

A Windows-initiated processing object is used to establish a relationship between the metadata file developed using the Visual Studio .NET TI designer plug-in, the IIS virtual directory, and the remote environment configured in the TI manager.

The New WIP Object Wizard allows you to specify values for the following properties:

• Path. Specify the path to the metadata file you created in step 3.
• File. Specify the name of the metadata file.
• Virtual directory. Specify the virtual directory where this object is stored.
• Remote environment. Specify the name of the remote environment.

Step 8: Implement a .NET Framework Client Application to Invoke the TI Client Interfaces

At this point, TI has been configured to provide access to the CICS mainframe transactions. All that is left is to develop the .NET Framework client application that invokes the mainframe transactions.

Example

The Global Bank scenario discussed in this pattern serves as a perfect example of how to deploy TI into production. The following example describes the specific functions and configurations that are required to meet Global Bank's needs. The steps in the example follow the same implementation strategy described earlier and explain the decisions you would make along the way if you were actually deploying TI into production.

Global Bank needs a solution that enables its .NET Framework applications to invoke business logic that resides on mainframe CICS transactions. The CICS transactions are used for handling typical banking operations, such as obtaining account balances and processing debits and credits. This example illustrates how the TI Windows-initiated processing features can be implemented to meet Global Bank's requirements.

Components

To deploy TI into production, the following components must be available:

• Host Integration Server 2004 with TI installed
• Visual Studio .NET with the TI Designer plug-in installed
• An ASP.NET Web application used by bank staff to manage accounts
• Mainframe CICS transactions that can be used to implement the required account management functions

Functions

The business logic implemented in the CICS transactions performs the following functions:

• It creates accounts.
• It obtains account details.
• It obtains lists of accounts.
• It deposits funds into existing accounts.
• It withdraws funds from existing accounts.

This example illustrates how the functionality currently implemented in mainframe CICS transactions can be invoked for execution from a .NET Framework application environment.

The following are the steps required for configuring TI for this example.

Step 1: Select the Programming Model

To access the mainframe applications for Global Bank, you must first select the appropriate programming model. The first thing to determine is whether the CICS transactions that you want to access use the COMMAREA. You then have to determine whether to use the LU 6.2 or the TCP/IP protocol for communications.

After conferring with the CICS developer, you learn that each of these transactions is coded to use the COMMAREA. You also learn from the mainframe systems programmer that LU 6.2 is configured for access to the CICS region on the mainframe. Based on this information, which you collected from the mainframe personnel, you determine that it is best to use the LU 6.2 Link programming model for access to the transactions.

Step 2: Configure the Mainframe Environment

Although this step is crucial to the successful deployment of a TI solution, it usually cannot be performed by the .NET Framework developer. You must rely on the mainframe personnel to properly configure the mainframe environment. Fortunately, the software required by TI is usually already installed in most mainframe environments. The mainframe systems programmer only needs to give you access to the transactions.

When contacting the mainframe personnel, you learn that they were able to review the Host Integration Server 2004 documentation and verify that all mainframe components are properly configured to allow access to the CICS transactions by using TI.

Step 3: Configure the TI Metadata File

You now have to develop the TI metadata file. In this case, you will implement the metadata file as a .NET Framework client library because the solution is being implemented in the .NET Framework, and you do not have a requirement to provide two-phase commit capabilities. To develop the TI metadata file, you must complete the following steps:

1. Create a Visual Studio .NET project. When you create the project, choose HIS as the project type and TI Project as the template. Name the project GlobalBank.

2. Add a new .NET Framework client library. Add a .NET Framework client library to the GlobalBank project and use the parameters specified in the following steps:

   1. On the Library page of the New .NET Client Library Wizard, type GlobalBank as the interface name, and then type a description for the interface.
   2. On the Remote Environment page of the wizard, select the following information regarding the host environment:
   • Vendor: Microsoft
   • Protocol: LU 6.2
   • Target environment: CICS
   • Programming model: Link
   1. On the next Remote Environment page, type CSMI in the Transaction ID box, and then type MSTX in the Source box.

   The new client library appears in the Visual Studio .NET main pane. The wizard uses the parameters you specified to create the default interface.

3. Add the methods for the example. After adding the .NET Framework client library, you can add the methods to the new library. The methods hold a one-to-one relationship with the CICS transactions being invoked. Table 1 lists all the transactions available to the client through Windows-initiated processing and the corresponding method name. You must configure one method for each of the transactions that appear in this table. All the transactions have an integer return value that is an error code.

   To add a method, follow these steps:

   1. In the Visual Studio .NET main pane, expand the GlobalBank component, and then select the GlobalBank interface.

   2. Right-click the GlobalBank interface, and then click Add Method.

      The Method1 method appears.

   3. Configure the method properties for this first method and for the other methods used in this example.

   The following table lists the property values to use for each method. You can accept the default value for any of the properties not included in Table 1.

   Table 1: Transactions Available to the Client Through Windows-Initiated Processing

   Method name/ transaction name (Name Property)	CICS transaction link-to-program name (Link-to-Program Name Property)	Input parameters	Output parameters	Description
   CreateAccount	GBCREACC	AccountNumber AccountName	None	Creates an account with a zero balance.
   GetAccountDetails	GBGETACC	AccountNumber	AccountName Balance	Retrieves details of a single account.
   GetAccountList	GBACCLST	TotalCountReceived	Array of AccountNumber, AccountName, and Balance	Gets list of accounts.
   Deposit	GBDEP	AccountNumber Amount	NeGBalance	Deposits money in the account.
   Withdraw	GBWDL	AccountNumber Amount	NeGBalance	Withdraws money from the account if the funds are available.

Figure 3 shows the way that the Global Bank client object should appear after you configure the interface and all its methods.

Figure 3. Global Bank client object with methods configured (Click the image to enlarge it)

1. Add the method parameters. The method parameters establish a mapping between the parameter types in the .NET Framework environment and the COBOL data types in the mainframe environment. Add the method parameters for each transaction according to the information in Table 2.

   Table 2: Global Bank Method Parameters

   Transaction	Input parameters	Input/ output	.NET Framework data type	COBOL data type
   CreateAccount	AccountNumber	Input	Decimal	PIC S9(n)V9(n) COMP-3
   CreateAccount	AccountName	Input	String	PIC X(n)
   GetAccountDetails	AccountNumber	Input	Decimal	PIC S9(n)V9(n) COMP-3
   GetAccountDetails	AccountName	Output	String	PIC X(n)
   GetAccountDetails	Balance	Output	Decimal	PIC S9(n)V9(n) COMP-3
   GetAccountList	TotalCountReceived	Input	Integer	PIC S9(n) COMP
   GetAccountList	Array of AccountNumber, AccountName, and Balance	Output	Decimal, String, Deciman	PIC S9(n)V9(n) COMP-3, PIC X(n),PIC S9(n)V9(n) COMP-3
   Deposit	AccountNumber	Input	Decimal	PIC S9(n)V9(n) COMP-3
   Deposit	Amount	Input	Decimal	PIC S9(n)V9(n) COMP-3
   Deposit	NewBalance	Output	Decimal	PIC S9(n)V9(n) COMP-3
   Withdraw	AccountNumber Amount	Input	Decimal	PIC S9(n)V9(n) COMP-3

Figure 4 shows the way that the Global Bank client object should appear after you configure the method parameters.

Figure 4. Global Bank client object with parameters configured (Click the image to enlarge it)

Step 4: Configure Network Protocol Connectivity

You have already learned that LU 6.2 communications to the Global Bank mainframe are available and that the mainframe systems programmer has configured the proper mainframe applications to allow access to CICS transactions. The mainframe systems programmer also informed you that you should set your local APPC LU name to Local and your remote APPC LU name to GBCICS1. The mode name is PA62TKNU. Using this information, you configure LU 6.2 communications by using Host Integration Server 2004. For more information about how to configure LU 6.2 communications, see the Host Integration Server 2004 documentation.

Step 5: Configure a TI Remote Environment

Use the TI Manager to implement the remote environment for Global Bank. In the Remote Environment Wizard, specify the values for the properties according to Table 3. Accept the default values for any properties that are not listed in the table.

Table 3: Global Bank Property Values

Property	Value
Name	Global Bank Host
Network type	LU 6.2
Target host	CICS
Programming model	Link
Local LU alias	Local
Remote LU alias	GBCICS1
Mode name	PA62TKNU

Step 6: Add an IIS Virtual Directory

The IIS virtual directory is used to store the Windows-initiated processing object that you configure in the next step. This IIS virtual directory is associated with the Windows-initiated processing object and with the remote environment. It is then made available to .NET Framework applications that use this TI configuration to access mainframe transactions. In this example, you create an IIS virtual directory named GlobalBank in the C*:\Inetpub\Wwroot\GlobalBank* physical directory*.*

Step 7: Configure a Windows-Initiated Processing Object

Complete the following steps to configure a Windows-initiated processing object. In the TI Manager, add a Windows-initiated processing object by using the parameters and values listed in Table 4.

Table 4: Windows-Initiated Processing Object Property Values

Property	Value
Path	C:\GlobalBankSource\GlobalBank\DotNetTIObjects
File	ServerWIP.dll
Virtual directory	DefaultWebSite/GlobalBankWIP
Remote environment	Global Bank Host

Step 8: Implement a .NET Framework Client Application

At this point, TI has been configured to provide access to the CICS mainframe transactions. All that is left is to develop the .NET Framework client application that invokes the mainframe transactions.

Resulting Context

The Gateway implementation described here results in the following benefits and liabilities:

Benefits

• Reduced complexity. The gateway encapsulates data and protocol translations required to use the account management system.
• Reduced redevelopment efforts. Business logic that already exists on the mainframe transactions does not have to be redeveloped in the .NET Framework environment.
• Reduced need for retraining. .NET Framework developers do not have to become familiar with CICS or COBOL to use the existing mainframe transactions.

Liabilities

• Increased maintenance effort. Host Integration Server 2004 is an additional system that must be maintained.
• Lack of support for two-phase commit transactions when using .NET Framework client libraries. The .NET Framework client library used in this scenario does not support two-phase commit transactions. Many organizations rely on two-phase commit transactions for day-to-day operations, so this configuration may not suit them. Instead, they would have to use a COM type library that does support two-phase commit transactions.

Tests

To fully test the deployment of TI in this scenario, you must have access to a mainframe computer that is running the proper CICS transactions. However, you can use the TI host-initiated processing capabilities to simulate this access. For instructions on how to configure this simulation, see the Host Integration Server 2004 online documentation at https://www.microsoft.com/biztalk/en/us/host-integration.aspx.

Start | Previous

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

© Microsoft Corporation. All rights reserved.