CICS Web Services

Hemant BabtiwaleCapgemini/GM

Sunday, April 9, 2023

Overview of CICS Web services in CICS TS

Learn about the development, deployment, testing and debugging of CICS Web services

Demo of VOM Services implemented for Order Work Bench Mexico

Slide 204/09/2023

Agenda

CICS Web Services

Slide 304/09/2023

CICS Web Services provides the ability to front-end existing CICS programs with a web service interface … “exposing” the CICS program as a service.

CICS Web Service

Front-End

Existing CICS

Program

CICS TS

Network

Web Service Client

Program CICS program unchanged

Appl

3270EXCI

Traditional access unaffected

New front-end allows service oriented

invocation

SOAP/HTTP

Therefore, a traditional CICS program can be turned into a message based “service” which can then be used by “service consumers” in the enterprise

Inte

rfa

ce

CICS Web Services Scenarios

CICS TS

GM Order Work Bench

OR J2EE, .NET,

Reactivity, other …

CICSWeb

Servicessupport

Integration logic

Dataaccess

Business Function

DI

Business logic

B

Service Requester (Service Provider)

CICS TS

CICSWeb

Servicessupport

From CICS Program

Business logic

B

Service Provider(Service Requester)

J2EE, Portal, Reactivity,

.NET, other …

Slide 4

CICS Resources (Provider mode)

Slide 504/09/2023 WebSphere® Support Technical Exchange

5 of 37

WEBSERVICEIdentifies application specific processing

PIPELINEIdentifies shared qualities of service

URIMAPIdentifies the type of processing required

TCPIPSERVICEThe listener process (if HTTP is used)

TCPIPSERVICE

This definition controls the IP (internet protocol) messages. This resource invokes three unique transaction codes to process the message as it arrives in and out of the network. The messages all arrive and leave via a pre-assigned port that is unique to the CICS region. The next slide depicts the arrival of an input message and the internal CICS transactions that are invoked to process this message.

CICS Resources

TCPIPSERVICE- continued

• CSOL: This transaction monitors the port specified in the TCPIP resource definition for incoming HTTP requests.

• CWXN: When the SOAP message arrives, CWXN finds the URI in the HTTP request and then scans the URIMAP resource definitions for a URIMAP that has its USAGE attribute set to PIPELINE.

• CPIH: CPIH starts the pipeline processing. It uses the PIPELINE definition to find the name of the pipeline configuration file. CPIH uses the pipeline configuration file to determine which message handler programs and SOAP header processing.

CICS Resources

PIPELINE

The purpose of the pipeline is to provide a path to specific resources. These resources provide instructions on how to handle the messages from the client and also the location of the file containing the web-services. The Pipeline is defined in CICS.

CICS Resources

URIMAP

The purpose of the URIMAP is to pass the incoming request to the appropriate pipeline. This is dynamically built when the pipeline is scanned. This resource is does not require a predefined CICS definition.

WEBSERVICEThis resource is used in conjunction with the WSBIND

file to associate the Web-service to the URIMAP. There is no defined CICS resources for a web-service. It is created dynamically by reading the contents of the WSBIND file.

CICS Resources

WSDL

The WSDL uses XML to specify the characteristics of a Webservice - what the Web service can do, where it resides, and how it is invoked. WSDL can be extended to allow descriptions of different bindings, regardless of what message formats or network protocols are used to communicate.

•Name of the Web service and addressing information •Protocol and encoding style to be used when accessing the public operations of the Web service

•Type information: Operations, parameters, and data types comprising the of the Web service, plus a name for this interface.

UNIX Resources

WSBIND

When the application runs, CICS uses the WSBIND file to transform the application data into a SOAP message on output and to transform the SOAP message to application data on input. Each program that has been converted to a web-service will have en entry in the WSBIND file.

CICS retrieves from the WSBIND file, the name of the specific webservice(s). This information will be used to dynamically build the webservice and URI.

UNIX Resources

Configuration File

This file contains a series of programs (message handlers) that instruct the pipeline how to handle the messages.

Shelf File

As WSBIND files are installed, they stored in the shelf directory by CICS.

UNIX Resources

TCPIPSERVICE

CEMT I TCPIPSERVICE(OM0TCPSV)Tcpips(OM0TCPSV) Ope Por(03151) Http Nos

Tra(CWXN) Bas Con(00000) Bac( 00300 ) Max (000100 ) Urm( DFHWBAAX )

==Ensure that the resource is open and directed to the correct port.

CICS Commands

PIPELINE--

CEMT PERFORM PIP(OM0PIPEL) SCAN

When a PIPELINE is installed or in response to a PERFORM PIPELINE SCAN command, CICS searches this pickup directory for files ending with “wsbind”. For each wsbind file, CICS dynamically creates a WEBSERVICE and URIMAP resource, associates them with the PIPELINE and installs them ready for use.

CICS Commands

PIPELINE—

CEMT I PIP(OM0PIPEL)*** This will return the following response ***? pip(OM0PIPEL) Ena ProSoa(1.1 )

Con(/users/gmom/owbvomws/confi)

