Please Note!

This example assumes you have familiarized yourself with the Universal Display Files, Using the Universal Display File Editor, and Using the Web Connector! Notes and links may be provided, but complete explanations may not!



Table of Contents


The Goal of This Example

Show how a Universal Display File can work in tandem with a Rich Display File's List Box Widget's choices URL property. You could also utilize the choices URL property within a Combo Box Widget, but this example will be using a List Box Widget.

Files Used by This Example

Below are downloadable versions of the files used in this example:

  • Choices URL in Universal Display File: COLORSD.json
  • Universal Display File RPG Code: COLORSR.txt
  • Rich Display File: SHOWCOLORD.json
  • Rich Dipslay File RPG Code: SHOWCOLORR.txt
  • Sample Color Table SQL File: COLORSP.sql (contains the CREATE TABLE)
    Note: This data set was randomly generated meaning that the color name and the hex color associated with it might not match up. The functionality is the same and it is being provided to help users practice.


The Universal Display File

Read more about it: Using the Universal Display File Editor

For this example, we are creating a JSON object to reference for the options of our options box. 

Below are screen shots of the Universal Display File (COLORSD) being created the Universal Designer. There are 3 record formats representing the parts of an HTML page, the HeaderBody, and Footer. The middle image shows CONAME and COHEX as the bound fields. CONAME (color name) is the variable containing names of colors, the example CONAME is defined as CHAR(30)COHEX (color hex) is the variable containing the hex values of CONAME's colors, the example CONAME is defined as CHAR(7) and the records include the '#' along with the hex color value (i.e. #FF0022). If you would prefer, you can use valid CSS color names instead of the hex color value and the example will still work. You will need to make sure your fields are properly defined for the length and type of field. Our Universal Display File will access the information in these bound fields and display them in our program. Please refer to the Adding Dynamic Content Using Fields of the Using the Universal Display File Editor documentation page for more information with this step. 


The Header format is used to define the file/object being made by the Universal Display Program and is only printed once to the file/object. The Header format in this example defines the start of a JSON object .


The Body  format is used to define a section of the file/object that will be printed one or more times depending on an input source. The Body format in this example defines an Option for the List Box and will be printed to the JSON object as many times as there are records in the COLORSP database file. Please notice that the separator property is set. This property will add the separator after each WRITE.


The Footer format is used to define the end of the file/object that will only be printed once. The Footer format in this example ends the JSON object .

The Insert Field button is used to add bound fields like CONAME and COHEX.

CONAME and COHEX are defined as References to their corresponding field in the table.

The REF keyword containing the NAME of the table is added to File Keywords.

The library containing the table should be added to the Library List.


The Universal Display RPG Source Code

Read more about it:  RPG Coding for Universal Display Files

The source code file of this example is named COLORSR. An important part to mention is that the Universal Handler is used for this program.

What this program will do is grab a list of colors from a specified database file, COLORSP for this example, on the IBM i and create a JSON object that will contain the option objects that will populate the List Box.  CONAME will display in the List Box and the corresponding COHEX will be passed to the program when a selection is made.

Universal Display RPG Source Code File
**FREE          // This program is utilizing FREE-FORMAT RPG
ctl-opt DFTACTGRP(*NO);

dcl-f   COLORSD WorkStn
                // Use the Universal Handler as the handler in this program.
dcl-f   COLORSP Keyed;
Write   Header; // Write the Header from the Universal Display File to the JSON object.
Read    COLORS; // Read a record from the database file COLORSP. 
Dow Not %Eof(); // While not at the end of COLORSP
  Write Body;   // Write the record to the JSON object
  Read  COLORS; // Read the next record of COLORSP
Write  Footer;  // Write the Footer from the Universal Display File to the JSON object.
// End program
*InLr = *On;


Hard coded libraries are a bad practice! We strongly suggest you do not use hard coded libraries!

The following is the resulting JSON object of what was shown above:

