Since its introduction in 2008, Valence has helped countless IBM i developers create top-notch web and mobile apps using some of the slickest UI technology available.  As the customer base grew, CNX introduced a number of additional development tools to Valence, including AutoCode and App Builder, to make the process of creating and deploying apps as easy as possible. 


But despite all this UI wizardry for creating NEW applications, many companies running on IBM i today still rely on core applications rooted in the AS400 days, which means their users must interact frequently with green screen programs as they go about their jobs.  While Valence has supported IBM i Access for Web for many years as a mechanism for integrating 5250 screens into Valence, the integration with Valence was less than ideal and the interface leaves a bit to be desired when compared to standalone clients like TN5250 or Client Access/ACS.

So with last month's release of Valence 5.2+ CNX is pleased to announce a new feature, at no additional cost, to more effectively address the legacy green screen user base — a revolutionary approach to integrating 5250 apps into the portal for a seamless user experience.  Available as of Valence 5.2.20180528.0, Fusion5250 is a brand-new socket-based app that runs right alongside all your standard Valence apps with no special configuration required.  You just launch the app and you're logged in — no special servers to set up or configure.  It just works!

And it's the underpinnings to Fusion5250 that has us most excited.  While already impressive for being a true HTML5-based emulator for IBM i, the "secret sauce" behind Fusion5250's functionality is some behind-the-scenes wizardry in which the 5250 data stream is converted to and from standard JSON segments.  This JSON-based foundation means terminal emulation is just the first of many super useful features in the pipeline for legacy applications running on IBM i.  For instance, the JSON data extracted from 5250 screens could ultimately be extended for use in other applications such as NAB apps, web services, batch processes and much more.

But for now we're focused on the emulator so let's dive into how it works.

Once you've downloaded and installed the latest build of Valence 5.2+, you'll notice a new Fusion5250 icon in the "Utilities" section of the Valence Portal launchpad.

New Fusion5250 App

Figure 1 - New Fusion5250 tile on Valence Portal Launchpad

Click on this tile to launch the app, then you should be automatically logged into an IBM i terminal session running on the same partition hosting your Valence instance.  From the system's perspective, this is a standard telnet session, no different than using Client Access, ACS, TN5250, Rumba or whatever your favorite 5250 emulator might be.

Initial Fusion5250 screen - default theme

Figure 2 - Initial Fusion5250 screen after login (standard theme)

Since Fusion5250 is an HTML5-based emulator, standard styling elements can be applied to "dress up" the look and feel of the page.  The default look is the universally familiar green-on-black interface, but you can click on the palette icon on the upper left to switch to different pre-configured themes.  In a future blog post we'll describe how you can create your own custom themes.

Initial Fusion5250 screen - Valence theme

Figure 3 - Initial Fusion5250 screen after login (Valence theme)


Creating a Fusion5250 Macro

One of the more enticing benefits of having an emulator integrated into the Valence Portal is the ability to automatically place users into specific points within a 5250 program, filling in specific fields wherever possible to minimize user typing.  By creating special macros that are linked to the apps, Fusion5250 can significantly streamline the way users interact with green screen programs on your system.

A Fusion5250 macro is simply a string of JSON directives that tell the app where to enter text and what function keys to press.  Currently macros must be created manually, though CNX will be releasing a macro recording function enhancement on a future build.

All macros are stored on the IFS in the /resources/fusionmacros directory inside your Valence instance (i.e., /valence-5.2/).  A demonstration macro called sample_macro.json is included for reference, which looks like this:

Sample Fusion5250 Macro

Figure 4 - Fusion5250 sample macro 

Let's break down the elements of this JSON object.

  • note: Developer notes for internal documentation purposes.  This has no impact on the macro itself.
  • showProgress: if set to true then users will be able to see individual screens as the macro is being run;  if set to false then users see nothing but the end-result of the macro call — it just pops them straight into the final screen
  • steps: an array of individual steps for the macro to execute...
    • row (must be used in conjunction with col): positions the cursor on a specific x,y screen coordinate
    • type: text to be "typed" into the location specified via row and col.  Substitution values passed in from an external call may be specified using [hard brackets].
    • action: indicates what action key should be hit after any text has been entered via type.  Valid values are F1, F2, F3, ... F23, F24, ENTER, PAGE_UP, PAGE_DOWN, ESC
    • note: Developer notes for internal documentation purposes.  This has no impact on the macro itself.
    • shift: a value of true indicates the shift key should be activated in conjunction with the key specified in action.  So action=F12 and shift=true is equivalent to action=F24; action=ESC and shift=true is equivalent to System Request
    • alt: a value of true indicates the alt key should be activated in conjunction with the key specified in action
    • ctrl: a value of true indicates the ctrl key should be activated in conjunction with the key specified in action

