In-place modernization —z/OS Web Enablement Toolkit
Overview
In the Era of Web3, it becomes imperative that legacy applications running on Mainframe are required to communicate not just within the organization, but also across the network, irrespective of platform.
IBM z/OS Web Enablement Toolkit provides a suite of useful utilities, which enables mainframe-based applications to invoke an HTTP/HTTPS based URL over the internet. The data exchanged(payload) between the client(Mainframe) and Server(any) would be in JSON format. This tool kit provides utilities to work with JSON messages within COBOL easier.
Let’s consider an example, where your COBOL application needs a currency exchange rate to be obtained from an external server.
- Here your COBOL application would first need to build a request message in the industry standard JSON format,
2. Then invoke the external API over HTTPS protocol.
3. The response message would be received in JSON format.
4. which will then have to be converted into a flat structure(copybook format) for our COBOL module to continue working with the new data.
Here the handling of converting between copybook → JSON → Copybook will be handled by the JSON Parser( https://www.ibm.com/docs/en/zos/2.3.0?topic=toolkit-zos-json-parser )
The part which is required for handling the HTTPS calls is performed by https://www.ibm.com/docs/en/zos/2.3.0?topic=toolkit-zos-httphttps-protocol-enabler
A view from Mainframe application developers perspective
To enhance an existing Cobol program to call a web API, certain preliminary steps are required. Just like the preliminary steps needed when handling a file(Open, Read, Close), DB2 table (Define(cursor), Open, Fetch, Close) or MQ (Connect, Open, Get/Put, Close, Disconnect) which are familiar for a mainframe programmer. These configurations are commonly required for establishing a HTTP(S) based connection. They are,
- HTTP Initialize Connection
2. HTTP Setup Connection — Configurate the essentials for a HTTPS call, they are performed represented by the following parameters,
a. HWTH_OPT_VERBOSE
b. HWTH_OPT_USE_SSL
c. HWTH_OPT_SSLKEYTYPE — HWTH_SSLKEYTYPE_KEYRINGNAME
d. HWTH_OPT_SSLKEY: Specify Key Ring name specific to you site, which has the certificates required for PKI.
e. HWTH_OPT_SSLCIPHERSPECS : The cipher suite that will be used between client and server during the interaction.
f. HWTH_SSLVERSION_TLSv12: version of the HTTPS connection, it support SSL/TLS V1.2 and TLS V1.3
g. HWTH_OPT_URI: URL of the external server which your legacy application intends to interact with
h. HWTH_OPT_COOKIETYPE: Cookie behavior for this connection. This will determine how subsequent interaction with the intended server will take place.
3. HTTP Connect
4. HTTP Init Request
5. HTTP Setup Request: HTTP Method GET, POST, PUT, DELETE are set here
6. HTTP Issue request: Here you will receive back the response from the server, which you could process at this step.
7. HTTP Terminate Request
8. HTTP Disconnect
9. HTTP Terminate Connection
While this isn’t the exhaustive list of setup, you may refer the official documentation. But these configurations listed here are essentials to make your first web Api invocation from mainframe.
Web enablement toolkit provides a lot of flexibility for programmer to build upon.
