RXS Code Generators
From Wiki
|
| User Guide |
RPG-XML Suite code generators are provided to facilitate writing code faster, because the code writing for composing and parsing XML can be laborious and often times similar from program to program. There are currently two different code generators included with RPG-XML Suite – BLDPRS (Build RPG Parse Subprocedure) and BLDTPL (Build XML Template). These code generators are callable from the command line and can be prompted for parameter assistance.
BLDPRS (Build RPG Parse Subprocedure)
The BLDPRS command is used to aid in writing RPG-XML Suite parsing code. In the examples included with RPG-XML Suite (i.e. MYRXS/EXAMPLE,*) there are many “handler” or parsing subprocedures that take an XML file and parse it for the data contents. After writing a few of these parsing subprocedures you will find that much of keying is repetitive with just a few things changing from program to program. This brings about a perfect case for a code generator that will take care of much of the parsing code.
BLDPRS usage can best be explained with an example. The first thing needed is an XML document residing in the IFS. Type the following on the command line to create an XML file named /home/bldprs001.xml in the IFS.
QSH CMD('touch -C 819 /home/bldprs001.xml')
The file now exists but without content. To add content we will use the EDTF command and copy/paste the following XML.
EDTF '/home/bldprs001.xml'
Add the following XML to the file:
<PostAdr residential="true"> <name title="Mr."> <first>Aaron</first> <last>Bartell</last> </name> <street>123 Center Rd</street> <cty>Mankato</cty> <state>MN</state> <zip>56001</zip> <phone>123-123-1234</phone> <phone>321-321-4321</phone> </PostAdr>
While in the Edit File editor select F2 to save the document changes. Now it is time to invoke the BLDPRS command to generate the parsing code. You will need to provide the library, source physical file, and source member of where you would like the generated code to be place and also where the XML document resides in the IFS that should be used. The last parameter, BASEENV, can be omitted but serves a code readability purpose. BASEENV allows you to specify the beginning portion of an XPath that is repeated for every element, or attribute, in the XML document. In the below example /PostAdr is specified for the BASEENV parameter. This value will be applied to an RPG variable named baseEnv and baseEnv will then be used in the WHEN clauses to make the statements shorter.
BLDPRS
SRCLIB(MYRXS)
SRCPF(EXAMPLE)
SRCMBR(BLDPRS001)
IFSXMLLOC('/home/bldprs001.xml')
BASEENV('/PostAdr')
The following is the contents of source member MYRXS/EXAMPLE,BLDPRS001 after running the above command. Note that some of the code was omitted for brevity's sake.
D allHandler pr D pType value like(RXS_Type) D pXPath value like(RXS_XPath) D pData value like(RXS_XmlData) D pDataLen value like(RXS_Length) //----------------------------------------------------------------- // @Author: // @Created: // @Desc: //----------------------------------------------------------------- P allHandler b D allHandler pi D pType value like(RXS_Type) D pXPath value like(RXS_XPath) D pData value like(RXS_XmlData) D pDataLen value like(RXS_Length) D chgMe s like(RXS_XmlData) D baseEnv s 70a varying /free baseEnv = '/PostAdr'; select; when pXPath = baseEnv +'>'; chgMe = pData; when pXPath = baseEnv +'@residential'; chgMe = pData; when pXPath = baseEnv +'/'; chgMe = pData; when pXPath = baseEnv +'/name>'; chgMe = pData; when pXPath = baseEnv +'/name@title'; chgMe = pData; when pXPath = baseEnv +'/name/'; chgMe = pData; when pXPath = baseEnv +'/name/first>'; chgMe = pData; when pXPath = baseEnv +'/name/first/'; chgMe = pData; when pXPath = baseEnv +'/name/first/>'; chgMe = pData; when pXPath = baseEnv +'/name/last>'; chgMe = pData; when pXPath = baseEnv +'/name/last/'; chgMe = pData; when pXPath = baseEnv +'/name/last/>'; chgMe = pData; when pXPath = baseEnv +'/name/>'; chgMe = pData; when pXPath = baseEnv +'/street>'; chgMe = pData; when pXPath = baseEnv +'/street/'; chgMe = pData; when pXPath = baseEnv +'/street/>'; chgMe = pData; ... when pXPath = baseEnv +'/>'; chgMe = pData; endsl; /end-free P e
BLDTPL (Build XML Template)
The BLDTPL command aids the composing of RPG-XML Suite template (*.tpl) files which are used in conjunction with the Template Engine to compose XML documents. Composing the necessary XML for the *.tpl files can become quite laborious and typing errors can cause wasted time debugging trying to figure why your program is not working as expected. BLDTPL aims to alleviate those problems and make you more productive.
BLDTPL usage can best be explained with an example. The first thing needed is an XML document residing in the IFS. Type the following on the command line to create an XML file named /home/bldtpl001.xml in the IFS.
QSH CMD('touch -C 819 /home/bldtpl001.xml')
The file now exists but without content. To add content we will use the EDTF command and copy/paste the following XML into the EDTF editor.
EDTF '/home/bldtpl001.xml'
Add the following XML to the file:
<PostAdr residential="true"> <name title="Mr."> <first>Aaron</first> <last>Bartell</last> </name> <street>123 Center Rd</street> <cty>Mankato</cty> <state>MN</state> <zip>56001</zip> <phone>123-123-1234</phone> <phone>321-321-4321</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('/home/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. Note that all elements and attributes have had their values replaced with variable place holders (i.e. .:variable:.) respective to the element or attributes name. This file is now ready to be used by the RPG-XML Suite Template Engine. Note that you would reference the file bldtpl001.tpl on the RXS_loadTpl subprocedure (i.e. RXS_loadTpl(‘bldtpl001.tpl’) ).
<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>
One last thing to note is that in file bldtpl001.xml there were two <phone> elements. Whenever the BLDTPL command comes across the same XPath (i.e. ‘/PostAdr/phone’ in this case) it will not process it a second time. It will instead assume the <phone> tag will most likely be in its own section (maybe named ::phone). By putting the <phone> tag in its own section you have modularized the template file and now many <phone> tags can be easily written out in the transaction file by wrapping it with a DOW loop.
Once the BLDTPL process is complete you will need to add your sections. Below is an example of how bldtpl001.tpl has been modified with 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>