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

Back
XML Schema Choice, Sequence and All

<div style='clear: both;'>
        XML schemas define the “rules” that a set of XML documents must follow. These “rules” cover things such as:
    </div>
    <p>
        <span style='font-family: Symbol'>·</span> The structure of an XML document (e.g. element and attribute names, minOccurs, and maxOccurs)
    </p>
    <p>
        <span style='font-family: Symbol'>· </span>The data content found within the XML document (e.g. minLength, maxLength,
and domain)
    </p><br><div style='clear: both;'>
        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 - &lt;sequence&gt;, &lt;all&gt; and &lt;choice&gt;. The following describes these order indicators and how they are supported in XML Thunder.
    </div><br> &nbsp; &nbsp; <div style='clear: both;'>
        <h3>XML Schema Sequence</h3>
    </div>
    <div style='clear: both;'> Order indicator &lt;sequence&gt; denotes that child elements must appear in the exact order they are listed. The example below specifies the order for the elements under &lt;Customer&gt;. 
    </div><br><div style='clear: both;'><b><i>XML Schema Example</i></b></div>
    <div style='clear: both;'>
        [imageleft||{UP(ChoiceSequenceAll)}image001.jpg]
    </div>
    <div style='clear: both;'><br><b><i>Valid XML Document (children of
            &lt;Customer&gt;
            are in correct order)</i></b></div><div style='clear: both;'>[imageleft||{UP(ChoiceSequenceAll)}image002.jpg]</div>
    <div style='clear: both;'><br><b><br><i>Invalid XML Document (children of
            &gt;Customer&gt;
            are not in correct order)</i></b></div><div style='clear: both;'>[imageleft||{UP(ChoiceSequenceAll)}image003.jpg]</div>



    <b><br><span style='font-size: 14.0pt; line-height: 107%; font-family: "Calibri",sans-serif'>
        <br
            clear="all" style='page-break-before: always'>
    </span></b>
    <div style='clear: both;'><br><h3>XML Schema All</h3>
    </div>
    <div style='clear: both;'>
        &lt;all&gt; denotes that child elements can appear in any order. The example below specifies that the elements under &lt;Customer&gt;. 
    </div>
    <div style='clear: both;'> <br><b><i>XML Schema Example</i></b>
    </div>
    <div style='clear: both;'>
        [imageleft||{UP(ChoiceSequenceAll)}image004.jpg]
    </div>
    <div style='clear: both;'><b><br><i>Valid XML Document</i></b>
    </div><div style='clear: both;'>
        [imageleft||{UP(ChoiceSequenceAll)}image002.jpg]
    </div>
    <div style='clear: both;'>
        <b><br><i>Also Valid XML Document (any order is allowed for children of
            &lt;Customer&gt;)</i></b>
    </div>
    <div style='clear: both;'>
        [imageleft||{UP(ChoiceSequenceAll)}image003.jpg]
    </div>
    <div style='clear: both;'>
        The parent and children of an
        &lt;all&gt; order indicator must be an elements. The child elements of &lt;all&gt;
        can appear 0 or 1 times. However, repeating children (i.e. maxOccurs > 1) are not allowed.</div>
    <div style='clear: both;'> <br><h3>XML Schema Choice</h3>
    </div><div style='clear: both;'>
        &lt;choice&gt; denotes that only one of the child elements can appear in the document. The example below specifies that the elements under &lt;Address&gt; are mutually exclusive. A document can have either &lt;CAN-Address&gt;, &lt;US-Address&gt; or &lt;OtherCountry&gt;. Only one of those elements can appear in any one document instance.</div>
    <div style='clear: both;'>
        [imageleft||{UP(ChoiceSequenceAll)}image005.jpg]
    </div>
    <div style='clear: both;'><b><br><i>Valid XML Document</i></b>
    </div>
    <div style='clear: both;'>[imageleft||{UP(ChoiceSequenceAll)}image006.jpg]</div>
    <div style='clear: both;'> <br><b><i>Invalid XML Document (both choices are appearing in the same document)</i></b>
    </div>
    <div style='clear: both;'>[imageleft||{UP(ChoiceSequenceAll)}image007.jpg]</div>
    <div style='clear: both;'><br><h3>XML Thunder Support for Order Indicators</h3></div><div style='clear: both;'>XML Thunder fully supports XML Schema order indicators. When creating a new Handler from an XML schema, Thunder extracts
        &lt;sequence&gt;, &lt;all&gt; and &lt;choice&gt;
        information and gives a representation in the Handler Design.
    </div><div style='clear: both;'>[imageleft||{UP(ChoiceSequenceAll)}image008.jpg]</div><div style='clear: both;'><br><b><i>XML
            &lt;sequence&gt;
            Support</i></b></div><p>
        <span style='font-family: Symbol'>· </span>An <b>XML Thunder Writer</b> will always output the XML in the order shown in the Handler Design thereby ensuring that the sequence is correct.
    </p><p><span style='font-family: Symbol'>· </span>An <b>XML Thunder Reader</b> will validate and XML document for sequence and raise an “Out of Sequence” error when child nodes are out of order.
    </p><div style='clear: both;'><br><b><i>XML
            &lt;all&gt;
            Support</i></b>
    </div><p><span style='font-family: Symbol'>· </span>An <b>XML Thunder Writer</b> will always output the XML in the order shown in the Handler Design. Since order doesn’t matter for
        &lt;all&gt;, any order will be valid. Other rules of &lt;all&gt;
        (elements only and no repeating immediate children) are respected because the elements are defined this way in the Handler Design.
    </p><p>
        <span style='font-family: Symbol'>·</span>An <b>XML Thunder Reader</b> will allow any order for the immediate children of an
        &lt;all&gt; indicator. Other rules of &lt;all&gt;
        (elements only and no repeating immediate children) are respected because the elements are defined this way in the Handler Design.</p>
    <div style='clear: both;'><br><b><i>XML
            &lt;choice&gt;
            Support</i></b><br></div>
    <div style='clear: both;'>
        Thunder provides a special field called “selection” to control choice structures. It is mapped to an IDS field.
    </div><div style='clear: both;'>
        [imageleft||{UP(ChoiceSequenceAll)}image009.jpg]
    </div><p class="BodyText">
        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.</p>
    <p class="BodyText"> <br><b><i>Customizing the Selection Attribute</i></b>
    </p>
    <p class="BodyText">
        You can customize certain properties of the Selection attribute by going to Tools -> Default Properties -> XML Rules -> XSD Indicators.</p><p class="BodyText"><br>[imageleft||{UP(ChoiceSequenceAll)}image010.jpg]</p><p class="BodyText"><span style='font-family: Symbol'>· </span><b>Selection
