XMLi - XML Generation Utility
Version 1.0.1: Released 21st May 2011
***********************************************************************************************
---: ABOUT XMLi (abstract from "XMLi - XML Composition.doc" provided in the download) :---
***********************************************************************************************
XMLi is a suite of service programs which can be used to generate XML, HTML or even standard text data. The generated data can be written to a stream file, written to standard output, passed in raw form to a user-defined call-back procedure, or passed to a running HTTP server.
There are two supported methods of XML generation:
1. Generation of xml within application programs via the XMLi1 build toolset.
This method allows the application program to control the way the xml data is structured within the xml document. The application program typically provides the memory to store the xml (either a variable, or a space pointer) and builds the document programmatically node-by-node via XMLi procedure calls.
Excellent for building well-defined XML documents, this method suits the developer who prefers the document to be defined and built within the RPG application code.
The ability of XMLi1 to allow the construction of XML on up to 256 memory spaces concurrently provides an easy way to modularize the building of the XML. For example, a program could build the header of an XML document, call another program to build the body (passing a parameter to hold it), and then attach the body (returned in the parameter) to the current document. The original program can then complete the document and process accordingly.
The example programs contained within the XMLi package demonstrate the way in which very complex XML documents can be built using this and other techniques.
2. Generation of xml by running xml templates via the XMLi2 utility.
This method is the most flexible as it uses a pre-defined xml template document to instruct XMLi how to build the xml. The template contains everything needed to build the XML. An XML document itself, the template is a template of the XML to be built containing document structure, content, and instructions on how to build it. The role of the RPG program is therefore relegated to providing parameters when running the template or providing a (call-back) procedure for the running template to call when required. The template is self-contained. As a result the memory used by the template is provided by XMLi internally. This internal memory is termed Managed Memory and will expand automatically during the xml build process to a maximum of 16Mb. The resulting xml can be provided to the application program via a call-back routine and/or the resulting xml can be written to the IFS, to Standard Output, or passed to an XMLi Extension to process (for example, the MMAIL Extension can instruct MMAIL to attach the built document to an email and send it).
XMLi2 allows the ability to load and use up to 256 templates simultaneously. Each template can take up to 64 parameters during execution, can define up to 1024 variables internally, and can run up to 128 SQL queries and any number of CL Commands. The results of the SQL queries can be accessed within the template and used as required.
XMLi templates can even import other templates and/or include static xml document data. This allows commonly used templates or static xml files to be used in many templates, providing a means of modularizing the template definitions.
XMLi provides full conditioning and looping constructs. The generation of markup can be conditioned using IF or CHOOSE statements. Looping constructs such as DO-WHILE, DO-UNTIL, and FOR are also supported.
XMLi templates support a basic scripting language via the xmli:script tag. This allows the developer to write simple scripts to perform arithmetic operations, or concatenate string variables, for example.
XMLi templates support the ability to extend the language via plug-in extensions. XMLi extensions are service programs that can be called by a running template to perform actions that are not defined within the XMLi base language. It is possible to write custom extensions and plug them into XMLi via configuration settings. No binding is required as XMLi will load, activate, and link to the extension when a template referencing the extension is loaded. XMLi supports the use of up to 256 extensions.
XMLi allows participating extensions to work together. This provides a powerful way to extend the capabilities of XMLi templates. Such capabilities could be to send emails, call web services, serve dynamic web pages, and much more.
***********************************************************************************************
---: INSTALLATION: To install this utility on your system perform the following :---
***********************************************************************************************
1) Unzip the XMLI_V101.zip file to a folder on your PC
2) Create a SAVF in a work library on your IBM i system. Call it XMLI_V101
3) Using FTP in binary mode, put the XMLI_V101.SAVF to the XMLI_V101 save file object on your IBM i system
4) Restore the XMLILIB library from the XMLI_V101 save file
The objects are compiled to V5R4M0
5) To create the directories in the IFS for the sample templates, do either of the following:
i) Create the directory XMLi in the root directory
Create the directory config in the /XMLi directory
Create the directory Examples in the /XMLi directory
Create the directory Templates in the /XMLi/Examples directory
fCreate the directory Results in the /XMLi/Examples directory
or...
ii) Call the XMLILIB/BUILD program to build the program objects and create the directories
6) Using FTP or RDPi/RDi/WDSCi, put the Example xml files from the XMLi/Examples folder on the PC to the /XMLi/Examples folder in the IFS
7) Using FTP or RDPi/RDi/WDSCi, put the xmli_config.xml file from the XMLi/config folder on the PC to the /XMLi/config folder in the IFS
Once completed, the examples and utility should be ready to use
Sample DB tables have been provided in XMLILIB to be used in the examples. These, along with the sample programs can be deleted if not required.
PLEASE NOTE: Documentation and source code is provided with the download - you DO NOT need to restore the SAVF to view the documentation, source code, or sample templates
***********************************************************************************************
---: BUILD NOTES :---
***********************************************************************************************
All objects have been compiled to run in OS version V5R4M0. However, there is source in QCLLESRC for build programs as follows:
1) To rebuild all programs to your current OS version call XMLILIB/BUILD.
2) To rebuild all programs to V5R4 call XMLILIB/BUILD_V5R4.
3) To rebuild all programs to V6R1 call XMLILIB/BUILD_V6R1.
These build programs simply rebuild the RPG service programs and example programs. They will create the XMLi folder and sub-folders in the root directory if they do not exist.
Only the XML templating service program (XMLI2) requires V5R4 or later (as it ises the xml-sax op-code). XMLI1 (API building of xml), SQLI, and PRSI can run on earlier releases.
***********************************************************************************************
!!! IMPORTANT NOTE FOR BETA USERS UPGRADING TO VERSION 1 !!!
***********************************************************************************************
Version 1 is a re-engineer of the original BETA version. the new version offers significant improvements in both usability and performance. It is important that all programs and service programs that use the original BETA version are recompiled to use version 1.0.0 or later.
Although every effort has been made to keep the versions as close as possible the sheer amount of rework meant it was not possible to provide full backward compatibility.
After recompile there may be a couple of subtle changes to templateas that run with the BETA version, to make them run with Version 1.
1) The select attribute of the xmli:value-of element has been changed. It now supports full expressions. This means it no longer requires variable names to be wrapped in {$...}. This also means that string literals should be wrapped in single quotes.
As an example:
Original code: <xmli:value-of select="{$variable1}" /> should be replaced with
New code: <xmli:value-of select="variable1" />
Original code: <xmli:value-of select="my string" /> should be replaced with
New code: <xmli:value-of select="'my string'" />
It is now possible in Version 1 to use full expressions so this is now possible:
New code: <xmli:value-of select=" variable1 + 'my string' + variable2" />
2) The test attribute of the xmli:if element has been changed. It now supports full expressions. This means it no longer requires variable names to be wrapped in {$...}. This also means that string literals should be wrapped in single quotes.
Additionally, the single comparison allowed in the BETA version using the comparators *LT, *LE, *EQ, etc have been replaced as follows:
*EQ ==
*NE !=
*LT <
*LE <=
*GT >
*GE >l=
Additional for Version 1:
and, or, not
As an example:
Original code: <xmli:if test="{$variable1} *EQ {$variable2}" /> should be replaced with
New code: <xmli:if test="variable1 == variable2" />
Original code: <xmli:if test="{$variable1} *EQ AAA" /> should be replaced with
New code: <xmli:if test="variable1 == 'AAA'" />
It is now possible in Version 1 to use full expressions so this is now possible:
New code: <xmli:if test="result == ((a + b) * (c + b)) / (a * (a + b))" />
3) The path attribute of the xmli:write-to-file element has been changed. It now supports full expressions. This means it no longer requires variable names to be wrapped in {$...}. This also means that string literals should be wrapped in single quotes.
As an example:
Original code: <xmli:write-to-file path="{$variable1}"/> should be replaced with
New code: <xmli:write-to-file path="variable1" />
***********************************************************************************************
Changes for Version 1.0.1: Date 20/04/2011
***********************************************************************************************
1) Fixed issue with reset attribute of write-to-file and write-to-stdout
2) Fixed issue with leave not working correctly with do-until loop
3) Fixed issue with if, when, dox not using correct test string in some cases
4) Fixed issue with attribute transition not clearing actionFlag
5) Introduced two new XMLi Options:
- Mode has XMLI_MODE_STD (default and current)
XMLI_MODE_CGI (allows caller to use and free managed memory outside template)
- Load Style has XMLI_LOAD_STYLE_STD (default and current)
XMLI_LOAD_STYLE_ON_CHANGE (always pass path on loadTemplate but reload
will only occur if file has changed)
LOAD_STYLE_ON_CHANGE can be used to enable hot-swap of templates in a running HTTP Server
***********************************************************************************************
Changes for Version 1.0.0: Date 13/02/2010 through 01/11/2010
***********************************************************************************************
1) Added support for loading and switching between up to 256 template definitions
2) Added ability to pass template name and up to 64 parameters on call to xmli_runTemplate()
3) Added <xmli:include /> element to allow the include of static xml from a stream file to the template. This occurs only once, during template load
4) Added <xmli:escape-markup /> element to allow the markup of all output xml within this element to be escaped with entity references
5) Added 4 new xml output formats. Now supported: none, simple, pretty, tabbed, template
6) <xmli:call-handler /> now includes a reset attribute to condition whether to reset the current offset in the memory space back to 0
7) <xmli:write-to-file /> now includes a reset attribute to condition whether to reset the current offset in the memory space back to 0
8) Added <xmli:write-to-stdout /> element to allow writing to standard output. This includes a reset attribute, as above
9) Fixed issue with variable data allocation to allow values to be correctly set for variables at run-time
10) Fixed issue with pre-defined static entity references not transposing to output xml correctly
11) Refactored element data parsing code to make it more efficient
12) Re-engineered the storage of template static resource to considerably enhance runtime performance, and allow for more efficient building of multiple template resources
13) Added <xmli:do-while> looping construct
14) Added <xmli:do-until> looping construct
15) Added <xmli:for> looping construct
16) Enhanced <xmli:leave /> and <xmli:iter /> to support leaving the three new looping constructs in addition to the <xmli:for-each> SQL Result Set looping construct
17) ADDED ABILITY TO PLUG IN XMLI EXTENSIONS
This is a major advance ans it now allows for custom extensions to be built into XMLi. Extensions for working with strings, dates, times, timestamps, math, and xml data are provided
18) New xmli XSD Schema Created
This schema can be included in the XML Catalogue in RDi to allow for Content Assis when building the template
19) Modified the xmli template root tag to be written as either <xmli-template> (original) <xmli:template> (preferred)
20) Added <xmli:space> and <xmli:crlf>
21) Re-engineered conditional test to provide a more intuitive interface and compound tests
22) added <xmli:choose> conditional construct to emulate the select/when/otherwise/endsl construct
23) Re-engineered conditional testing to support full expressions.
***********************************************************************************************
*** NOTES ON XMLI EXTENSIONS ***
***********************************************************************************************
The extensions used by XMLi are configured as follows:
Give your extension a namespace prefix and namespace. The namespace prefix is used to prefix XML elements used by your extension. The associated namespace should be a unique value. By convention URIs are used as namespaces. This is because naming conflicts are reduced due to the fact that two different entities don't share the same domain name (myCompany.com, etc).
Your extension is registered with XMLi by adding this definition to the xmli_config.xml file. The default config file is found in /XMLi/config. You can create different config files for different applications and tell XMLi to use them by calling xmli_loadCOnfig().
*** THis is highly recommended ***
An example Extension config entry is displayed below:
<!-- Example String Extension -->
<extension name="string" namespace="http://www.larryducie.com/string" version="1.0" core="true">
<object-name>XMLI_STRNG</object-name>
<object-type>*SRVPGM</object-type>
<object-library>XMLILIB</object-library>
</extension>
The prefix is "string" and the namespace is ""http://www.larryducie.com/string"
This definition also tells XMLi which service program object is associated with the Extension and where to find it. The object library can be *LIBL.
Once this config is loaded any XMLi templates that contain elements beginning with the "string" prefix will cause XMLi to pass control to the Extension for each START ELEMENT, ATTRIBUTE NAME, ATTRIBUTE CHARS, CHARS, and END ELEMENT. The values are resolved by XMLi prior to passing the values to the eXtension.
Here is some sample XML that uses the extension above.
<!-- Substring from a position 4 from the right for a length of 3 -->
<string:substring start="-4" length="3" ><xmli:value-of select="variable2" /></string:substring>
In this instance, the value of variable2 is passed to the string extension as CHARS and the extension will return the substring value (In this case, substringing from the right).
An extension is declared within a template by adding a namespace declaration (xmlns) in the root element of the template:
<xmli:template xmlns:xmli="http://www.sourceforge.net/xmli" ccsid="819"
xmlns:string="http://www.larryducie.com/string" format="pretty">
This associates the namespace with the prefix (as in the config file).
When the template is loaded this declaration tells XMLi to locate the associated service program (as defined in the config file) and load/activate it. This is all done dynamically - no need to compile/bind to the extensions. If the service program has already been activated it is simply bound to it (handy if you have already pre-loaded it with config information prior to running your template).
If you have an extension you use frequently then you may want to define it as core to your application. This is done by adding the core="true" attribute to the extension element in the config file (See above). When this is set the extension is loaded/bound when the config file is loaded. This means the extensions can be loaded and ready to use before a single template is called - very useful when running in a HTTP server.
If you have a conflict with a namespace prefix you can simply change the prefix in the config file and namespace declaration at the top of your template and XMLi will associate the new prefix with your extension.
Alternatively, if you or another developer/company writes a better/cooler version of an existing extension then all you have to do to use the new version is alter the config file to point to that new SRVPGM object. That's it!!!
Some prefixes are reserved. You can see this by trying to open Example27.xml in a browser. THe browser doesn't like it because I used "xml" as the prefix for the xml Extension. This is reserved by the XML specification and I was a little naughty using it. XMLi doesn't care though, and as the extension elements are consumed by XMLi and not transferred to the xml you generate it doesn't hurt anybody. If you wish to change it though, simply change the xml prefix in the config file to a name of your choice, and use that name in your template.
Download Latest Version
XMLI_V101_For_V5R4.zip (4.5 MB)