== Place ? to the left of the pip to expand the display.

CICS Commands

PIPELINE – expanded display

Pipeline(OM0PIPEL)Enablestatus ( Enabled ) = Mode(Provider)Mtomst(Nomtom)Sendmtomst(Nosendmtom)Mtomnoxopst(Nomtomnoxop)Xopsupportst(Noxopsupport)Xopdirectst(Noxopdirect)Soaplevel(1.1) = Respwait( )Configfile(/users/gmom/owbvomws/config/owbsoap11provider.xml) =

CONFIG NAME Shelf(/users/gmom/owbvomws/shelf/) = Shelf for storing WSBIND files

Wsdir(/users/gmom/owbvomws/wsdir/) = Location of WSBIND files prior to

usage.Ciddomain(cicsts)

CICS Commands

URI

CEMT I URI(*) =Displays the active URI maps.

STATUS: RESULTS - OVERTYPE TO MODIFY

Uri($100370 ) Pip Ena Http

Host(* )

Path(/vom/services/retrieveTagDetails) Uri($548070 ) Pip Ena Http

Host(* )

Path(/vom/services/dealerAssignmentSu)

CICS Commands

WEBSERVICE-

CEMT I WEBS(*) = Issue this command to display active web-services.

Webs(dealerAssignmentSubmit )

Pip(OM0PIPEL) Ins Ccs(00000) Uri($548070 ) Pro(OM0PW540) Cha

Xopsup Xopdir Webs (reassignDealerForVehicle )

Pip(OM0PIPEL) Ins Ccs (00000) Uri ($609400) Pro(OM0PW509) Cha

Xopsup Xopdir

CICS Commands

WEBSERVICE-

CEMT I WEBS(*) = Issue this command to display active web-services.

Webs(dealerAssignmentSubmit )

Pip(OM0PIPEL) Ins Ccs(00000) Uri($548070 ) Pro(OM0PW540) Cha

Xopsup Xopdir Webs (reassignDealerForVehicle )

Pip(OM0PIPEL) Ins Ccs (00000) Uri ($609400) Pro(OM0PW509) Cha

Xopsup Xopdir

CICS Commands

URIMAP($918180)PATH(/user/gmom/App/dispatchOrder)

PIPELINE(EXPIPE01)

WEBSERVICE(dispatchOrderEndpoint)

WEBSERVICE(dispatchOrderEndpoint)PIPELINE(EXPIPE01)

URIMAP($918180)PROGRAM(DFH0XODE)

