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

Back
Creating a JSON Handler

====Overview====

XML Thunder generates COBOL or C source code for Reading and / or Writing XML and JSON instances. Using the XML Thunder toolset, you create an JSON Handler design that specifies the mapping between program data fields and JSON nodes, and the data validation rules that should be applied. 

The following will walk you through creating and generating a JSON Handler to give you a quick overview of how XML Thunder works.

=====Step 1: Launch the New Handler Design Wizard=====

To create a new JSON handler, launch the Wizard by either clicking on XML Handler New… from the menu or click on the icon on the tool bar. Choose “Next” to move past the Introduction pane.

[image||{UP}XMLThunderWiki/CreatingJSONHandler/1.gif]

[image||{UP}XMLThunderWiki/CreatingJSONHandler/2.gif]

=====Step 2: Select the Source for the JSON and Program Data Field Structures=====

An XML Thunder Handler Design contains the mappings between program data fields (called the IDS) and JSON nodes. To create a new JSON Handler, you begin by specifying the source for these two data structures. You can choose from a number of possible IDS and JSON combinations, but for this example choose “Derive from XML” and “XML Structure -> JSON”. Prompt out and select the JSON schema you want to create a Handler design for.

[image||{UP}XMLThunderWiki/CreatingJSONHandler/3.gif]

=====Step 3: Select Root Element=====

Some XML schemas can have more than one possible root element. JSON schemas have only one possible root though so we can accept the default.

[image||{UP}XMLThunderWiki/CreatingJSONHandler/4.gif]

=====Step 4: Confirm Selections=====

The Summary window lists the selections made. Click “Finish” to confirm the selections and create a JSON Handler design. 

[image||{UP}XMLThunderWiki/CreatingJSONHandler/5.gif]

=====Step 5: Review The Handler Design=====

When you click on “Finish”, XML Thunder will use your selections to create a JSON Handler Design. In this case, the JSON structure and validation rules have been created using the selected schema and any subordinate schemas it imported. The program data fields – also called Interface Data Structure (IDS) – were derived from the JSON nodes. The mappings between the JSON nodes and program data fields were done automatically. 

[image||{UP}XMLThunderWiki/CreatingJSONHandler/5.gif]

=====Step 6: Generate the JSON Handlers=====

From the Handler design, you can now generate either a JSON Reader or a JSON Writer. You can also optionally choose to generate a Test Harness for testing and an IDS (copybook) file.

Click the “Generate Code” icon to open the Generation window.

[image||{UP}XMLThunderWiki/CreatingJSONHandler/7.gif]

__JSON Reader Generation Tab__ 

Confirm / modify the language, and target settings and choose “Document-level” for the JSON Handler type.

On the JSON Reader tab, confirm / modify the Program ID and source code file names. 

[image||{UP}XMLThunderWiki/CreatingJSONHandler/8.gif]

__JSON Writer Generation Tab__

On the JSON Writer tab, confirm / modify the Program ID and source code file names.

[image||{UP}XMLThunderWiki/CreatingJSONHandler/9.gif]

If you choose to generate both an JSON Reader and an JSON Writer - as well as the Test Harnesses and copybook files, then 6 source code files will be created.

[image||{UP}XMLThunderWiki/CreatingJSONHandler/10.gif]

__'''JSON Reader Source Code '''__

For a JSON Reader, the following code has been generated:

'''BAXSDR '''– The''' JSON Reader '''module. This is a COBOL sub-program. You call this program passing it the JSON document in a variable (called JSON-BUFFER). The Reader validates the document, parses the nodes into program data fields and then returns these fields back to the calling program in the IDS variables.

'''BAXSDRT '''– The''' JSON Reader Test Harness'''. This is a fully functional program used to test the JSON Reader. It can read in an JSON file, or create one inline using dummy data values. The Test Harness passes the JSON document to the JSON Reader via the JSON -BUFFER variable. It receives back the parsed content in the IDS (i.e. program data fields). Note: The Test Harness is optional. It gives you a great way to quickly test your JSON Reader. It also gives you an example of how you would call the JSON Reader from your own program. 
'''BAXSDRC '''– The '''JSON Reader Copybook'''. This is the IDS (program data fields) used as the API to the JSON Reader. This is optional. Neither the Test Harness, nor the JSON Reader uses the copybook. It is generated for your convenience – for use in your programs that will call the Reader. 

__'''JSON Writer Source Code '''__
For a JSON Writer, the following code has been generated:

'''BAXSDW '''– The''' JSON Writer '''module. This is a COBOL sub-program. You call this program passing it the JSON content via the IDS (i.e. program data fields). The Writer will validate the content and assemble the JSON document. The JSON document is returned to the calling program via the JSON -BUFFER variable.

'''BAXSDWT '''– The''' JSON Writer Test Harness.''' This is a fully functional program used to test the JSON Writer. It populates the IDS (i.e. the program data fields) using dummy data values (x’s for character and 9’s for numeric values). The Test Harness passes the JSON content via the program data fields to the JSON Writer. It receives back the JSON document via the JSON -BUFFER variable. Note: The Test Harness is optional. It gives you a great way to quickly test your JSON Writer. It also gives you an example of how you would call the JSON Writer from your own program.

'''BAXSDWC '''– The''' JSON Writer Copybook'''. This is the IDS (program data fields) used as the API to the JSON Writer. This is optional. Neither the Test Harness, nor the JSON Writer use the copybook. It is generated for your convenience – for use in your programs that will call the Writer. 

=====Step 7: Testing the JSON Handlers=====

Once the COBOL source code has been generated, it can be transferred to the target platform to be compiled and executed. The JSON Readers and Writers are sub programs that should be invoked from a calling program. The calling program and JSON Handler are statically linked together into one executable program. 

To help test a JSON Handler, XML Thunder generates a Test Harness program. This Test Harness program will populate dummy data for testing purposes and call the JSON Handler. It provides a great way to quickly test that the handler is behaving properly. It also provides an example of how a handler should be called from an existing program – or it can be used as the starting point for creating your own main program. 

'''Testing the JSON Reader: '''
To test your JSON Reader, compile the BAXSDRT and BAXSDR programs. The BAXSDRT (i.e. the Test Harness) is the main program. It calls the BAXSDR program (i.e. the JSON Reader). The copybook is not needed to test the Handler.

The Test Harness calls the JSON Reader from the CALL-TO-JSON-HANDLER paragraph. The same three structures are always passed. 

[image||{UP}XMLThunderWiki/CreatingJSONHandler/11.gif]

'''CANAM-JSON-DATA''' – contains the program data fields. The Reader will return the parsed contents in these fields.

'''CANAM- JSON -BUFFER''' – contains the JSON message. The calling program will pass the JSON message to the reader in this structure.

'''CANAM- JSON -STATUS''' – contains the results of the call to the Reader. If JSON message is not valid, or if another error was encountered, an error code and additional error information will be returned in this structure.

'''Testing the JSON Writer:''' 
To test your JSON Writer, compile the BAXSDWT and BAXSDW programs. The BAXSDWT (i.e. the Test Harness) is the main program. It calls the BAXSDW program (i.e. the JSON Writer). The copybook is not needed to test the Handler.

The Test Harness calls the JSON Writer from the CALL-TO-JSON-HANDLER paragraph. The call to a Writer looks identical to the call to a Reader. The same three structures are always passed. The difference is which fields are populated before and after the call. 

[image||{UP}XMLThunderWiki/CreatingJSONHandler/12.gif]

'''CANAM-JSON-DATA''' – contains the program data fields. The Writer will return the parsed contents in these fields.

'''CANAM-JSON-BUFFER '''– contains the JSON message. The calling program will pass the JSON message to the reader in this structure.

'''CANAM-JSON-STATUS''' – contains the results of the call to the Writer. If an error was encountered, an error code and additional error information will be returned in this structure.

'''Summary'''

Using XML Thunder, a developer is able to create a Handler Design that will define an JSON and a COBOL structure, the mappings between COBOL fields and JSON nodes within those structures, and the validation rules for content found in a given JSON instance. From the Handler Design, COBOL sub programs can be generated to Read and / or Write JSON instances. Optionally a COBOL copybook and Test Harness program can be generated. The copybook contains the COBOL fields passed to and from the Handler and can be used by your calling program. The Test Harness provides an example of how to call a JSON Handler and can be used to quickly test your Handler and confirm it is performing as expected. 

If you have any questions or would like more information, please contact us at support@canamsoftware.com.
Modified on 2013/09/26 15:42 by SuperUser Account
Tags: Handler Creation, Handler Definition, JSON, Reader, SOAP, Writer, XML, XML Thunder
Consent Management • Privacy Statement • Terms of Use
Username
Email
Password
First Name
Last Name