Creating an XML Handler using a COBOL data structure

This tutorial will help you to Understand:

· How to create an XML Reader (Parser) and an XML Writer from a COBOL data structure

· How to use special field settings flag field, track pointers

· What files you should have after code generation

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 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 IDS source to Data structure – COBOL and set the location to Program Files\CANAM\XML ThunderV4\Tutorials\COBOL Copybooks\BANKREC.cpy. Set Derive from IDS as your XML source. Click Next to continue.

Step 3: Specify Additional IDS Properties

On the Properties panel, accept the default values for the Identifiers and set the COBOL

code format to Fixed format. Click Next to continue.

Step 4: Confirm Selections

On the Summary panel, review your selections and click Finish.

XML Thunder will create an XML Handler design with the IDS based on the COBOL copybook provided and the XML derived from the IDS. Each IDS group has become an XML element. Each IDS field will be transformed as either an element or attribute depending on your setting under Tools -> Defaults -> IDS Rules. The mappings between IDS fields and XML nodes have been completed automatically.

Add an Optional Flag special field

When the optional Flag field property is set to “true” for a node, then the generated IDS will contain an additional “flag field” that is associated with the node.

An optional flag field is:

· Returned by an XML Reader to indicate if a node was found in the XML instance. If the flag value is set to 1, the node was found and the content returned in the IDS field is the content found in the document. If the flag value is 0, then the node was not found and the content returned in the IDS field is the initialized value.

· Passed to an XML Writer to indicate if an optional node should be suppressed or not. If the flag value is set to 1, then the node will be written out. If the flag is set to 0, the node will not be written out.

To insert an optional flag field into the IDS, select the account-comment node and set the Optional Flag field property to “True”.

An Optional Flag field will be inserted into the COBOL structure. The field name will be the same as the original field but with a “-flag” appended to the end.

Add the Track Pointers Special fields

Track Pointers are used to indicates the start position of the open tag and the end position of a closing tag for a node. If the Track Pointers property is set to “true”, then 2 fields (one for the starting position and one for the end) will be automatically inserted in the IDS for the corresponding program data field.

Track pointers are only used by XML Readers. The Reader will return the start and end position of the particular XML node.

To insert Track Pointers into the IDS, select the account-comment node and set the Track pointers property to “True”.

An Optional Flag Field special field will be inserted into the COBOL structure. The field name will be the same as the original field but with “-Start” and “-End” appended to the end.

Step 5: Generate the XML Handlers

Click Generate icon 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 "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" TO BANK-Name-0006(XML-GVW-I1)

To:
MOVE "Your Company Name" TO BANK-Name-0006(XML-GVW-I1)

Now let’s analyze the most important sections of the BNKRECWT.cbl program.

Save this change, compile all open files, and run BNKRECWT.cbl. (the test harness). It should produce a file with the name BNKREC.xml which will look as follows:

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