Universal Display Result
new Option("WHITE","#FFFFFF")
new Option("SILVER","#C0C0C0")
new Option("GRAY","#808080")
new Option("BLACK","#000000")
new Option("RED","#FF0000")
new Option("MAROON","#800000")
new Option("YELLOW","#FFFF00")
new Option("OLIVE","#808000")
new Option("LIME","#00FF00")
new Option("GREEN","#008000")
new Option("AQUA","#00FFFF")
new Option("TEAL","#008080")
new Option("BLUE","#0000FF")
new Option("NAVY","#000080")
new Option("FUCHSIA","#FF00FF")
new Option("PURPLE","#800080")


The Rich Display File

Read more about it: Visual Designer BasicsUsing the Web ConnectorWork with URL Mappings Tool

Below is a screen shot of the layout of the SHOWCOLORD rich display file.There are 3 bound fields. Two for OK and EXIT buttons, and one for the color bound field. Once you click the OK button after selecting a color name in the List Box, the background color of the label underneath will change to the corresponding color. The COLOR bound field is bound to the background color attribute of the label widget, and is also bound to the value property of the List Box; this is how the label is able to change colors accordingly. 

The Choices URL property of the List Box is what populates the choices of colors that can be picked. We set this property to the URL of our Universal Display File application. 


Example Display Arrangement

This is an image of the Visual Designer with the arrangement of elements of this example.


Don't forget that the choices url value needs to be mapped! The Web Connector, as of Profound UI Version 5, Fix Pack 10.0, has a URL Mappings Tool that can be used to maintain the URL Mappings, previous versions require a PUIMAPP record to be created. Please notice that the URL shown in the screenshot is /profoundui/universal/colors , this is the URI Mapping I set up using the PUIWRKMAP tool, as shown in the screenshot below (click the thumbnail to view the full size image).


The Rich Display RPG Source Code

File name is SHOWCOLORR. Notice that the ProfoundUI Handler is being used in the handler for this program. The EXFMT operation will display the SHOWCOLORD display file. 

Rich Display RPG Source Code
**FREE  // This program is utilizing FREE-FORMAT RPG
ctl-opt DFTACTGRP(*NO);
dcl-f   SHOWCOLORD WorkStn 
        // Use the ProfoundUI Handler as the handler in this program
// Run program until the exit button is pressed
Dou BTNEXIT = *On;

// End program
*InLr = *On;


Hard coded libraries are a bad practice! We strongly suggest you do not use hard coded libraries!

The Result

After compiling the Universal Display File (COLORSD) and the Rich Display File (SHOWCOLORD) the corresponding RPG programs, COLORSR and SHOWCOLORR, may be compiled and then the program run.

To run the program, login to a Genie session and use EDTLIBL or ADDLIBLE to make sure the libraries where the program files are stored are in the library list. Then you may run the command CALL YOURLIBRARY/SHOWCOLORR to run your program and you can display the colors after highlighting a color name and pressing the OK button, double-clicking the color, or selecting a color and pressing the 'Enter' key on your keyboard. 


Actions in Order:

  1. Select Silver -> Click Ok
  2. Select Red

  3. Scroll down using ▼ of the scrollbar
  4. Double-click Olive to select and pass to program
  5. Select Maroon -> Press "Enter" on keyboard
  6. Click Exit to exit the program



The Program in Action

Why Do It This Way?

  1. Universal Display Files can be used to output:
    • A program that produces dynamic HTML content for a web browser.
    • A web service that outputs an XML or JSON document to a client program via HTTP.
    • A plain text, XML, JSON, or CSV document on the IFS.
  2. The static content is embedded into the DDS source and display file object, allowing for easy integration with existing change management systems and procedures.

  3. The Universal Display File web connector allows you to map a URL on the Profound UI HTTP server to a call to an RPG program on the IBM i, which will take the information written to the Universal Display File (COLORSD) by the Universal RPG program (COLORSR) and send it to the client via the HTTP response where the called RPG program can use the HTTP query string and POST input for READ operations.
  • No labels