To attach a macro to a Fusion5250 app, simply add the macro name to the path on the app with a query parameter of "macro=".  So to use "sample_macro" you would specify a path like this:


You can also include substitution values in your macro definitions and paths.  So, for example, if your macro is directing users into an inventory inquiry app and you know the part number will be ABC123, you could add the substitution value to the query parameters after the macro name, like this:


You would then reference the part number inside your macro steps using hard brackets — [part_number] — and Fusion5250 would automatically inject ABC123 into the appropriate location.


Configuring the Fusion5250 Server-Side Jobs

Fusion5250 does not require any third party servers or other configured voodoo to function.  If you've got Valence installed and running, and Fusion5250 is activated, then it just works.  On the back-end if you look at WRKACTJOB you'll notice a single "daemon" job running program VVFUSIOND.  This is the "traffic cop" job that automatically fires off a new "proxy" job (program VVFUSIONP) whenever an interactive session is launched in the portal.  Each proxy/VVFUSIONP job corresponds to a single telnet session — i.e., a QPADEVxxxx job running in the QINTER subsystem.

The controls for these back-end jobs can be accessed in Portal Admin > Settings > IBM i Settings > Fusion5250 Settings...  

Fusion5250 Settings in Portal Admin

Figure 5 - Fusion5250 controls in Portal Admin > Settings

By default the Fusion5250 jobs all run in the same subsystem as your Valence instance (QHTTPSVR), so you'll see a mix of CGI jobs, Apache control jobs and Fusion5250 jobs all running with a job name corresponding to your Valence instance...

Fusion5250 jobs running in QHTTPSVR

Figure 6 - Valence jobs running in QHTTPSVR, including Fusion daemon (D) and proxy (P) jobs

Some sites prefer to have a separate subsystem handling the Fusion5250 jobs so they're not mixed in with the Valence CGI jobs in QHTTPSVR.  If you would like to have the same or a similar setup, run the following commands to create a separate subsystem called VVFUSION, tweaking as needed for your particular system needs:

  • CRTCLS CLS(QGPL/VVFUSION) RUNPTY(20) TEXT('Valence Fusion5250 Job Class')

Now that you have a VVFUSION job queue, job description and subsystem created, the next task is to adjust the Fusion5250 settings in Portal Admin to use them (again, tweak as needed):

  • Change the Proxy Job Queue from QHTTPSVR/QZHBHTTP to QGPL/VVFUSION
  • Change the Proxy Job Description from QHTTPSVR/QZHBHTTP to QGPL/VVFUSION
  • Change the Proxy Routing Data from HTTPWWW to VVFUSION
  • Uncheck the "Service Active" box.  This will terminate the VVFUSIOND and VVFUSIONP jobs.  Click Save.  Then reactivate Fusion5250 by checking the box and click Save again.

The VVFUSIOND and VVFUSIONP jobs should restart inside your new subsystem, looking something like this:

Fusion5250 jobs running in VVFUSION

Figure 7 - Fusion5250 jobs running in their own dedicated subsystem (VVFUSION)


Improvements on the Horizon

We plan to invest a lot of resources into Fusion5250 in the coming months.  Some features we're expecting to add in the near future include:

  • Ability to auto-terminate a session based on values appearing in a specific part of the screen (i.e., when the user exits a particular 5250 program it's treated the same as closing the app)
  • Support for "dynamic" macros that can be passed into the app, rather than using a macro file on the IFS
  • Add an embedded macro recording function to make it easier to create JSON macro text
  • Add support for TAB key as an "action" in macros, in lieu of using specific x,y coordinates to enter text into specific fields
  • Support for additional CCSIDs (Fusion5250 currently only works in CCSID 37 and 273)
  • Copy/Cut/Paste enhancements
  • Ability to set specific workstation device names (instead of the QPADEVxxxx default)
  • Create special integration options for Nitro App Builder (NAB) apps
  • (longer term) Add ability to automatically re-render 5250 screens as web or mobile Valence apps based on special rule sets


Send us your feedback!

Our intent is to make Fusion5250 as appealing as possible for integrating legacy programs with newer apps inside the Valence Portal.  If there are additional features you would like to see, please post them in the Valence Forum.