There are three development approaches for creating web services in CICS:
-
Top-down approach: Creates a service from an existing Web Services Description Language (WSDL) - used for
new applications with existing WSDL/new WSDL. WSDL uses eXtensible Markup Language (XML) to specify the
characteristics of a web service: name of the web service, what it can do and how it is invoked.
-
Bottom-up approach:Creates a WSDL from an existing application - used for existing application.
-
Meet-in-the-middle-pproach: Used for existing application with existing WSDL.
Since we already have an existing COBOL application for the Replenish Inventory function, we employ the
bottom-up-approach.
We execute the following steps to enable the Replenish Inventory function as a web service provider in CICS.
-
Step 1. Run CICS web services assistant DFHLS2WS passing it as input, our Replenish Inventory
function data structure (see Figure 1). This does the following:
-
-
Creates a WSDL for the replenish function
-
Creates a WSBIND file. The WSBIND file is used by CICS to:
-
-
Transform Simple Object Access Protocol (SOAP) messages to application data on input.
SOAP is the protocol that is used to communicate between the three actors in an SOA (Figure 2):
the service provider (Catalog Manager via CICS), the service requester (web services client), the
service broker. The service broker (also known as a service registry) makes the Web service access
and interface information available to any potential service requester. A service broker is not
being used in the Catalog Manger example.
-
Transform application data to SOAP messages on output.
Catalogue COMMAREA structure
03 CA-REQUEST-ID PIC X(6).
03 CA-RETURN-CODE PIC 9(2) DISPLAY.
03 CA-RESPONSE-MESSAGE PIC X(79).
Fields used in Replenish Inventory
03 CA-ORDER-REQUEST.
05 CA-USERID PIC X(8).
05 CA-CHARGE-DEPT PIC X(8).
05 CA-ITEM-REF-NUMBER PIC 9(4) DISPLAY.
05 CA-QUANTITY-REQ PIC 9(3) DISPLAY.
05 FILLER PIC X(888).
|
Figure 1: Replenish Inventory Function Data Structure

