Gen 8.6 Consuming REST APIs: Getting Started
search cancel

Gen 8.6 Consuming REST APIs: Getting Started

book

Article ID: 234414

calendar_today

Updated On:

Products

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

Issue/Introduction

The Gen 8.6 Consuming REST APIs for Java and CICS Applications feature allows your Gen applications to use functionality provided by RESTful Web Services.  The purpose of this document is to help you get started using this feature.  This document will cover what PTFs are required and what actions need to be performed on your Encyclopedias and your Models in order to be able to add the new Call REST statement.  Some application execution environment configuration topics will also be covered.

In June of 2022, native support for security schemes like BasicAuth, BearerAuth, ApiKeyAuth, and OAuth2 (Client Credentials Flow) was added to the Consuming REST APIs for Java and CICS Applications feature.  This article has been updated to reflect this additional functionality.

Environment

Gen 8.6
Java applications
COBOL applications executing on CICS

Resolution

To get started using the Consuming REST APIs for Java and CICS Applications feature, please follow these steps:

  1. Apply PTFs
  2. Update Encyclopedia Schema Tables
  3. Convert Models
  4. Add Call REST statement
  5. Configure Execution Environment



Apply PTFs

The following PTFs provide the Consuming REST APIs for Java and CICS Applications functionality.  Apply the PTFs that are appropriate for your development and execution environments.  You can click on the individual PTF links below or you can access all the PTFs from the page Gen 8.6 Solutions and Patches.  The Mainframe PTFs can be accessed from the CA Gen Maintenance Grid link on that page.
NOTE: For the distributed side the PTFs below which added the Consuming REST APIs for Java and CICS Applications functionality have since been superseded by 8.6.3 Consolidation PTFs.

Workstation

 

Client Server Encyclopedia (CSE)

Host Encyclopedia (HE) and z/OS Runtimes

The Consuming REST APIs for CICS Applications feature has modified the CEHBSAMP and CEHBSKL0 members listed below in Table 1.  If you have customized any of these members, please make sure you have a backup copy of these members before APPLYing these PTFs.

 

Table 1.  Modified CEHBSAMP and CEHBSKL0 members

Member

Type

MTQDEFLT

CEHBSAMP

NDEFCICS

CEHBSAMP

TIRMTQB2

CEHBSAMP

DEFCICS

CEHBSKL0

TICICSAB

CEHBSKL0

TICLDB2C

CEHBSKL0

 

    • LU03643 / FMID CEHB860 – Prerequisite PTF to update your SMP/E CSI 
      • After APPLYing this PTF, you must customize and execute the TIDDDEF1 CEHBSAMP member before APPLYing the remaining PTFs
    • LU03408 / FMID CEG6860 – Host Encyclopedia support for Call REST statement 
      • After APPLYing this PTF, you must rebind the necessary DB2 Packages. Use the PTFBIND job with TIB03408 as the input clist.
      • The Sample and Help models have been re-converted so the Call REST statement can be added to these models. Use CEJOB12 and CEJOB13 to reload these models to your Host Encyclopedia, if desired.
    • LU03409 / FMID CEHB860 – Common Modules support for Call REST statement
    • LU03410 / FMID CEHC860 – CICS Runtime Modules support for Call REST statement
    • LU05281 / FMID CEHC860 – CICS Runtime Modules support for Call REST statement security schemes



Update Encyclopedia Schema Tables

New system objects are required to support the Call REST statement.  Update your encyclopedia’s Schema tables to pick up these new objects.

  • On the CSE, run cse_config and select the “Update Encyclopedia tables to this release” configuration option to reload the Schema tables
  • On the HE, use CEJOB05 (or CAJOB05) to reload the Schema tables



Convert Models

To add the Call REST statement to an existing model, the model must first be converted (or re-converted) to the 9.2.A6 schema level after the encyclopedia’s Schema tables have been updated.  If you are adding the Call REST statement to a new model, conversion is not necessary.

  • On the CSE, use the Encyclopedia Client or the convmodl server command to perform model conversion
  • On the HE, use the 1.3.11 option from the HE Main Menu to access the model conversion utilities



