BizTalk 2009 : Host Integration Server 2009 - Transaction Integrator

Transaction Integrator is the Host Integration Server feature that allows you to create and configure objects that will act as mainframe applications in the .NET context. It provides libraries, tools, and assistants to create wrappers and services that will access mainframe program by using SNA, TCP, or HTTP transports.

Transaction Integrator offers two mechanisms for legacy integration. The first one is called Windows-initiated processing (WIP). With WIP, you can create and manage .NET object definitions that will be used when triggering mainframe calls synchronously from the .NET clients. The second one is called host-initiated processing (HIP). With HIP, you can create listeners that will be able to receive requests from mainframes or AS/400 platforms. To summarize, both mechanisms were designed to close the loop between legacy platforms and the Windows world.

1. Enabling Transaction Integrator

To use Transaction Integrator, first you will need to enable it. During the setup configuration process, you will be asked to enable it and to provide a database server where the HIP database will reside. The HIP database is a SQL Server database whose main purpose is to store HIP configuration information. An important note here is that in a multiserver installation, you can share the same HIP database between multiple Transaction Integrator server instances. Bear in mind that even though all your Transaction Integrator servers will be using the same HIP database, Transaction Integrator WIP objects will not be shared across multiple servers or stored in the HIP database; consequently, you will have to use the export/import definitions wizard to deploy your Transaction Integrator objects. One of the benefits of using a shared HIP database for WIP is that whenever a user tries to manage the tracing, regions, or Transaction Integrator objects (including import/export features) for one Transaction Integrator server, the other ones will be automatically locked for performing those activities. Figure 1 shows the actions menu for the WIP feature.

Figure 1. WIP actions menu locked by user accessing remote TI server

For HIP applications, though, the HIP database allows remote administration. In a multiserver TI HIP installation, every TI HIP server can be managed from the other TI HIP servers that use the same TI HIP database.

2. Deploying Transaction Integrator Servers

The Transaction Integrator deployment options totally depend on your architecture. There is a base premise here. Transaction Integrator should be deployed on application servers. The reason for this is that if you deploy Transaction Integrator with the SNA Gateway services, Transaction Integrator will always try to use the local SNA Gateway services. Although having both Transaction Integrator and SNA Gateway services on the same box is a supported configuration, we don't recommend it for multilayer architectures. In multilayer architectures, scalability is a critical factor. So, unless you plan to scale out both roles (SNA and Transaction Integrator) always at the same time, you wouldn't want to have the servers with total dependency upon each other.

We recommend using Transaction Integrator nodeless servers. Basically, a Transaction Integrator nodeless server is a Transaction Integrator server that does not run the SNA Server service (it does still run the SnaBase service). In this configuration, requests can be routed to remote sponsor servers that provide SNA services and that make possible the execution of remote requests using Host Integration Server client-server connectivity. The effect is similar to installing an HIS client, which will implicitly be part of its sponsor Host Integration Server subdomain. Figure 2 shows the configuration screen you will need to populate with information about the sponsor servers.

Figure 2. Transaction Integrator nodeless server using sponsor server SNAHUB

Figure 3 shows three Transaction Integrator nodeless servers connected to an enterprise SNA Gateway. They use the 1477 and 1478 ports to access the SNA Gateway. A SQL Server is required to work with Transaction Integrator, so the port 1433 should be opened, and remote access should be enabled.

Figure 3. Transaction Integrator multiserver architecture

3. Programming Model

Transaction Integrator requires you to choose a programming model before creating your TI projects. A programming model is the definition of how Transaction Integrator will interact with the mainframe at the transaction level. Although the SNA Gateway is the low-level layer, now you will need to make sure that your application structure and data will be handled in an expected way for the mainframe application. There is a chart available in the product documentation that we strongly recommend you review, understand, and use; it's called "Choosing the Appropriate Programming Model," and you can find it at http://msdn.microsoft.com/en-us/library/aa770990.aspx. It is extremely important to bring this information to your customer and discuss with them the requirements and characteristics of every programming model. The following are the programming model requirements for the CICS LU 6.2 link programming model:

• IBM MVS operating system version 4.3 or later

• IBM CICS version 3.3 or later

• The CICS mirror transaction, which is included in CICS version 3.3 or later

• VTAM

• One or more CICS regions defined in an application (APPL) statement in VTAM with transaction programs configured

• The VTAM PU, LU, and mode definitions necessary to establish SNA connectivity

Once you have decided which programming model you will use, then you can design your Transaction Integrator solution. We will use the CICS LU 6.2 link programming model. This model is based on the LU 6.2 APPC independent sessions discussed earlier. With this model, the transaction is transferred from Transaction Integrator to the mainframe using Distributed Program Link (DPL) to a CICS transaction called CSMI. CSMI is known as a mirror transaction, because it is used to access mainframe transaction programs (TPs) on behalf of other TPs. It also issues the EXEC CICS link command in CICS and transfers the DFHCOMMAREA^[] with all the values populated in the Windows application. After the TP is executed, it returns the data to Transaction Integrator by issuing an EXEC CICS RETURN command.

