Creating a JSON Handler from a COBOL Copybook

Overview

JSON Thunder generates COBOL source code for Reading and / or Writing JSON messages.  Using the JSON Thunder toolset, you create a JSON Handler Design that specifies the mapping between program data fields and JSON nodes as well as 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 JSON Thunder works.

Step 1: Launch the New Handler Design Wizard

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

Image

Image

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

A JSON 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 “Data Structure -> COBOL” and “Derive from IDS”.  Prompt out and select the COBOL copybook you want to create a Handler design for. These settings are used to create a Handler Design from a COBOL copybook.  The JSON layout will be based on the COBOL structure.

Image

Step 3: Select the Conversion Layout

Thunder Suite supports both XML and JSON while JSON Thunder supports only JSON. To convert the COBOL structure to JSON so choose the following:

Image

Step 4: Confirm Selections 

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

Image

Step 5: Review The Handler Design 

When you click on “Finish,” JSON Thunder will use your selections to create a JSON Handler Design. The tree on the left represents the COBOL layout. The tree on the right represents the JSON layout. In this case, the JSON layout and validation rules have been created based on the COBOL copybook you provided. The mappings between the JSON nodes and program data fields were done automatically.  

Image

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



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

JSON Writer Generation Tab

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

Image

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

Image



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

Image



JSON Reader Source Code 

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

BPOLMR – 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.

BPOLMRT – The JSON Reader Test Harness. This is a fully functional program used to test the JSON Reader. It can read in a 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.

BPOLMRC – 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:

BPOLMW – 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.

BPOLMWT – 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.

BPOLMWC – 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, JSON 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 



POLICY-MASTER-RECORDS, V-POLMSTR-N, V-POLMSTR – are your 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.

CANAM- JSON –SPECIAL-FIELDS – contains count fields to control the repeating structures.

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



POLICY-MASTER-RECORDS, V-POLMSTR-N, V-POLMSTR – are your program data fields. The Writer will use the content in these fields to create the JSON message.

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.

CANAM- JSON –SPECIAL-FIELDS – contains count fields to control the repeating structures.

Summary 

Using JSON 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.