IBM Support

Recommendations and Considerations for the Support of JSON in EGL for Generated COBOL Applications using RBD

White Papers


Abstract

Kushagra Goyal
Senior Technical Specialist

This paper details the functionality of newly introduced functions, their limitations, and execution in various requirement scenarios.

Content

IBM Rational Business Developer (RBD) is an Eclipse-based IDE that helps programmers develop applications using EGL that generates COBOL. Based on users' inputs for the previous versions of RBD, there was a need to enhance RBD to support JSON.

Cobol 6.2 introduced support to JSON. The corresponding COBOL statements provided by IBM are:
  1. JSON GENERATE
  2. JSON PARSE

The new version of RBD (V9.6) has been enhanced to incorporate JSON which is a new feature of COBOL. By this inclusion, the current RBD community (which uses EGL for their application development and maintenance on mainframes) can use the new version of RBD to develop and enhance applications including JSON functions, when required.
The corresponding EGL functions are:
Table 1: Mapping between EGL and COBOL Functions
EGL Function COBOL Function
servicelib.convertToJSON(EGLType) JSON GENERATE
servicelib.convertFromJSON(String, EGLType) JSON PARSE

 
Description of new functions:
We introduced two new functions in EGL for handling JSON functionality in the COBOL environment.
  • convertToJSON(EGLType) 
    This function is part of ‘servicelib’ library. The parameter must be an object of EGL Data Type. The return type of this function is a string.
    This function is to be used to generate JSON String from the given input.   
  • convertFromJSON(String, EGLType)
    This function is part of ‘servicelib’ library. The first parameter must be a string and must hold a valid JSON String. The second parameter is an object of EGL data type that is populated upon successful parsing of JSON string provided as input. This function is to be used to
    parse the JSON String (provided as input) to extract values and populate corresponding EGL Type.
Integration of functions in RBD (aligning between EGL and COBOL)

In reference to Table 1, we state how the JSON has been integrated in RBD and how the two aspects of it are handled in our product.
  1. The EGL function “convertToJSON()” generates and uses the IBM-provided COBOL statement, “JSON GENERATE” for generation of JSON String from the given input.
  2. The EGL function “convertFromJSON()” generates and uses the IBM-provided COBOL statement “JSON PARSE” for parsing of JSON String to extract values from it and populate a corresponding EGL data type.
  3. In an EGL program, the programmer provides a reference name to all the variables. During generation of COBOL, corresponding variables      are generated in COBOL or RBD standard way. So, there is a need to create a mapping between names of defined variables in EGL and how     they are defined in COBOL.
  4. A conversion routine is developed where reference variables are used for the interchange between EGL and COBOL variable names. We            traverse through the entire JSON string and upon locating COBOL variables, the conversion is performed to make JSON string compliant to EGL.
  5. The same routine is used for performing the reverse conversion by reversing the pointers as required.

This conversion is required to keep mainframe-generated JSON String usable to EGL users and/or any external system with which JSON string can be exchanged.
Supported Environment
For JSON handling Cobol 6.2 is required, and these new functions are supported only on z/OS.

Limitations
There are certain limitations to JSON processing supported in RBD v9.6. The details of these limitations are listed below:
  1. The record specified in function ServiceLib.convertToJSON (record) cannot contain a Boolean field.
  2. The EGLtype 'Dictionary' is not supported, and the only supported EGLType is 'Record'.
  3. The JSON String specified in function ServiceLib.convertFromJSON (jsonString, record) cannot contain a Boolean field.
  4. Using Boolean fields can lead to a runtime error with Cobol error message ‘IGZ0340W’ (https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.ceea900/igz0340w.htm).
  5. The annotation JsonName is not supported, and is ignored, in records for JSON processing.
  6. Object name must be present in the JSON string. This is different from the way JSON string is parsed for Java generation. The following  
    example describes the difference:
                   
record MyRec
           userId int;
           id int;
           title String;
end		 str4Parse string = "{\"MyRec\":{\"userId\": 1, \"id\": 1, \"title\": \"Welcome to Hello World!\"}}";
In this example, the JSON string must contain the name of the key (name of EGL record - MyRec) at the start of string.
Examples

Scenario 1: JSON Generation and Parsing for basic user-defined data type

In this case, one EGL record has basic member variables. These variables are assigned with values and corresponding JSON is generated. This generated JSON when parsed and in turn populates another object of below stated EGL record for storing Student Record.
image 1856
image 1825
Scenario 2: JSON Generation and Parsing for mixed case

The examples that follow show the below listed features:
  1. Nested user-defined data type.
  2. Array object of another user-defined data type.
  3. Order of initialization of member variables is different from the order of definition.
image 1827
image 1828
image 1829
image 1848
Scenario 3: JSON Parsing for existing or incoming JSON strings from an external system

This case explains the parsing of JSON string received from another source. 
Note: As mentioned under the limitations section, EGL programmers must ensure that the name of the object is present.
image 1851
image 1852
image 1855
Conclusion

The following were discussed in this white paper:
• Newly introduced functions in EGL to support JSON for generated COBOL using RBD
• Integration of these functions into RBD
• Usage of each of these functions
• Limitations of the new functions
• Working examples of various scenarios where JSON generation and parsing is performed

[{"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SSMQ79","label":"Rational Business Developer"},"Component":"","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"9.6","Edition":"","Line of Business":{"code":"LOB35","label":"Mainframe SW"}}]

Document Information

Modified date:
01 December 2020

UID

ibm11096144

Page Feedback