^[] DFHCOMMAREA is the name of the data area, known also as the communication area, that is specified in the LINKAGE SECTION and is used by the COBOL programs to receive data.

In a nutshell, managing Transaction Integrator is about managing libraries. Therefore, before creating the Transaction Integrator object, you should plan ahead for the COBOL program you will need to invoke. Some things you should have handy are the program ID and the transaction ID. Your mainframe team should be able to provide you with these values, and each combination of these two values should represent a unique program in the CICS environment. But the most important resources will be the Host Definition-COBOL copybook when working with mainframes and the RPG copybook when working with AS/400. With Transaction Integrator, you can either create one host definition or import one. Transaction Integrator gives you the possibility of creating one from scratch by using legacy data types or importing one from a COBOL copybook definition. We prefer the second approach.

When working with the CICS link programming model, you are accepting that the size of each block of data that you send will be less than or equal to 32KB. This limitation has nothing to do with Host Integration Server; it is actually a restriction imposed by IBM on the size of the DFHCOMMAREAS.

Host Integration Server uses the CICS intersystem communication (ISC) concept to execute CICS transactions. SNA and APPC provide the needed network and APIs, and it is finally the DPL, which allows the execution of CICS link commands to transfer Transaction Integrator requests to the DFHCOMMAREA in the remote system.

There is an option in Transaction Integrator called Enable 32KB, which allows you to send 32KB and receive 32KB as the DFHCOMMAREA. We recommend you select it so you are using 100 percent of the DFHCOMMAREA size. There are also other important considerations when working with DFHCOMMAREAS. First, DFHCOMMAREAS can include an extraordinary number of fields. When the DFHCOMMAREA is imported using Transaction Integrator, your object definition will expose all the fields of the DFHCOMMAREA. Sometimes this number of fields can be a little overwhelming for .NET developers not used to manipulating more than five or six parameters per method. We recall once that we had to invoke a Transaction Integrator object whose definition had more than 45 parameters. Our advice here is to work with your COBOL programmer to totally understand the copybook she is preparing for you, and try to limit the number of fields when possible.

You should also review the data types that your program will receive and the data types that the program will have to send. They have to be compatible with the mainframe data types. For the complete list of the TI-supported data types, please visit http://msdn.microsoft.com/en-us/library/aa754292.aspx. Also review the COBOL UNIONS that you will need to populate and its corresponding discriminator, if available. Fortunately, Transaction Integrator can handle COBOL UNIONS and render dynamic content depending on the discriminator value. For example, you might have a valid EBCDIC array "redefined" as a set of COMP-3 values. Although a COBOL programmer can handle this situation easily, Transaction Integrator may fail if you don't specify a valid discriminator. Again, take the time to review and validate such things before taking the COBOL copybooks as input.

Another issue with copybooks is that you need to ensure that they follow basic COBOL coding rules. Sometimes we have received copybooks that break the rules. Table 1 presents the basic rules that a COBOL program should follow.

Transaction Integrator does evaluate some of the rules, but not all of them. The following are additional recommendations you may want to take into account when working with COBOL copybooks:

• Remember that COBOL is not case sensitive.

• Don't forget to add the dots at the end of every line. Although with the COBOL latest versions this is not required, be prepared.

• If there are REDEFINES in the copybook, talk to the mainframe team to verify the definition that you will actually use if there is no "discriminant" available.

• Remove any character other than the ones stated in the previous chart. Make sure you have the right count of characters.

One of the most important recommendations that we have for you when working with Transaction Integrator WIP is to include the Metadata Error Control Block. The Metadata Error Control Block is a Transaction Integrator feature that, once enabled, provides a COBOL program with an additional mechanism to report errors to Transaction Integrator. Instead of having a mainframe transaction "abending" because of a critical error, you can have the COBOL program write to one of the fields in the Metadata Error Control Block section to report to Transaction Integrator without even reaching the point in the code that triggers the abend. The Metadata Error Control block is shown here:

01 GETEMPINFO-META-DATA.
* META-DATA GENERATED BY TRANSACTION INTEGRATOR.
  02  LMETADATALEN                        PIC 9(9) COMP-4.       INOUT
  02  BSTRRUNTIMEVERSION                  PIC X(32).             INOUT
  02  BSTRMETHODNAME                      PIC X(32).             INOUT
  02  BSTRPROGID                          PIC X(40).             INOUT
  02  BSTRCLSID                           PIC X(40).             INOUT
  02  USMAJORVERSION                      PIC 9(4) COMP-4.       INOUT
  02  USMINORVERSION                      PIC 9(4) COMP-4.       INOUT
  02  SREADYTOCOMMIT                      PIC 9(4) COMP-4.       INOUT
  02  SWILLINGTODOMORE                    PIC 9(4) COMP-4.       INOUT
  02  SRETURNERRORTOCLIENT                PIC 9(4) COMP-4.       INOUT
  02  SERRORCODE                          PIC 9(4) COMP-4.       INOUT
  02  LHELPCONTEXT                        PIC 9(9) COMP-4.       INOUT
  02  BSTRHELPSTRING                      PIC X(256).            INOUT

