Tutorial: CICS Web Service Provider, RESTful JSON

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the top-down method to create a RESTful Web service provider that receives POST and GET requests. These requests are sent to a wrapper program that passes the requests on to the filmREST program. The filmREST program creates a film record on a POST request, and returns a film record on a GET request.

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 filmWeb 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 filmsREST project

  1. In Eclipse, start the Team Developer Application Explorer.
  2. From the main menu, click File > Import.
  3. Expand General, and select Existing Projects into Workspace; then click Next.
  4. Select Set root directory, then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS\JSON\Provider\REST directory; then click OK.
  5. On the Projects list, ensure that filmsREST is checked.
  6. Under Options, check Copy projects into workspace; then click Finish.

    The Application Explorer now shows the filmsREST project, which is created in a filmsREST 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.

  1. From the Application Explorer, click the filmREST project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed:
    1. Select Other.
    2. Expand Micro Focus Service Interface.
    3. Select CICS Web Service; then click Next.
  3. Under Service type, select JSON message processing.
  4. From the drop-down list, select CICS Web Service Provider (Top-Down, RESTful); then click Next.

    The Project field is already populated with the name of the current project, filmsREST.

  5. Click the Browse button that corresponds to the JSON schema field.
  6. Navigate to and select the films.json file, located in your project's schema folder.
  7. In the Service location field, type /cics/services/json/film/*.
  8. Under HTTP methods, check GET, POST, PUT, and DELETE.
  9. 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.

  10. Click Next.
  11. In the Output artifacts group, type filmREST into the Program name field. This is the name of the generated COBOL skeleton program.

    The file prefix you supply for the Copy file prefix field becomes the first part of the filename of the generated copybook that supplies the generated skeleton program file with both request data structures and response data structures.

  12. In the Copy file prefix field, type film.

    Enterprise Developer generates a WSBIND file that maps the JSON request and response data structures in the generated copybook. You need to provide a folder and filename for this file.

  13. Click the Browse button that corresponds to the WSBIND file field.
  14. On the Browse for WSBIND file dialog, click New folder.
  15. In the field for the folder name, overwrite New folder with loadlib; then press Enter.
  16. Double-click the loadlib folder.
  17. In the File name field, type filmREST; then click Open.
  18. Click Finish.

Enterprise Developer generates the following CICS Web service components:

filmREST.cbl
A skeleton CICS program for a RESTful service.
film01.cpy
A copybook containing data structures.
loadlib\filmREST.wsbind
The binary file that maps JSON messages to and from COBOL.

Implement the service

The generated skeleton program, filmREST.cbl, contains some basic functionality that is common to any CICS Web service that uses the Channel interface, such as:

  • It retrieves the type of request being made from the DFHHTTPMETHOD container, and evaluates it.
  • For a GET request, it populates the DFHWS-DATA container with the content of the response data structure (in film01.cpy).
  • For a POST or PUT request, it populates the request data structure (in film01.cpy) with the contents of the DFHWS-DATA container.

To provide the required operation logic, you must code it manually by editing the program.

  1. From the Application Explorer, double-click filmREST.cbl to open it in the COBOL editor.
  2. Within the when "GET" statement, just before the exec cics put container statement, add: 
    perform GET-logic
  3. Within the when "PUT" statement, just after the exec cics get container statement, add: 
    perform POST-logic
  4. Scroll down to the bottom of the program, and add the following copy statement at the very end of the program: 
    copy "RESTLogic.cpy".
  5. Close the COBOL editor.

Create an enterprise server region

Here you use Enterprise Server to create an enterprise server region on which to run the Web service.

  1. In Enterprise Developer for Eclipse, activate the Server Explorer.
    Note: If Server Explorer is not showing, click Window > Show View > Other > Micro Focus > Server Explorer.
  2. Right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type CWSREST. This is the name for the new enterprise server region.
  4. Click the Browse button that corresponds to the Template field, and navigate to the CICSWebServicesTemplate.xml file located in the project folder.
  5. Double-click CICSWebServicesTemplate.xml. This populates the Template field.
  6. On the list next to Associate with projects, check filmREST.
  7. Click Finish.

    The Server Explorer should now show the CWSREST enterprise server region listed under Local [localhost:86].

    Note: If CWSREST is not showing, expand Local [localhost:86].

Configure CWSREST 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 CWSREST 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 a resource group to contain the resources required by the filmREST program, and also add the new group to the startup list.

Start Enterprise Server Administration
  1. 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 CWSREST enterprise server region listed.

  2. Back on the Server Explorer, right-click CWSREST; 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)
  1. After CWSREST has started, on the Administration Home page, click the Details button located in the Status column for the CWSREST region.
  2. 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
  1. On the ESMAC menu, click the drop-down list located under Resources; then select by Group.
  2. Click Startup. This invokes a list of CICS Startup Lists in the right pane.

    The CWSREST region uses the default startup list, named DEMOSTRT.

  3. 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 CWSRESTP resource group name to the startup list. At this point, you have you have neither created nor defined the CWSRESTP group and its respective resources. Those tasks are completed in the next few sections of this tutorial.
  1. 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.
  2. In the new empty field, type DFHPIPE; then click Apply.
  3. In the new empty field, type CWSRESTP; then click Apply.
Create the CWSRESTP resource group
  1. On the ESMAC menu, click the Groups button located under Resources.
  2. On the CICS Resource Groups page, click New.
  3. In the Name field, type CWSRESTP.
  4. In the Description field, type CICS Web Services JSON Provider Resources; then click Add. This invokes the CICS Group CWSRESTP page where you can create and define resources for the group.
Define CWSRESTP resources
The BookREST program requires a resource for TCP/IP service, and a resource to support a pipeline.
  1. On the CICS Group CWSRESTP page, click TCPIPSv.
  2. Complete these fields:
    Name RSTTCPIP
    Description My TCP/IP Service
    Port No 5482
  3. Click Add. Enterprise Server returns Add successful.
  4. Click Apply. Enterprise Server returns Update successful.
  5. Click Group List to return to the CICS Group CWSRESTP page.
  6. Click Pipeline.
  7. Complete these fields:
    Name RESTPIPE
    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\JSONConfig.xml The IDE_XML_LOC environment variable in CWSREST points to the xml project folder.1
    WebSvc Dir $IDE_LOADLIB\ The IDE_LOADLIB environment variable points to the loadlib project folder.1

    1 To see a list of environment variables defined for CWSREST, from the ESMAC menu, click Env.Vars..

  8. Click Add. Enterprise Server returns Add successful.
  9. Click Apply. Enterprise Server returns Update successful.
  10. Click Home to return to the Administration Home page.

    You can install the new resources by stopping and starting the region.

  11. From the Enterprise Developer Server Explorer, right-click CWSREST; then select Restart. This stops and then starts the CWSREST enterprise server region, automatically installing and loading the newly added resources on the startup list.

Verify Resources

After CWSREST is started, you can verify that the resources you have defined are installed and active.

  1. In Enterprise Server, start ESMAC for the CWSREST region.
  2. On the ESMAC menu, select Active from the drop-down list located under Resources.
  3. On the ESMAC menu, click the WebSvc button. You should see the filmREST Web service listed and marked as INSERVICE.
  4. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to RESTPIPE. The Pipeline resource sets the response wait period, identifies the JSON configuration file, and the Web Service directory.
  5. On the ESMAC menu, click URIMAP; then click the Details button that corresponds to PIPELINE and /cics/services/json/filmREST/*.

    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 RESTful CICS Web service, you can either send an HTTP GET request to retrieve an existing film record or an HTTP PUT request to create a new film record. The request is sent 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 film Web service provider

Now that you have your Web service provider running with all of its resources active, you are ready to send a POST and a GET request to run the Web service. You can do this using any JSON requester tool.

  1. Create and submit a JSON request with the following endpoint URL: 
    http://localhost:5482/cics/services/json/film
  2. Set the method to POST.
  3. Enter the following JSON request and send it to create a new film record: 
    {"film-details": [{ 
   "title": "Jaws", "year": "1975", 
   "director": "Steven Spielberg", "format": "VHS" 
}]}

    The response should be a status code of 200, and the body should contain the string /cics/services/json/film/Jaws. This is the string placed into the DFHRESPONSE container by the application.

  4. Set the method to GET.
  5. Create and submit a JSON request with the following endpoint URL: 
    http://localhost:5482/cics/services/json/film/jaws

    The response should be a JSON message containing the film details placed into the DFHWS-DATA container by the application.

Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables