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

Suppressing Optional XML Elements and Attributes

When using XML Thunder to create an XML document, there are several options for suppressing XML elements and attributes.

Option 1 – Use “Optional Flag Fields”
The XML Thunder toolset has a setting called “Optional Flag Fields”.  When this setting is on, you will get “xxx-flag” fields next to each optional field in your generated copybook (note: only optional nodes can be suppressed).  The generated copybook will look as follows.  

For Writers:
Flag fields can be used to control which nodes are output by an XML Writer.  Setting a flag field to “0” will suppress the XML element or attribute. Setting it to “1” will output it.

For Readers:
Flag fields indicate if the value in the associated COBOL field came from the XML document or is an initialized value (i.e. it was not in the document being read).  For example, if a field containing temperature has a value of “0”, it may be important to know if the value is really a temperature or not.

The setting can be set at the toolset level (as a default for all new Handlers created), at the Handler level (as a default for the currently opened Handler) or at the individual node level. 

Toolset Default (only affects new Handlers)
Go to Tools -> Default Properties -> Code Generation -> General. 

Handler Default (only affects current Handler)
Go to XML Handler -> Properties -> Code Generation -> General.

Node Level (only affects selected node)
Select a specific XML node and change the Optional Flag Field setting (under Generation Settings). Remember only optional fields can have this setting set to “True”.

Option 2 – Exclude the Node
Beginning with XML Thunder version 4.5.24, a new include / exclude feature has been introduced.  This feature allows you to exclude XML elements and attributes (i.e. nodes) from a Handler design instead of deleting them.  Excluding a node (or branch of nodes) has the same effect as deleting a node in that:
* The excluded nodes will not appear in the generated IDS (COBOL copybook or C header file)
* The Reader will not look for excluded nodes
* The Writer will not output excluded nodes (Flag fields are not necessary to suppress a node). 

The difference between excluding and removing a node from a Handler design is that excluded nodes are still visible in the Handler design in the toolset.  This enables them to be brought back into the by using the “Include” command.  It is not possible to bring deleted nodes back into a Handler design.  

To exclude a node or branch of nodes, right-click on an element or attribute and choose “Exclude” (alternatively you can use the menu option under XML Item -> Exclude). 

Excluded nodes are greyed out and in italics.

To bring back a node or branch of nodes, right-click on the element or attribute and choose “Include”. 

You can only exclude/include elements and attributes. You cannot exclude/include , or nodes.  This is intentional as starting an “exclude” from one of these nodes would leave the parent as an orphan node with no content. 

Option 3 – Delete the Node
If you will never be outputting the node in the XML document, then you may just want to delete it from the Handler design.

Option 4 – Suppress Output When Spaces (text fields only)
Another possible approach is to use the “Suppress Output When Spaces” setting.  When this setting is on, a text field will be automatically suppressed if its value is spaces.  This setting only works for text fields though (not numeric or date/time fields).  It also only works on elements or attributes that have data (i.e. it does not suppress on parent elements).  You need to be careful that you do not have a situation where you would want to suppress a parent element when all the child elements are suppressed.  Only Flags can do this. 

As with flag fields, you can control this setting at the toolset level, Handler level or node level

Toolset Default
Go to Tools -> Default Properties -> Formatting -> Text. 

Handler Default
Go to XML Handler -> Properties -> Formatting -> Text.

Node Level
Select the node and set the “Suppress When Spaces” under Data Value properties.

Which Option to Use?
The Optional Flag Field setting is the most flexible and complete approach.  It allows you to control both parent and child elements. It also works on all data types (number, text, date, etc.).  However, the setting will insert additional flag fields into your copybook.   The calling program must set each flag field to “1” or “0” before calling a Writer.    
The “Suppress Output When Spaces” setting will only work on child node that hold text content.  It is easier to work with though, in that empty elements or attributes are automatically suppressed (no additional logic required in the calling program).

Generating Special Fields as a Separate “01” Level
As with all special fields, the optional flag field can be generated as a separate “01” level in your copybook. To do this, select “More Options” on the code generation panel.


Change the “Special Fields” setting to “Generate as a separate structure”.

Instead of inserting the flag fields next to the corresponding field in the CANAM-XML-DATA structure, a new “01” structure will created containing just the special fields (include flag fields).


Modified on 2016/04/22 12:10 by John Russell  
Tags: Not Tagged