Creating the CICS infrastructure for a JSON service provider

To create the CICS infrastructure for a JSON service provider, you must create a pipeline configuration file and create a number of CICS resources.

Before you begin

Several different technologies exist for implementing JSON services in CICS. The most feature-rich option is z/OS® Connect. This task describes the alternative options.

If you do not want to use z/OS Connect, use CICS as a service provider for JSON requests, or use the linkable interface to transform JSON. To use these methods, define and install a JVMSERVER resource with a JVM profile that specifies the JAVA_PIPELINE=YES option. An example JVMSERVER resource definition called DFHAXIS is provided in group DFH$AXIS.

Note: The infrastructure described here assumes that you are not using z/OS Connect to connect to your JSON service provider, and consequently it uses Java™ parsing within the JVM server to parse the JSON messages.

If you want to use non-Java JSON parsing, see Creating the CICS infrastructure for a non-Java JSON service provider.

Restriction: Context switch in the pipeline is not supported.

Procedure

  1. Define the transport infrastructure.

    Define a TCPIPSERVICE resource that defines the port on which inbound requests are received. See CICS resources for web services for details.

  2. Define the message handlers that you want to include in the pipeline configuration file to process inbound web service requests, and their responses.

    If you want to perform your own processing in the pipeline, you must create a message handler. See Message handlers and the message handler interface for details. If you decide to create custom message handler programs, to optimize performance you must make them threadsafe.

  3. Create an XML pipeline configuration file containing your message handlers, header processing programs, and application handler.
    CICS provides a basic provider mode pipeline configuration file sample, jsonjavaprovider.xml. You can edit this sample to add additional message handlers as appropriate. This sample is provided in the /usr/lpp/cicsts/cicstsnn/samples/pipelines directory, where /usr/lpp/cicsts/cicstsnn is the default installation directory for CICS files on z/OS UNIX and cicstsnn reflects the release of CICS TS. For example, the directory is /usr/lpp/cicsts/cicsts64/samples/pipelines for CICS TS beta. For more information about options available in the pipeline configuration file, see Pipeline configuration files and XML elements for web services pipeline configuration.
  4. Copy the pipeline configuration file to a suitable directory in z/OS UNIX.
  5. Change the pipeline configuration file permissions to allow the CICS region to read the file.
  6. Create a PIPELINE resource.
    The PIPELINE resource defines the location of the pipeline configuration file. It also specifies a pickup directory, which is the z/OS UNIX directory that contains the web service binding files. Repeat this step for each different pipeline configuration.

    When you install a PIPELINE resource or perform a PIPELINE SCAN, CICS reads the .wsbind files in the specified pickup directory, and creates appropriate WEBSERVICE and URIMAP resources dynamically.

  7. Unless you use autoinstalled PROGRAM definitions, create a PROGRAM resource for each program that runs in the pipeline. These include the target application program, which normally runs under transaction CPIH. The transaction is defined with the attribute TASKDATALOC(ANY). Therefore, when you link-edit the program, you must specify the AMODE(31) option.

Results

You have created the infrastructure needed for each service provider and you can now install these resources on your CICS system.

What to do next

Install the resources. You can extend the configuration when you need to do so, either to define additional transport infrastructure, or to create additional pipelines.