Luckily, Microsoft provides us with the right tools to integrate with System i and System z environments. These tools are packaged into Host Integration Server and allow you to integrate on different levels with Host environments:

• Network integration
• Application or Program integration
• Data integration (databases and Host files)
• Message integration (queuing)
• Security integration

In this post, I will go deeper into Application Integration. More specifically calling a piece of RPG code hosted on an AS/400 system. I will call the RPG program from BizTalk Server by using the adapter for Host Applications.

The scenario

The AS/400 is running a RPG program that returns the balance of someone’s account when passing his name and account number.
BizTalk Server will call into this RPG program by passing in the input parameters and receiving the return value (balance).
BizTalk Server will leverage the Adapter for Host Applications to make this distributed program call into RPG possible.

The RPG program looks like this (*will be used later, you don’t have to understand RPG code):

      *********************************************************************                        

      *  PROGRAM      – GBALDPC                                                                 

      *  DESCRIPTION  – AS400 GETBALANCE SERVER

      *  WRITTEN FOR  – MICROSOFT Corporation                                                             

      *********************************************************************                        

      *                                                                                            

     H                                                                                             

      *                                                                                            

      * Data Definitions                                                                           

      *                                                                                            

     D Name            s             30A

     D AccNum          S              6A                                                                 

     D AccBal          S              9P 2                                                         

      *                                                                                            

      * Mainline                                                                                   

      *                                                                                            

     C     *ENTRY        PLIST                                                                     

     c                   PARM                    Name                                              

     c                   PARM                    AccNum                                           

     c                   PARM                    AccBal                                            

      *                                                                                            

     c                   Z-ADD     2003.66       AccBal                                            

      *                                                                                            

     C                   EVAL      *INLR         = *ON                                             

For the sake of simplicity, but also to make it easy for you to reproduce this, I’m using the standard Microsoft ‘GetBal’ sample here.

Lets get started…

To realize this scenario, the following components are used to make this possible:

• AS/400 running the RPG program (In my case, the ‘real’ AS/400 will be replaced by a ‘simulator’ – because I don’t have an AS/400 on my laptop…)
• BizTalk Server 2013
• Host Integration Server 2013
• Visual Studio 2012

After you setup BizTalk Server and Host Integration Server (not part of this blog post), the work in Visual Studio can start.

Visual Studio will display 4 new project types that were installed together with Host Integration Server 2013.

The project types:

– BizTalk Pipeline Conversion
This project type allows to integrate with Host Data Structures without the use of the Adapter for Host Applications. This is very useful when you are – for example – reading a Host Data structure from a queue.

– Host Application
This project type is used when you call a Host program via a .NET program or via the BizTalk Adapter for Host Application (BAHA). The Host Application project type will describe how the Host Data Structure translates to .NET data structures and vice versa.

– Host Files
Project type to integrate with the Host File system (VSAM for example).

– Message Queuing
Project type to integrate with Host Queuing systems.

For this scenario, use the ‘Host Application’ project type and create a new project based on that template.

After creating the project, a blank canvas is presented:

To continue, we will create a .NET Definition. There are two types of .NET Definitions, a Client and a Server Definition.

The .NET Client Definition is used when .NET will call a program on the Host system (also called Windows-Initiated Processing or WIP).
The .NET Server Definition is used when the Host System will call a .NET program (also called Host-Initiated Processing or HIP).

In this case, we will call the Host program, so choose ‘Add .NET Client Definition’.

Name your .NET Client Definition:

On the next page, provide a name for the interface, and an initial version number.

The next page in the wizard looks like this:

Protocol: Choose the correct protocol that is used to communicate with your Host System (TCP, Http and LU6.2). AS/400 is using TCP so we select that. *note: when doing Mainframe integration 2PC (two-phase commit) will only be possible over LU6.2

Target environment: Choose the target environment. In this case System i Distributed Program Call (other options: System i, System z, CICS, IMS)

