CICS

  • 1.  Developing web services with CICS JSON assistant

    Posted Fri August 26, 2022 08:51 AM
    Edited by Medha Parekh Fri August 26, 2022 09:35 AM
    Dear community,
    CICS already offers quite a lot for the topic of web services. I am currently experimenting with connecting a web service that works with JSON format. On the mainframe side, PLI, COBOL and CICS V5R5 are used

    A copybook is used as the basis for the structure. The name of the copybook is TEST01A and looks something like this:
    DCL 02 MESSAGE CHAR(50);​

    In the JCL of the CICS JSON assistant, the PDSMEM must also be specified, which is called TEST01A. The JSON file and the JSON bind files are generated from this with the CICS JSON assistant DFHLS2JS. After that the JSON file looks like this:
    {
       "type":"object",
       "properties":{
          "test01a":{
             "type":"object",
             "properties":{
                "message":{
                   "type":"string",
                   "maxLength":50,
                   "minLength":0
                }
             },
             "required":[
                "message"
             ]
          }
       },
       "required":[
          "test01a"
       ]
    }

    So far so good. The bundle resource is then created and installed in CICS. The web service is requested with GET and some query parameters. A JSON message comes back that looks like this:
    {
       "message": "okay"
    }​

    The response is then transformed into the internal data format in TRANSFORM JSONTODATA. At this point, an error is returned that the message is not compliant.

    I know why and I also know how I can work around the problem. I'm currently wondering if there isn't an easier way. I couldn't find anything about it in the documentation, which surprises me.

    For the current problem, I would like to ask whether I can pass a parameter or something similar in DFHLS2JS that does not specify the high-level structure in the JSON file, so that the following JSON file is generated:
    {
       "type":"object",
       "properties":{
          "message":{
             "type":"string",
             "maxLength":50,
             "minLength":0
          }
       },
       "required":[
          "message"
       ]
    }

    Did you have similar experiences and how did you deal with it?

    Best regards
    Adrian

    ------------------------------
    Adrian Kawalla
    ------------------------------


  • 2.  RE: Developing web services with CICS JSON assistant
    Best Answer

    Posted Thu September 01, 2022 11:39 AM
    You use DFHLS2JS when you have an existing data structure and want to generate a JSON schema to match that structure/copybook.  If you need for your application to conform to a specific JSON format, such as when your CICS application is the client/requester, then you want to use DFHJS2LS -- starting with the JSON schema to which the other system implements.

    Since you know what the JSON message and its schema should look like, I suggest that you use it as input to the DFHJS2LS utility and generate a copybook from that.

    When you start working with more complex message structures, you could consider using a non-CICS tool which will create JSON schema from a JSON sample message.  Or you could use DFHLS2JS to produce an initial schema from a sample copybook, then edit that schema (as you did above) to reduce it to only the elements which you want to appear in the JSON messages.  You'll still need to create new copybooks from this edited schema since the mapping between JSON objects and PL/1 structures is not symmetrical.

    ------------------------------
    Leigh Compton
    Consulting IT Specialist - CICS and Enterprise Integration
    IBM
    TX
    ------------------------------



  • 3.  RE: Developing web services with CICS JSON assistant

    Posted Tue September 06, 2022 06:22 AM
    Hi Leigh,
    Thank you for your time and your answer. I will follow your suggestion. Is there already a process under IBM that converts a JSON message into a JSON schema?
    Best regards
    Adrian

    ------------------------------
    Adrian Kawalla
    ------------------------------



  • 4.  RE: Developing web services with CICS JSON assistant

    Posted Wed September 07, 2022 01:47 PM
    I know of no process supplied by IBM to build a schema from a sample message.  I have found a couple of open source programs and online sites which can do this for you.

    ------------------------------
    Leigh Compton
    Consulting IT Specialist - CICS and Enterprise Integration
    IBM
    TX
    ------------------------------



  • 5.  RE: Developing web services with CICS JSON assistant

    Posted Wed September 07, 2022 01:53 PM

    I should add that the majority of environments that I see these days using JSON services are implementing APIs (RESTful JSON services) and the documentation is in the form of an OpenAPI Specification Version 2.0 (aka Swagger) or OpenAPI Specification V3.x.  CICS does not implement support for either of the OpenAPI specifications, but both of these include imbedded JSON schema declarations.  If the server you wish to connect to supplies its documentation via Swagger or OAS, then you could extract the schema from that source.

    OR, you could employ z/OS Connect to perform the JSON and HTTP handling for your CICS client application.  Today, z/OS Connect supports Swagger documents and has limited support for OAS 3.0.



    ------------------------------
    Leigh Compton
    Consulting IT Specialist - CICS and Enterprise Integration
    IBM
    TX
    ------------------------------