Gen 8.6 Consuming REST APIs: Batch and Compatibility

Products

Gen Gen - Host Encyclopedia Gen - Run Time Distributed Gen - Workstation Toolset

Issue/Introduction

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.

Environment

Gen 8.6

COBOL applications executing on CICS or in Batch

Execution Environment Requirements:

CICS

z/OS 2.2 or newer
CICS TS 5.4 or newer

Batch

z/OS 2.3 or newer

Resolution

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)

Pre-requisites

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.

PTFs

This enhancement is delivered in the following three PTFs:

PTF Name	FMID	Description
LU08865	CEHB860	Common Modules
LU08866	CEHC860	CICS Common Modules
LU08867	CETA860	Unresolved Runtime Modules

ISPF Skeletons

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:

CEHBSKL0 Member

TI$LAE

TI$LAED

TI$LBTCH

TI$LDB2C

TI$LDSN

TI$LEXEC

TICBATAB

TICBATNO

TICLAE

TICLAED

TICLBTCH

TICLDSN

TICLEXEC

Batch Application Requirements

The following items are required in order to consume RESTful APIs from a Gen-generated batch application:

OMVS Segment

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.

POSIX

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 *
POSIX(ON)

These JCL cards are not needed for the TIRIOVFI job step or other job steps that do not use Call REST statements.

TIRABRTB

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.

TIRXINFO

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.

AT-TLS

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

Port Numbers

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

Installation Checklist

The following steps can be used to get this enhancement installed and ready for use by your generated applications:

Backup any customized CEHBSKL0 members
Make sure your CSI is current on Gen PTFs so you will have all necessary pre-requisite PTFs
Use CSM, SAMPJCL or z/OSMF to apply the three PTFs that deliver this enhancement
Merge any CEHBSKL0 customizations into the new members
If necessary, customize the TIRXINFO user exit and rebuild the TIRXINFZ user exit DLL
For CICS applications, copy the TIRABRT, TIRABRTC, TIRMTQBZ, TIRORUNC and TIRXINFZ DLLs to a dataset in your CICS region’s DFHRPL concatenation and perform a NEWCOPY on these programs
For Batch applications, make sure the TIRABRT, TIRABRTB, TIRBRUNB, TIRMTQBZ and TIRXINFZ DLLs are available in a dataset in your batch job step’s STEPLIB concatenation
For Batch applications, edit your JCL to indicate your application is POSIX-enabled
For Batch applications, make sure the userid executing the batch job has an OMVS segment defined

Additional Information

For additional information, please see hub article: Gen 8.6 Consuming REST APIs (Call REST) feature