I recently worked on a pilot to access RPG programs on an IBM AS/400 from BizTalk Server 2006. We used the new Host Applications adapter which is included with the Microsoft BizTalk Adapters for Host Systems (which is available for free as long as you have a BizTalk Server 2006 license.)
The pilot went smoother than I thought it would and it was pretty easy for the most part. We did run into a few issues which I will cover in this post. Before I cover the issues though, I would like to provide some context for using the Host Applications adapter:
- The documentation is heavily focused on Host Integration Server 2006 (my naïve understanding is that the BizTalk Adapters for Host Systems and HIS 2006 are largely the same product) and it is hard to get a grasp of what you need to review in the docs; however, in the Operations section of the docs there are sections on the BizTalk Adapters for Host Systems: Host Applications, Host Files, DB2, WebSphere MQ (client-side, does not require a Windows version of WebSphere MQ.)
- For the Host Applications adapter, you can’t just install the adapter – you need TI Manager, Dev Tools, etc. When installing the adapters, we used the default settings, which installs lots of HIS components (and the 4 BizTalk adapters) but it does not upgrade Enterprise Single Sign-On to version 4.0 (version 4.0 is included with HIS 2006, version 3.0 is included with BizTalk 2006.)
- You will have additional services running after installing the BizTalk Adapters for Host Systems so make sure you have a beefy development machine if you are going to be utilizing these adapters.
- The docs state that you need Windows 2003 to connect to an RPG program using the Host Applications adapter but it works fine from my laptop running Windows XP SP2.
- You must generate metadata (.dll and .xsd) to use the Host Applications adapter – check out the docs for more info on doing this.
- You must configure a Remote Environment in TI Manager to use the Host Applications adapter – check out the docs for more info on doing this.
Issues
We only ran into a couple of major issues. The first issue was that when connecting to RPG programs we would get an error message complaining that the programs didn’t have a PLIST – when using the Host Applications adapter to communicate with an RPG programs that RPG program must have PLIST. If it doesn’t, you will not be able to generate the Transaction Integrator .dll and .xsd (metadata necessary for connecting to the RPG programs.) My understanding of a PLIST is that is something analogous to an interface in the .NET world. We examined two different courses of action to work around this issue. The first was to call the RPG programs from DB2 stored procedures and then use the DB2 adapter to access the mainframe. The second option, which we opted to use, was to have the mainframe developers create small wrapping RPG programs which contained PLISTs and then call the program that we really want to access. This worked very well.
The second major issue was that we didn’t know the port number that we needed to use to connect to the mainframe. In our case it was 8475 (this appears to be the standard port to call RPG programs on AS/400s.)
Minor Issues and Other Notes
We did not use SSO with the Host Application Adapter (some parts of the docs seem to imply that you must use SSO.) We used the TIClientContext elements that are part of the generated .xsd and passed in the USERID and PASSWORD by including them in the message sent through the adapter:
<ns0:TIClientContext TIContextKeyword="USERID" TIContextValue="theuserid" />
<ns0:TIClientContext TIContextKeyword="PASSWORD" TIContextValue="thepassword" />
If you do this, you must set the Set the ‘Allow Security Overrides’ send port adapter configuration property to ‘Yes’. Additionally, in TI Manager, for your Remote Environment, you must check the ‘Require client provided security’ on the Properties-Security tab.
We had to use the XmlReceive pipeline on the solicit-response Host Application adapter send port to get the response message back to our orchestration. The default is of course the PassThruReceive pipeline.