attribute name</b> allows you specify your own name for the selection field (default is “Selection”). </p><p class="BodyText">
        <span style='font-family: Symbol'>· </span><b>Selection attribute length</b>
        allows you specify the length of the selection field (default is 100).&nbsp; 
    </p><p class="BodyText">
        <span style='font-family: Symbol'>· </span><b>Selection attribute value. </b>The
value of the selection attribute value determines which choice is<b> </b>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 - “<b>XML Node Name</b>” and “<b>Qualified XML Node Name</b>”. </p><p class="BodyText"> <br><b><i>Qualified XML Node Name:</i></b>
    </p>
    <p class="BodyText">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.</p><p class="BodyText"> <br><i>Example:</i> Contact.Customer.Address.XT-XML-CHOICE-0003.CAN-Address
    </p>
    <p class="BodyText"> <br><b><i>Node Name:</i></b></p><p class="BodyText">
        The selection attribute will contain the name (excluding context) of the XML node that comprises one of the choice nodes. </p><p class="BodyText"><br><i>Example:</i> CAN-Address
    </p>
    <p class="BodyText"> <br><b><i>Implementing Choice as COBOL Redefines or C Union</i></b>
    </p>
    <p class="BodyText">
        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).
    </p><p class="BodyText">
        [imageleft||{UP(ChoiceSequenceAll)}image011.jpg]
    </p>
    <div style='clear: both;'><br><b><i>Working with Choice Structures</i></b></div>
    <p class="BodyText">
        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. 
    </p>
    <div style='clear: both;'>[imageleft||{UP(ChoiceSequenceAll)}image012.png]</div>
    <div style='clear: both;'>
        The XML Thunder Test Harness contains all of the logic necessary for processing choice structures and can be customized for your own calling program.
    </div>
    <div style='clear: both;'> <br><b><i>For Readers:</i></b></div>
    <div style='clear: both;'>
        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.
    </div>
    <div style='clear: both;'>
        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.
    </div>
    <div style='clear: both;'> <br>E.g
    </div>
    <div style='clear: both;'>
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; IF SELECTION-0003 IS EQUAL TO "CAN-Address"
    </div>
    <div style='clear: both;'>
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;DISPLAY "PROVINCE: " PROVINCE 
    </div>
    <div style='clear: both;'>
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DISPLAY "POSTALCODE: " POSTALCODE 
    </div>
    <div style='clear: both;'>
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; END-IF
    </div>
    <div style='clear: both;'><br>
        <i><b>For Writers:</i></b></div>
    <div style='clear: both;'>
        The calling program will populate the selection attribute with the “choice” to be output.&nbsp; 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.</div>
    <div style='clear: both;'><br>E.g.
    </div>
    <div style='clear: both;'>
        MOVE "CAN-Address" TO SELECTION-0003
    </div>
    <div style='clear: both;'>
        <b>Summary</b>
    </div>
    <div style='clear: both;'>
        XML Thunder fully supports the XML Schema Order Indicators
        &lt;sequence&gt;, &lt;all&gt; and &lt;choice&gt;. For more information on this topic or on XML Thunder in general please contact support@canamsoftware.com
    </div>
</div> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
Modified on 2015/11/25 17:25 by Kristin Sedgwick
Tags: Not Tagged
Consent Management • Privacy Statement • Terms of Use
Username
Email
Password
First Name
Last Name