DEV03 - Using XML from REXX

Christian Langanke for netlabs.org

Overview

• Why XML files for REXX scripts ?
• What is already available ?
• REXXXML - pros and cons
• Yet another REXX solution ?
• Exploring REXX stem variables
• RXXML API / Parsing Sample
• Using XML validation / DTD / XML Schema
• Current Limitations
• Things to do

Why XML files for REXX scripts ?

• allows complex configuration files
• allows implementation of complex data interfaces
• can be used to read data from XML standard application document formats
  • think of OpenOffice.org documents
• validation implemented by parser -
  requires definition by DTD or XML Schema

What is already available ?

• REXX code for parsing XML code
  • puts several restrictions on the XML format
  • slow (interpreted code)
• REXXXML
  • REXX implementation of the libxml API
• more ?...

REXXXML - pros and cons

• pros
  • high-quality implementation of a REXX API
  • complete implementation of the libxml API
    • provides all features of the libxml API
    • very useful for prototyping usage of libxml features
  • extremely well documented
    • also included:
      docs on REXX basics, XML, DTD, XML Schema,...
• cons
  • implementation of libxml API not REXX-like
  • XML file contents is read into a binary DOM tree
    • pointers are used to represent nodes of the tree, passed back to REXX (!)
    • access to elements and attributes only by scanning the tree
    • not suitable for small used cases, too much code required to read the data of a XML file

Yet another REXX solution ?

• Goals of an alternative REXX interface
  • no 1 to 1 implementation of a C API
  • easy-to-use (string) interface,
    provide all data in a REXX-alike way
  • concentrate on functionality required for most use cases,
    possibly accept limitations as trade-offs
  • prefer simplicity over functionality, where acceptable
  • take REXXXML as a fallback solution, where limitations are a problem

Exploring REXX stem variables 1/3

• stem variables are
  • compound symbols
  • are used to build associative arrays

• Classic REXX example:

  
    /* Code */
    Website.0 = 3
    Website.1 = 'www.netlabs.org'
    Website.2 = 'www.os2voice.org'
    Website.3 = 'www.os2world.com'
  
    DO ThisSite = 1 TO Website.0
       SAY Website.ThisSite
    END
  
    /* Output */
    www.netlabs.org
    www.os2voice.org
    www.os2world.com
    

Exploring REXX stem variables 2/3

• XML represents data in a hierarchical namespace
  

  
    <inventory>
      <drink>
        <lemonade>
          <price>$2.50</price>
          <amount>20</amount>
        </lemonade>
        <coke>
          <price>$1.50</price>
          <amount>10</amount>
        </coke>
      </drink>
  
      <snack>
        <chips>
          <price>$4.50</price>
          <amount>60</amount>
        </chips>
      </snack>
    </inventory>
  

Exploring REXX stem variables 3/3

• multidimensional arrays also can be used to represent a hierarchical namespace
  

  
  
   Inventory.Items                   = 'Drink Snack'
   Inventory.Drink.List              = 'Lemonade Coke'
   Inventory.Drink.0                 = 2
   Inventory.Drink.1.Lemonade.Price  = '$2.50'
   Inventory.Drink.1.Lemonade.Amount = 20
   Inventory.Drink.2.Coke.Price      = '$1.50'
   Inventory.Drink.2.Coke.Amount     = 10
  
   Inventory.Snack.List              = 'Chips'
   Inventory.Snack.0                 = 1
   Inventory.Snack.1.Chips.Price     = '$4.50'
   Inventory.Snack.1.Chips.Amount    = 60
  

RXXML API

• RxXmlLoadFuncs
• RxXmlDropFuncs
• RxXmlVer
• RxXmlParseFile

Parsing Files with RXML 1/2

• Parse XML Files with

  
  rc = RxXmlParseFile( File, Stem,
                       Options[, XPathExpr, NsList])

• Parameters:
  • File: pathname of XML file
  • Stem: name of stem variable to receive XML data
  • Options: processing options (DPEV)
  • XPathExp: XPath expression to specify the part of the XML file to be read
  • NsList: list of Namespaces being used in the XPath expression

Parsing Files with RXML 2/2

• Processing options
  • D - dump/display variables added to the stem to standard output
    does not provide 100% valid REXX code (watch out for quotes)
  • P - prefix element and attribute names with an underscore to prevent name clashes with other variables of the script
  • E - dump/display parser and validation errors to standard error
  • V - validate XML file against DTD and/or XML Schema
• Rules for validation
  • at least one of DTD or XML Schema must be provided
  • if both methods are provided, both must validate
  • DTD and XML Schema must be specified in the XML file
    • specify the XML Schema file in the attribute xsi:schemaLocation of the root element

Parsing Sample 1/2

• XML example test.xml

  
  <?xml version="1.0"?>
  <pim>
    <Contact FirstName='Carl'
             LastName='Meier'>My good old pal</Contact>
    <Contact FirstName='Mary'
             LastName='Meier'>Carl's wife</Contact>
  </pim>
  

• REXX code to parse the file and dump the stem variable

  
  Call RxFuncAdd 'RxXmlLoadFuncs', 'RXXML', 'RxXmlLoadFuncs'
  Call RxXmlLoadFuncs
  rc = RxXmlParseFile( 'text.xml', 'xml.', 'DP')
  

