_____________________________________________________________________________________________________________________________________________________________

Creating an XML Handler using an XML instance

This tutorial will help you to understand:

· How to create an XML Reader(parser) and an XML Writer from an XML Instance

· How to change the property of a node.

· How to set the generation options.

· What files you should have after code generation.

· How to write a Writer calling program.

_____________________________________________________________________________________________________________________________________________________________

It is always prefereable to use an XML schema for the XML structure. The XML node properties and validation rules will be based on the content in the sample XML document. These properties and rules will only be as good as the content in the sample XML document. For best results, ensure that the sample document contains the extreme cases – each node filled to its maximum length, repeating structures repeating the maximum number of times, etc...

Step 1: Launch XML Thunder

The welcome screen will appear and give you two different options, one to Create a New XML Handler and one to Open existing handlers. If you disabled the welcome screen, please click icon from the toolbar or choose XML Handler -> New from main menu.
For now, click the first option.

If the wizard starts with the Introduction panel, click Next.

Step 2: Select the IDS and XML source

On the Source panel, set the XML source to Derive from XML Instance and set the location to Program files\Xml ThunderV4\tutorial\XML Samples Instances\BAXSD.xml

Set Derive from XML as your IDS source. Click Next to continue.

Step 3: Specify Additional IDS Properties

On the Properties panel, leave the default values for the Identifiers and click Next to continue.

Step 4: Confirm Selections

On the Summary panel, review the information and click Finish.

XML Thunder will create an XML Handler design with the XML structure based on the sample XML document provided and the IDS derived from the XML. The mappings between IDS fields and XML nodes have been completed automatically.

Step 4: Modify Properties

Often, when creating a handler from a sample XML document, some of the properties established will have to be modified. In this case, the sample document contained only 3 occurrences of ACCOUNT. Let's modify the ACCOUNT node and change the “Max Occurs” from node property to 40.

The ACCOUNT-Comment node can be longer that the comment found in the sample XML document. Modify the ACCOUNT-Comment data node and change the length property to 4000. Also, make sure the option variable length is checked.

Note the change on the IDS list. The length of the IDS node has increased to 4000.
The Logical IDS should now look like this:

Step 5: Generate the XML Handlers

Click Generate or select Tools -> Generate… from the main menu.

On the XML Reader tab

· Select the XML Reader, IDS (Interface Data Structure) and Test Harness for generation.

· Set source names to BNKRECR, BNKRECRC and BNKRECRT.

· Access the More Options pane of the Test Harness and change “Read XML from” to “External File” and “Output Data” to “Display”.

On the XML Writer tab

· Select XML Writer, IDS (Interface Data Structure) and Test Harness for generation.

· Set source names to BNKRECW, BNKRECWC and BNKRECWT.

· Access the More Options pane of the Test Harness and change the Output Data To field to File.

Click Generate.

When generation completes, six COBOL source code files should be created.

· BNKRECR.cbl – The XML Reader

· BNKRECRC.CPY – The copybook to support the API to the XML Reader

· BNKRECRT.cbl – The Test Harness for the XML Reader

· BNKRECW.cbl – The XML Writer

· BNKRECWC.cpy - The copybook to support the API to the XML Writer

· BNKRECWT.cbl - The Test Harness for the XML Writer

Step 6: Test the Generated Handlers

The generated COBOL source code can be can be compiled in the same manner you compile your other COBOL programs. The Test Harness programs are fully functional standalone programs that can be run to test the XML Handlers. Depending on your platform, you may find that minor changes to the Test Harness and JCL will be required to support the file processing.

The Writer Test Harness program uses dummy data as content for the XML instance it creates. Open the BNKRECWT.cbl program and change the following line:

From:
MOVE "XXXXXXXXXX" TO BANK-Name-0005(XML-GVW-I1)

To:
MOVE "Canam Software" TO BANK-Name-0005(XML-GVW-I1)

Save these changes, compile all open files, and run BNKRECWT.cbl. (the test harness). It should produce BNKREC.xml.
The generated XML file will look like:

Run BNKRECRT.cbl. The XML Reader will be invoked by the test harness which will then read the same XML document back into COBOL.