Thunder Suite   •  JSON Thunder   •  XML Thunder   •  FAQs   •  Tutorials   •  Wiki   •  Levelset History   •  JSON Thunder Technical Details   •  XML Thunder Technical Details

Thunder Wiki for Thunder Suite, JSON Thunder & XML Thunder

Page History: XML Schema Choice, Sequence and All

Compare Page Revisions



« Older Revision - Back to Page History - Newer Revision


Page Revision: 2015/11/25 15:02


XML schemas define the “rules” that a set of XML documents must follow. These “rules” cover things such as:

· The structure of an XML document (e.g. element and attribute names, minOccurs, and maxOccurs)

· The data content found within the XML document (e.g. minLength, maxLength, and domain)


As part of defining the structure of an XML document, XML schemas use order indicators (also known as compositors) to specify how child elements may appear. There are three order indicators - <sequence>, <all> and < choice >. The following describes these order indicators and how they are supported in XML Thunder.

   

XML Schema Sequence

Order indicator denotes that child elements must appear in the exact order they are listed. The example below specifies the order for the elements under < Customer >.

XML Schema Example
Image

Valid XML Document (children of < Customer > are in correct order)
Image


Invalid XML Document (children of < Customer > are not in correct order)
Image






XML Schema All

< all > denotes that child elements can appear in any order. The example below specifies that the elements under < Customer>.

XML Schema Example
Image

Valid XML Document
Image

Also Valid XML Document (any order is allowed for children of < Customer >)
Image
The parent and children of an order indicator must be an elements. The child elements of < all> can appear 0 or 1 times. However, repeating children (i.e. maxOccurs > 1) are not allowed.

XML Schema Choice

< choice > denotes that only one of the child elements can appear in the document. The example below specifies that the elements under
are mutually exclusive. A document can have either < CAN-Address >, < US-Address > or < OtherCountry >. Only one of those elements can appear in any one document instance.
Image

Valid XML Document
Image

Invalid XML Document (both choices are appearing in the same document)
Image

XML Thunder Support for Order Indicators

XML Thunder fully supports XML Schema order indicators. When creating a new Handler from an XML schema, Thunder extracts < sequence >, < all > and < choice > information and gives a representation in the Handler Design.
Image

XML < sequence > Support

· An XML Thunder Writer will always output the XML in the order shown in the Handler Design thereby ensuring that the sequence is correct.

· An XML Thunder Reader will validate and XML document for sequence and raise an “Out of Sequence” error when child nodes are out of order.


XML Support

· An XML Thunder Writer will always output the XML in the order shown in the Handler Design. Since order doesn’t matter for < all >, any order will be valid. Other rules of < all > (elements only and no repeating immediate children) are respected because the elements are defined this way in the Handler Design.

·An XML Thunder Reader will allow any order for the immediate children of an indicator. Other rules of < all > (elements only and no repeating immediate children) are respected because the elements are defined this way in the Handler Design.


XML < choice> Support
Thunder provides a special field called “selection” to control choice structures. It is mapped to an IDS field.
Image

As with all special fields, the “Selection” attribute will not appear in the actual XML instance created by a Writer, nor will it be searched for by an XML Reader. It is included in the Handler copybook so that the calling program can work with choice structures.


Customizing the Selection Attribute

You can customize certain properties of the Selection attribute by going to Tools -> Default Properties -> XML Rules -> XSD Indicators.


Image

· Selection attribute name allows you specify your own name for the selection field (default is “Selection”).

· Selection attribute length allows you specify the length of the selection field (default is 100). 

· Selection attribute value. The value of the selection attribute value determines which choice is created (for a writer) or specifies the choice that was read (for a reader). You have two options for how the selection attribute value is set - “XML Node Name” and “Qualified XML Node Name”.


Qualified XML Node Name:

The selection attribute will contain the full name (including context) of the XML node that comprises one of the choice nodes. Using the qualified XML Node Name will mean the the selection attribute value be longer, but will be unique.


Example: Contact.Customer.Address.XT-XML-CHOICE-0003.CAN-Address


Node Name:

The selection attribute will contain the name (excluding context) of the XML node that comprises one of the choice nodes.


Example: CAN-Address


Implementing Choice as COBOL Redefines or C Union

Because an XML choice specifies that one – and only one – of the choices can appear in any XML instance, it is possible to use a COBOL redefines or C union structure to support this. You can control how the choice is implemented by going to Handler -> Properties -> IDS Rules (it can also be configured under Tools -> Default Properties).

Image


Working with Choice Structures

XML Thunder will include a choice “selection” field in the program data structure used as the API to the Reader or Writer. Below is an example of a selection field generated to support a choice structure for address types. The possible selection values are listed as 88 levels.

Image
The XML Thunder Test Harness contains all of the logic necessary for processing choice structures and can be customized for your own calling program.

For Readers:
The XML Reader will parse the XML document and populate the selection attribute with the value of the choice that was found. The calling program can then use the selection value to know which choice structure to work with.
In the above example, a selection value of “CAN-Address” tells the calling program that the CHOICE-DATA-0003 redefined area contains the CAN-ADDRESS structure.

E.g
           IF SELECTION-0003 IS EQUAL TO "CAN-Address"
                DISPLAY "PROVINCE: " PROVINCE
                DISPLAY "POSTALCODE: " POSTALCODE
           END-IF
For Writers:
The calling program will populate the selection attribute with the “choice” to be output.  In the above example, setting the selection to “CAN-Address” tells the Writer program to the CAN-Address XML choice using content from the CAN-Address redefined area.

E.g.
MOVE "CAN-Address" TO SELECTION-0003
Summary
XML Thunder fully supports the XML Schema Order Indicators < sequence>, < all> and < choice>. For more information on this topic or on XML Thunder in general please contact support@canamsoftware.com