WSBIND(…dispatchOrderEndpoint.wsbind)ENDPOINT(http://ip:port/exampleAppdispatchOrder)

BINDING(dispatchOrderSoapBinding

Configfile – msg handlers

WSDIR pickup directorysearchPopConfig.wsbind

PIPELINE(OM0PIPEL)CONFIGFILE(users/gmom/owbvomws/config)

SHELF(users/gmom/owbvomws/shelf)WSDIR(users/gmom.owbvomws/wsdir)

TCPIPSERVICE(OM0TCPSV)PORT(03151)

URIMAP($918180)PATH(/user/gmom/owbvomws/wsdir/searchPop)

PIPELINE(OM0PIPEL)

WEBSERVICE(searchPopConfig)

WEBSERVICE(searchPopConfigt)PIPELINE(OM)PIPEL)

URIMAP($918180)PROGRAM(OM0PW534)

WSBIND(…searchPopConfig.wsbind)ENDPOINT(http://ip:port/exampleAppdispatchOrder)

BINDING((…searchPopConfig.wsbind)

Putting it all together

Message Handler

Slide 2104/09/202321 of 42

WEBSERVICE

URIMAP

CICS TS V3.2TCPIPSERVICE

TABCCWXN

ServiceRequester

URIMAPmatching

CSOL

Pipeline

handlers

handlers

handlers

SOAP request

data mapping

PIPELINE

HFS

Pipeline

Config

VOM

Wrapper

Program315

0

SOAP response

STD IBMSecurityMsg handler

STD IBMSOAP

Msg handler

STD IBMXML/COPYBOOK

Msg handler

Message Handlers:–Program to process a request during input or a response during

output.NOTE: The IBM Default Message Handlers

Are used for NAOWB SOAP & XML/ COPYBOOK conversion

Web attachtask

Socketslistener

Security Planning

How to authenticate How to pass security credentials (in message or in transport layer) Whether identity assertion is required How to ensure confidentiality and data integrity

CICS TS

Web ServiceRequester

CICSWeb

Servicessupport

Businesslogic

DB

WebLogic Application Server

Pipeline

I

App

WS-Security/ WS-Trust

Authentication?

SOAP/HTTPS

Confidentialityand Integrity

Authorization

Dealer

Authentication

CICS supplied security handler

Slide 22

Background - Vehicle Order Management • The existing VOM application has a Visual Basic front end that interacts

with the VOM midrange code and Mainframe CICS code using NetEssential RPC middleware to implement vehicle tagging functionality. CICS Cobol programs perform all updates to VOD (DB2).

• There are 2 user types for the tagging functionality – Mexico dealers and GM Mexico central office (corporate) users. The Mexico dealers utilize Citrix to access the tagging functionality over internet. Corporate users utilize locally installed VB client within GM network.

• OWB R2.3 Mexico project has a requirement to migrate the tagging functionality from VOM for Mexico dealers. The existing VB application will continue to serve the corporate users, however certain corporate functions will be available from OWB as well.

• Total Number Of Users– 320 Dealer users– 50 Corporate users

Slide 23

Slide 2404/09/2023

Slide 24

Initial State

Creating Business Services for VOM• Business Context

– GM wants to expose existing VOM functions to wide variety of internal corporate and external dealer users

• Manage complexity – avoid point-to-point integration

• Business Value– Ease integration challenge– Leverage the business value of existing legacy systems– Enhance responsiveness to business demands

• Architectural Patterns– Directly expose the application as service

• Direct access to CICS COMMAREA as Web services– Indirectly expose the application via service component

• Create a middle-tier Web services façade for accessing CICS– CICS ECI Adapter with CICS Transaction Gateway

Slide 25

VOM Services

SDP Template Version 1.1

Version 1.0026 Slide 26

Slide 26

Listed below are the transactions required to invoke a specific resource.

OWB Screen OWB Web Service VOM Wrapper VOM Driver Test Transact

ion

Test Program

Avail List searchPopConfig  OM0PW534 OM0P0534 M574 OM0PT534

Request Popcon searchVehForTagging  OM0PW535 OM0P0535 M575 OM0PT535

Tag Vehicle  tagVehicle  OM0PW536 OM0P0536 M576 OM0PT536

View Tag Details retrieveTagDetails  OM0PW541 OM0P0541 M581 OM0PT541

Untag  unTagVehicle   OM0PW537 OM0P0537 M577 OM0PT537

Dealer Assignment window

 searchDealerAssignmentVehicles

 OM0PW539 OM0P0539 M579 OM0PT539

Submit from Dealer Assignment

 dealerAssignmentSubmit   OM0PW540 OM0P0540 M580 OM0PT540

Reassign from Dealer Assignment

 reassignDealerForVehicle   OM0PW509 OM0P0509 M569 OM0PT509

Slide 2704/09/2023

1. SearchAvailableConfigurations

Program OM0P0534 which is used to search the available popular configurations.

2. SearchAvailableVehiclesforTagging

Program OM0P0535 which is used to search the available popular configurations.

3. TagVehicle

Program OM0P0536 calls a subprogram to get credit, constraint, and vehicle availability. then updates the order management tables with the appropriate tag information.

4. RetrieveTagActivityDetail 

OM0P0541 program selects data from the tag vehicle detail inquiry screen

5. UnTag Vehicle

OM0P0537 will perform untagging of vehicles before the credit/rebill invoice

 

Legacy Program Details

Slide 2804/09/2023

6. SearchDealerAssignmentVehicles

OM0P0539 will retrieve a list of orders that are awating final dealer assignment by GMof mexico. Orders that fall into this category are employee orders which are candidates for a credit / rebill, and orders which have been rejected in the credit / rebill process because the charge to dealer's credit limit has been reached.

7. SubmitDealerAssignmentVehicles

This service corresponds to the VOM CICS program OM0P0540.

1)for each order in an array of orders, apply a final dealer assigned event code .

2)for a single order, change the dealer of record bac/bfc and the charge to bac/bfc and/or ship to bac/bfc on a firm order or a tagged free order

8.ReassignDealerForVehicle

Program OM0P0509 a pass through program. It calls subprogram om0s0042 to perform edit / validate reassignment input and perform reassignment updates. No updates are applied to any tables

Legacy Program Details

29

Slide 29

Deployed State

Summary

04/09/2023

CICS provides a robust and scalable Web services infrastructure

Web services enable secure interoperability with internal systems and external business partners

Many of IBMs largest customers are using CICS Web services today

Check out the CICS Information Center and the IBM Redbooks for more information on deploying CICS Web services

Slide 30

Useful Resources

04/09/2023

CICS Information CentersTS 3.1 http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jspTS 3.2 http://publib.boulder.ibm.com/infocenter/cicsts/v3r2/index.jspTS 4.1 http://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp

IBM Web Services Red BooksArchitecture http://www.redbooks.ibm.com/abstracts/sg245466.html?OpenImplementationhttp://www.redbooks.ibm.com/abstracts/sg247206.html?OpenPerformancehttp://www.redbooks.ibm.com/abstracts/sg247687.html?OpenSecurityhttp://www.redbooks.ibm.com/abstracts/sg247658.html?OpenWLM http://www.redbooks.ibm.com/abstracts/sg247144.html?OpenDevelopmenthttp://www.redbooks.ibm.com/abstracts/sg247126.html?Open

Examples http://www-01.ibm.com/support/docview.wss?uid=swg24020774

Knowledge Collection http://www-01.ibm.com/support/docview.wss?uid=swg27010507

Slide 31

Questions

Slide 3204/09/2023