IBM’s free CGIDEV2 library is the most flexible way to generate XML.
While lecturing on the topic of RPG IV's V5R4 support for processing XML, people often say, "That is a great feature, but how can I generate XML?" There are of course a number of answers to this question, ranging from "Buy tool x" to "Write it to a work file and then use CPYTOIMPF to generate the IFS file." Of all of the "no-charge" options, our favorite, and by far the most flexible, is to use IBM's free CGIDEV2 library. Some of you may be wondering why we would be using a Web-development tool when the objective is to generate XML. If you think about it though, it's perhaps not such an odd choice. The most cursory look at examples of the two will quickly reveal the similarities. Take a quick look at the snippet of XML (Figure 1) and you'll see what we mean. Looks a lot like HTML doesn't it?
This particular XML document contains the basic details (product code, description, price, etc.) of all of the tools that a company sells. Tools are grouped into categories (hammers in this example) and there are multiple products in each category.
Both HTML and XML are examples of tag languages. In fact, both have their origins in Generalized Markup Language (GML), which was invented by IBM engineers in the late 1960s as a mechanism to try to solve the problems inherent in exchanging documents between different computer systems.
"But CGIDEV2 outputs its results to the browser - how does that help me?"
Luckily, some time ago, CGIDEV2 incorporated the ability to write its generated HTML to a file in the IFS. Mel Rothman (the Rochester developer originally responsible for CGIDEV2) developed this feature originally as a means to dynamically generate a Web page that could subsequently be served statically, for example, to build Web pages containing price lists that would be updated daily. Why use CPU power to dynamically build the page every time it is requested when you can build it once a day and display the results!
So How Does it Work?
As we discussed in our earlier article, CGIDEV2 uses a template system and a "fill in the blanks" approach to building its output stream--think DDS, the approach is very similar. If you take a look at the template (Figure 2) and compare it with the earlier XML sample, you should be able to get a good idea of how the template relates to the final XML file. (Note: This template excludes the normal XML header information in the interests of simplicity.)
There are two (hopefully) obvious differences between this template and the original XML. The first (A) is the introduction of the lines that begin with "/$" - these identify what CGIDEV2 refers to as section names. You can think of them as record format names, and they are used to specify the section(s) of the template that we wish to output at a specific time. This one (FileHeader) will be output to mark the beginning of the document.
IBM’s free CGIDEV2 library is the most flexible way to generate XML.
The second (B) marks a substitution variable - in this case referenced by the name CatCode. As you can see, the characters "/%" mark the beginning of a substitution variable name, and the end of the name is marked by "%/". During the execution of the program, we will use CGIDEV2 APIs to supply the data that is to be used to populate these substitution variables.
Now that we've had a chance to look at the finished XML document and the template that will be used to create it, it's time to study the RPG program that will do the work.
The program begins (C) by calling the CGIDEV2 API GetHTMLIFS. This loads our XML template into memory. In doing so it identifies all of the names of the sections and substitution variables contained within the template. Once the skeleton is loaded, we then use the WrtSection API to output the section FILEHEADER to CGIDEV2's buffer.
Now the real action begins. At (D) you will see the beginning of the DO loop that controls the process of reading through all of the product records. Within the loop we compare the category code in the record to see if a new category has commenced. (Hey we've reinvented the RPG cycle!) If it has, we output the (E) CategoryTrailer section to terminate the previous category. We then read the category file and use the API UpdHTMLVar (F) to update the values for the CatCode and CatName substitution variables. Once those variables have been updated, we can then write out the CategoryHeader section to the buffer.
The next thing to do is output the details of the product information. This begins at (G). Notice that because the FullDescription element of the XML is optional, we have conditional logic at (H) controlling the output of this information. We then continue to process the product details finally outputting the section ProductDataMain2 to complete the product information.
Once the product file has been completely processed, the trailer section is written (J). At this point the CGIDEV2 buffer contains the completed XML document, but we still have to write it to the IFS. This is achieved by the use of the WrtHtmlToStmf API (K). The name of the file to which the document is to be written is supplied by the first parameter XML_Output. The second parameter identifies the code page for the IFS file. The value 819 is one of the standard values used in North America. You may have to modify this to reflect a code page commonly used in your area, or indeed to the code page specified by the organization to which you are sending the document.
IBM’s free CGIDEV2 library is the most flexible way to generate XML.
That's all there is to it. And the beauty of it is that if the specification of the XML document changes, we have very little work to do. In fact if there are no additions to the substitution variables, then we may not need to make any changes to the program at all. A simple change to the template will do it all (Figure 3).
If you want to try using CGIDEV2 for this purpose you can download the current version from IBM's site. If you would also like to try your hand at using CGIDEV2 for Web programming, you might want to get the download from the Easy400 Web site as that version includes a more automated install process than the IBM download.
The code from this article is available for download from our Web site. If you have any questions about the program, please contact us