LAB 3 Creating CICS Services from COBOL (60 min)

Updated April, 30, 2009 (by Regi, Reviewed by Nagasaki, Zvi, Steve)
This lab will take you through the steps of using the Enterprise Service Tools (EST) feature of Rational Developer
for System z version 7.5 to transform an existing CICS COBOL program so that it can be accessed as a Web
service through the CICS Web Services facilities of CICS Transaction Server for z/OS V3.x.
The lab will guide you through the generation of the following:
1. Driver/converter program(s) and a WSBind file that can be deployed to a CICS Transaction Server for z/OS V3.x
system;
2. WSDL (Web Services Description Language) and XSD (XML Schema Definition) files that describe the CICS
based service.
The lab will illustrate the steps needed to build and deploy the programs and WSBind file to the CICS Transaction
Server for z/OS system. Also this lab will show you how you can use the Web Service Explorer tool to test the CICS
based service.

Enterprise Service Tools
The Enterprise Service Tools (EST) is a set of features that lets you transform COBOL and PL/I based business
programs and applications exposing them as Web services.

Enterprise Service Tools perspective
The Enterprise Service Tools perspective provides views and editors that allow you to develop service flow projects
and EST single-service projects (including Web services for CICS projects, SOAP for CICS projects, IMS SOAP
Gateway projects, and Batch, TSO, USS projects).
XML Services for the Enterprise
The XML Services for the Enterprise (XSE) tools is part of Enterprise Service Tools along with other tools like
Service Flow Features.
The XSE capability of Rational Developer provides tools that let you easily adapt COBOL-based applications so
that they can consume and produce XML messages. This adaptation is accomplished without modifying the
existing COBOL applications; and, more importantly, without modifying other applications that call the existing
COBOL application. A COBOL application must be able to processing XML messages to become a Web service,
since XML is the transport used to describe the Web service request and the parameters that are passed to the
existing application. XSE supports the creation of driver programs that work with existing CICS or IMS applications.
XSE consist of the following wizards:
The Create New Service Interface (bottom-up) wizard that generates a new web service interface for
and existing running program. Typically, this is called a "bottom-up" approach since the existing COBOL
application is at the "bottom" of the new web service creation process.
This Lab will cover this capability
The Create New Service Implementation (top-down) wizard that generates a new web service
implementation template for a CICS Web Service runtime. Typically, this is called a "top-down" approach
since the COBOL application is created "top-down" starting from the existing Web service definition
(typically, a WSDL file)
The XML to COBOL mapping wizard and tools that help map existing Web service interfaces or an XML
data definition to the existing COBOL program.
The Batch processor that allows you to generate the Web service interface in unattended ("batch") mode.
The Batch processor currently supports the "bottom-up" Web services creation with compiled XML
message conversion technology at runtime. The functionality provided by the Batch processor is equivalent
to that of the 'Create new service interface' (Bottom up) wizard for compiled XML conversion.
LAB 3 - Creating CICS Services from COBOL Page 1
This lab will focus on the bottom-up approach. In this scenario you generate a Web service description and runtime
specific XML message processing artifacts from a high level language data structure. This allows you to expose an
application program as a service provider.

WSBind Web service binding file used by CICS Transaction Server for z/OS V3.x to perform the mapping
between application data structures and XML based SOAP messages. This is generated when the Web Services
for CICS converter type is specified.

Web Services Description Language (WSDL) file XML based language for describing a Web Service and how
to access it.

(*) Web Services for CICS Driver Program - COBOL program that drives shows how the input and output
converters that interact with the existing COBOL application.
(*) CICS SOAP Inbound XML converter - COBOL program that takes an incoming XML document and maps it
into the corresponding COBOL data structure that the existing COBOL application expects.
(*) Outbound XML converter - COBOL program that takes the COBOL data results returned from the existing
COBOL application and maps them to an outbound XML document.
(*) Inbound XML schema definition (XSD) - XML schema that describes the incoming XML document for
processing by the input converter.
(*) Outbound XML schema definition (XSD) - XML schema that describes the outgoing XML document
produced by the output converter.


(*) Note that this asset is generated only if Compiled XML Conversion was chosen as the conversion type vs.
Interpretive XML Conversion. Same comment for the Inbound/Outbound XML converters and the
Inbound/Outbound XSD files.

CICS Web Services
Previous support for Web services in CICS Transaction Server for z/OS V2.2 and V2.3 was provided through the
SOAP for CICS feature. This support has now been fully integrated into CICS Transaction Server for z/OS V3.x.
With this new release of CICS, applications can now act in the role of both service provider and service requester,
where the services are defined using Web Services Description Language (WSDL). The infrastructure provided as
part of CICS TS V3.x includes a distributed transaction coordination capability compatible with the WS-Atomic
Transaction specification.

The support for Web services includes the CICS Web Services Assistant Integration, a batch utility which can help
you to

Transform an existing CICS application into a Web service
Enable a CICS application to use a Web service provided by an external provider.

The assistant can create a WSDL document from a simple language structure, or a language structure
from an existing WSDL document. It supports COBOL, C/C++, and PL/I. It also generates information
used to enable automatic runtime conversion of the SOAP messages to containers and COMMAREA,
and vice versa.

The XML Services for the Enterprise capability of Rational Developer for zSeries V7 extends and
complements this by providing conversion for COBOL types and constructs which are not covered
natively by CICS. For example, OCCURS DEPENDING ON and REDEFINES used in data description
entries are not supported by the CICS Web services assistant.


LAB 3 - Creating CICS Services from COBOL Page 3
LAB Instructions Start Here.. Overview of development tasks
This lab creates a CICS Web Service from an existing COBOL/CICS program (LAB3POT) that is invoked by
another one (LAB3CLI).



The COBOL program LAB3CLI sends a 3270 map and ask for a customer number. If the customer number is valid
it invokes another COBOL program named LAB3POT using EXEC CICS LINK via CICS COMMAREA.
LAB3POT receives the customer number, read a KSDS VSAM dataset and send back to the COMMAREA the data
retrieved (Name, last name and address). When LAB3CLI receives the control it display the data received back to
the 3270 screen.
Since the objective here is to learn CICS web services we made this example quite simple, using VSAM, instead of
DB2 to simplify the deployment of the generated artifacts.

The idea is to create a WSDL and use the Web Services Explorer tool that will invoke the Server using CICS web
services as shown below without making any change in the existing server program.

The main tasks that you will perform are:
1. Get familiar with the programs and run them using the 3270 terminal

2. Create a Web Services for CICS Project and import the program to be used.

3. Generate the converter driver, input and output converters, XML schemas, WSDL, and CICS
required file (WSBind)

4. Using Rational Ddeveloper for System z to test the CICS-based Web service.

5. Optional: Deploy the generated COBOL to CICS Transaction Server for z/OS

6. Optional: How the CICS Web Services was configured on z/OS
7. Optional: Regenerate the Web services created
8. Optional Using Web 2.0 to invoke the CICS Web Services created

Optional:
Regenerate
the Web
Service

Each time you see this symbol it means that you have to do something on your
computer not merely read the document.

Tips!
1) If you want to have the lab in HTML format displayed in your browser, you can find it at
the location: C:\RDZ_POT_V7\HTML
Then you can CUT/PASTE the names and the code, using the Browser.

2) Most of the labs will be performed under VMware. So we will run 2 Windows on the
same machine. This will cause some overhead and sometimes the performance will not be
as good as if the program would be running in the native windows So, please be patient

3) If you lost the VMware full screen either type Ctrl + Alt + Enter or use the VMware
icon (on top).
Section 1 Get familiar with the programs and run it using the 3270 terminal

You will be starting a CICS emulation, execute the existing program to be sure that system is running well and
become familiar with the program that you will apply a transformation.
We will also create here an EST project to be used later and to emulate the 3270 screen.

___ 1.1 Emulating a CICS 3270 terminal with Rational Developer for System z.
This section assumes that you had finished the LAB #2 and have a connection to the z/OS system. If this is not the
case contact the instructor, he will show you how to create a z/OS connection.
1.1.1 Start Rational Developer for System z (RDz):
Start Programs IBM Software Development Platform RDz 7.5 + EGL 7.5.1 + HATS 7.5 IBM Rational
Developer for System z IBM Rational Developer for System z 7.5
or click on the icon in the windows quick launch:
Type or select C:\Workspaces7.5\RDz and click OK.

Important!
Be sure that you are using the right workspace. This Lab uses C:\Workspaces7.5\RDz as
your work workspace.



LAB 3 - Creating CICS Services from COBOL Page 5
1.1.2 Using the z/OS Projects perspective and Remote Systems view, right click on dallas and select Host
Connection Emulator.




1.1.3 Since you will need more space, double-click on the dallas.hce title. Later, to return the screen to its
original size, double-click again on the dallas.hce title.

1.1.4 To connect to our CICS Region, type logon applid(cicsrdz) and press Ctrl key


Problems connecting to CICS Region?
This CICS Region was created specially for this Lab and you will use the port number 9046
(or 9036). If you have problems connecting to CICS, it could be because the CICS region is
not started. Contact the instructor.
This Lab might work using the application CICSA that is listed in the black screen above, but
in this case the port number to be used would be 3091 instead of 9046/9036, but everything
else would be the same. If you will use CICSA, please also inform the instructor.

1.1.5 Signon with your provided userid and password:



1.1.6 Be sure that the region that you are connected is RDZPOT and press Esc Key (Clear)
You are now connected to CICS.



___ 1.2 Run CICS transaction LAB3
You should be now on the z/OS CICS named RDZPOT.
1.2.1 Type the CICS transaction LAB3 and press Ctrl key.


1.2.2 Type 004 and press Enter . Try to remember these results since you will compare later with the execution
via a CICS Web Service. You can try any valid customer number (any number from 001 to 010).

LAB 3 - Creating CICS Services from COBOL Page 7
The LABCLI program sends the BMS map and accepts the Customer number. If a valid customer is entered, it
executes an EXEC CICS LINK to the LAB3POT program that reads a VSAM data set and sends the results back
via the COMMAREA.
The LABCLI program receives the control, get the results from the COMMAREA and send it back to the map.
Later you will use the LAB3POT program to create a CICS Services that will invoke it.

1.2.3 Type 999 to end this dialog. A message below is sent:



1.2.4 Close the terminal emulation using CTRL + F4



What have you done so far?

You emulated a 3270 terminal using Rational Developer for System z.
You also executed the transaction LAB3 that executed the programs LAB3CLI and
LAB3POT.
The objective here was to be sure that the LAB3POT program to be used soon is working
fine and returning a correct data from a VSAM file.
Now you are ready to import the program LAB3POT to your workspace since this program
is the one that you will invoke via CICS Web Services.


Section 2 Create a Web Service for CICS Project

You will now create a Web Service for CICS project and import the COBOL program LAB3POT and its required
copybooks to this project.
Note that this could be done directly from the z/OS system if you were connected to the z/OS.
LAB3POT is the CICS COBOL program that you had tested before. This program is on your workstation but also at
your dataset <HLQ>.POT.COBOL.
You need to use the Enterprise Service Tools perspective.

2.1 Select Window Open Perspective Other:




2.2 Select Enterprise Service Tools and click OK.



2.3 If is the first time that this workspace is used the Welcome Page should open. (note that this is not your case).
If the welcome page is not opened, right click the blank area of the EST Project Explorer view and select Open
Welcome Page.
From here you can start learning the Enterprise Service Tools. There are links for demos and tutorials.



2.4 Close the Welcome window (Ctrl + F4).

LAB 3 - Creating CICS Services from COBOL Page 9
2.5 To create a CICS Web services Project:
Select File New Web Services for CICS Project



