Restriction: This topic applies to Windows environments only.
In this tutorial, you use the top-down method to create a CICS Web service provider application that receives a character
string in the form of a JSON request. The application reverses the string, and sends the reversed string back to the requester
as a JSON response message.
To use the top-down method to create a CICS Web service provider, you start with request and response JSON that describes
request and response data structures. From the JSON, you generate a skeleton CICS COBOL provider application, and a WSBIND
file that provides mapping between the JSON and the COBOL data structures.
The
sample
project used in this tutorial to create your
Enterprise Developer
for Eclipse project contains the
reverse.json schema, which describes both the request and response data structures.
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 ReverseJSON Web service provider section of this tutorial, we recommend that you install a JSON requester tool.
This tutorial assumes that your
Enterprise Developer project is set to
Build Automatically. If not, turn this feature on by clicking
Project > Build Automatically from the main menu.
Import the ReverseJSON 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\TopDown directory; then click
OK.
- On the
Projects list, ensure that
ReverseJSON is checked.
- Under
Options, check
Copy projects into workspace; then click
Finish.
The Application Explorer now shows the
ReverseJSON project, which is created in a
ReverseJSON 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
ReverseJSON 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 (Top-Down, Request-Response); then click
Next.
The Project field is already populated with the name of the current project,
ReverseJSON.
- Click the
Browse button that corresponds to the
JSON request field.
- Navigate to and select the
reverse.json file, located in your project's
schema folder.
- Click the
Browse button that corresponds to the
JSON response field.
- Navigate to and select the
reverse.json file, located in your project's
schema folder.
You need to provide a URI that
Enterprise Server can use to identify and locate the appropriate Web service upon receiving a request or a response. This information goes
into the
Service location field.
- In the
Service location field, type
/cics/services/json/reverse.
- Select
CHANNEL from the
Program interface drop-down list.
The default container name is
DFHWS-DATA, which is the top-level container used in service provider applications for CICS Web services.
- Click
Next.
- In the
Output artifacts group, type
reverseJ into the
Program name field. This is the name of the generated COBOL skeleton program.
The file prefixes you supply for the
Request file prefix and
Response file prefix fields become the first part of the filenames of the generated copybooks that support the generated skeleton program file;
one for request data structures, and one for response data structures.
- In the
Request file prefix field, type
REQ.
- In the
Response file prefix field, type
RESP.
Enterprise Developer generates a WSBIND file that maps the JSON request to the data structure in the generated request copybook and maps the JSON
response to the data structure in the generated response copybook. You need to provide a folder and filename for this file.
- Click the
Browse button that corresponds to the
WSBIND file field.
- On the Browse for WSBIND file dialog, click
New folder.
- In the field for the folder name, overwrite
New folder with
loadlib; then press
Enter.
- Double-click the
loadlib folder.
- In the
File name field, type
ReverseJ; then click
Open.
- Click
Finish.
Enterprise Developer generates the following CICS Web service components:
- reverseJ.cbl
- A skeleton CICS program.
- reverseJ.svi
- A service interface file.
- REQ01.CPY
- A copybook containing the COBOL data structures required to send a JSON request as input. This file is generated but does
not appear in the Solution Explorer.
- RESP01.CPY
- A copybook containing the COBOL data structures required to receive a JSON response message as output.
Implement the service
The generated skeleton program,
reverseJ.cbl, contains some basic functionality that is common to any CICS Web service that uses the Channel interface. The Web service:
- Populates the request data structure (in
REQ01.CPY) with the content of the DFHWS-DATA container.
- Populates the DFHWS-DATA container with the content of the response data structure (in
RESP01.CPY).
To provide the required operation logic, you must code it manually by editing the program.
- From the
Application Explorer, double-click
reverseJ.cbl to open it in the COBOL editor.
- Declare the following two variables in the
Working-Storage section:
01 ws-string-len pic x(4) comp-5.
01 ws-reversedString-len pic x(4) comp-5.
The provided
revLogicJ.cpy copybook contains one PERFORM statement that populates the request and response data structures. You need to include the
copybook in the program and execute the PERFORM statement.
- reverseJ.cbl contains two comment lines between the
EXEC CICS GET and the
EXEC CICS PUT statements. Code the following PERFORM statement between the comment lines:
perform reverse-logic
- Scroll down to the
bottom of the program, and add the following
copy statement after the
exit program statement:
copy 'revLogicJ.cpy'.
- Click
File > Save.
- Close the COBOL editor.
Eclipse automatically builds the project to include your changes.
Create an
enterprise server region
Here you use
Enterprise Server to create an
enterprise server region on which to run the Web service.
- In
Enterprise Developer, activate the Server Explorer.
Note: If Server Explorer is not showing, click
Window > Show View > Other > Micro Focus > Server Explorer.
- Right-click
Local [localhost:86]; then select
New > Enterprise Server.
- In the
Name field, type
JSONPROV. 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
ReverseJSON project folder.
- Double-click
CICSWebServicesTemplate.xml. This populates the
Template field.
- On the list next to
Associate with projects, check
ReverseJSON.
- Click
Finish.
The Server Explorer should now show the
JSONPROV
enterprise server region listed under
Local [localhost:86].
Note: If
JSONPROV is not showing, expand
Local [localhost:86].
Configure
JSONPROV 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.
JSON 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 resource definition file supplied with the project
does not include these resources; 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,
JSONPROV, to contain the resources required by the
reverseJ program.
- Start
Enterprise Server Administration
-
- From Server Explorer, right-click
Local [localhost:86]; then select
Open Administration Page. 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
JSONPROV
enterprise server region listed.
- Back on the Server Explorer, right-click
JSONPROV; 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
JSONPROV has started, on the 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 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
JSONPROV 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
- CICS Web Services are built on top of the CICS Web Interface (CWI) support, so you need to ensure that all CWS and CWI resources
are available. These reside in the DFHPIPE and DFHWEB resource groups respectively, which are already defined, but not included
in the startup list. Here you add these resource groups to the startup list.
- In addition, you need to add a new resource group for the CICS provider resources named
JSONPROV. At this point, the
JSONPROV resource group is neither created nor defined. 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
JSONPROV; then click
Apply.
- Create the
JSONPROV 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
JSONPROV.
- In the
Description field, type
CICS Web Services Provider Resources; then click
Add. This invokes the CICS Group
JSONPROV page where you can create and define resources for the group.
- Define
JSONPROV resources
- The
reverseJ program requires a resource for TCP/IP service, and a resource to support a pipeline.
- On the CICS Group
JSONPROV 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
JSONPROV page.
- Click
Pipeline.
- Complete these fields:
Name
|
JSONPIPE
|
|
Description
|
My CICS JSON 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\JSONConfig.xml
|
The IDE_XML_LOC environment variable in
JSONPROV points to the
xml project folder.1
|
WebSvc Dir
|
$IDE_LOADLIB\
|
The IDE_LOADLIB environment variable points to the
loadlib project folder, which contains the WSBIND file.1
|
1 To see a list of environment variables defined for
JSONPROV, from the ESMAC menu, click
Env.Vars..
|
- 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
JSONPROV; then select
Restart. This stops and then starts the
JSONPROV
enterprise server region, automatically installing and loading the newly added resources on the startup list.
Verify Resources
After
JSONPROV is started, you can verify that the resources you have defined are installed and active.
- In
Enterprise Server, start ESMAC for the
JSONPROV region.
- 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
reverseJ Web service listed and marked as
INSERVICE.
- 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/reverse.
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 ReverseJSON 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 request with the following endpoint URL:
http://localhost:5482/cics/services/json/reverse
- Set the Method to POST.
- Enter the following JSON request:
{"InputStrings" : {"myStrings":["olleH","NOSJ"]}}
You should receive the following JSON response:
{"OutputStrings" : {"myStrings":["Hello","JSON"]}}