HostBridge Technology


JavaScript-Java Integration on z Systems (and under CICS!)

From Russ
November 3, 2011 (Updated Sept 28, 2015)

At HostBridge, we enjoy tackling projects that force us to do new things. Not only do they test our products, they also test us. They also tend to be projects that yield a buzz-word bingo in a single paragraph.

A (Very) Unique Scenario

Recently we were presented with the following scenario:

Company A has CICS applications running on an IBM z Systems mainframe. They use HostBridge as their application integration hub. Company A needs to access apps/data hosted by Company B. These apps also happen to run on an IBM z Systems mainframe; in fact, they run under CICS. But Company B has a “standard” for how their system should be accessed: TN3270 over SSL.

Our first reaction was: “Seriously? TN3270 over SSL? That’s the only way?” Yes, they were serious.

It turned out that, in the past, Company B permitted mainframe-to-mainframe connections via SNA/SNI. On top of this infrastructure, they supported CICS region-to-region connections. However, in an effort to modernize their infrastructure, they decommissioned SNA in favor of TCP/IP. At the same time they determined that their new standard for connecting to their z System CICS apps would be TN3270 over SSL. This probably seemed justified in light of the fact that (a) most of their key apps were still 3270-based, and (b) most of their customers accessed their system from distributed workstations and/or servers. Their customers were (and apparently still are) accomplishing integration on the back of a 3270 emulation layer. Realistically, they probably had few (if any) customers who wanted to access their services programmatically from another z System mainframe.

That was then…this is now. Welcome to the new age of possibilities opened up by products like HostBridge running under CICS TS and on z Systems.

Never mind that the “right” way to do this would be to interconnect the two z/OS systems in a more closely coupled manner... Perhaps the CICS regions could be allowed to interoperate over TCP/IP using some of the modern CICS TS features. Better yet, Company B could install HostBridge on their mainframe and use it to publish bona fide, secure Web services that can be consumed by anyone (including HostBridge on Company A’s mainframe). But the fact was, Company B had spent a lot of time and money standardizing on TN3270 over SSL, and none of these were going to happen.

With this as the backdrop you can probably appreciate our quandary: How were we going to get HostBridge, running under CICS, to make an outbound connection via TN3270 (with SSL) and interact with the remote application? That is a requirement we had certainly never encountered before.

Understanding the Requirements

HostBridge has been specifically architected to be a high-performance, high-fidelity integration tool for CICS. I use the phrase “high fidelity” to denote that HostBridge allows the highest degree of interaction with the target apps. A HostBridge integration script can “see” or “hear” the app at the finest level (think high-definition TV compared to standard-definition). Our thesis has always been that low-fidelity integration marginalizes many valuable, albeit legacy, apps. So our objective with HostBridge is to allow the integration script to control the full range of functional capabilities of the existing apps.

So what does this mean in practical terms? It means we try to avoid using 3270 data streams as the basis of the integration (we much prefer the CICS Link3270 Bridge interface). And more to the point, we never even considered incorporating TN3270 Client functionality under the covers of HostBridge. Along the way we did add support for the CICS FEPI interface, but FEPI only allows a HostBridge script to interact with a 3270 app within an SNA domain (via VTAM). However, Company B had eliminated this option as part of their standardization effort years ago.

Thus, in order to prototype what Company A needed, we were going to have to integrate a full-function TN3270 Client – with SSL support – under the covers of HostBridge. When we broke the problem down, the list of key functional components and capabilities included:

That’s a tall order. In fact, to our knowledge, it had never been done before.

Choices and Tradeoffs

The short list of TN3270 Client candidates that could fit our requirements was very short (i.e., commercial products or code bases). After investigating various alternatives, we implemented our prototype by partnering with Red Oak Software. The nucleus of Red Oak’s Legacy Integrator (ROLI) product is a top-notch TN3270 Client that includes SSL support. Additionally, ROLI has a strong bias toward programmatic integration (which is exactly what we wanted). So far, so good. However…

ROLI is written in Java, and this raised some interesting technical issues because the HostBridge JavaScript Engine (HB.js) is written in C/C++ (which is why it performs so well). So we had a choice:

After we debated the pros and cons, we decided on Option 2. It might be more work, but it made perfect sense. The fact that IBM is continuing to make significant improvements in Java support under CICS TS (version 4.2 specifically) clinched the deal. We were going to have to cross the JavaScript-to-Java bridge sooner or later.

Invoking Java from JavaScript

But wait… Invoking Java from JavaScript is not new. It’s been around for years in the form of LiveConnect: a feature of Web browsers that allows JavaScript and Java software to interact within a Web page. (In fact, if you are reading this article on the Web, it might be happening right in front of you.) And since our philosophy with the HostBridge JavaScript Engine has always been to make the server side of the world work exactly like the client side, it made perfect sense to start our journey using LiveConnect.

Porting LiveConnect to z Systems (and running under CICS/HostBridge) turned out to be challenging for various reasons – mostly due to differing character set assumptions (EBCDIC vs. UNICODE). However, once those issues were isolated everything worked fine.

Running HostBridge Under a JVM

Whether we used LiveConnect or not, one thing was clear: if we are going to invoke Java methods from HB.js, HostBridge would have to run within the context of a Java Virtual Machine (JVM). Furthermore, in order to live comfortably within the constructs of CICS, this meant that the top level wrapper program must be written in Java. We named it HBR$JSEJ and defined it to CICS with the following attributes:

In the JVMProfile, the following lines are critical:

Since this is the top-level program for the CICS transaction, CICS will start it on a Java TCB. As mentioned already, HBR$JSEJ is a just a wrapper program.

Here’s the source:


HBR$JSEJ is very simple (at least for Java). All it really does is make a JNI call to a C/C++ function run_jse() – which is another simple wrapper program. All run_jse() does is LINK to the HostBridge JavaScript Engine — HBR$JSE. The reason we wrote this program in C/C++ (using the EXEC CICS API), instead of Java (using the JCICS API) is so we can get the COMMAREA and EIB pointers and use them to LINK to HBR$JSE.

Here’s the source:

By using these two simple wrapper programs, the HostBridge JavaScript Engine, HBR$JSE, receives control running on a CICS Java TCB. As a result, it (and/or LiveConnect) can use JNI to invoke Java methods.

LiveConnect Implementation

We chose to implement LiveConnect as a separate module so that the install cost is only incurred if the script actually needs this capability.

HBR$DLC is statically LINK’ed to HBR$DLCI.

There’s not too much more to be said about LiveConnect… It just works.

Sample HostBridge Script

Now that the infrastructure has been described, let’s look at what we can do with it. Specifically, let’s show how we can solve Company A’s problem: programmatically access apps/data hosted by Company B using a TN3720 and SSL connection. The JavaScript program below uses methods supported by Red Oak Legacy Integrator.

Here is the sample script:

Invoking the Sample

Assuming that the above script was named as “liveconnect1”, the following HTTP request could be used to invoke it:


Note that hb_proc= specifies that our Java top-level program should be used.


Our journey to achieve JavaScript-to-Java integration started with a real-world customer scenario: Company A wanted to use HostBridge to programmatically access apps and data hosted by Company B. However, those apps/data were only accessible via TN3270 and using SSL. While this scenario highlights the unintended consequences of standardization decisions made a decade ago, it also created the opportunity for us to do something new: support JavaScript-to-Java integration on z Systems and under CICS.

If you have any thoughts, comments, or questions about this, please let us know. We always enjoy projects that illustrate the power and flexibility of server-side JavaScript on System z.

1 Legacy Integrator™ is a product from Red Oak Software, Inc. ( Red Oak specializes in Transaction Integration™ solutions for legacy and Web application systems.