Figure 2: Service-Oriented Architecture (SOA) Components and Operations
The following example shows the input parameters passed to DFHLS2WS
for the Replenish Inventory function:
//LS2WS EXEC DFHLS2WS,
// JAVADIR='/usr/lpp/java/J1.4/',
// USSDIR='cicsts31',
// PATHPREF=''
//INPUT.SYSUT1 DD *
PDSLIB=//RUP4Z.SDFHSAMP
PGMNAME=DFH0XCMN
LANG=COBOL
PGMINT=COMMAREA
REQMEM=DFHRUP4Z
RESPMEM=DFHRUP4Z
LOGFILE=/u/rup4z/provider/wsbind/replenishInventory.log
WSBIND=/u/rup4z/provider/wsbind/replenishInventory.wsbind
WSDL=/u/rup4z/provider/wsdl/replenishInventory.wsdl
URI=exampleApp/replenishInventory
|
The input parameters have the following meaning:
-
-
PDSLIB The library containing the Replenish Inventory program that is exposed as a Webservice.
-
PGMNAME The name of the program for the CICS catalog manager example application DFH0XCMN.
-
LANG Specifies the language the program is written in (in this example,COBOL).
-
PGMINT Describes the program input. DFH0XCMN uses a COMMAREA.
-
REQMEN and RESPMEM Define the copybooks for request and response.
-
LOGFILE, WSBIND, and WSDL Specify the fully qualified HFS file names of the files to be generated.
-
URI Stands for the URIMAP that is used to map a Web services request to a Web service.
-
Step 2. Copy the generated WSBIND file to a UNIX directory on z/OS that will act as a web service
pickup directory for the PIPELINE (see next step). For our example, we define a pickup directory called
/u/rup4z/provider/wsdir.
-
Step 3. Define a service provider PIPELINE in CICS using the following CICS transaction:
-
CEDA DEFINE PIPELINE(RUP4ZPIP)
The output of this transaction is illustrated in Figure 3.
DEFINE PIPELINE(RUP4ZPIP)
OVERTYPE TO MODIFY CICS RELEASE = 0640
CEDA DEFine PIpeline( RUP4ZPIP )
PIpeline ==> RUP4ZPIP
Group ==> SOADEVWS
Description ==> RUP4Z PIPELINE for Catalog Manager Replenish web services
STatus ==> Enabled Enabled | Disabled
Configfile ==> /usr/lpp/cicsts/cicsts31/samples/pipelines/basicsoap11provider.xml
==>
==>
SHelf ==> /var/cicsts/
(Mixed Case)==>
==>
Wsdir :/u/rup4z/provider/wsdir
(Mixed Case):
:
|
Figure 3: PIPELINE Definition for Replenish Web Services Provider
A PIPELINE is a sequence of programs arranged so that the output from one program is used as input to the next.
There are pipelines that support service provider and pipelines that support service requesters.
In our example, we are creating a service provider PIPELINE which is a pipeline of user provided and system
provided programs that receives an inbound SOAP message, processes the contents and sends a response.
-
Step 4. Install the PIPELINE in CICS which will subsequently create the WEBSERVICE definition in
CICS:
CEDA INSTALL PIPELINE(RUP4ZPIP) GROUP(SOADEVWS)
-
Step 5. We check if the WEBSERVICE is installed. Note that the web service definition is required
to map the incoming SOAP body to the COMMAREA interface of the program.
CEMT INQUIRE WEBSERVICE
The replenishInventory web service definition is displayed in Figure 4.
-
INQUIRE WEBS
RESULT - OVERTYPE TO MODIFY
Webservice(replenishInventory)
Pipeline(RUP4ZPIP)
Validationst( Novalidation )
State(Inservice)
Urimap($309050)
Program(DFH0XCMN)
Pgminterface(Commarea)
Container()
Datestamp(20061102)
Timestamp(13:09:05)
Wsdlfile()
Wsbind(/u/rup4z/provider/wsdir/replenishInventory.wsbind)
Endpoint()
Binding(DFH0XCMNHTTPSoapBinding)
|
Figure 4: Catalog Manager replenishInventory webservice
-
Step 6. The URIMAP $309050 in the Figure 8-4 is created dynamically by CICS. It is used to map
incoming request to the associated web service and pipeline. CICS bases the definition on the URI specified in the
input to DFHLS2WS in step 1 and stored by DFHLS2WS in the WSBIND file. We list the contents of the URIMAP by
issuing the following command:
-
CEMT I URIMAP($309050)
The output in Figure 5 is displayed:
INQUIRE URIMAP($309050)
STATUS: RESULTS - OVERTYPE TO MODIFY
Uri($309050 ) Pip Ena Http
Host(* ) Path(/exampleApp/replenishInventory )
|
Figure 5: URIMAP for replenishInventory
Notice that the PATH attribute is set to the URI that will be found in the HTTP request issued by our web
client.
-
Step 7. We use WebSphere Developer for zSeries (WDz) to import our WSDL
/u/rup4z/provider/wsdl/replenishInventory/wsdl into our Software Development Platform (SDP).
-
-
Start up Websphere Developer for zSeries v6.
-
Create a new project as follows: File, New, Project, "My-WSDL"
-
Copy WSDL file to workstation: File, Import, FTP
-
Host=myzOS or 9.9.9.9
(CEMT I TCPIPS, then expand output to get your IP address)
-
Folder=/u/rup4z/provider/wsdl/
-
login=userlogon
-
password=userpass
-
finish
|
Figure 6: Importing our replenishInventory wsdl file
-
Step 8. We are ready to test our web services so we utilize the WSDL editor in WDz as follows:
-
-
In WDz, Right-click your WSDL file and select Open With WSDL Editor
-
In the WSDL editor click the graph tab
-
In the Services pane, expand services and port and select soap:address
-
Click the Properties tab to specify the web service end point
-

Figure 7: replenishInventory Web Services Endpoint
Notice that the web services address is as follows:
http;//host ip address:host port/URI for replenishInventory.
This URI corresponds to the URI path defined earlier in CICS for the replenishInventory web services provider.
-
Step 9. We now test the web service by doing the following:
-
Right-clicking on the WSDL file
-
Select Web Services Test with web Services Explorer
-
Right click on the DFH0XCMNOperation link
Web services explorer provides a form where you enter your request-specific data.
All values must be filled in according to the WSDL specification (See Figure 8).
-
Enter 01REPL for ca-request_id
-
Enter 0 for other fields
-
Click Go

Figure 8: Invoking the replenishInventory Web Service in WdZ
-
Step 10. The results of the replenishInventory request is displayed in the status panel as seen in
figure 9.

Figure 9: Response from replenishInventory Web Service Request
|