Parsing Sample 2/2

• resulting REXX stem variable

  
   xml.__RootElement='_pim'
   xml._pim._Contact.1._FirstName='Carl'
   xml._pim._Contact.1._LastName='Meier'
   xml._pim._Contact.1.__Properties='_FirstName _LastName'
   xml._pim._Contact.1='My good old pal'
   xml._pim._Contact.2._FirstName='Mary'
   xml._pim._Contact.2._LastName='Meier'
   xml._pim._Contact.2.__Properties='_FirstName _LastName'
   xml._pim._Contact.2='Carl's wife'
   xml._pim._Contact.0='2'
   xml._pim.__Elements='_Contact'
  

Using XML validation

• XML validation checks for the following in the parsed data
  • proper element hierarchy in the parsed XML data
  • element occurrence limits (define lower and upper limit)
  • matching attributes for a given element
    • only defined atributes are accepted
    • attributes may be defined as a prerequisite (must-have)
  • several "languages" are used to define the validation
    • Document Type Definition (DTD), is part of the SGML standard
    • XML schema
    • ... others ...

Using DTD 1/2

• a DTD can be included in the XML file
  
  file: pim.xml

  
  <?xml version="1.0"?>
  
  <!DOCTYPE pim [
    <!ELEMENT pim (Contact+)>
    <!ELEMENT Contact CDATA>
    
    <!ATTLIST Contact FirstName CDATA #REQUIRED>
    <!ATTLIST Contact LastName CDATA #REQUIRED>
   ]>
  
  <pim>
    <Contact FirstName='Carl'
             LastName='Meier'>My good old pal</Contact>
    <Contact FirstName='Mary'
             LastName='Meier'>Carl's wife</Contact>
  </pim>
  

Using DTD 2/2

• a DTD can be put in an external file
  
  file: pim.dtd

  <!ELEMENT pim (Contact+)>
  <!ELEMENT Contact CDATA>
  
  <!ATTLIST Contact FirstName CDATA #REQUIRED>
  <!ATTLIST Contact LastName CDATA #REQUIRED>
  

  
  file: pim.xml

  <?xml version="1.0"?>
  <!DOCTYPE pim SYSTEM "pim.dtd">
  <pim>
    <Contact FirstName='Carl'
             LastName='Meier'>My good old pal</Contact>
    <Contact FirstName='Mary'
             LastName='Meier'>Carl's wife</Contact>
  </pim>
  

Using XML Schema 1/3

• an XML Schema
  • is written using a specific XML language, using an own XML namespace
  • does not require extra knowledge than this XML language
• the following pim.xml defines pim.xsd as the schema:

  <?xml version="1.0"?>
  <pim xmlns="http://www.netlabs.org/samples/pim/1.0/"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
       xsd:schemaLocation="http://www.netlabs.org pim.xsd">
  
    <Contact FirstName='Carl'
             LastName='Meier'>My good old pal</Contact>
    <Contact FirstName='Mary'
             LastName='Meier'>Carl's wife</Contact>
  </pim>
  

Using XML Schema 2/3

• the following pim.xsd defines the schema for pim.xml

  
  
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             targetNamespace="http://www.netlabs.org/samples/pim/1.0/"
             xmlns="http://www.netlabs.org/samples/pim/1.0/"
             elementFormDefault="qualified">
  
    <xsd:element name="pim">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element name="Contact" type="TypeContact"
               minOccurs="1" maxOccurs="unbounded"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>
  
    <xsd:complexType name="TypeContact"  mixed="true">
      <xsd:attribute name="FirstName"  type="TypeNameString"/>
      <xsd:attribute name="LastName"   type="TypeNameString"/>
    </xsd:complexType>
  
    <xsd:simpleType name="TypeNameString">
      <xsd:restriction base="xsd:string">
        <xsd:maxLength value="255"/>
      </xsd:restriction>
    </xsd:simpleType>
  
  </xsd:schema>
  
  
  

Current Limitations - 1/2

• the maximum length of a REXX variable name is 252 characters
  • may be a problem for XML files with a long chain of child elements
  • is even worse when using the prefix option
• dot characters in element and attribute names are replaced with an underscore parameter
  • avoids problems with REXX stem variables
  • requires additional translation data when write access is imlemented

Current Limitations - 2/2

• element and attribute names differing only in case can not be used within the same parent element with (IBM) REXX
• Variables within the (IBM) REXX variable pool are stored uppercase only - Regina REXX can handle case sensitive varable names
• only the first XML schema specified in the XML file is being used for validation

Things to do

• implement write access - Options:
  • extend stem in compatible way
    Problem:
    • no way to catch errors, added data can be ignored by accident

  • scan REXX variable pool for added values to catch errors
    Problems:
    • REXX runtime stores names uppercase only, so tanslation data is required for proper naming of element and attribute names
    • XML schema can be used to determine the correct case for element and attribute names (naming limitation still applies)

  • use extra API to add elements and/or attributes to a XML stem
    Problems:
    • REXX coding overhead (acceptable ?)
    • yet most safe, probably best option

Questions and Answers

• Your questions ?
• Your suggestions ?
• Your comments ?

The End

Thank you very much for your your attention!