The following are some of the XML Thunder key features and concepts that users should be aware of:
User Interface Customization
Under Tools -> Default Properties -> Editor, there are settings that allow you to customize the toolset interface. Two settings that are very helpful are “Optional nodes shown with “?” and Extensible nodes shown with “+”.
With these two settings turned on, you can quickly see which XML nodes are optional (by the “?”) and extensible (by the “+”).
Extensible means that the node can have more children are defined in the Handler Definition. If a node is defined as extensible, then an error will not be raised if a Reader encounters a child under that node that is not defined in the handler definition.
By default, all nodes are extensible. You can change this setting by going to Tools -> Default Properties -> XML Rules -> XML Node Defaults .
Controlling the Program Data Field Names
For Handlers created with a “derived” IDS structure, XML Thunder will apply its own naming conventions to the program data field names. You can configure how these fields are named by choosing “More Options” next to IDS on the Code Generation window.
Below is the “More Options” panel showing the configuration options.
Code Generation – Compact Code
When generating Readers, it is always best to have the compact code option checked. The compact code generator was introduced with version 4. It has several improvements over the original version 3 generator and there are some features that are only implemented in the compact generator. The non-compact code generator was kept to maintain backward compatibility with handlers generated under version 3.
XML Thunder makes use of “special fields” to:
• Return additional information found by XML Readers when parsing and
• Allow for greater control of XML output by XML Writers.
A special field is included in the program data fields (IDS) that make up the API into the Handler; however, unlike other fields in the IDS, they do not exist in the XML structure. There are five special fields.
1. Optional Field Flags
4. Track Pointer
5. Extended Precision
Below is an example of an IDS containing all 5 special fields:
fields are automatically inserted for repeating structures. There is no toolset setting to turn counters on/off. If a structure repeats, it will have a counter field. Optional Field Flags, Length
and Track Pointers
can be turned on/off at the Node level. These settings are found in the property pane under Generation Settings.
Optional Flag Fields
and Extended Precision
can also be turned on/off at the Handler level.
Optional Field Flags and Counters are by far the most common special fields used. Here is a brief description of each special field. A more complete description can be found in the XML Thunder User Manual.
1. Optional Field Flags
• Flag = 1
indicates node was found in XML document; Flag = 0
indicates node was not found in XML document
• Helpful to determine if the value in the program field came from the XML document or is the initialized value. For example, if an XML message contains a node containing temperature, it may be helpful to know if the value “0” came from the XML document or is the initialized value.
• Flag = 1
indicates node should be written out in XML document; Flag = 0
indicates node should be suppressed in XML document
• Helpful to remove complete branches or individual nodes from XML output. You use this as part of conditional logic (sometimes output the node, sometimes do not output the node) or to permanently suppress a node or branch (i.e. an unnecessary portion of the XML message). For example, it may be the case that an empty XML node should not be output in the XML document (e.g.
). If this is the case, an Optional Field Flag can be used to suppress the node when its content is empty.
2. Counter Fields
• Counter fields are automatically inserted for repeating structures. There is no toolset setting to turn counters on/off. If a structure repeats, it will have a counter field.
• Indicates how many occurrences of a repeating structure were found in the XML document.
• Helpful to know how many of iterations of a repeating structure need to be processed by the calling program. For example, if a structure can repeat up to 1,000 times and the counter returned by the Reader is “10”, then the calling program knows that it is only necessary to process the first 10 occurrences (the rest are empty)
• Indicates how many occurrences of a repeating structure should be output in the XML document.
• Prevents empty nodes from being output for repeating structures. For example, if a structure can repeat up to 1,000 times, but you only have content for 10 occurrences, setting the counter to “10” will output only the first 10 occurrences.
3. Length Field
• Used for variable length fields
• Indicates the length of a field found
• Used for variable length fields
• Specifies how many characters of the field to output
4. Track Pointer Fields
• Indicates the start of an element’s open tag and end position of an element’s closing tag.
• Does not apply
5. Floating Point Fields
• Indicates the number of decimal positions found in a numeric field
• Used to control decimal precision for decimal fields
• Indicates the number of decimal position contained in a numeric field
Toolset Default, XML Handler Default and Node Properties»
The properties for an XML Handler can be controlled at three levels – Default (or system), Handler and Node.
Default Level (or system) settings are used when creating new Handlers or when manually adding new nodes to an existing Handler design. They are used to initialize the Handler Level settings for each new handler created. Aside from affecting new nodes, changes to the Default Level properties do no affect existing handlers. Default Properties can be modified using Tools -> Default Properties or by clicking the Default Properties icon on the menu bar.
Handler Level properties affect only the current Handler. They are initialized using the Default Level settings when the handler is first created. These settings can be modified using XML Handler -> Properties or by clicking the Handler Properties icon on the menu bar.
XML Node Level properties are initialized using the Handler Properties. Node Level properties can be viewed in the XML Properties pane on the right side of the designer window.
When a Handler Property is changed, it is propagated down to every node that uses the default property. Nodes that are using the handler default settings will have the word “(default)” showing as a part of the property value. This means that, if a particular node has the value “(default)”, it will pick up the value from the handler properties (see below).For example, if the Date Separator is changed from “None()” to “/” at the handler level, then every Date domain node with a separator value of “default” will inherit that property value.
The handler properties can be over-ridden at the XML node level by clicking on the XML node and changing the particular value in the properties pane. By selecting a “non-default” value for a property, the property value will not be affected if the handler-level properties are later changed.
Working with Large Documents
There a couple of things to be aware of that may be helpful when working with large XML Handler Designs. The first is that you can reduce the size of your handler design by removing unwanted nodes. The second is that you can choose to generate a handler using the “Node-Level” option.
Customizing a Handler Design
You can remove unwanted nodes and branches from your handler design by right-clicking on a node and choosing “Remove”.
Node-Level Code Generation
XML Thunder can generate two distinct handler types for processing XML instances; document-level and node-level.
A document-level handler processes the entire XML instance in one call. The calling program gathers all required data, calls the XML handler and receives back the results. A node-level handler on the other hand uses several calls to process an XML instance. Each call processes a portion of the XML and the handler is continually called until the entire instance has been processed.
In most cases a document-level handler will meet your needs. In some cases though, an XML document may be so large that the size of the program data structures required to support the document will exceed the limitations of the compiler. For example, it may not be possible to define an XML-BUFFER field large enough to hold the entire document or the OCCURS clause on a structure may be too large. In these cases, a node-level handler can be used.
There are no changes required to a handler design to support node-level processing. It is a code generation setting that is used to control the handler type.
See the XML Thunder help for more details on node-level processing.
Over time, a handler definition may need to be modified to support changes to an XML message. For example, a new version of an XML schema may be released resulting in XML nodes being added or removed.
If the Handler Design was created by letting XML Thunder derive the IDS side (i.e. the program data fields), then there are 2 possible approaches. If the Handler design was created using an existing data structure (COBOL copybook or C Header file, then you can use the XML Thunder Adopt feature.
Implementing Changes in Handlers that Derive IDS Side from XML Side
If the Handler Design was created by providing an XML structure (schema, WSDL, DTD or sample instance) and the IDS was derived based in the XML, then you can:
1. Add, remove or change the XML nodes manually using the designer.
• If there are only a few nodes to be changed, you can implement the changes yourself in the designer. You can change properties for an existing node (e.g. name, length, number of occurrences, etc.) by selecting the node and changing its properties. You can also right click on a node and Add / Remove nodes from the design. Any change to the XML structure will automatically be reflected in the IDS structure since the IDS side is “derived” from the XML side.
2. Create the Handler Design again using the new schema.
If the number of changes to the schema is fairly large, you may find it easier – and safer – to simply recreate the handler using the new schema.
Implementing Changes in Handlers Created From a Predefined IDS Structure
If the Handler Design was created by providing an IDS structure (COBOL copybook or C header file), then you can use the Adopt feature.
To use the Adopt feature:
1. Create a new copybook. The new copybook will look exactly the same as the original copybook except that it will contain the new fields that will mapped to the new xml nodes.
2. Create a new XML Thunder Handler Design using the new copybook. For the XML Structure you can choose your new schema – but it doesn’t really matter what you use for the XML structure (i.e. the right-hand side) because it will be replaced.
3. In the new handler go to XML Handler -> Adopt and select your original handler.
4. Choose to “Auto Match” on name (there is an “Options” setting that will let you configure how the matching is done, but the default is to match on name).
5. The adoption will bring in all of the XML settings from original handler.
6. Manually add the new XML nodes to the XML structure.
7. Manually map the new XML node to the IDS field.