ZMF Support for z/OS Connect
What is z/OS Connect and How Does It Work?
z/OS Connect is IBM’s mechanism for exposing mainframe resources (such as a batch program, CICS® transaction, IMS™ transaction, and so on) to web applications and desktop clients as Representational State Transfer (REST)-ful APIs, using GET/PUT/POST/DELETE actions along with JavaScript Object Notation (JSON) message bodies.
z/OS Connect runs as a started task through which external communications are routed to the target z/OS resource. IBM products such as CICS, IMS, MQSeries®, and so on, are already enabled to talk to z/ OS Connect. However, any mechanism that can call WebSphere® Optimized Local Adapter (WOLA) services can use z/OS Connect to talk to the outside world.
A z/OS resource is identified to z/OS Connect as a service. A zFS file called server.xml defines the method by which the z/OS resource/service is to communicate with the z/OS Connect started task. You simply edit this file; there is no build process. You need to be able to promote the file to the relevant target directory so it will be picked up by the relevant z/OS Connect server.
The service itself is provided by a back-end process (for example, a CICS transaction, a program that uses WOLA services, and so on) that is able to communicate with the z/OS Connect server.
A request copybook and a response copybook are required to expose the service to the outside world. For example, a COBOL copybook maps the data as the back-end program will see incoming requests and present outgoing responses. These copybook components are used to generate the following zFS files:
| zFS | File Description |
|---|---|
| serviceName_request.json | The request JSON schema. |
| serviceName_response.json | The response JSON schema. |
| serviceName.wsbind | The data structure mapping. |
| serviceName.sar | The service archive. |
...
An IBM-provided utility BAQLS2JS takes the copybooks and generates these outputs.
Once the service archive (.sar) file is created, you can use it to build an API to a web or desktop application. You use the IBM-supplied desktop workbench called IBM® Explorer for z/OS® with the z/OS Connect EE API editor.
The output from this process is another archive, the API archive (.aar) file.
The build process required to generate a service archive to support communications via the CICS IP Interconnectibility (IPIC) facility, or via native Db2 RESTful, is different to the z/OS Connect build processes available earlier. We cannot use the BAQLS2JS or the BAQJS2LS service programs to perform the generation. We must use the z/OS Connect Build Toolkit.
A sample build procedure is supplied, CMNBAQIP. This works on a like-SRC parameter to generate a (like-P, zfs) target .sar component, and listings. The service archive component implements the service mechanism between the HTTP requester, z/OS Connect, and the target CICS IPIC facility.
What is ChangeMan ZMF’s Role?
The artifacts that define the service to z/OS Connect must be built under the control of ZMF and generated as ZMF package components. The build process is driven from a like-SRC parameter component in a similar fashion to that described for the CICS web services below.
A utility program (delivered as a load module) and four skeletons (delivered as members of the CMNZMF.SKELS distribution library) enable this process:
| Module | Description |
|---|---|
| CMNBAQLJ | Skeleton to generate z/OS Connect JSON schema and binding. |
| CMNBAQJL | Skeleton to generate z/OS Connect copybooks and binding from JSON schema |
| CMNBAQIP | Skeleton to build a (like-P, zfs) .sar component for z/OS Connect and the target CICS IPIC facility |
| CMNBAQD2 | Skeleton to build a (like-P, zfs) .sar component for z/OS Connect and the target Db2 RESTful service. |
| CMNBAQ00 | Program to prepare input to the IBM-provided BAQLS2JS utility and CMNBATCH activation transactions. |
...
Initially, outputs are built to temporary directories. These outputs are copied to the ZMF package staging directories only when the build process has been successful. The SUCCESS step execution of CMNBATCH results in all related components being activated in the package.
You can stage any RESTful API (.aar file) that you have developed based on this service definition directly into a ZMF package from the directory where it currently resides. It can then be processed through the package lifecycle.
The definitions for the web service itself are generated by the build process and consist of artifacts such as the .sar and .wsbind files and the JSON schemas.