Programming model: DPC. The programming model depends on the Target environment that was selected. More information on programming models and their functionalities can be found here.

Host Language: Choose the language of the Host program that will be called. In this case RPG. (Can also be COBOL)

On the next screen in the Wizard, we have to tell in what Program library our Host program is located.
The Host administrator or programmer should be able to provide you this value:

Finally, when the wizard is complete, a new .NET Client Definition is added to the Host Application project.

Now that we have a base Host Application project with a .NET Client Definition, we are ready to import the data definition of the RPG program. This import will set the in/out and return parameters of the RPG program. This can be done by importing the RPG program, or manually by adding functions and parameters to the IBanking interface.

The easiest way is to import the RPG program. Right click the ‘GetBalClient’ and select ‘Import Host Definition’.

In the wizard, brows to the RPG program

When your RPG program is read without errors, the following screen of the wizard is shown:

Choose a friendly name for the method we will call. In this case ‘RPGGetBalance’.

The Library name is inferred from the information we entered earlier, this should be correct.
Finally, set the Program name. This is the Program name on the Host environment, this value should be given by the Host administrator (or developer).

On the next screen, set the direction of each parameter:

In this case, ‘NAME’ and ‘ACCNUM’ our input paramters. ‘ACCBAL’ is the return value.

Click ‘Finish’.

The Host Definition was imported successfully:

With that, our Host Application project is finished! We will now generate a DLL and Xsd schema that we can use in BizTalk Server.

Right click the Host Application project and click ‘Save AS400RPG’. (Unlike other .NET project types, a Host Application project is not compiled but saved!)

After saving, a DLL and XSD is generated in the projects folder structure.

We are now ready to setup the BizTalk part. We will keep the BizTalk part very simple. A receive location will read a request message from a File location, a solicit/response send port will send the request to AS/400, a send port will subscribe to the result and write it to an output folder.

Let’s focus on the solicit/response send port that will call the RPG program.

Open the send ports properties and select the HostApps adapter

Open the adapter’s configuration

Set the HostApps Transport properties as shown above.
Then click the ellipsis button on the ‘Connection Strings’ field.

The connection string windows is shown.

Click the ‘Add assemblies – Browse…’ button.

Browse to the DLL that was generated by the Host Application Project in Visual Studio.
The DLL is added to the connection string window:

Double click the newly added DLL to set it’s connection string properties:

Set a TimeOut value for call to the RPG program.

Scroll down to the TCP/IP properties:

Set the IP Adress and port number of the AS/400.

The send port to call the RPG program on AS/400 is not configured correctly.

The last thing to do is test our RPG integration. To do that, I will create a sample message based upon the Xsd Generated by the Host Application project.

My sample message looks like this:

<ns0:GetBalClient__Banking__RPGGetBalance__RequestTIAssemblyVersion=”1.0″xmlns:ns0=”
http://microsoft.com/HostApplications/TI/WIP”>
<ns0:RPGGetBalanceInDocument>
<ns0:NAME>Kim Akers</ns0:NAME>
<ns0:ACCNUM>123456</ns0:ACCNUM>
</ns0:RPGGetBalanceInDocument>
</ns0:GetBalClient__Banking__RPGGetBalance__Request>

When BizTalk picked up the message, the RPG program replied with the expected balance response:

<?xmlversion=”1.0″encoding=”utf-8″?>
<ns0:GetBalClient__Banking__RPGGetBalance__Responsexmlns:ns0=”
http://microsoft.com/HostApplications/TI/WIP”TIAssemblyVersion=”1.0″>
<ns0:RPGGetBalanceOutDocument>
<ns0:returnValue>777.12</ns0:returnValue>
</ns0:RPGGetBalanceOutDocument>
</ns0:GetBalClient__Banking__RPGGetBalance__Response>

As you can see, integrating with Host Programs (RPG, COBOL), is possible out-of-the box with BizTalk Server and Host Integration Server.
In straightforward scenarios like this, even no coding at all was necessary!

Peter Borremans