Set Up the CWSJSON Enterprise Server Region

Guides you through the process of creating and configuring the CWSJSON enterprise server region, and installing and verifying resources.

Start the Server Explorer

The Server Explorer expandable ribbon is visible in Visual Studio on the top left side of the IDE by default when using Enterprise Developer. However, if it is not visible:

  • In Visual Studio, click View > Server Explorer.

Create an enterprise server region

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

  1. On the Server Explorer, expand Micro Focus Servers.
  2. Right-click localhost; then select New Enterprise Server.
  3. In the Name field, type CWSJSON. 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 ReverseJSON\ESTemplates project folder.
  5. Double-click CICSWebServicesTemplate.xml. This populates the Template field.
  6. On the list next to Associate with projects, check ReverseJSON.
  7. Click OK.

    The Server Explorer should now show the CWSJSON enterprise server region listed under localhost.

    Note: If CWSJSON doesn't immediately appear, right-click Micro Focus Servers; then select Refresh from the context menu.

Configure CWSJSON 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, CWSJSON, to contain the resources required by the reverse program.

Start Enterprise Server Common Web Administration (ESCWA)
  • On the Server Explorer, right-click Micro Focus Servers, and then click Administration.

    The ESCWA UI opens in a browser outside of the Visual Studio window.

Start the CWSJSON enterprise server region
  • On the Server Explorer, right-click CWSJSON; 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.

    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. Also, if prompted to disable password recovery, click No. If a Secure Storage prompt appears, click No.
Access the CICS resource settings for the server
  1. After CWSJSON 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 CWSJSON resource group
  1. On the RESOURCES page, expand the Groups node.
  2. Click NEW in the GROUPS pane.
  3. In the Name field, type CWSJSON.
  4. In the Description field, type CICS Web Services Provider Resources; then click SAVE. This invokes the CWSJSON page where you can create and define resources for the group.
Define CWSJSON resources
The reverse program requires a resource for TCP/IP service, and a resource to support a pipeline.
  1. On the CWSJSON page, click NEW and then click TCPIPSv from the drop-down list.
  2. Complete these fields:
    Description My TCP/IP Service
    Port 5639
  3. Click SAVE.
  4. Click BACK to return to the CWSJSON page.
  5. On the CWSJSON 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.
  6. Complete these fields:
    Description My CICS JSON 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 is 10 seconds for HTTP and 60 seconds for MQ.
    Config file $IDE_XML_LOC\jsonjavaprovider.xml The IDE_XML_LOC environment variable in CWSJSON 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 CWSJSON, from the list of Directory Servers, click the Edit (EDIT) button that corresponds to the CWSJSON 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 Visual Studio.

  7. Click SAVE.
  8. Click BACK to return to the CWSJSON page.
Open the DEMOSTRT startup list
  1. Expand Startup Lists to see the list of CICS STARTUP LISTS.

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

  2. Click DEMOSTRT.

    This opens the DEMOSTRT page in the right pane.

Add resource groups to the startup list
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. In addition, you need to add the new CWSJSON resource group.
  1. On the DEMOSTRT page under GROUPS, click ADD.
  2. On the Available Groups list, check the DFHPIPE, DFHWEB, and CWSJSON groups.
  3. Click Select.

    This adds the all groups to the end of the list.

  4. Cllick APPLY.

Install resources

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

  • From the Server Explorer in Visual Studio, right-click CWSJSON; then select Restart. This stops and then starts the CWSJSON enterprise server region, automatically installing and loading the newly added resources on the startup list.

Verify Resources

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

  1. From the ESCWA UI, click the CWSJSON 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 reverse Web service listed and marked as INSERVICE.
  5. On the list, click Pipeline > JSONPIPE. You should see that the JSONPIPE pipeline is enabled.
  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/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.

  7. Close ESCWA.