Creating an RXS Template

To generate XML, RPG-XML Suite relies on what is referred to as the “template engine” or “composition engine”. This engine uses a specially marked up psuedo-XML file divided into sections and with variable fields embedded in it as well as a set of RPG-XML Suite subprocedures. The combination of the template file and the subprocedures allow you to build XML of any complexity or depth needed to meet your business requirements.

To start with creating a template file, we need to create a file in the IFS. This command uses QSHELL to create an IFS stream file using CCSID 819. Note that this command is case-sensitive.

QSH CMD('touch -C 819 /www/myrxs/templates/bldtpl001.xml')

Next, we need to populate this file with a sample of the XML that we’re going to use as the basis of the template. Note that to make your life easier, you want this to be as complete an example as possible. If your XML has many optional fields, try to include them all in this sample file, even if it some of them would not logically appear with others in normal usage. To get the XML into our IFS stream file, we’ll use the EDTF command.

EDTF '/www/myrxs/templates/bldtpl001.xml'

Now, paste your sample XML into the resulting editor window. For the sake of this example, we’ll use the following XML:

<PostAdr residential="true">
  <name title="Mr.">
    <first>Sample</first>
    <last>Resident</last>
  </name>
  <street>999 Totally A Real Street</street>
  <city>Cityville</city>
  <state>OH</state>
  <zip>12345</zip>
  <phone>123-456-7890</phone>
  <phone>987-654-3210</phone>
</PostAdr>

While in the Edit File editor select F2 to save the document changes. Now it is time to invoke the BLDTPL command to generate a *.tpl file that will facilitate composing the PostAdr XML document.

BLDTPL IFSXMLLOC('/www/myrxs/templates/bldtpl001.xml') IFSTPLLOC('/www/myrxs/templates/bldtpl001.tpl') INDENT(2)

The IFSXMLLOC parameter is the location of the XML file that was created in the above steps. The IFSTPLLOC is where we want the new bldtpl001.tpl file to be located – place it in the location of all other RPG-XML Suite templates. The last parameter, INDENT, allows you to specify how the template’s XML should be indented. Note that indenting is purely for ease of editing.

See below for the resulting template file located at /www/myrxs/templates/bldtpl001.tpl - use EDTF to open it. Note that all elements and attributes have had their values replaced with variable place holders (i.e. .:variable:.) respective to the element or attribute’s name.

<PostAdr residential=".:residential:.">
  <name title=".:title:.">
    <first>.:first:.</first>
    <last>.:last:.</last>
  </name>
  <street>.:street:.</street>
  <cty>.:cty:.</cty>
  <state>.:state:.</state>
  <zip>.:zip:.</zip>
  <phone>.:phone:.</phone>
</PostAdr>

An important thing to note is that in the generated template file, there is only one >phone< element, where before there were two. This is because of the other main concept used in RXS template files - sections. A section is a portion of a template file that is referred to by name. Sections can be written out multiple times in an XML document. Sections are also not created by BLDTPL - you will need to go in and add them yourself based on your knowledge and understanding of how the document is meant to be composed and would best be divided. Below is an example of how to split up our example XML into sections:

::PostAdr_beg
<PostAdr residential=".:residential:.">
  <name title=".:title:.">
    <first>.:first:.</first>
    <last>.:last:.</last>
  </name>
  <street>.:street:.</street>
  <cty>.:cty:.</cty>
  <state>.:state:.</state>
  <zip>.:zip:.</zip>
::phone
  <phone>.:phone:.</phone>
::PostAdr_end
</PostAdr>

By giving the <phone> element a separate section, it gives us the flexibility to write as many of those elements as we need - our document could have one phone number, or a thousand phone numbers - or even none! Not all sections in an XML document need to be used during XML composition. Sections of your XML may be optional - unused depending upon your business logic or a specific request’s needs.