2.6 Type LAB3_CICS_Services as the project name accept the defaults as seen below and click Next
Note that as you will start from the COBOL to create the Web Services, this is called a bottom-up operation.
Also since we want that the parsing will be done by our COBOL generated code and not by CICS you will need to
specify a Conversion type of Compiled XML Conversion.



2.7 You will need to import the COBOL program LAB3POT that you will want to use in the web services dialog.
Click on File System since your file is on your workstation.



2.8 Be sure that *.cbl is specified in the Files of type: field:
Navigate to C:\RDZ_POT_V7\LAB3, select LAB3POT.cbl and click Open:




2.9 Verify that the program to be imported is correct and click Finish :


2.10 You still need to import 2 copybooks that are part of this code
Right-click on LAB3_CICS_Services and select Import Source Files


LAB 3 - Creating CICS Services from COBOL Page 11
2.11 Click on File System



2.12 Using the Ctrl key, select COMAREA.cpy and POTVSAM.cpy and click Open




2.13 Verify that the copybooks to be imported are correct and click Finish



2.14 The code imported should be the as shown below:



How do I find the required COPYBOOKS used in the COBOL code?
If you import your code from the z/OS (remote), Rational Developer for System z will let
you know which are the required copybooks to be used using the check dependencies
capability..

Can I use just the DFHCOMMAREA copy book instead of the whole program? Yes,
you can use only data structures. But the copybook (*.cpy) is expected to have the whole
structure that would include the 01 level (or 77 levels).
You do not need to have the whole program and the wizard can accept only the data
structure that has the DFHCOMMAREA (or container).
But if you decide to use a program, then it must be complete will all copybooks..
For this lab we decided to have the complete program so you can understand it, if you
want, and in this case we will need all the required copybooks, otherwise the wizard will
flag the compile errors.
You also can change More COBOL Options on Window Preferences Importer
COBOL if you need other extensions in addition to *.cpy for the data structure.

2.15 Note that we have imported the COBOL program LAB3POT and two copybooks. This is the program that is
invoked by the client COBOL and that retrieves the data from the VSAM file.
Double click on the program LAB3POT and spend a few minutes to understand this program:



2.16 Close the editor (Ctrl + F4).

What have you done so far?
You have tested the programs LAB3CLI and LAB3POT using 3270 CICS Terminal
emulation, created a project to hold the Web Services components and imported the
LAB3POT and its components to this project.
Now you are ready to start the Web Services wizards that will generate the necessary
components to create the CICS Web Services.

Section 3 Generate the converter driver, input and output converters, XML
schemas, WSDL, and CICS required file (WSBind)
You will invoke the Rational Developer for System z wizards that will generate the COBOL driver and converter
programs, the WSDL file, the CICS WSBind file, and the XML schemas.
Also you will see the new wizard capability which allows you to keep the dialog information in the project. This is
very useful in case you need to re-execute this activity.

LAB 3 - Creating CICS Services from COBOL Page 13
3.1 Right-click on the LAB3_CICS_Services project and select Generate Web Services for CICS resources

3.2 Select the COBOL code and click OK

This will launch the Web Service Runtime and Scenario Selection dialog allowing you to specify the necessary
options to start the web service wizard.
3.3 On the Language structures dialog expand DFHCOMMAREA by clicking the + sign beside it and select
CustNo as the only element that will form the data structure for the inbound XML converter.

3.4 Select the Response Language Structure tab. Click on the checkbox next to DFHCOMMAREA to select
all the data items as the data structure for the outbound XML converter. and click Next>.

3.5 On the Generation Options page, make sure the XML Converter tab is selected.
Type LAB3xx as the Converter program name prefix (instead of LAB3POT). Where xx is your z/OS userid
suffix. For example: if you are EMPOT24 use LAB324. If you are EMPOT05 use LAB305, etc..
Do NOT press any button; you still have to do more specifications

Note that we specified 4.1 as Compiler level. and the COBOL compiler option XMLPARSE (COMPAT). If the compiler is not at
4.1 level (that is our case, we are using version 3.4) this option will be discarded at compiler time and you will have a return
code 8. You will see that in section 5.
But if you specify Compiler level 3.4 there is no possibility to specify XMLPARSE options. We decided to use 4.1 to show the
warning at compiler level, but in the real world it is better to use the correct compiler level.
LAB 3 - Creating CICS Services from COBOL Page 15
3.6 Click on WSDL and XSD tab and specify the following as the endpoint URI:

http://zserveros.demos.ibm.com:9046/wdz/LAB3POT
(You can copy/paste from the file located at C: \ RDz_POT_V7\ LAB3\ Lab3_CI CS_Ser vi ces_URI . t xt )


Important!

Due to Firewall issues you may need to use port number 9036 instead of 9046.
The port number 9046 could be closed and you may have errors during the
execution.
Please contact the instructor for details.


This will be the TCP/IP address that is used to reach the target CICS system where the conversion program
(LAB3XXD) is deployed. The transport used is HTTP. The local URI portion ( /wdz/LAB3POT) was be used to
create the URIMAP on CICS for matching URI requests. The port number used for CICS Web Services is
9046.
Type DFHCOMMAREA (two Ms) in Root element name (two places) instead of RequestMessage and
ResponseMessage. The reason you MUST do that is that the COBOL Driver was deployed with WDz 7.0 and
we want to reuse it here. Normally you would not do this and may keep the default names.



Note: If you are using CICSA instead of our RDZPOT region the port to be used here would be 3091 instead of
9046.
3.7 Click on tab Advanced Options , clear Generate qualified elements in XML Schemas., and click
Next.
Normally you dont need to worry about this choice, but we will invoke a CICS Web service deployed with WDz
version 7 that did not have this capability.


3.8 On the Web Services for CICS page, using the Basic Options tab and accept the default WSBind file
name of LAB3POT and COMMAREA as the program interface and click Next.

LAB 3 - Creating CICS Services from COBOL Page 17

