The ability for Gen applications to use functionality provided by RESTful Web Services began with the release of the Gen 8.6 Consuming REST APIs for Java and CICS applications feature. This was followed by providing native support for some of the most commonly used authentication security schemes. The next step in Gen's Continuous Delivery strategy extends this feature to also include support for COBOL Batch and Compatibility applications. The purpose of this document is to help you get started using this latest enhancement.
COBOL applications executing on CICS or in Batch
Execution Environment Requirements:
z/OS 2.2 or newer
CICS TS 5.4 or newer
z/OS 2.3 or newer
This enhancement adds the following support to the Consuming REST APIs feature:
1) Batch application support
Gen-generated Batch applications can now consume RESTful APIs
Supported functionality includes:
HTTP Methods: GET, POST, PUT, and DELETE
Security Schemes: Basic, Bearer, API Key, and OAuth2 Client Credentials Authentication
DB2 Attach Types: DB2_DSN and EXEC (or NONE)
2) Compatibility support for Batch and CICS applications
Call REST Action Blocks can now have their Dynamic Link (z/OS) property set to Compatibility (CMP)
This enhancement is delivered in three PTFs for the z/OS platform. However, to be able to add Call REST statements to your models, you will also need the earlier PTFs that delivered the Consuming REST APIs feature. The instructions in this document are written with the assumption you are up-to-date on Gen 8.6 PTFs and have already installed all of the pre-requisite PTFs. If you are not, we recommend that you first read the Knowledge Base articles in this hub article. Specifically, the Getting Started article will guide you through the steps you need to get your environment ready to use the Consuming REST APIs feature. There are steps such as updating your Encyclopedia’s Schema tables and converting your models that must be done before you can add Call REST statements to your models.
This enhancement is delivered in the following three PTFs:
|LU08866||CEHC860||CICS Common Modules|
|LU08867||CETA860||Unresolved Runtime Modules|
This enhancement updates several ISPF skeletons in the CEHBSKL0 dataset. If any customizations have been made to these skeletons, please make a backup copy of the skeletons before applying the PTFs to avoid losing the customizations. After applying the PTFs, any customizations will need to be merged into the updated skeletons.
The list of updated skeletons is shown below:
The following items are required in order to consume RESTful APIs from a Gen-generated batch application:
z/OS UNIX System Services (USS) are used by batch applications that contain Call REST statements. Therefore, the userid executing the batch job must have an OMVS segment defined.
A batch application must be executed as a POSIX-enabled application in order to use a Call REST statement. There are several ways to indicate that the application is POSIX-enabled, but one of the simplest methods is to add the following JCL cards to each batch job step that uses Call REST statements:
//CEEOPTS DD *
These JCL cards are not needed for the TIRIOVFI job step or other job steps that do not use Call REST statements.
This enhancement delivers a new DLL named TIRABRTB. Please make sure this DLL is included in a dataset in the batch job step's STEPLIB concatenation, along with the other necessary Gen runtimes, for any batch application that contains Call REST statements.
The TIRXINFO user exit in the CEHBSAMP dataset specifies the EBCDIC codepage used in the z/OS execution environment by CICS and batch applications that contain Call REST statements. The default exit is set to use codepage 37. If a different codepage value is needed, modify the TIRXINFO user exit and rebuild the TIRXINFZ user exit DLL using only the last two steps of the MKCRUN job in the CEHBSAMP dataset. Then make sure this DLL is included in a dataset in the batch job step's STEPLIB concatenation, along with the other necessary Gen runtimes, for any batch application that contains Call REST statements.
Gen Batch applications depend on Application Transparent-Transport Layer Security (AT-TLS) being configured properly to support making secured HTTP calls (HTTPS). Essentially the Gen application has no knowledge of the security required and the security is handled by the transport layer (TCP/IP).
If the Base URL used for a Call REST statement does not include a port number, then the following defaults will be used:
HTTP - port 80
HTTPS - port 443
The following steps can be used to get this enhancement installed and ready for use by your generated applications:
For additional information, please see hub article: Gen 8.6 Consuming REST APIs (Call REST) feature