In this tutorial, you use the top-down method to create a Web service provider that sends one or more character strings in
the form of a SOAP request to a generated CICS application. The application reads and then reverses each string, and sends
the reversed strings back to the Web service as a SOAP response message.
To use the top-down method, you supply a WSDL file that describes the CICS application you want to access. The project template
used in this tutorial to create your
Enterprise Developer project contains the
reverse.wsdl file for this purpose.
Prerequisites
To complete this tutorial,
you must first install the IBM CCSID Conversion Tables and configure accordingly. See
CCSID Conversion Tables for more information.
To complete the
Test the Reverse Web service provider section of this tutorial, we recommend that you
install
a SOAP requester tool.
Create the Reverse project
Use the CWSProject demonstration project to create a project for your CICS Web service provider.
- Using Windows Explorer or at a command prompt, create a project directory named
Reverse.
- Extract the
CICSWebServicesTemplate_VS.zip file, located in the
%PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS directory by default, to the new
Reverse project directory.
- From the
Enterprise Developer
for Visual Studio 2017 main menu, click
File > Open > Project/Solution.
- Browse to the new
Reverse project directory, and select the
CWSProject.cblproj project file; then click
Open. This starts the Solution Explorer.
Here, you rename the project to match the name of the service interface you are going to create. This is not mandatory in
general, but done here to differentiate between tutorial projects.
- In the Solution Explorer, right-click the
CWSProject project; then select
Rename.
- Type
Reverse; then press
Enter.
Generate CICS Web Service provider components
Use the Generate Web Service dialog box to generate the components of your Web service provider.
- From the Solution Explorer, expand the
Reverse project's
wsdl folder.
- Right-click the
reverse.wsdl file; then select
Generate Web Service from the context menu.
- In the
Generate group, select the
Service radio button.
- In the
Name field associated with the
Service radio button, ensure that
reverse is specified as the name for the generated service interface.
- In the
Program group, check
CICS.
- In the
Program group's
Name field, type
reverse, which is the name for the generated COBOL skeleton program.
The
Type radio buttons in the
Program group enable you to specify the generation of either a
Commarea or a
Channel interface in the skeleton program. In this tutorial, you want to generate a Channel interface.
- In the
Type group, select the
Channel radio button. This activates the
Inline array size limit and
Container name fields.
The default container name is
DFHWS-DATA, which is the top-level container used in service provider applications for CICS Web services.
- In the
Inline array size limit field, type
1. This turns on container mappings in the generated service.
- Click
OK.
Enterprise Developer generates the following CICS Web service components in the
wsdl\reverse project folder:
- reverse.cbl
- A skeleton CICS program.
- reverse.svi
- A service interface file.
- reverI01.cpy
- A copybook containing the COBOL data structures required to send a SOAP request as input. This file is generated but does
not appear in the Solution Explorer.
- reverO01.cpy
- A copybook containing the COBOL data structures required to receive a SOAP response message as output. This file is generated
but does not appear in the Solution Explorer.
Generate and move the
reverse.wsbind file
- In the Solution Explorer, right-click the
reverse.svi file; then select
Generate WSBIND.
Because the
reverse.wsbind file is generated to the
Reverse project's
wsdl\reverse directory, but the output path is set to the project's
loadlib directory, you need to move the file from the
Reverse project's
wsdl\reverse to the project's
loadlib directory so that
Enterprise Server finds the correct file.
- Using Windows Explorer or at a command prompt, change to the
Reverse project directory.
- Copy or move the
reverse.wsbind file from the
wsdl\reverse project directory to the
loadlib project directory.
Implement the service
The generated skeleton program,
reverse.cbl, contains some basic functionality that is common to any CICS Web service that uses the Channel interface, such as:
- It checks the operation name by retrieving the content of the DFHWS-OPERATION container.
- If the returned operation name matches the name expected by the program (in this case,
reverserequest), the program:
- Populates the request data structure (in
reverI01.cpy) with the content of the DFHWS-DATA container.
- Populates the DFHWS-DATA container with the content of the response data structure (in
reverO01.cpy).
To provide the required operation logic, we have provided a fully implemented version of the program for you to use.
- Using Windows Explorer or at a command prompt, change to the
Reverse project directory.
- Copy the
reverse.cbl file from the
cbl directory to the
wsdl\reverse directory, overwriting the generated COBOL skeleton program.
Build the Reverse project
- From the Solution Explorer, right-click the
Reverse project; then select
Build.
Create an enterprise server region
Here you use the Server Explorer in
Enterprise Developer to create an
enterprise server region on which to run the Web service.
- From
Enterprise Developer, activate the Server Explorer.
- Expand
Micro Focus Servers.
- Right-click
localhost; then select
New Enterprise Server.
- In the
Name field, type
CWSDEMO. This is the name for the new
enterprise server region.
- Click the
browse button that corresponds to the
Template field, and navigate to the
CICSWebServicesTemplate.xml file located in the
ESTemplates project folder.
- Double-click
CICSWebServicesTemplate.xml. This populates the
Template field.
- On the list next to
Associate with projects, check
Reverse.
- Click
OK.
The Server Explorer should now show the
CWSDEMO
enterprise server region listed under
localhost.
Configure
CWSDEMO resources
All
enterprise server regions require access to certain resources, depending on the types of applications they run. Resources that are defined on a region's
startup list are loaded during the startup routine, making them available for as long as the region is running.
CICS Web services use the underlying resources provided by the standard
Enterprise Server CICS Web interface (CWI) and CICS Web Services (CWS) support. However, the CICSWebServicesTemplate used to create the
CWSDEMO region does not include these resources on the startup list; therefore, you need to add them manually. The CWI resources
reside in a predefined resource group named DFHWEB. The CWS resources are in the predefined DFHPIPE group.
In addition, you need to create and define a resource group, MYCWSPRV, to contain the resources required by the Reverse program.
- Start
Enterprise Server Administration
-
- From Server Explorer, right-click
Micro Focus Servers; then select
Administration. This starts
Enterprise Server Administration.
Note: If this is the first time you have started the server you see a sign-on dialog box. If
Server is secured is checked, uncheck it; then click
OK. Unchecking
Server is secured prevents this dialog box from showing when you subsequently start the region. If
Server is secured is not checked, simply click
OK to clear the dialog box. If a Secure Storage prompt appears, click
No.
On the Home page, you should see the
CWSDEMO
enterprise server region listed.
- Back on the Server Explorer, right-click
CWSDEMO; then select
Start.
As the region is starting, the
Enterprise Server Administration Home page should show log information in the region's
Status Log column. When the region is fully started, this is indicated in the region's
Status column.
- Start ES Monitor and Control (ESMAC)
-
- After
CWSDEMO has started, on the Administration Home page, click the
Details button located in the
Status column for the
CWSDEMO region.
- On the
Server > Control page, click
ES Monitor & Control. This starts the ESMAC utility where you can edit the startup list.
- Open the DEMOSTRT startup list
-
- On the ESMAC menu, click the drop-down list located under
Resources; then select
by Group.
- Click
Startup. This invokes a list of
CICS Startup Lists in the right pane.
The
CWSDEMO region uses the default startup list, named DEMOSTRT.
- Click the
Details button that corresponds to
DEMOSTRT. This takes you to the CICS STARTUP - DEMOSTRT page.
- Add resource groups
- Here, you add the DFHWEB and DFHPIPE resource groups to the startup list, and add the MYCWSPRV resource group name to the
startup list. At this point, you have neither created nor defined the MYCWSPRV group and its respective resources. Those tasks
are completed in the next few sections of this tutorial.
- On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type
DFHWEB into the empty field at the bottom; then click
Apply. ESMAC adds the DFHWEB group, and adds another empty field at the end of the list.
- In the new empty field, type
DFHPIPE; then click
Apply.
- In the new empty field, type
MYCWSPRV; then click
Apply.
- Create the MYCWSPRV resource group
-
- On the ESMAC menu, click the
Groups button located under
Resources.
- On the CICS Resource Groups page, click
New.
- In the
Name field, type
MYCWSPRV.
- In the
Description field, type
CICS Web Services Provider Resources; then click
Add. This invokes the CICS Group MYCWSPRV page where you can create and define resources for the group.
- Define MYCWSPRV resources
- The Reverse program requires a resource for TCP/IP service, and a resource to support a pipeline.
- On the CICS Group MYCWSPRV page, click
TCPIPSv.
- Complete these fields:
Name
|
CWSTCPIP
|
Description
|
My TCP/IP Service
|
Port No
|
5482
|
- Click
Add.
Enterprise Server returns
Add successful.
- Click
Apply.
Enterprise Server returns
Update successful.
- Click
Group List to return to the CICS Group MYCWSPRV page.
- Click
Pipeline.
- Complete these fields:
Name
|
PROVPIPE
|
|
Description
|
My CICS Provider Pipeline
|
|
Resp Wait
|
DEFT
|
This is the number of seconds that an application waits for a response from the service. DEFT indicates the default value,
which is 10 seconds for HTTP and 60 seconds for MQ.
|
Config file
|
$IDE_XML_LOC\basicsoap11provider.xml
|
The IDE_XML_LOC environment variable in
CWSDEMO points to the
xml project folder.1
|
WebSvc Dir
|
$IDE_LOADLIB\
|
The IDE_LOADLIB environment variable points to the
loadlib project folder.2
|
1 To see a list of environment variables defined for
CWSDEMO, from the Administration Home page, click the
Edit button that corresponds to the
CWSDEMO region. The list appears in the
Configuration Information field on the
Server > Properties > General page.
2 The IDE_LOADLIB environment variable is set automatically when you start the
enterprise server region from the
Enterprise Developer Server Explorer.
|
- Click
Add.
Enterprise Server returns
Add successful.
- Click
Apply.
Enterprise Server returns
Update successful.
- Click
Home to return to the Administration Home page.
You can install the new resources by stopping and starting the region.
- From the
Enterprise Developer Server Explorer, right-click
CWSDEMO; then select
Restart. This stops and then starts the
CWSDEMO
enterprise server region, automatically installing and loading the newly added resources on the startup list.
Verify Resources
After
CWSDEMO is started, you can verify that the resources you have defined are installed and active.
- Start ESMAC.
- On the ESMAC menu, select
Active from the drop-down list located under
Resources.
- On the ESMAC menu, click the
WebSvc button. You should see the
Reverse Web service listed and marked as
INSERVICE.
- Click the
Details button that corresponds to the
reverse Web service.
Notice the value for
WSBIND. This value is taken from the information you provided when you created the Web service.
- On the ESMAC menu, click
Pipeline; then click the
Details button that corresponds to
PROVPIPE. The Pipeline resource sets the response wait period, identifies the SOAP configuration file, and the Web Service directory.
- On the ESMAC menu, click
URIMAP; then click the
Details button that corresponds to
PIPELINE and
/cwsDemo/reverseMe.
Enterprise Server generates URIMAPs to provide CICS with the information it needs to process requests. The name of each generated URIMAP begins
with a pounds sterling symbol (£).
To run your provider CICS Web service, you send a SOAP request to an endpoint URL that routes the request to your
enterprise server region. The endpoint URL contains a URI value. The incoming request reads the installed URIMAPs to identify the map whose
Path value matches the
URI value of the endpoint URL. When the correct URIMAP is identified, CICS uses the data defined in the URIMAP, such as the name
of the
Web Service and its associated
Pipeline, to process the request.
Test the Reverse Web service provider
Now that you have your Web service provider running with all of its resources active, you are ready to send a SOAP request
to run the Web service. You can do this using any SOAP requester tool.
- Create a SOAP request that contains the following:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:cws="http://tempuri.org/reverse">
<soapenv:Header/>
<soapenv:Body>
<cws:reverseRequest>
<cws:InputStrings>
<cws:myString>dlroW olleH</cws:myString>
<cws:myString>esaelP eM esreveR</cws:myString>
</cws:InputStrings>
</cws:reverseRequest>
</soapenv:Body>
</soapenv:Envelope>
- Submit the SOAP request to the following endpoint URL:
http://localhost:5482/cwsDemo/reverseMe
You should receive the following SOAP response:
<SOAP-ENV:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:cws="http://tempuri.org/reverse"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<reverseResponse xmlns="http://tempuri.org/reverse">
<OutputStrings>
<reversedString>Hello World</reversedString>
<reversedString>Reverse Me Please</reversedString>
</OutputStrings>
</reverseResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>