Add Call REST statement

The Call REST statement is how your Gen application can use the functionality provided by a RESTful Web Service.  The following restrictions apply to the Call REST statement:

  • Call REST statements are not allowed in Procedure Steps
  • Each Call REST statement must be added to a separate Action Diagram
  • Only the Call REST statement and Note statements can exist in the Action Diagram
  • Only Import and Export Views are used in the Action Diagram. Local and Entity Action Views are not used
  • Action Diagrams containing a Call REST statement cannot have their “Dynamic Link (z/OS)” property set to Compatibility

Please see this link for details on how to add a Call REST statement.



Configure Execution Environment

This section will describe execution environment configuration tasks for both Java applications and CICS applications.

Java applications

A couple of methods are available to configure the execution behavior of the Call REST statements in your Java applications.  You can choose either method or a combination of both methods.  However, using the Configuration parameters is the recommended method since it allows more flexibility and does not require application redeployment whenever changes are needed.

1)  Callrest.properties file

Certain configuration parameters can be set or overridden by using the callrest.properties file, which will be read at application runtime.  The parameters in this file can be configured for all services or for individual services.  The following items apply to the callrest.properties file:

        • Only used by Java applications
        • Contains Key/Value pairs
        • Case Sensitive – Keys need to be uppercase; Values can be lowercase, uppercase, or mixed case
        • Needs to be included in EAR file – Select the “Include optional runtime property files” option at Assemble time in the Build Tool

 

2)  Configuration parameters

An alternative to using the callrest.properties file is to use the Configuration parameters that are available as Import parameters to every Call REST statement.  These parameters can be matched to views in your Action Diagram and dynamically set in your PAD logic.

Please see this link for details on configuring your Call REST statements.

CICS applications

Several steps may be required to configure the execution environment for your CICS applications.  Perform the following steps that apply to your environment:

      1. If you have customized any of the members listed above in Table 1, then you will need to merge your customizations into the new members provided in the Consuming REST APIs for CICS Applications PTFs.
      2. If you have customized either the MTQDEFLT or TIRMTQB2 CEHBSAMP members, then you will need to rebuild the TIRMTQBZ user exit DLL after merging your customizations into the new members. Use the MK5EXITS job to rebuild the TIRMTQBZ user exit DLL.
      3. Modify the TIRXINFO CEHBSAMP member to set the codepage for your CICS applications and rebuild the TIRXINFZ user exit DLL. Use the MKCRUN job to rebuild the TIRXINFZ user exit DLL.  If you are already using Cooperative packaged applications on CICS, then this step should have already been performed.  Online packaged applications on CICS did not previously use the TIRXINFZ user exit DLL, but will now use it if any Call REST statements are used.
      4. Add new CICS Program Definitions for TIRABRT and TIRABRTC to your CICS region(s). The NDEFCICS CEHBSAMP member can be used to add these new CICS resources.
      5. 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.
      6. Add new CICS URIMAP Definitions to your CICS region(s). You will need a unique URIMAP resource for each RESTful Web Service server (not each Web Service endpoint) that is being accessed.




        • URIMAP is the name of the URIMAP resource
          • Should be used in the Service Name field when adding a Call REST statement in the Toolset
        • USAGE must be set to Client
          • The Gen application is acting as an HTTP client
        • SCHEME can be HTTP or HTTPS
        • HOST and PORT defines the machine that is hosting the RESTful Web Service
        • PATH doesn’t really matter to Gen
          • Gen only uses URIMAP to make the connection to the machine hosting the RESTful Web Service
          • Gen uses other Base URL and Path information from selections you made in the Toolset
        • SOCKETCLOSE should be set to a non-zero value to take advantage of connection pooling

 

You can see IBM’s URIMAP documentation here.

Additional Information

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

Powered by Wolken Software