Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Version History

« Previous Version 7 Next »

Overview

In this example, we’ll show you how to display a static HTML invoice with dynamic content using a Universal Display File. A Universal Display File is a general-purpose template that you can use for any file format, with HTML being used in this example. The template can be used for displaying dynamic content which can include variables from your program. You can learn more information about Universal Display Files here.

 

(I think the below explains it better.)

A Universal Display File is a display file that an RPG program can use to create dynamic text output. The output can be transmitted to a client via HTTP or written to a stream file on the IBM i Integrated File System (IFS).  

For example, Universal Display Files can be used to create:

  • 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.

Universal Display File Design

For this example, we organized our data into 4 separate record formats: header, detail, footer and error. You should separate your logic into multiple record formats based on the data that you want to display. While it’s not necessary to use multiple record formats in your Universal Display File, we recommend this approach to more easily manage your logic. In this example, the data in the header, footer and error record formats is data that we want our program to only output once. Data in the detail record format is written multiple times, depending on the data in the database file that you’re using. In the next few sections of this documentation, we will break down the individual record formats into further detail. (needs more elaboration on WHY you would only write certain formats once vs. writing others more than once)

Header

Below is an image of the header format:

Note that the contents of the style tag have been omitted from the screen shot to make it easier to understand. These contents will be included in the full source code, however. You can download the entire source code for this example using the links that are provided later in this document.

As mentioned previously, we want the information in the header record format to only be written once when the invoice is created. This record format is a good place to create tables, add the invoice title, include any styling and output any static text you may want for your invoice. In the case of this example, we want certain elements of the invoice to show only once, such as: the ‘Invoice’ title, the company address, the invoice number table, and the item table. Because the header will only be written one time, this information will only be output once when you run the application and create the overall setup of the invoice.

(In our example, you can place the input parameter in any record format really, you would just read that record format in your RPG program.)

Another important aspect of the header record format is the ‘input parameters’ property. In this example, we have one input parameter – the invoice number. In our RPG program we will check if this parameter has been provided and show the correct invoice depending on the invoice number that is given as the parameter. We have 1 input parameter for this program that we’ve set up using the following (this pic will be bigger in the actual doc page):                     

We’ve named the parameter ‘invoice’ – this will be used in the (query string or post data we are using the query string but we can also use it for post and put methods) URL that will run the program. We’ve also bound the parameter to a nine-digit 9 digit long decimal field called ‘Invoice’. This field will be used in the RPG program, which is discussed later on this page.

**Should probably mention that the fields in the orange/yellow boxes are fields that are bound – getting these from DB/RPG 

Detail

Below is an image of the detail record format:

Unlike the header format, data in the detail record format is written as many times as needed until all the data that exists has been outputted to the screen. This record format will display data in the ‘Item’ table for the invoice. In this example, there is only one item for this invoice number, so there is only one item being written to the table. However, if there were other items for this invoice, the logic in the detail record format would continue to write these items to the table until there were no other items to display. 

Footer and Error

Below is an image of the footer record format:

Like the header record format, we want the data in the footer format to only be written once. In this example, the footer record handles the subtotal, tax and total price of the items that are listed in the ‘item’ table. This information will be included as a part of the ‘item’ table (notice that this information is located inside of the <table> tag). Also notice that this format contains the closing main <div>, <body> and <html> tags. Because of this, the footer record format will officially end the HTML page.

The last record format that we have in this example is the error record format:

The error format will display any errors that you may receive when attempting to run this program. For example, the RPG program would display the contents of the error format if the user did not provide the required parameter before attempting to run the program. The error record format would notify the user that they had forgotten to provide the parameter for the program.

RPG Program

In this section, we will explain our RPG program along with some important details that are needed for this example. Below is the RPG program in its entirety:

// Control Options
       ctl-opt ActGrp(*Caller) Main(Main);
       // Display File
       dcl-f INVOICE01D WorkStn Handler('UNIVERSAL(HANDLER)') UsrOpn;
 
       // Data Files
       dcl-f INHEADERP Keyed UsrOpn;
       dcl-f INDETAILP Keyed UsrOpn;
       dcl-f CSMASTERP Keyed UsrOpn;
 
 
       // Main Procedure
       Dcl-Proc Main;
 
         Open INVOICE01D;
         Open INHEADERP;
         Open INDETAILP;
         Open CSMASTERP;
 
         // Get Invoice Number (Query String Parameter)
         Read HEADER; 
 
         // Find Invoice
         Chain Invoice INHEADERR;
         If Not %Found();
           Message = 'Invoice cannot be found.';
           Write ERROR;
         Else; 
 
           // Get Customer Name from Customer Master
           CMNAME = '';
           Chain HDCMID CSMASTERR;
 
           InvDate = %Char(%Date(HDTIME) : *USA);
           Write HEADER;
 
           // Output Detail Records
           SubTotal = 0;
           SetLL Invoice INDETAILR;
           ReadE Invoice INDETAILR;
           Dow Not %Eof();
             Write DETAIL;
             SubTotal += DTXAMOUNT;
             ReadE Invoice INDETAILR;
           EndDo;
 
           Total = SubTotal + HDSTAXAMT;
           Write FOOTER;
 
         EndIf;
 
         Close INVOICE01D;
         Close INHEADERP;
         Close INDETAILP;
         Close CSMASTERP;
 
       End-Proc;

 

** I’m going to come back to this paragraph at some point. This is going to be harder to write…

Configuring the URL

Before launching the Universal Display File program, you will need to configure the URL using the Web Connector. The Web Connector lets you map a URL like http://server:port/profoundui/universal/myprogram to a program using a Universal Display File. Note that “server” and “port” are simply generic names for example purposes – “server” would be replaced with the actual server name and “port” would need to be replaced with the correct port number for the instance. You can read more about the Web Connector and configuring URL mappings here.

In this case, we’ve set up our URL like so: http://server:port/profoundui/universal/invoice. We want this URL to map to program INVOICE01R in library INVOICE. This is set up in the Web Connector using the following:

URIMAP: /invoice

LIBRARY: INVOICE

PROGRAM: INVOICE01R

So, having /invoice in the URL will result in the program INVOICE01R in library INVOICE being called. This is also where we will reference the input parameter that was discussed previously. You will need to provide the invoice number in the parameter of the URL when launching this program in order for this to work as expected. The following is the complete URL used to run this program: http://server:port/profoundui/universal/invoice?invoice=53696.

End Result/Running the Program/Something Else

Once you have compiled your Universal Display File, compiled your RPG program and configured your URL using the Web Connector, you should be able to launch your program. For example purposes, we are using this program as a stand-alone report, however, this program could be used with another program to dynamically set the URL parameter to show different invoices based on the invoice number that is provided. The following image shows the result for invoice number 53696:

 

 

 

  • No labels