Restriction: This topic applies to Windows environments only.
In this tutorial, you use the bottom-up method to expose an existing CICS COBOL application, LOANPAYM, as a Web service.
The LOANPAYM application accepts a principal amount, a loan term, and a rate as input values; then returns the calculated
monthly loan payment.
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 loanPaym Web service provider
section of this tutorial, we recommend that you install a JSON requester tool.
Import the LoanDemoJSON project
- In Eclipse, start the Team Developer Application Explorer.
- From the main menu, click
File > Import.
- Expand
General, and select
Existing Projects into Workspace; then click
Next.
- Select
Set root directory, then browse to the
%PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS\JSON\Provider\BottomUp directory; then click
OK.
- On the
Projects list, ensure that
LoanDemoJSON is checked.
- Under
Options, check
Copy projects into workspace; then click
Finish.
The Application Explorer now shows the
LoanDemoJSON project, which is created in a
LoanDemoJSON subdirectory of your current Eclipse workspace, and is built automatically.
Generate CICS Web Service provider components
Use the New CICS Web Service wizard to generate the components of your Web service provider.
- From the Application Explorer, click the
LoanDemoJSON project to select it.
- Click
File > New > CICS Web Service. This starts the
New CICS Web Service Wizard.
Note: If
CICS Web Service is not listed:
- Select
Other.
- Expand
Micro Focus Service Interface.
- Select
CICS Web Service; then click
Next.
- Under
Service type, select
JSON message processing.
- From the drop-down list, select
CICS Web Service Provider (Bottom-Up, Request-Response); then click
Next.
The Project field is already populated with the name of the current project,
LoanDemoJSON.
- Click the
Browse button that corresponds to the
Program location field.
- Navigate to and select the
loanPaym.cbl file, located in the
LoanDemoJSON folder; then click
OK.
- In the
Service location field, type
/cics/services/json/loanpaym.
- Select
COMMAREA from the
Program interface drop-down list; then click
Next.
In the
Mapping group, you specify the copybooks that contain request and response data structures.
- Click the
Browse button that corresponds to the
Request structure field.
- Navigate to and select the
LOANINP.cpy file, located in the
LoanDemoJSON folder; then click
OK.
- Similarly, find and select the
LOANOUT.cpy file to populate the
Response structure field.
In the
Output artifacts group, you specify names and locations for request and response schema files and the location for the WSBIND file.
- Click the
Browse button that corresponds to the
JSON request field.
- Navigate to your project directory.
- Click
Make New Folder.
- Name the new folder
schema; then press
Enter.
- Double-click the
schema folder to select it.
- In the
File name field, type
loanDemoReq; then click
Open.
- Click the
Browse button that corresponds to the
JSON response field.
- Navigate to the new
schema folder.
- In the
File name field, type
loanDemoResp; then click
Open.
- Click the
Browse button that corresponds to the
WSBIND file field.
- On the Browse for WSBIND file dialog, create a new folder named
loadlib; then open the new folder.
- In the
File name field, type
loanPaym; then click
Open.
- Click
Finish.
Configure the enterprise server region
This tutorial uses the
JSONPROV
enterprise server region created in
Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method to run the Web service provider.
Do one of the following:
- If you did not complete
Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, skip the instructions in this section, go back to
Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, and complete the sections titled
Create an enterprise server region and
Configure
JSONPROV resources. However, when selecting a project with which to associate the new region, check the
LoanDemoJSON project instead of the
ReverseJSON project.
- If you created and configured
JSONPROV while completing
Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, follow the steps in this section to update the
dfhdrdat file and properly associate
JSONPROV with the
LoanJSON project.
- Update the
dfhdrdat file
- When you create an
enterprise server region from the
Enterprise Developer Server Explorer, it stores some configuration information in the project's
system\dfhdrdat file. Therefore, to update the
LoanDemoJSON project with this information, you can copy the file from the
ReverseJSON project to the
LoanDemoJSON project:
- Using Windows Explorer or at a command prompt, copy the
dfhdrdat file located in the ReverseJSON project's
system directory to the
LoanDemoJSON project's
system directory, overwriting the existing file.
- Associate the
LoanDemoJSON project
- In previous tutorials, you have associated your project with an
enterprise server region as part of the steps to create the region. Because the region you are using here was previously associated with the ReverseJSON
project, you need to change the association to the
LoanDemoJSON project.
- On the Server Explorer, right-click
JSONPROV; then select
Associate with project.
- Click
LoanDemoJSON to create an association.
- If you are prompted to restart the server, answer
Yes; if you are not prompted, right-click
JSONPROV and select
Start from the context menu.
Verify Resources
After
JSONPROV is started, you can verify that the resources you have defined are installed and active.
- Start
Enterprise Server Administration
-
- From Server Explorer, right-click
Micro Focus Servers; then select
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
JSONPROVenterprise server region listed.
- Start ES Monitor and Control (ESMAC)
-
- On the
Enterprise Server Administration Home page, click the
Details button located in the
Status column for the
JSONPROV region.
- On the
Server > Control page, click
ES Monitor & Control. This starts the ESMAC utility where you can view the defined resources.
- View defined resources
-
- On the ESMAC menu, select
Active from the drop-down list located under
Resources.
- Click the
WebSvc button. You should see the
loanPaym Web service listed and marked as
INSERVICE.
- Click the
Details button that corresponds to the
loanPaym Web service.
Notice the value for
WSBIND. This is determined by the information stored in your project.
- On the ESMAC menu, click
Pipeline; then click the
Details button that corresponds to
JSONPIPE. The Pipeline resource sets the response wait period, identifies the JSON configuration file, and the Web Service directory.
- On the ESMAC menu, click
URIMAP; then click the
Details button that corresponds to
PIPELINE and
/cics/services/json/loanPaym.
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 JSON 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
loanPaym Web service provider
Now that you have your Web service provider running with all of its resources active, you are ready to send a JSON request
to run the Web service. You can do this using any json requester tool.
- Create a JSON POST request that contains the following:
{
"loanPaym" :
{
"LOANINP" :
{
"principal" : "50000",
"loanterm" : "180",
"rate" : "5.56"
}
}
}
- Submit the JSON request to the following endpoint URL:
http://localhost:5482/cics/services/json/loanPaym
You should receive the following JSON response:
{"loanPaymResponse": {"LOANOUT": {"monthlyPayment": "$410.13"}}}