To use the Metadata Error Control Block, you should select the Include All Metadata option in the Metadata field for the Transaction Integrator object. Bear in mind that there is no need to include the metadata COBOL definition in the copybook that you will import, but the mainframe team should include the metadata COBOL definition in the DFHCOMMAREA of the program that you are planning to call using Transaction Integrator.

4. Importing the Copybook

Once your COBOL copybook is sanitized and completely defined, you can start thinking about the import procedure. Other than COBOL coding rules, you should take some additional considerations from an application integration perspective into account when importing COBOL copybooks. During the import process, you will be required to enter information about transaction IDs, program names, and of course the programming model. Remember that the same naming conventions rules that are followed on the mainframe for transaction programs also apply to the Transaction Integrator. Program names should have a length of eight characters, while the CICS transaction IDs should have a length of four characters.

For the LU 6.2 CICS link programming model, you will have to specify a mirror transaction. A mirror transaction is a transaction provided by CICS to execute CICS transactions on behalf of other transaction programs. By default, the transaction CSMI is specified. You will also have to locate your DFHCOMMAREA in the copybook definition. You will have to enter the direction of the parameters (whether they are input, output, or input/output).

Let's take a look at a COBOL copybook. The following shows a simple COBOL program that returns static data. We have put the DFHCOMMAREA definition in bold, because it will be used in the import process.

IDENTIFICATION DIVISION.
PROGRAM-ID. GTEMPINF.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
01 DFHCOMMAREA.
   05 CODEMP                         PIC X(5).
   05 EMPLOYEE-INFO.
       10 LO-HR-DATA.
          15 LO-HR-FNAME             PIC X(30).
          15 LO-HR-LNAME             PIC X(30).
          15 LO-HR-FULLNAME          PIC X(71).
          15 LO-HR-DNI               PIC X(08).
          15 LO-HR-STAT              PIC X(01).
          15 LO-HR-REQ               PIC 9(10).
          15 LO-HR-CONTRIB-LAST2     PIC 9(10).
          15 LO-GRADE OCCURS 2 TIMES PIC X(02).
          15 FILLER                  PIC X(90).
       10 LO-PRJ-MGMT.
          15 LO-PRJ-DPT OCCURS 2 TIMES.
             20 LO-PRJ-ID            PIC X(05).
             20 LO-PRJ-NAME          PIC X(40).
             20 LO-DIR-REP           PIC X(10).
             20 LO-PRJ-DES           PIC X(10).
             20 LO-PRJ-VERT          PIC X(65).
*
* THIS PROGRAM READS THE CODEMP VALUE AND FILLS IN THE
* HR DATA AND PROJECT DATA FOR THAT PARTICULAR EMPLOYEE
* DATA IS RETURNED TO THE CALLING PGM VIA THE DFHCOMMAREA
*
PROCEDURE DIVISION.
    IF CODEMP = 'HVCUN' THEN
       MOVE SPACES TO EMPLOYEE-INFO
       MOVE 'Harold' TO LO-HR-FNAME
       MOVE 'Campos' TO LO-HR-LNAME
       MOVE 'Harold Campos Urquiza' TO LO-HR-FULLNAME
       MOVE '99999999' TO LO-HR-DNI
       MOVE '1' TO LO-HR-STAT
       MOVE '1234567890' TO LO-HR-REQ
       MOVE 'A+' TO LO-GRADE(1)
       MOVE 'A+' TO LO-GRADE(2)
       MOVE '00010' TO LO-PRJ-ID(1)
       MOVE 'Legacy Integration with .NET' TO LO-PRJ-NAME(1)
       MOVE '10' TO LO-DIR-REP(1)
       MOVE 'Legacy Integration' TO LO-PRJ-DES(1)
       MOVE 'RETAIL'TO LO-PRJ-VERT(1)

					  

MOVE '00011' TO LO-PRJ-ID(2)
       MOVE 'Legacy MIgration to .NET' TO LO-PRJ-NAME(2)
       MOVE '45' TO LO-DIR-REP(2)
       MOVE 'Legacy Migration' TO LO-PRJ-DES(2)
       MOVE 'BANKING' TO LO-PRJ-VERT(2)
   END-IF.
   EXEC CICS RETURN END-EXEC.

Figure 4 presents the outcome of the Transaction Integrator import process for the copybook. The Visual Studio template for the Host Applications project required to create Transaction Integrator objects is available only when you select the development support option during the product installation. Visual Studio 2005 and Visual Studio 2008 are supported.

Figure 4. Transaction Integrator object definition after the import process

Host application projects support .NET and COM libraries. For .NET, in WIP scenarios, a .NET Client Library template should be selected. The other option is use the .NET Server library template, which is used in host-initiated processing scenarios. One of the additions to Host Integration Server 2009 is the support of WCF. In previous editions, there was support for web services and BizTalk Server templates. Now, with the addition of the WCF support, the TCP and HTTP bindings are available as are behaviors for metadata with exceptions.