All-in-one Display Files

Owned by Alex Roytman
Last updated: Aug 16, 2023 by Jessica Tomkins
6 min read

 

Overview

Many organizations choose to keep green-screen interfaces for a significant period of time after modernizing to a Rich user interface. A common challenge for these companies is the need to maintain separate files and programs as the capabilities of the two types of interfaces diverge.

Profound UI's All-in-one Display Files provide the ability to package green-screen and Rich interfaces in the same set of display files and RPG programs. While the new Rich UI is no longer connected to or limited by the green-screen, the metadata for it can be stored in the same display file as the green-screen. Furthermore, the same RPG program can be used to drive the separate interfaces, even after the RPG Open Access Handler is added.

The pros and cons of All-in-one Display Files

When deciding whether to convert your green-screens into standard Rich Display Files or All-in-one Rich Display Files, several pros and cons should be considered.  Even when you have a clear need to keep your existing green-screens for some time, using All-in-one Display Files may not always be the right choice for you.  The other alternative is to simply keep a separate green-screen display file and a separate Rich Display File for each program.

The pros of All-in-one Display Files are:

  • You won’t need a separate library or libraries for your Rich user interface.  Both interfaces are kept in the same set of libraries.

  • You will only have one set of display files to manage – it’s just 1 source member and 1 object for every display, whereas the alternative would require 2 source members (green-screen and Rich) and 2 display file objects.

  • You will only have 1 copy of the program object to manage instead of managing 2 program objects.  However, keep in mind, that with the alternative method, it is still possible to keep only 1 copy of the program source by using conditional compile directives to surround the HANDLER keyword.

  • If you must keep and maintain your green-screen interfaces for an extended period of time, this option greatly simplifies source control and change management.

The cons of All-in-one Display Files are:

  • It may take additional effort to maintain the integrity between the Rich portion and the green-screen portion of the display file.  This is because the record buffer, or fields, in the two interfaces are now shared and must match.  If you are planning to make major changes or a major redesign in both the look-and-feel and the flow of the application, this may require additional work with All-in-one Display Files compared to standalone Rich Display Files.

  • Deviating from the functionality of the green-screen (like combining several screens into one in your Rich interface) may take additional consideration and effort.

  • Tasks like expanding fields may require changes to RPG code.  For example, on the green-screen, you may have a Customer Name output field that is limited to only 12 characters due to real estate limitations of the screen.  On the Rich interface, you may decide to expand the field to 30 characters to show the full name.  If the Rich Display was in a separate source member, it would generally be a simple matter of changing the field from 12 to 30 characters.  However, in an All-in-one Display File, a change like this will cause a mismatch to the green-screen.  Therefore, to implement the change, an additional field would have to be added and an additional line of RPG code will be necessary to populate this new field with the full Customer Name.

Converting a green-screen into an All-in-one Display File

To convert into All-in-one Display Files, a configuration option must be set before Visual Designer is loaded in the browser1. In a JavaScript file2 in the ProfoundUI installation's IFS directory, /www/yourProfoundInstanceName/htdocs/profoundui/userdata/custom/js/,  Set a configuration option, pui["enable retain gs"] = true; Then, open Visual Designer.

When using the DDS conversion in the Visual Designer, make sure to select the Retain Green Screens option in the conversion dialog.  This will automatically create an All-in-one Display File.

When you save the converted display file, both the original DDS and the new Rich interface (added via DDS HTML keywords) will be kept in the source member.

1This configuration option is required in Profound UI Version 6 Fix Pack 1.0 and later. Earlier versions always show the "Retain Green Screens" checkbox.

2For example, if your Profound UI instance is named "PROFOUNDUI", you can save the setting in /www/profoundui/htdocs/profoundui/userdata/custom/js/settings.js

How All-in-one Display File are stored

Profound UI knows that it is working with an All-in-display File because it is marked with a pseudo file level keywords called ALLINONE.  To check if the ALLINONE keyword is present, select File Keywords in the Visual Designer.

 Since ALLINONE is not a real DDS keyword, it is written to the source member as a special comment.  

When you are ready to retire your green-screens, you can permanently remove the DDS that describes the green-screen in a Rich Display File by simply removing the ALLINONE keyword from the File Keywords Dialog and saving the display file in the Profound UI Visual Designer.

When a conversion to an All-in-one Display File occurs, all original DDS is retained, while new Rich UI information is added as JSON (JavaScript Object Notation) via the HTML keyword.  While the information is stored within the same display file, the two definitions (green-screen and Rich UI) are treated separately.  Therefore, the Rich user interface is not “sitting on top” of the green-screen and is not limited by 5250.  The Rich UI portion can have additional information, more functionality, more rows and columns in subfile listings, drag and drop features, and other capabilities that the green-screen will not have.

However, the definition for fields that are shared between the two interfaces must match.  The JSON for those field definitions must be equivalent to the DDS definition.  Otherwise, you will receive an error message while trying to save the file in the Visual Designer.


Numeric indicators and their usage (response vs output) must match as well.

Please note that certain errors in the conversion process, such as not finding Reference files successfully, may cause these field definitions to not match.

Modifying the RPG

In the RPG source, only the HANDLER keywords must be added to the F spec of the Display File declaration.  See Open Access.

FMYDSPFILE   CF   E             WORKSTN HANDLER('PROFOUNDUI(HANDLER)')

No other directives are necessary to enable All-in-one Display Files.  Similarly, a separate copy of the RPG source and/or program object does NOT have to be created.  Everything is retained in one display file and one program.

Future changes and additions to the RPG code will affect both interfaces.

Running the application

Before you can run the application, the runtime library list should be adjusted to include the Profound UI product library (by default, the product library name is PROFOUNDUI).  This will take care of both running the green-screen version and the Web version of the application.

Profound UI will automatically detect the mode it is running in and either call system APIs for displaying green-screens or use its internal functionality for displaying browser interfaces.

The green-screen version is called from a regular 5250 session using any standard desktop 5250 emulator, while the Rich UI browser version can be called by either launching an anonymous session, a Profound UI Rich Display File session, or a Genie session.  See Launching Programs for more details.

Maintaining and Enhancing All-in-one Display Files

The Rich UI portion of an All-in-one Display File must be maintained within the Profound UI Visual Designer.  The Visual Designer will maintain the green-screen portion of the display file intact.  Developers can add new elements and fields or remove elements and fields from the interface as needed.  However, if a field’s data type or length must be modified and this field also exists on the green-screen interface, this change should first be made in the green-screen DDS code.  The Profound UI Visual Designer will not allow you to save the display file member unless field definitions match between the Rich UI and the green-screen. 

The green-screen portion of an All-in-one Display File can be maintained using RDi’s Screen Designer or SDA.  However, RDi is the recommended tool, since SDA is no longer enhanced by IBM.  Both RDi and SDA will maintain the Rich UI portion of the display, stored as JSON within HTML keywords, intact as you modify the green-screen interface.  

However, developers should be aware of a known SDA bug.  SDA does not properly encode single quotes within HTML keywords when saving display files.  If your Rich UI screens contain constants with single quotes in them, each single quote must be encoded as 2 single quotes within the HTML keyword.  SDA does not do this and this may cause your display file not to compile.  If you run into this issue, one solution to this is to reopen the display file in the Profound UI Visual Designer and then save it again.  This re-encodes the single quotes within the JSON and fixes the problem.