Introduction

Mainframe z/OS online environment often has backend CICS transactions that are invoked by CICS itself or by other CICS transactions. Generally, backend transactions perform business logic that do not have user input via Green Screens or BMS. The invoking CICS transactions also often pass parameters to the invoked CICS transaction.

AWS Mainframe Modernization service can migrate the COBOL/PL1 CICS mainframe applications to AWS fully managed runtime environments. It is a set of managed tools providing infrastructure and software for modernizing, migrating, testing, and running mainframe applications.

In the refactor pattern powered by AWS Blu Age mainframe applications written in COBOL, PL1, CICS, etc. are transformed into modern distributed applications relying on Angular, Java/Spring, Groovy, etc. The underlying mainframe databases like DB2, VSAM, IMS, etc. and data files are migrated to AWS PostgreSQL or other databases such as Amazon Aurora, RDS for PostgreSQL, Oracle database, IBM Db2.

Once migrated to AWS Mainframe Modernization service, the backend CICS transaction (called JICS in AWS Blu Age environment) can now be invoked using API calls. Thus applications or other AWS services that can execute REST based API calls can easily invoke and integrate with backend JICS transactions.

Example: Triggering JICS transaction from AWS Lambda function

Below sample Python code shows how to -

• build a String/ALPHANUMERIC parameter and encode it
• invoke the JICS transaction passing the parameter through CICS Program DFHCOMMAREA
• accept the response back from the JICS transaction in String/ALPHANUMERIC format
• check response status and decode the response

import urllib.request
import json
import base64
from datetime import datetime
import uuid
import os

def lambda_handler(event, context):

    m2_host_dns = os.environ['M2_HOST_DNS']
    m2_host_port = os.environ['M2_HOST_PORT']

    url = m2_host_dns + ':' + m2_host_port

    date = datetime.today().strftime('%y%m%d')
    time = datetime.today().strftime('%H%M%S')

    commarea_data = '{"lkCommarea":[{"VALUE":"' + date + ',' + time + ',' + 'HELLO WORLD' + '","TYPE":"ALPHANUMERIC","LENGTH":200}]}'
    print('commarea_data:', commarea_data)
    #sample commarea_data -->  {"lkCommarea":[{"VALUE":"231211,215444,HELLO WORLD","TYPE":"ALPHANUMERIC","LENGTH":200}]}
    
    params = json.dumps(json.loads(commarea_data)).encode('ascii')

    res = urllib.request.urlopen(urllib.request.Request(
            url='http://' + url + '/gapwalk-application/jicstransaction/CXXX',
            data=params,
            headers={'Accept': 'application/json', 'Content-Type': 'application/json'},
            method='POST'),
        timeout=50)
    
    print('Call Request status:', res.status)
    
    resp_json = json.loads(res.read())
    convertedbytes = base64.b64decode(resp_json["recordContent"])
    response_string = convertedbytes.decode("cp500")
    
    print('Call Request value:', response_string)

    return {
        'statusCode': 200,
        'body': json.dumps(response_string)
    }

Code explanation:

• In the above code M2_HOST_DNS and M2_HOST_PORT are set as Environment variables for the Lambda function -

The values of those properties are obtained from the running Blue Age application on AWS Mainframe Modernization console. The below screenshot shows the location of the DSN [1] and the PORT [2] under Applications.

• The CXXX in the url '/gapwalk-application/jicstransaction/CXXX' refers to the name of the CICS /[JICS] transaction name that will be invoked.

• In the sample code above the parameter is passed as ALPHANUMERIC value via CICS Program DFHCOMMAREA. The value is passed as a JSON format with TYPE and LENGTH are required attributes. lkCommarea is the name of the JSON key for the value to be passed.

• Below is the sample COBOL CICS code for the program corresponding to the CXXX transaction, showing how it parses the DFHCOMMAREA values.

  

• Similarly, the sample COBOL CICS code showing how the response is set in DFHCOMMAREA.

  

• CICS CHANNEL/CONTAINER is also supported. For documentation of the format please refer to here

Important notes:

• When invoking the REST API make sure the VPC/Security Groups, if applicable are setup correctly to allow access to the end-points.
• When running the AWS Lambda function, the IAM roles are setup correctly.

References:

• [1] AWS Mainframe Modernization
• [2] AWS Mainframe Modernization documentation
• [3] AWS Blu Age Refactoring
• [4] AWS Blue Age well-architected Workshop