CICS WebServices

CICS WebServices

Restrictions

This data shall not be disclosed and shall not be duplicated, used, or disclosed in whole or
in part for any purpose.

HCL Technologies Page 1 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

Document Control Information

Release Date 31 March, 2011

Version Number 1.0

Prepared MF-COE 31 March, 2011

Approved

Revision No. Date of Release Changes

1.0 31 March, 2011 Initial Release.

HCL Technologies Page 2 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

Contents
1. Introduction ............................................................................................................................. 4

2. CICS as a Service Provider .................................................................................................... 5

2.1. Processing the inbound Service Request ...................................................................... 5
3. Steps for setting up CICS as Service Provider: ..................................................................... 7
3.1. Run the job DFHLS2WS to create the WSDL and WSBIND files .................................. 7
3.2. Define the TCPIPSERVICE in CICS region ................................................................... 8
3.3. Define the PIPELINE in CICS region ............................................................................. 8
3.4. Install the TCpipservice and Pipeline in the CICS region .............................................. 9
3.5. Define and Install the application program ................................................................... 10
4. CICS as a Service Requester .............................................................................................. 13
4.1. Processing the outbound Service Request .................................................................. 13
5. Steps For Setting up CICS as a Service Requester ............................................................ 14
5.1. Run the job DFHWS2LS .............................................................................................. 14
5.2. Define and Install the Pipeline Definition...................................................................... 16

HCL Technologies Page 3 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

1. Introduction
CICS support for Web services makes it possible for CICS applications to be integrated more
rapidly, easily, and cheaply than ever before.

Application programs running in CICS TS V3.1 can participate in a heterogeneous Web services
environment as service requesters, service providers, or both, using either an HTTP transport or
a WebSphere MQ transport.

HCL Technologies Page 4 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

2. CICS as a Service Provider

When CICS is a service provider, it receives a service request, which is passed through a
pipeline to a target application program. The response from the application is returned to the
service requester through the same pipeline. In this section we first discuss how to prepare for
running a CICS application as a service provider. Then we discuss how CICS processes the
incoming service request.

2.1. Processing the inbound Service Request

Figure shows the processing that occurs when a service requester sends a
SOAP message over HTTP to a service provider application running in a CICSTS V3.1
region.

Fig 1 CICS Web Service provider run-time processing

For CICS as a service provider, following operations are performed:

• Receive the request from the service requester.
• Examine the request and extract the contents that are relevant to the target application
program through a pipeline.
• Invoke the application program, passing data extracted from the request.
• Construct a response (when the application program returns control) using data returned
by the application program.
• Send a response to the service requester through the same pipeline.

HCL Technologies Page 5 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

For CICS as a service provider we need to do the following on mainframes:

1. Generate the WSBind and WSDL files.
• Create an HFS directory in which to store the generated files. For example, we
might create a directory named
/u/SharedProjectDirectory/MyFirstWebServiceProvider.
• Run the JCL for DFHLS2WS.

2. Create a TCPIPSERVICE resource definition.

3. Create a PIPELINE resource definition

• Create a service provider pipeline configuration file.
• Create an HFS directory in which to store installable WSBind and WSDL files.
• Create an HFS directory for CICS to store installed WSBind files.
• Create a PIPELINE resource definition to handle the Web service request.
• Copy the WSBind and WSDL files.

4. Install the TCPIPSERVICE and PIPELINE resource definitions.

5. Publish WSDL to clients.

• Customize the location attribute on the <address> element in the WSDL file so
that its value specifies the TCP/IP server name of the machine hosting the
service and the port number.
• Publish the WSDL to any parties wanting to create clients to this Web service.

The CICS-supplied sockets listener transaction (CSOL) monitors the port specified in the
TCPIPSERVICE resource definition for incoming HTTP requests. When the SOAP message
arrives, CSOL attaches the transaction specified in the TRANSACTION attribute of the
TCPIPSERVICE definition; normally, this will be the CICS-supplied Web attach transaction
CWXN.

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 and its PATH attribute set to the URI
found in the HTTP request. If CWXN finds such a URIMAP, it uses the PIPELINE and
WEBSERVICE attributes of the URIMAP definition to get the name of the PIPELINE and
WEBSERVICE definitions, which it will use to process the incoming request. CWXN also uses the
TRANSACTION attribute of the URIMAP definition to determine the name of the transaction that
it should attach to process the pipeline; normally, this will be the CPIH transaction. 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 programs to invoke.

