Generating mappings from a JSON schema

To create application data from JavaScript Object Notation (JSON) or JSON from application data, you create the mappings to describe how CICS® should transform the data and JSON at run time. You can start from a JSON schema. After the language structure and the mapping are generated, you can develop CICS application using the language structure, and transform JSON to application data and vice versa.

Before you begin

Before you create the mappings, you must make sure that these preconditions are met:
  • You must have the JSON schema that describes a JSON record.
  • You must configure the user ID under which DFHJS2LS runs to use z/OS® UNIX.
  • The user ID must have read permission to access the JSON schema and write permission to put the output in the appropriate directories on z/OS UNIX.
  • You must allocate sufficient storage to the user ID for the ID to run Java™. You can use any supported version of Java.

About this task

Use the CICS JSON assistant to create the data mappings for the application record. The CICS JSON assistant creates a CICS bundle and issues error messages about any unsupported items that it identifies in your language structure. The reference information for the CICS JSON assistant lists the restrictions that apply to each high-level language. For more information, see DFHJS2LS: JSON schema to high-level language conversion for linkable interface.

Procedure

Run the DFHJS2LS batch job. DFHJS2LS has optional parameters that you select to meet your requirements, such as selecting a particular code page. Use the following parameters as a minimum:

  • Specify the name and location of a bundle resource in the BUNDLE parameter.
  • Specify the name and location of the JSON schema file in the JSON-SCHEMA parameter.
  • Specify the mapping level in the MAPPING-LEVEL parameter. Although you can use any mapping level, to get the most advanced mapping options use the latest mapping level.
  • Specify the high-level language for the generated language structure in the LANG parameter.
  • Specify the location and the code page of the language structures that describe the application record in the PDSMEM and PDSCP parameters. DFHJS2LS creates the language structure, but not the directory structure.
  • Specify the name that is used for the JSONTRANSFRM bundle resource in CICS. This name is used by applications to identify the JSON mappings.

    The batch job creates a bundle directory structure on z/OS UNIX. The bundle directory has a META-INF subdirectory that contains the bundle manifest. The batch job also creates a JSON binding and copies the JSON schema into the bundle directory, using the file names that you specified for the JSONTRANSFRM and JSON-SCHEMA parameters. The batch job also creates the language structure at the location specified in the PDSMEM and PDSLIB parameters.

    Install the BUNDLE resource that specifies this JSON binding. The JSONTRANSFRM bundle resource dynamically creates a JSONTRANSFRM resource, which defines the location of the JSON schema and binding file. This bundle resource is visible in CICS when you view the contents of the installed bundle using the CICS Explorer®. It is not a normal CICS resource, and is not visible when using CEMT or the CPSM WUI.

Results

A CICS bundle that contains one JSON transformation is generated. A language structure is generated.
The following example shows DFHJS2LS with the minimum set of parameters specified.
//JS2LS JOB  'accounting information',name,MSGCLASS=A
//  SET QT=''''
//JCLLIB JCLLIB ORDER=FPHLQ.SDFHMOBI
//JAVAPROG EXEC DFHJS2LS,
//INPUT.SYSUT1 DD * 
LANG=COBOL
BUNDLE=/u/exampleapp/bundle/test2
LOGFILE=/u/exampleapp/jsbind/example.log
MAPPING-LEVEL=3.0
PDSLIB=/u/exampleapp
PDSMEM=CPYBK2
JSONTRANSFRM=example.jsbind
JSON-SCHEMA=/u/exampleapp/example.json
/*

What to do next

Write an application program to transform the application data to JSON and vice versa. You can use the same mappings for both transformations.