Creating Handler from a Copybook and a Schema

Step 1 – Create the Handler Design:»

a. In the New Handler Wizard, specify the copybook for your IDS and the schema for your XML structure.

Image

b. Some schemas can have more than one possible root element. In this example, there is only one possible root, so you can accept the default.

Image

c. Select “Finish” on the summary panel to create the Handler design.

Image

Step 2 – Manually Map Program Data Fields to XML Nodes»

When both the program data structure (IDS) and the XML structure are provided by the developer, then the mapping between fields and XML nodes must be done manually. The screen image below shows the Handler immediately after it has been created using the Wizard.

Note that the program data fields are not mapped to XML nodes. It is important to note this because if you had provided only one side to the Handler design (e.g. either the copybook or the schema), then you could have to chosen to have XML Thunder derive the other side and do the mapping automatically for you.

Image

a. Map Repeating Data Structures

Repeating data structures must be mapped before you can map their children. To map a repeating structure, drag and drop the repeating field to its corresponding repeating XML node. In the example below, the program data field Customer occurs 10 times. It needs to be mapped to the XML node Customer that also repeats 10 times.

Important . You will not be able to map any nodes under a repeating structure until the repeating structure itself has been mapped.

Image

b. Map Program Data Fields to XML Nodes

To map program data fields to XML nodes, drag and drop each field to its corresponding node. Continue until all desired fields have been mapped. It is not necessary to map all fields – but only the mapped fields will be used by the XML Handler.

Image

Step 3 – Generate the XML Handler»

After the program data fields have been mapped, you are ready to generate your Handler.

Important Any special fields will automatically be inserted into your IDS structure for you. Below is an example of a copybook modified by XML Thunder. The circled fields were added automatically to be able to make use of the Count, Flag and Length special fields.

Image

You can generate the special fields to a separate 01 structure, but choosing More Options next to the IDS on the Generation Window and changing the setting for special fields.

Image

Image

See below for more information on XML Thunder Special Fields.

XML Thunder Special Fields XML Thunder uses a set of “special fields” to provide extra control over an XML document being read or created. They are used within an XML Handler and are part of the Handler’s API. (i.e. they are passed between the calling program and the XML Handler).

There are 6 special fields: 1. Count – for repeating structures 2. Flag – for optional fields (to suppress nodes for a writer and identify existence for a reader) 3. Length – control the length of output for variable length text fields. 4. Track Pointers – Identify the start and end position of a node 5. Extended Precision – control the decimal output of a decimal value. 6. Selection Attribute – used for controlling XML Choice structures.

The 2 most highly used special fields are Count and Flag. All special fields can be turned off with the exception of the count field. The count field always exists for repeating structures in a Handler design.

Count Special Field The counter field is used to control repeating structures. For an XML Writer, the count field is used by a developer to control how many occurrences should be created in the XML document. For an XML Reader, the count field specifies how many occurrences of a repeating structure were found in the XML document. A Count special field will automatically be added for all repeating structures.

Flag Special Field The flag field is used to control optional fields. For an XML Writer, the developer can suppress an optional field from an XML document by setting its corresponding flag to “0”. For an XML Reader, the developer can use the flag field to determine if the value returned for an optional field is the initialized value or if it was found in the document (flag = 0 > “not found”, flag = 1 > “found”).

See the XML Thunder help file for information on the remaining special fields. Special fields can be controlled at the Toolset, Handler and Node level. For the example, the Flag field for optional nodes can be set:

As a toolset default (under Toolset -> Defaults)

Image

As a Handler default (under XML Handler -> Properties):

Image

At the node-level (by selecting a node and setting a generation property).

Image

See the XML Thunder help file for more information on setting special fields.