A message handler in the pipeline (typically, a CICS-supplied SOAP message handler) removes
the SOAP envelope from the inbound request and passes the SOAP body to the data mapper
function. CICS uses the DFHWS-WEBSERVICE container to pass the name of the required
WEBSERVICE definition to the data mapper. The data mapper uses the WEBSERVICE definition
to locate the main storage control blocks that it needs to map the inbound service request (XML)
to a COMMAREA or a container.

The data mapper links to the target service provider application program, providing it with input in
the format that it expects. The application program is not aware that it is being executed as a
Web service. The program performs its normal processing and then returns an output
COMMAREA or container to the data mapper.

HCL Technologies Page 6 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

The output data from the CICS application program cannot just be sent back to the pipeline code.
The data mapper must first convert the output from the COMMAREA or container format into a
SOAP body. Path (/mtaas/websvc/wsbind) must match the uri in the HTTP request.

Fig 2 CICS as Service Provider

3. Steps for setting up CICS as Service Provider:

3.1. Run the job DFHLS2WS to create the WSDL and WSBIND files
1. Run the job DFHLS2WS to create the WSDL and WSBIND files, make sure the region
size is 0M.

000100 //H348604C JOB (TRG-TRG-H348604-XXX-999),CLASS=A,REGION=0M,

000200 // MSGCLASS=X,MSGLEVEL=(1,1),NOTIFY=&SYSUID
000300 //JC JCLLIB ORDER=H348604.KUM.BKUP
000400 //JAVAPROG EXEC DFHLS2WS
000500 //INPUT.SYSUT1 DD *
000600 PDSLIB=//H348604.KUM.SRC
000700 REQMEM=MTCEAPIP
000800 RESPMEM=MTCEAPOP
000900 LANG=COBOL
001000 LOGFILE=/mtaas/websvc/provider/ mfmtaas.log
001100 PGMNAME=MTCEWS1
001200 URI=/mtaas/websvc/provider
001300 PGMINT=COMMAREA
001400 WSBIND=/mtaas/websvc/provider/mfmtaas.wsbind
001500 WSDL=/mtaas/websvc/provider/mfmtaas.wsdl

HCL Technologies Page 7 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

