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
- 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.
- 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.
- 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.