Creating bind and schema files

IBM® 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. IBM z/OS Connect supplies two new utilities called BAQLS2JS and BAQJS2LS.

Before you begin

Before you create your binding and schema files, make sure that your setup complies with these conditions:
  • 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 BAQLS2JS or BAQJS2LS 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 BAQLS2JS and BAQJS2LS utilities use the Java version that is specified by JAVA_HOME in BAQLS2JS and BAQJS2LS sample JCL. Otherwise, the ID uses the Java version specified on the PATH statement.

About this task

The BAQLS2JS utility reads a COBOL copybook, PLI structure, or C structure file and generates a binding file and JSON schema files. The BAQJS2LS utility reads a JSON schema and generates the corresponding binding file and language structure file. The utilities are similar to the existing DFHLS2JS and DFHJS2LS tools, which are part of the CICS® Transaction Server Mobile Extensions feature pack.

Procedure

  1. Copy the BAQLS2JS or BAQJS2LS sample JCL to a writeable directory or dataset
  2. Use the BAQLS2JS procedure to generate a IBM z/OS Connect service binding file from a language structure.
    You will need to provide JCL to invoke the BAQLS2JS procedure with the input parameters. Refer to the BAQLS2JS reference documentation for information on the input parameters and an example job to help you use the procedure. When you submit the BAQLS2JS 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. For more information, see Conversion for z/OS Connect (OpenAPI 2) data transformation.
    Note: In order to generate a service archive file, SERVICE-ARCHIVE and SERVICE-NAME must be specified in BAQLS2JS.
  3. Review the generated JSON schema.
    These schemas are used to define the input and output data formats for interacting with the IBM 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 BAQJS2LS 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.