001600 /*

3.2. Define the TCPIPSERVICE in CICS region

3.3. Define the PIPELINE in CICS region

:

HCL Technologies Page 8 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

1. Add the DFHPIDIR data set to the CICS startup JCL. DFHPIDIR stores a mapping
between contexts and tasks.
a. Add a new DD statement for the DFHPIDIR data set to your CICS startup JCL
b. Create the DFHPIDIR data set using information in DFHDEFDS.JCL. The default
RECORDSIZE of DFHPIDIR is 1 KB, which is adequate for most uses. You can
create DFHPIDIR with a larger RECORDSIZE if you need to.
c. Install the appropriate group for the data set on your CICS system: DFHPIVS,
DFHPIVR, or DFHPICF.

XX* THE DFHPIDIR WEBSERVICES TRANSACTION

XXDFHPIDIR DD DISP=SHR, DSN=CICSTS31.CICS.CNTL.CICS8.DFHPIDIR

000001 //H348604C JOB (TRG-TRG-H348604-XXX-999),CLASS=A,

000002 // MSGCLASS=X,MSGLEVEL=(1,1),NOTIFY=&SYSUID
000003 //ST1 EXEC PGM=IDCAMS
000004 //SYSPRINT DD SYSOUT=*
000005 //SYSIN DD *
000006 DEFINE CLUSTER(NAME(CICSTS31.CICS.CNTL.CICS8.DFHPIDIR) -
000007 INDEXED -
000008 CYL(2 1) -
000009 VOLUME(Z17SM2)-
000010 RECORDSIZE( 1017 1017 )-
000011 KEYS( 16 0 )-
000012 FREESPACE ( 10 10 )-
000013 SHAREOPTIONS( 2 3 ))-
000014 DATA (NAME(CICSTS31.CICS.CNTL.CICS8.DFHPIDIR.DATA) -
000015 CONTROLINTERVALSIZE(1024)) -
000016 INDEX (NAME(CICSTS31.CICS.CNTL.CICS8.DFHPIDIR.INDEX))
000017 /*

2. Copy the CICS pipeline configuration file from

/usr/lpp/cicsts/cicsts31/samples/pipelines/ basicsoap11provider.xml into
/mtaas/websvc/config/ registrationservicePROV.xml

000001 <?xml version="1.0" encoding="EBCDIC-CP-US"?>

000002 <provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline"
000003 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
000004 xsi:schemaLocation="http://www.ibm.com/software/htp/cics/pipeline
000005 <service>
000006 <terminal_handler>
000007 <cics_soap_1.1_handler/>
000008 </terminal_handler>
000009 </service>
000010 <apphandler>DFHPITP</apphandler>
000011 </provider_pipeline>

Define and install the DFHPIDIR dataset in the CICS region.

3.4. Install the TCpipservice and Pipeline in the CICS region

1. Install the TCpipservice and Pipeline in the CICS region, once the installation is
completed CICS will auto generate and install the URImap and Webservice
definitions.

HCL Technologies Page 9 Version 1.0

Confidential Release Date: March 31, 2011
 CICS WebServices

URImap

WebService

3.5. Define and Install the application program

1. Define and install the user application program MTCEWS1.

HCL Technologies Page 10 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

3. Install the CICS system programs DFHWSATH, DFHWSATR, DFHWSATX.

4. Pipeline scan

Run the pipeline scan for auto installing new web services in the same wsdir path.

HCL Technologies Page 11 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

CICS SPOOL:
DFHPI0715 I 11/22/2010 15:39:04 CICS8 H348604 PIPELINE MFPIPE explicit scan has
completed. Number of wsbind files found in the WSDIR directory: 000003. Number of
WEBSERVICEs created or updated: 000000. Number of WEBSERVICEs not requiring an
update: 000003. Number of failed WEBSERVICE creates or updates: 000000.

HCL Technologies Page 12 Version 1.0

Confidential Release Date: March 31, 2011
 CICS WebServices

4. CICS as a Service Requester

When CICS is a service requester, an application program sends a request, which is passed
through a pipeline to a target service provider. The response from the service provider is returned
to the application program through the same pipeline. In this section we discuss how to prepare
for running a CICS application as a service requester. Then we discuss how CICS processes the
outbound service request.

When CICS is in the role of service requester, it must perform the following operations:
• Build a request using data provided by the application program.
• Send the request to the service provider.
• Receive a response from the service provider.
• Examine the response, and extract the contents that are relevant to the original
application program.
• Return control to the application program

4.1. Processing the outbound Service Request

Fig 3 CICS as service requestor

When the service requester issues the EXEC CICS INVOKE WEBSERVICE command, CICS
uses the information found in the wsbind file that is associated with the specified WEBSERVICE
definition to convert the language structure into an XML document. CICS then invokes the
message handlers specified in the pipeline configuration file, and they convert the XML document
into a SOAP message.

CICS sends the SOAP request message to the remote service provider via either HTTP or
WebSphere MQ.

When the SOAP response message is received, CICS passes it back through the pipeline. The
message handlers extract the SOAP body from the SOAP envelope, and the data mapping
function converts the XML in the SOAP body into a language structure, which is passed to the
application program in container DFHWS-DATA.

HCL Technologies Page 13 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

5. Steps For Setting up CICS as a Service Requester

Generate the wsbind file and the language structures.
a. Create an HFS directory in which to store the wsbind file. For example, you might create
a directory named /u/SharedProjectDirectory/MyFirstWebServiceRequester
b. Run the DFHWS2LS program. The input you provide to the program includes the
following:
• The fully qualified HFS name of the WSDL file that describes the Web service
you want to request.
• The names of the partitioned data set members into which DFHWS2LS should
put the high-level language structures it generates. The application program uses
the language structures to describe the Web service request and the Web
service response.

Create a PIPELINE resource definition.

a. Create a service requester pipeline configuration file.
The pipeline configuration file describes the message handler programs and the SOAP
header processing programs that CICS will invoke when it processes the pipeline.
b. Create an HFS directory in which to store installable wsbind files.
CICS will pick up the wsbind file from this directory and store it on a “shelf” directory.
c. Create the shelf directory for CICS to store installed wsbind files in.
d. Create a PIPELINE resource definition to handle the Web service request:
• Specify the CONFIGFILE attribute to point to the file created in step 2a.
• Specify the WSDIR attribute to point to the directory created in step 2b.
• Specify the SHELF attribute to point to the directory created in step 2c.
• Copy the wsbind file created in step 1to the pickup directory created in step 2b.

Install the PIPELINE resource definition.

When the CICS system programmer installs the PIPELINE definition, CICS scans the pickup
directory for wsbind files. When CICS finds the wsbind file created in step 1, CICS dynamically
creates and installs a WEBSERVICE resource definition for it. CICS derives the name of the
WEBSERVICE definition from the name of the wsbind file. The WEBSERVICE definition identifies
the name of the associated PIPELINE definition and points to the location of the wsbind file in the
HFS.

During the installation of the WEBSERVICE resource, CICS uses the wsbind file to create main
storage control blocks to map the outbound service request to an XML document and to map the
inbound XML response document to a language structure.

Use the language structure generated in step 1 to write the application program.
a. The application issues the following command to place the outbound data into container
DFHWS-DATA:
EXEC CICS PUT CONTAINER(DFHWS-DATA) CHANNEL(name_of_channel)
FROM(data_area)
b. It then issues the following command to invoke the Web service:
EXEC CICS INVOKE WEBSERVICE(name_of_WEBSERVICE_definition)
CHANNEL(name_of_channel) OPERATION(name_of_operation)

5.1. Run the job DFHWS2LS

000001 //H348604L JOB (TRG-TRG-H348604-XXX-999),CLASS=A,REGION=0M,
000002 // MSGCLASS=X,MSGLEVEL=(1,1),NOTIFY=&SYSUID
000003 // SET QT=''''

HCL Technologies Page 14 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

000004 //JC JCLLIB ORDER=H348604.TEST.JCLLIB

000005 //JAVAPROG EXEC DFHWS2LS,
000006 // TMPFILE=&QT.&SYSUID.&QT
000007 //INPUT.SYSUT1 DD *
000008 PDSLIB=//H348604.TEST.JCLLIB
000009 REQMEM=INREQ
000010 RESPMEM=OUTREQ
000011 LANG=COBOL
000012 LOGFILE=/mtaas/websvc/req6/reqwsc.log
000013 URI=/mtaas/websvc/req6
000014 PGMINT=COMMAREA
000015 WSBIND=/mtaas/websvc/req6/reqwsc.wsbind
000016 WSDL=/mtaas/websvc/req6/reqwsc.wsdl
000017 /*

PDSLIB: Specifies the name of the partitioned data set that contains the high-level language
data structures to be processed.

REQMEM: Specifies the name of the partitioned data set member that contains the high-level
language structure for the Web service request.
• For a service provider, the Web service request is the input to the application program.
• For a service requester, the Web service request is the output from the application
program.

RESPMEM: Specifies the name of the partitioned data set member that contains the high-level
language structure for the Web service response:
• For a service provider, the Web service response is the output from the application
program.
• For a service requester, the Web service response is the input to the application
program.

LANG: Specifies the language of the language structure to be created.

PGMNAME: Specifies the name of the target CICS application program that is being exposed as
a Web service. No need of the PGMNAME parameter for the service requestor JOB

URI: In a service provider, this parameter specifies the relative URI that a client will use to
access the Web service. CICS uses the value specified when it generates a URIMAP resource
from the Web service binding file created by DFHLS2WS. The parameter specifies the path
component of the URI to which the URIMAP definition applies.

PGMINT: For a service provider, specifies how CICS passes data to the target application
program (using a COMMAREA or a channel).

WSBIND: Specifies the HFS name of the Web service binding file.

WSDL: Specifies the HFS name of the Web service description file.

Note1: FTP the WSDL from the provider into the HFS path /mtaas/websvc/req6/.

Note2: Make sure to remove the encoding='EBCDIC-CP-US from the WSDL, before submitting
the
above job.

HCL Technologies Page 15 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

Note 3: Make sure to start the WebService before submitting the above job, as CICS is checking
for the service before creating the BIND file.

Requester Config file:

BROWSE -- /mtaas/websvc/config/serviceREQ.xml ------ Line 00000000 Col 001 080
********************************* Top of Data ***************************************************************
<?xml version="1.0" encoding="UTF-8"?>
<requester_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/software/htp/cics/pipeline requester.xsd
</requester_pipeline>
******************************** Bottom of Data ************************************************************

Sample WSDL:

calculator.wsdl

The above job will create the REQMEM and RESPMEM members from the input WSDL

INREQ01.txt OUTREQ01.txt

5.2. Define and Install the Pipeline Definition

HCL Technologies Page 16 Version 1.0

Confidential Release Date: March 31, 2011
CICS WebServices

WebService will be created after the Pipeline Installation is completed successfully:

Note: There will be no URImap definition for the requester WebService.

HCL Technologies Page 17 Version 1.0

Confidential Release Date: March 31, 2011