Creating binding and schema files for use with z/OS Connect

z/OS Connect provides the ability to optionally transform request and response payloads that are used for calling a business asset on z/OS operating systems. z/OS Connect supplies two new utilities called BBGLS2JS and BBGJS2LS.

Before you begin

Before you create your binding and schema files, make sure that your setup complies with these preconditions:
  • Your high-level language data structures must meet the following criteria:
    • The data structures must be defined separately from the source program; for example, in a COBOL copybook.
    • If your PL/I or COBOL application program uses different data structures for input and output, the data structures must be defined in two different members in a partitioned data set. If the same structure is used for input and output, the structure must be defined in a single member.
    • For C and C++, your data structures can be in the same member in a partitioned data set.
  • The language structures must be available in a partitioned data set.
  • You must define to Open Multiple Virtual Storage (OMVS) the user ID that BBGLS2JS or BBGJS2LS uses to run.
  • The user ID must have read permission to z/OS® UNIX and PDS libraries, and write permission to the directories that are specified on the LOGFILE, WSBIND, and JSON-SCHEMA-REQUEST and JSON-SCHEMA-RESPONSE output parameters.
  • The user ID must have a sufficiently large storage allocation to run Java™. You can use any supported version of Java. The BBGLS2JS/BBGJS2LS utilities use the Java version that is specified by JAVA_HOME in the USS environment by default. Otherwise, the ID uses the Java version specified on the PATH statement.

About this task

The BBGLS2JS utility reads a COBOL copybook or PLI, or C structure file and generates a binding file and JSON schema files. The BBGJS2LS utility reads a JSON schema and generates the corresponding binding file and language structure file (COBOL copybook or PL/I, or C structure header file). The utilities are similar to the existing DFHLS2JS and DFHJS2LS tools, which are part of the CICS Transaction Server Mobile Extensions feature pack. While the input parameters are the same, the symbolic parameters are different.

Procedure

  1. Obtain the BBGLS2JS JCL procedure. The BBGLS2JS and BBGJS2LS JCL procedures are available on GitHub. For information about how to use the JCL, see the readme file on GitHub. You will need to copy the JCL procedure from this location into a member named BBGLS2JS in a JCL procedure library on your z/OS system.
  2. Use the BBGLS2JS procedure to generate a z/OS Connect service binding file from a language structure. You will need to provide JCL to invoke the BBGLS2JS procedure with the input parameters. Refer to the BBGLS2JS reference documentation for information on the input parameters and an example job to help you use the procedure. When you submit the BBGLS2JS procedure, the utility generates the service binding file to the location that you specified with the WSBIND parameter. The generated JSON schemas are placed in the location that you specified with the JSON-SCHEMA-REQUEST and JSON-SCHEMA-RESPONSE parameters.
  3. Review the generated JSON schema. These schemas are used to define the input and output data formats for interacting with the z/OS Connect service. The application developer must use these schemas when creating an application to call the service and pass the JSON request payload.
    Note: Changing the generated schema invalidates the generated binding file at WSBIND. If you want to change the schema, for example, to rename the fields within the schema, you must use BBGJS2LS to generate a new binding file, and a new set of language structures. The application program must be re-compiled to use the new language structures.

Icon that indicates the type of topic Task topic

File name: twlp_zconnect_binding_and_schema.html