Set Up the CWSREST Enterprise Server Region

Guides you through the process of creating and configuring the CWSREST enterprise server region, and verifying the resources required to run the RESTful JSON CICS Web service provider.

Start the Server Explorer

The Server Explorer view is visible by default when using the Team Developer perspective, and appears as a tab on the same level as the Application Explorer view. However, if it is not visible:

  • In Eclipse, click Window > Show View > Other > Micro Focus > Server Explorer, and then click Open.
Attention: You might encounter an ESCWA Sign On dialog box as you perform the steps required to create, configure, start, or stop an enterprise server instance from the Server Explorer. If you do, ensure that the Server requires credentials, Use specific server credentials, or Server is secured , and the Store credentials boxes are unchecked, and then click OK. Also, if prompted to disable password recovery, click No.

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 the Server Explorer, expand Local [localhost:10086].
  2. Right-click Default [127.0.0.1:86] and click 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 filmsREST.
  7. Click Finish.

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

    Note: If CWSREST is not showing, expand Local [localhost:10086] > Default [127.0.0.1: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 filmsws program, and also add the new group to the startup list.

Start Enterprise Server Common Web Administration (ESCWA)
  • On the Server Explorer, right-click Default [127.0.0.1:86] and then click Open Administration Page.

    ESCWA starts in your default browser.

Start the CWSREST enterprise server region
  • On the Server Explorer, right-click CWSREST; then select Start.
Access the CICS resource settings for the server
  1. After CWSREST has started, select it from the default Directory Servers list in ESCWA.
  2. At the top of the right pane, click CICS > Resources.
Create the CWSRESTP resource group
  1. On the Resources page, click the Groups node.
  2. Click New in the Groups pane.
  3. In the Name field, type CWSRESTP.
  4. In the Description field, type CICS Web Services Provider Resources; then click SAVE. This invokes the CWSRESTP page where you can create and define resources for the group.
Define CWSRESTP resources
The filmREST program requires a resource for TCP/IP service, and a resource to support a pipeline.
Define a TCP/IP resource
  1. On the CWSRESTP page, click New and then click TCPIPSv from the drop-down list.
  2. Complete these fields:
    Name RSTTCPIP
    Description My TCP/IP Service
    Port No 5482
  3. Click Save.
Define a Pipeline resource
  1. In the list of resources, click CWSRESTP under Group to return to the CWSRESTP page.
  2. On the CWSRESTP page, click New and then click Pipeline from the list.
    Important: If the Pipeline button is not present, check to be sure that you have properly installed the CCSID tables specified in the Tutorials: CICS Web Services topic.
  3. Complete these fields:
    Name RESTPIPE
    Description My CICS Provider Pipeline
    Response Wait Time Check System Default This is the number of seconds that an application waits for a response from the service. The default value 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
    Web Directory $IDE_LOADLIB\ The IDE_LOADLIB environment variable points to the loadlib project folder, which contains the WSBIND file.2

    1 To see a list of environment variables defined for CWSRESTP, from the list of Directory Servers, click the Edit (Edit) button that corresponds to the CWSRESTP region. Click the downward arrow next to MONITOR at the top of the page, then click Environment Variables.

    2The IDE_LOADLIB environment variable is set automatically when you start the enterprise server region from the Server Explorer in Eclipse.

  4. Click Save.
Open the DEMOSTRT startup list
  1. Expand Startup Lists to see the CICS Startup List page.

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

  2. Click DEMOSTRT.

    This opens the DEMOSTRT page in the right pane.

Add resource groups
Here, you add the DFHWEB, DFHPIPE, and the new CWSRESTP resource groups to the startup list.
  1. On the DEMOSTRT page under Groups, click ADD.
  2. On the Available Groups list, check the DFHPIPE, DFHWEB, and CWSRESTP groups.
  3. Click Select.

    This adds all groups to the end of the list.

  4. Cllick Apply.

Install CWSREST resources

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

  • From the 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. From the ESCWA UI, click the CWSREST server in default list.
  2. From the CICS drop-down list in the right pane, select Resources.
  3. Set the first field to the right of Resources to Active.
  4. On the resulting list of active resources, click WebSvc. You should see the filmREST Web service listed and marked as INSERVICE.
  5. On the list, click Pipeline > Restpipe. The Pipeline resource sets the response wait period, identifies the JSON configuration file, and the Web Service directory.
  6. On the list, click URIMap > £map-ref, where map-ref is an alphanumeric string generated by Enterprise Server. You should see the path specified as /cics/services/json/film/*.

    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.

    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.

Parent topic: Tutorial: CICS Web Service Provider from JSON, RESTful
Previous topic: Add Operation Logic to filmREST.cbl
Next topic: Test the films Web Service Provider