Can I use CHANNEL instead of COMMAREA to avoid the 32K limit?
CICS 3.x allows the usage of channel (container) that solves the famous32K limit.
The program interface can use either the COMMAREA or the new CHANNEL support in
CICS 3.x. If the CICS application program communicates via a CHANNEL, you must
specify the container name.
3.9 On the File, data set, or member selection page, under XML Converters tab make sure the LAB3xxD is
specified as the Converter driver file name. For Example if your logon id is EMPOT05 the converter driver should
be LAB305D. If not you must go back and select as shown in the step 3.5 above..
Also make sure the check box to Generate all to driver is checked. This generates all the components to the
same file.


3.10 Select the WSDL and XSD tab. No changes also are required here
Note the names of the WSDL and XSD (schemas) that that will be generated:

3.11 Click Next and note that the CICS code could be automatically deployed
Click Finish to complete the generation of the conversion program (converter driver, input and output
converters), WSBind, XSD, and WSDL files

3.12 After the Web Services Enablement wizard completes its generation, you should see several additional
artifacts in the LAB3_CICS_Services Project under the folder Generation:
a.. The *.xml files are properties that will be used in the next wizard generation run.
b. LAB3XX.wsdl - the WSDL file that describes this CICS based Web service
c. LAB3XXD.cbl - the conversion program which is made up of the converter driver, input and output converters.
d. LAB3XXI.xsd and LAB3XXO.xsd - the XML Schema Definition files that describe that input and output XML
documents respectively.
e. The *.log file that is the generation log
f. LAB3POT.wsbind - the WSBind file that tells CICS how conversion is to be performed and what the URI map
looks like.

3.13 Double-click on LAB3xxD.cbl and use the z/OS LPEX Editor to explore the code to understand the
productivity you gained from not having to develop the message converter manually.
Note that LAB3XXD.cbl file is in fact made of multiple programs. The main program calls the various subroutines.
All will be deployed as a simple load module named LAB3XXD.

LAB 3 - Creating CICS Services from COBOL Page 19
3.14. Remember that since we want to pass as input just the customer number, we need to do the compiled XML
conversion type instead of the interpreted XML conversion type.
When we specify the compiled conversion type, the XML parsing will be done by the COBOL converter program
instead by CICS.
Type Ctrl + F and click Next to find the command XML Parse. This is an example of the parsing being done by
the converter.
Note also that the converter driver for CICS Web Services is different from the driver for SOAP for CICS Version
2.2, specifically regarding its interaction with the original existing application program. The SOAP for CICS driver
contains an EXEC CICS LINK to the original existing application program. The CICS Web Services driver has no
call at all to that program. This is because CICS Web Services is responsible for calling that application program.
If you do a search for EXEC CICS LINK you will not find any instances.




Compiled versus Interpretive XML conversion
There are two conversion type choices available for this scenario and runtime
combination. Either Compiled XML Conversion or Interpretive XML Conversion may be
selected from the Web Service Runtime and Scenario Selection dialog. The choice of
conversion type involves considering the benefits and cost of either technology.
Compiled XML Conversion
A driver program interacts with the runtime and invokes bundled programs to provide
conversion of XML to and from language structures. The compiled XML conversion type
provides more extensive support for language structure data types and constructs than the
interpretive XML conversion type, however compilation of XML Converters is required and
there are more artifacts to manage.

Interpretive XML Conversion
XML conversion is accomplished using generated metadata and an XML conversion
component built into the runtime. While the Interpretive XML Conversion type has limited
support for language structure data types and constructs, it requires fewer artifacts and
does not involve compilation of XML converters.



3.15 Press Esc key and then Close the editor (Ctrl + F4).
3.16 Verify the WSDL that was generated
Double-click on LAB3XXD.wsdl and use the WSDL Editor to visualize the input and output messages.

3.17 Scroll right and move the mouse to the first blue arrow as shown below and wait until you see the input
message.. The name MUST be DFHCOMMAREA and it shows just CustNo as input message
3.18 When you finish exploring the WSDL, close this editor (CTRL + F4).

3.19 25. Right click on LAB3POT.wsbind and select Open with WSBind Editor.
Rational Developer for System z version 7.5 has added the capability to visualize as well as update the binary
contents of the WSBind file. Note the Service Interface and Pipeline properties as well as the Target Server
program to be invoked (LAB3POT) using COMMAREA.

LAB 3 - Creating CICS Services from COBOL Page 21
3.20 Close the files being edited with CTRL + Shift + F4

What have you done so far?

You used CICS to test the programs LAB3CLI and LAB3POT.
You created a project to hold the Web Services components, imported the LAB3POT
program and generated the necessary components that will create the CICS Web Services

Now you would be ready to deploy the CICS Web Services that has been already done for
you. This is a CICS administrator activity and needs special authorizations.
On next section you will test the web services created using the generated WSDL.

Section 4 Using Rational Developer for System z to test the CICS-based
Web service.
Now you are ready to invoke the Web Service created on CICS. You will use the WSDL generated and invoke the
CICS Services using Rational Developer for System z.
4.1 Using the Enterprise Service Tools perspective and the EST Project Explorer view, right-click on
LAB3xx.wsdl under the project LAB3_CICS-Services and select Web Services Test with Web Services
Explorer


4.2 Be patient (you are under VMware). After a while, the Web Services Explorer will be launched in a Web
Browser view.
Resize the view to see all areas of the Web Services Explorer. Or you just double-click on the Web
Services Explorer title to display full screen.


