XML Thunder offers two approaches for processing XML documents - Document-Level and Node-Level. This is controlled by a setting on the code generation window (also found under XML Handler -> Properties -> Code Generation -> General)
Document-Level processing is the most straight forward approach and meets most customers’ needs. For an XML Reader, the entire XML document is passed into the Handler (via the XML-BUFFER field) and the complete set of program data fields is returned (via the IDS fields).
Document-Level Readers require that you set the number of occurrences for repeating structures high enough to handle the most extreme case. If the document contains more occurrences than you defined then an error is raised.
To set the max Occurs in the XML Thunder toolset, select the node and change the Max Occurs property.
Setting the max Occurs for a repeating structure
The COBOL copybook for a document level reader will have an OCCURS clause for the upper limit of the repeating structure. In the example, below, it will be able to hold up to 10,000 occurrences of
In addition to Document-Level Readers, XML Thunder offers a more advanced approach called Node-Level processing. A Node-Level Reader works with “flattened” data structures. There are no "occurs" clauses used for the repeating structures. Instead, the XML Reader will be called multiple times - once for each occurrence in the repeating structure in the XML document. There are two main reasons for using a Node-Level Handler. They are:
1. The maximum XML document size is extremely large. In some cases, the document may be so large that the required size for the XML-BUFFER field will exceed the compiler limit. This can also be true for the Interface Data Structure (IDS) if the combination of nested repeating structures and data fields is very large.
2. The upper bound of a repeating structure is unknown. In other words, there is no “safe” upper limit that you can set for a repeating structure.
With a node-level XML Reader, each call to the Reader will return one occurrence from a repeating structure. You iteratively call the Reader until all occurrences have been processed. There is no limitation on the number of repeating structures that can occur in the document – nor is there a limitation on the number of levels of nested repeating structures that can occur.
You should set the unbounded property for the repeating structure to “true”. ** Note that a node-level Reader will use the node-level approach on all repeating structures in an XML document. If you have several repeating structures, they will all be read one at a time. You should only set the unbounded property to “true” for the structures that have no upper limit. If you want, you can leave the unbounded property set to “false”, but an error will be raised if the number of occurrences found in the document exceeds the max Occurs property.
Note that IDS (COBOL program fields) will no have an OCCURS clause. A counter field is still provided though to identify whether or not an occurrence was found. If the counter is “0” after a call to the Reader, then no occurrence of was found (i.e. all have been read).
Node-Level Handlers require more logic in the calling program to manage the multiple calls to the Handler, but they are capable of reading and writing documents of any size with unbounded repeating structures. The sample Test Harness generated by XML Thunder provides a great working example to follow.
Test Harness Details
A node-level Reader is an advanced approach for processing an XML document. The Reader is called repeatedly – once for each iteration in the XML document. Here are some more details on the key paragraphs in the Test Harness to help explain how this is done.
In the BUSINESS-LOGIC-BEFORE paragraph, the entire XML document is read and loaded into a field called TH-DATA-BUFFER. This is to simulate a generic data store area that will contain the entire XML document. You will not use this logic in your production program.
In the INVOKE-XML-HANDLER paragraph, the XML-BUFFER field is filled before calling the XML Reader. If the entire XML document can fit in the XML-BUFFER field, then this only needs to be done once – at the beginning. If the entire document cannot fit in XML-BUFFER, the logic here can be cloned and used to refill the Buffer before each call. The Reader removes what it has read from the buffer as part of the call – opening up room to append more to the end. The XML-PTR-BUFFER field holds the position of the current end of the document. You can use this field to know where to append to XML-BUFFER.
At the of the INVOKE-XML-HANDLER paragraph, the XML-BUFFER field should be populated with as much of the XML document as possible. The CALL-TO-XML-HANDLER paragraph can now be executed.