4.3 Click on the link for the LAB3xxOperation operation within the Actions section, (alternatively, you can click
on the + sign beside LAB3XXBinding and expand the view to display the LAB3XXOperation



4.4 Be sure that this view is maximized


4.5 Notice that the Actions section is now replaced with information about the LAB3XXOperation operation and the
parameters it takes. It also lists the endpoint associated with this request.
Type 4 for CustNo and click Go to invoke the operation.


LAB 3 - Creating CICS Services from COBOL Page 23
4.6 Resize the Status section and you should see results as below.
Click on Source to see the SOAP Envelopes


4.7 Resize again and you will see the XML SOAP envelopes with the input and output messages :


4.8 You can test with customer numbers from 1 to 10. After you are done testing, close the web browser using
(Ctrl + Shift + F4).
4.9 Reset the Enterprise Service Perspective: Window Reset perspective

What have you done so far?

You have executed the transaction LAB3 and run the programs LAB3CLI and LAB3POT.
You have generated the COBOL converter and the necessary CICS resources to invoke
LAB3POT as CICS Web Services.
You have tested the web Service created.

4.10 Use Ctrl + Shift + F4 to close all opened perspectives.

Section 5 Optional: Deploy the generated assets to CICS

This step is optional since the code has been already deployed for you, but if still have time do it since it shows how
to deploy COBOL/CICS components generated using Rational developer for system z.
If you are more interested on the CICS configurations, jump to the section 6.

This section assumes that you had finished the LAB #2 and has a connection to the z/OS system. If this is not the
case contact the instructor, he will show you how to create a z/OS connection.
We will explain in this section all the necessary steps to have the CICS Web services deployed. In section 6 we
show you how CICS must be configured to support those assets.
We will connect to z/OS, generate the J CL to created the COBOL converter, and create the z/OS components
required to execute the CICS Web Service.
___ 5.1 Connect to z/OS

You will use your assigned userid and password to logon to the z/OS where you will deploy the CICS Web
Services.

5.1.1 Open the z/OS Projects perspective if you are not already there :
Select Window Open Perspective Other .. (or just click in z/OS Projects perspective to switch to it if
this perspective is already in the workspace)


5.1.2 Select z/OS Projects and click OK.


LAB 3 - Creating CICS Services from COBOL Page 25
5.1.3 To Connect to the z/OS system (assuming you have completed LAB 2):
Right-click on dallas and select Connect:


5.1.4 You will be are prompted for your z/OS userid and password.
Type the assigned userid and password. In the figure shown below we used EMPOT24, but your userid will
be another one. The password can be any case, dont worry about having it in UPPER case.
Please BE SURE that you are using the right ID and password that were assigned for you.
Click OK to connect to MVS Files subsystem.

5.1.5 Since our connection is not secured, a message will prompt. Click Yes to continue.
5.1.6 Depending when you are doing this lab it may be possible that our z/OS system is using a previous
version of RSE (Remote System Explorer). If that is the case a message will be displayed. Click OK.
5.1.7 If you successfully connect to the remote system, the dallas icon changes to
Expand dallas, MVS Files and My Data Sets


___ 5.2 Move the Web services Generated assets to the z/OS
You will move the generated assets in section 3 to z/OS
5.2.1 We can make the view used in the Enterprise Services Perspective be part of the z/OS Projects perspective:
Click on Window Show View Other


5.2.2 Type EST select EST project Explorer and click OK . This is the view that show the assets created
before.


5.2.3 The view is displayed in the bottom. If necessary expand the nodes so you can see under Targets folder
the assets that must be moved to z/OS

LAB 3 - Creating CICS Services from COBOL Page 27
5.2.4 The assets LAB3POT.wsbind and LAB3xxD.cbl should be copied to the z/OS system.
The WSBind file was already copied to the HFS directory where the PIPELINE scan will look for.
Due to time constraints and authorization issues, you will move just the COBOL program to z/OS.
The WSBind file will not be moved and we have already created a LAB3POT.wsbind at
/u/dnet045/wdzv7pot/wspickup/provider/

Care to transfer WSBind to z/OS
The WSBind file is an EBCDIC binary file, it needs to be transmitted as binary to the target
z/OS system. You can use the Remote System Explorer facilities of Rational Developer
for System z copying this to a HFS directory on the target z/OS system. CICS will then
use this file during its Pipeline and Web Service generation process.
In order to move the WSBind file to z/OS, we need to make sure that file extensions of
wsbind are handled as binary files. You can check this using the preferences dialog
(Window>Preferences>Remote Systems>Files) note that the file type of *.wsbind has as
a default the Binary File transfer Mode. You do not need to make any change on this.
5.2.5 The COBOL program LAB3xxD.cbl must be copied to the PDS EMPOTxx.POT.COBOL
Using the EST Project Explorer view drag and drop LAB3xxD.cbl into EMPOTxx.POT.COBOL as seen below
(you could also do Copy/Paste).:



5.2.6 The COBOL program LAB3XXD.cbl will be copied to z/OS:

___ 5.3 Create a new MVS Sub-Project under POTCOB project
As we have already seen in LAB 2, it is much more convenient to create a z/OS project and move to a
Subproject the assets that we are working on. This makes the task simpler because we have all assets that are
being used, grouped in the same location.i
First you must import a property Group to the dallas connection.
5.3.1 Using the Property Group Manager view, right click on dallas import ,


5.3.2 Using the Browse button, navigate to C:\RDZ_POT_V7\LAB3\LAB3_Property_Group.xml and
select LAB3_Remote_COBOL_CICS and click OK

The Property group to be used by COBOL with CICS will be loaded into your workspace

5.3.3 Using the z/OS Projects view (on the left), right click on POTCOB and select New MVS
Subproject

LAB 3 - Creating CICS Services from COBOL Page 29
5.3.4 Type LAB3 as Subproject name, select LAB3_Remote_COBOL property group and click Finish.


5.3.5 Expand LAB3 and you see that this Subproject has no content yet. You need to add to this
subproject the required assets that you will work with (in this case just one program). Also probably you will have
either COBOL or PL/I subprojects already there, but not both as shown in the picture below.



___ 5.4 Add resources to the MVS Subproject
To make the LAB3xxD COBOL program available to your remote Subproject, you will need to add it.
5.4.1 Using the Remote Systems view (on your right). If necessary, expand the MVS Files , and My Data
Sets under dallas until you see the LAB3xxD program that you have moved to <HLQ>.POT.COBOL.
Right click on LAB3XXD.cbl , and select Add To Subproject



5.4.2 On the Add Resources panel, select POTCOB and LAB3 from the drop down list and click the Finish to
add the datasets to the project (Note that you could just drag and drop the asset to add it on the project.)


5.4.3 .Using the z/OS Projects view expand LAB3 and you will you will see that
<HLQ>.POT.COBOL(LAB3xxD).cbl is now defined to the LAB3 Subproject.
Click on <HLQ>.POT.COBOL(LAB3xxD).cbl and you will see in the Property View (will need to scroll
down) which Property Group will be used by this program.
Later when you generate J CL for this member all definitions will be used from the property group assigned.

LAB 3 - Creating CICS Services from COBOL Page 31
___ 5.5 Generate JCL to compile and Link the program LAB3xxD

5.5.1 Right click on <HLQ>.POT.COBOL(LAB3XXD).cbl and select Generate JCL For Compile Link,
.



5.5.2 Click OK. This is where the J CL will be generated and the member name. You should have other
values here.



5.5.3 Click OK for the massage that informs that the J CL has been generated.
5.5.4 The J CL for Compile and Link the COBOL with CICS program is generated.
Double click on <HLQ>.POT.JCL(LAB3xxD).jcl to edit it verify the J CL..



Note that the dataset names, etc.., where taken from the values defined for you in the property group. If you want
to see it you can right click the COBOL code (*.cbl) and select Properties Property Group. Edit
5.5.5 Scroll down and verify that the load module will be created on your data set, not in the CICS loadlib.
You have no authorization to add this on our CICS, but in the real world this load module should be created into a
library that CICS will see it.

5.5.6 Type submit in the command line and press enter to submit this job for compile and link.

5.5.7 A J ob Id will inform that this job has been submitted:


___ 5.6 Verify the job execution.
5.6.1 Use the JES on the Remote Systems view to see the output
Right click on My Jobs and select Refresh
Double-click on the job that you had submitted. The steps COBOL and LKED must have return code of 08
and 00 respectively. Note that there is multiple compiles on this job Ignore the return code 08 it is regarding a
compile option XMLPARSE(COMPAT) that does not apply for the compiler version 3.4 (see step 3.5 above for
details).

LAB 3 - Creating CICS Services from COBOL Page 33
Note that your load module program has been created in the library <HLQ>.POT.LOAD on the z/OS. This library
is NOT available to our CICS Region but when you tested the web service before you used a COBOL code
exactly the same as this one. The only difference is that we had added our code in a loadlib that is used by our
CICS.

5.6.2 Use Ctrl + Shift+ F4 to close all opened editors.
5.6.3 Using Remote Systems view, right click on your job select Purge to eliminate this job listing:



If you have authorization for (RACF authorization) the job is purged.

5.6.4 Disconnect from the z/OS system. Right click on LAB3 and select disconnect. You dont need to be
connected anymore for the other tests.




What have you done in this section?
You connected to z/OS, moved the COBOL generated program to z/OS, compiled and
linked it. The WSDBIND file was not moved due time/security reasons and is already
there. .You are ready to test the CICS Web Service.


___ 5.7 Install or rescan the PIPELINE referencing the pickup directory.
The PIPELINE resource contains a reference to a pickup directory. As noted above, we already copied the
LAB3POT.wsbind file to /u/xxxxx/wdzv7pot/wspickup/provider/ directory. When you install the
pipeline or perform a scan, CICS will read the WSBind files in that pickup directory and automatically define
WEBSERVICE and URIMAP resources associated with those WSBind files.

5.7.1 See one example below Note that LAB3POT.wsbind is in the directory below. You have no access to
this directory. This is just one example. On your shop you will need to move this file to a directory like this one.



Why we need to do the PIPELINE SCAN?

When you install each PIPELINE resource, CICS scans the directory specified in the
PIPELINE's WSDIR attribute (the pickup directory). For each Web service binding file in
the directory, which is for each file with the .wsbind suffix, CICS installs a WEBSERVICE
and a URIMAP if one does not already exist. Existing resources are replaced if the
information in the binding file is newer than the existing resources
If we copied a new WSBind file to the pickup directory a PIPELINE SCAN is required.
The PERFORM PIPELINE SCAN command initiates the scan of the PIPELINE's pickup
directory.
5.7.2 Using the z/OS Projects perspective and Remote Systems view, right click on dallas and select Host
Connection Emulator.



LAB 3 - Creating CICS Services from COBOL Page 35
5.7.3 Since you will need more space, double-click on the dallas.hce title. Later, to return the screen to its
original size, double-click again on the dallas.hce title.


5.7.4 To connect to our CICS Region, type logon applid(cicsrdz) and press Ctrl key

Signon with your provided userid and password:



5.7.5 Be sure that the region that you are connected is RDZPOT and press Esc Key (Clear)
You are now connected to CICS.


5.7.7 To do the Pipeline scan:
Type CEMT PERFORM PIPELINE(PIPEWDZ) SCAN and press the enter key.
If you were authorized to use this command you would receive a RESPONSE: NORMAL as seen below
in the bottom:
But since we implemented security in our CICS in cannot issue this command.
5.7.8 To verify all is working fine, it is a good idea to inspect the CICS PIPELINE, the WEBSERVICE and
URIMAP resources defined to CICS.
Press F3 to end the CEMT. and ESC to Clear the screen
To inspect the CICS WEBSERVICE definition, type CEMT INQ WEBSERVICE and press the enter key.

5.7.9 Scroll thru the defined WEBSERVICE definitions (press PF8 or PF7 ) looking for the Web Service
that we created for our LAB3POT program. Here is the summary view.
5.7.10 Move the cursor to the LAB3POT WEBSERVICE definition and press enter to see the details.
After the pipeline is installed or rescanned, it will automatically install the WEBSERVICE and URIMAP
resources that are associated with a WSBind file. The following example shows a WEBSERVICE resource
associated with a LAB3POT wsbind file. It shows that this is related to program LAB3POT (the existing
application) and an auto generated URIMAP ($241490).

LAB 3 - Creating CICS Services from COBOL Page 37
5.7.11 And lastly, taking the Urimap name, lets inspect the URI for the LAB3POT.
Press F3 to end the CEMT. and ESC to Clear the screen
Type CEMT INQ URIMAP($849090) and press the enter key. (Can just use URI). Note that this value (for
URIMAP) may be different; check the results of the previous commands.



5.7.12 Move the mouse under URI($241490) and press the enter key.
The following shows the definition for the auto generated URIMAP, $241490. It shows a path of /wdz/LAB3POT,
which was taken from the WSBind file. When a request comes into CICS with a local URI of /wdz/LAB3POT, this
URIMAP definition will match and the request will then be associated with WEBSERVICE LAB3POT, which has a
reference to the WSBind file.
The WSBind file contains the name of the conversion program that will be invoked by CICS Web Services.



5.7.13 Press PF3 to end your CEMT session and ESC to Clear the screen
Do not close the 3270 emulation as you will need it in the next section.

Note that some trivial CICS tasks that have been around for decades were not discussed here, even they still
should be done.
For example, making the converter driver program available by adding it to a library that is part of the DFHRPL
concatenation. In addition, a CICS PROGRAM resource must be defined if program auto-install is not enabled for
the target CICS system.



What have you done so far?

You have tested the programs LAB3CLI and LAB3POT, imported the LAB3POT program,
generated and tested the CICS Web Service created using Rational Developer for
System z.

Also you deployed the COBOL converter and verified the necessary CICS resources to
invoke LAB3POT as a CICS Web Service.

If you want to see how the configurations were done for CICS, see the next section.


Section 6 Optional: How CICS Web Services was configured on z/OS
This section is optional and dedicated to developers interested on the steps required to configure the CICS Web
Services. If you are not interested on those details, skip to the Section 7 to perform another optional section or
take a cup of coffee if you have seen enough Congratulations !

This Section will show the steps to configure CICS for Web services and is dedicated to CICS experts. It will show
you how to make a PIPELINE resource definition, and a TCPIPService definition. The intent is to show how this
was done. You will NOT perform any configuration here, since all has been done for you.

Note that definitions that we show here are NOT the same that were created for this PoT, but assuming that the
<HLQ>dataset name is DNET045.
___ 6.1 How to create the HFS Directories required by CICS Services


Important!
DO NOT DEFINE ANY CICS RESOURCE unless it is stated that you have to do it. The
information here is just for you to understand what must be done by the CICS administrator.
Remember ... Only when you see the symbol it mean that you have to do something
on your computer not merely read the document

To expose a CICS program as a Web service over HTTP, TCPIPService and PIPELINE resources are required.
The PIPELINE resource definition points to some Hierarchical File System (HFS) directories and also points to a
pipeline configuration file.
The setup requires configuring files and directories in the Hierarchical File System (HFS). You do not have to do
this at this lab, we will show here one example using DNET045 as dataset HLQ. In this example we created these
directories in the HSF directory : /u/DNET045/wdzv7pot/wspickup/provider

The provider directory will be used by CICS to store the Web service binding files that are associated with
WEBService resources. Each WEBSERVICE resource is associated with a PIPELINE. The provider directory is
managed by CICS together with the PIPELINE resource.

Several PIPELINEs can use the same provider directory because CICS ensures a unique directory structure
beneath this directory for each PIPELINE. Since CICS writes to this directory, CICS requires appropriate security
permissions for. /u/DNET045/wdzv7pot/wspickup/provider/
The pickup directory contains the Web service binding files that are to be associated with the PIPELINE.
When a PIPELINE is installed, or in response to a PERFORM PIPELINE SCAN command, CICS searches this
directory for files ending in .wsbind.
For each .wsbind file, CICS dynamically creates a WEBSERVICE and URIMAP resource, associates them with the
PIPELINE and installs them ready for use.
LAB 3 - Creating CICS Services from COBOL Page 39
Users could use an Rational Developer for System z USS shell to create those HFS directories.. Below is one
example creating the provider directory. (for your information Only - DONT try to do that since you not have the
authorizations required)


___ 6.2 How to create a PIPELINE Resource Definition

A PIPELINE resource definition contains a reference to a shelf directory, a pickup directory, and a pipeline
configuration file. The configuration file is in XML format and details the message handlers that will act on Web
service requests and responses as they pass through the pipeline. We are going to use the CICS supplied
PIPELINE configuration file for a SOAP V1.1 handler.
To define the PIPELINE we had used the CEDA transaction as below. Note that the HFS directories are case
sensitive:



Below is the content of the provided CICS Web Service Configuration file named cicsProvider.xml:


DFHPITP is a CICS supplied program that
- Locates the WSBind file associated with the Web service using this pipeline
- Performs the XML to COMMAREA (or Container) conversion specified in the WSBind file
- Invokes the user application program specified in the WSBind file
- Performs COMMAREA(or Container) to XML conversion
___ 6.3 How to create a TCPIPService Resource Definition
As the client connects to your Web services over an HTTP transport CICS must define a TCPIPSERVICE to
receive the inbound HTTP traffic. Usually the CICS Systems Programmer has to define the PIPELINE and this
entry here named TCPIPService, when using this CICS Services mechanism.
Below is one example of the TCPIP Service creation:



___ 6.4 How to install the CICS GROUP
As with any other resources defined, the PIPELINE and the TCPIPSERVICE must be installed in order to work.
This has been done already for you and below is one example how to do it.






LAB 3 - Creating CICS Services from COBOL Page 41
___ 6.5 How to query CICS to find if PIPELINE and TCPIPSRVICE are installed
This section will allow you to check the CICS resources that have been defined for you and if you want you can do
it here.

6.5.1 Using the Host Connection Emulator you can check the PIPELINE definition.
Type CEMT INQ PIPELINE and press the enter key (Ctrl key).





What is a CICS PIPELINE?

A PIPELINE is CICS resource that is used when a CICS application is in the role of a Web
service provider or requester. It provides information about the message handler
programs that act on a service request and on the response. Typically, a single PIPELINE
definition can be used by many applications.
You can ask CICS Web Services to validate the WSDL that is used by specifying the HFS
path on the target z/OS system where the WSDL file is located. This is usually done
during testing or debugging and is not recommended for production.

6.5.2 The results should be something similar as shown below





6.5.3 Move your cursor to the PIPEWDZ pipeline (Pip PIPEWDZ) and press enter to obtain the pipeline
details

The following is the PIPELINE (PIPEWDZ) that was used to install the Web service. Notice the pickup directory
/u/rdzpot/wdzv7pot/wspickup/provider/ which is where the WSBind file generated by Rational Developer for
System z wizard must be copied to later on, in order to implement the Web Service.



6.5.4 You can check the TCPIPSERVICE definition.
Press F3 and and ESC key to clear the screen and type CEMT INQ TCPIPSERVICE and press the enter key.


LAB 3 - Creating CICS Services from COBOL Page 43


What is the TCPIPSERVICE CICS resource?

This resource tells CICS to listen on a specified TCPIP port and accept HTML.


6.5.5 Note that there is only one TCPIPSERVICE opened for each port. Since in this example we used the
port 9036 our TCPIPSERVICE will be SOAPPORT . Moving the cursor under SOAPPORT and pressing enter we
will have the details below:
Note that in our lab we may use other TCPIPSERVICE other than this one.

.
6.5.6 Close the terminal emulation using CTRL +Shift + F4.

6.5.7 Select Window Reset Perspective. Click OK to have the default perspective .


What have you done so far?

You have tested the programs LAB3CLI and LAB3POT, and generated the necessary
components that will create the CICS Web Services.
Even though you did not do any configuration in this section you have seen how this was
done for you.
You are now ready to deploy the CICS Web Service created, but note that the deployment
has already been done for you.


Congratulations, you have completed the mandatory piece of this Lab

Section 7 Optional - Regenerated the web service.
Rational Developer for System z can record the generation options and if you need to run again you will already
have the options that you have specified. This is useful since you could do something once online interactively and
later do batch executions using the batch generation capabilities. Also this is useful when communicating with IBM
support in case of bugs so that they can reproduce the problem.

7.1 To understand this feature lets generate the web services again.
Using the Enterprise Service Tools Perspective and EST Project Explorer view, right click the
LAB3_CICS_Services project and select Generate Web Services for CICS resources

7.2 Click OK for the message below:


7.3 Expand DFHCOMMAREA, and as you can see, here are the options that you had specified before. They
are already selected.

LAB 3 - Creating CICS Services from COBOL Page 45
7.4 Navigate to the various pages; but do not make changes and after reviewing the pages, click Finish.


Note that assets are regenerated.

7.5 Close The Enterprise Services Tools Perspective all the opened editors (CTRL + SHIF + F4)



Section 8 Optional - Using Web 2.0 to invoke the CICS Web Service
created.
Rational Developer for System z version 7.5 with EGL helps you to create EGL applications that can be deployed
as COBOL or J ava.
On the new EGL 7.5.1 we also have the capability to generate J ava Script using Web 2.0 frameworks. You may get
more details in the EGL PoT.
On this section we have already created a simple EGL code that will invoke the CICS Web Services created above
using the Web 2.0 components (J ava Script) generated by EGL.

8.1 Close Rational developer for System z (RDz)..

8.2. Go to the windows desktop, double click on the folder and double-click in the icon


8.3. Switch to the EGL Rich UI perspective.
Select Window Open Perspective Other select EGL RICH UI and click OK


LAB 3 - Creating CICS Services from COBOL Page 47
8.4 Using the Project Explorer view, expand LAB3_EGL_RUI, EGLSource and callCICS until you see
InvokeCICSService.egl as below.



8.5 Right click on InvokeCICSService.egl and select Open with EGL Rich UI Editor.


8.6 The EGL code is opened using the Design view.
Click on tab Preview


8.7 This will generate J ava Script and when the screen below is displayed type 6 as Customer Number and
click the button Invoke CICS


8.8 If CICS is up and listening in the port 9046 (this is the port that we have created the WSDL in the solution
workspace) the results will be seen as below..
Cool ? Fast? Note that there is no Application Servers running. This Web service was implemented in CICS.


LAB 3 - Creating CICS Services from COBOL Page 49
8.9 In this code we implemented an EGL framework to help the debug.. called EGL Service Monitor.*
When a service is invoked, a bar is displayed and will indicate f the service succeeded or failed.
Clicking in the icon displays the monitor where you can see the * details for the message body, post header, and
response headers.
Click on the icon to see this monitor in action.



8.10 Feel free to explore the EGL code. Click on the tab Source and see how this was implemented.
Note that the EGL client code was automatically generated from the existing WSDL and the user has just to
complement it using their won logic More in the EGL PoT
Below you see where the EGL Service Interface is invoked.


8.11 Double click on LAB324.egl to see where the EGL code that invokes the Web service is implemented.


8.12 User Ctrl + Shift + F4 to close all opened perspectives. Close RDz.
LAB 3 - Creating CICS Services from COBOL Page 51
Solution
If you could not complete the lab dont get frustrated. In case you missed one step or typed a wrong name you
would have problems.
1) In any Perspective, import the Solution project using the options: File Import Other Project
Interchange and using the solution located at C:\RDZ_POT_V7\LAB3\solution\lab3_solution.zip.



Also there is the solution workspace (C: \ Wor kspaces7. 5\ RDZSOLUTI ON) in your VMware image.
To start the workspace with the solution:

Open the folder and double-click in the icon

Or specify this workspace when Rational Developer for System z starts: