Creating a channel-based service

Channel-based services are CICS® applications that are described as components and assembled together using a tool such as IBM® Developer for z/OS. These services are available only to other CICS applications that use the INVOKE SERVICE API command and pass binary data in containers on a channel.

About this task

In SCA, the application program that you want to expose as a channel-based service is the implementation of the business logic. The component service describes the interface to the application program in WSDL. A component has one interface, which can contain operations and bindings. For a channel-based service, a CICS binding describes the channel. If you select this binding, IBM Developer for z/OS adds a binding.cics section to the SCDL. A channel-based service has no data mappings, because the application interface expects a channel and binary data in containers.

Procedure

  1. Create a composite using IBM Developer for z/OS.
    1. Specify the application program name as the component implementation.
    2. Add the CICS binding to the appropriate service or reference by selecting the direct mapping mode in the tooling.
      • If you specify a URI on the CICS binding that is attached to the composite service, this URI provides the external name for the service. In CICS , this URI is a relative path name; for example, if the service is to be exposed as http://myhost:port/myService , the URI in the binding is myService , because the host and port are beyond the control of the composite application.
      • If you specify a URI on the CICS binding that is attached to the composite reference, the URI is complete for the targeted service; for example http://myhost:port/myService or cics://PROGRAM/prog1?user=user1.
    3. Optional: Define imports on the composite reference.
      Imports define the dependencies of the component or composite.
    A box represents the composite. Inside the composite is another box that represents the component. A small arrow enters the component from the left to represent the component service. Another small arrow leaves the component from the right to represent the component reference. A large arrow enters the composite from the left to represent the composite service; it has text to indicate it is an Operation with a CICS binding. A large arrow leaves the composite from the right to represent the composite reference; it has text to indicate it has Imports with a CICS binding.

    For details about the recommended ways to create and deploy composites in CICS , see Best practices for creating and deploying composites.

  2. Deploy the composite to CICS as a bundle.
    IBM Developer for z/OS generates the bundle manifest and packages the SCDL and other artifacts for you. The manifest describes all the resources and metadata that CICS requires to successfully install a BUNDLE resource; the BUNDLE resource represents the composite in the CICS region. The manifest defines the composite as an SCACOMPOSITE resource type and references the location of the SCDL using a relative path.
  3. Create and install the BUNDLE resource.
    You can optionally set an SCA domain on the BUNDLE resource definition. An SCA domain typically represents a set of services that provide an area of business function. You can install the same bundle using different SCA domains, because CICS identifies the service by combining the SCA domain and the name of the service. For details and examples of how to add an SCA domain, see Scoping of bundles.

    You must ensure that all prerequisites of the bundle are available in the CICS region for the BUNDLE resource to install successfully.

  4. Write an application to call the channel-based service using the INVOKE SERVICE API command: 
    
EXEC CICS INVOKE SERVICE('servicename')
				 CHANNEL(channel)
				 OPERATION(operation)

    The servicename is the external name of the service, the channel is the 16-byte name of the channel, and the operation is any value. Although the operation is a mandatory option on the command, the value is not used for channel-based services.

Results

When the application calls the channel-based service, CICS resolves the name of the service and issues an EXEC CICS LINK command to pass the specified channel and containers to the application program that you defined in the composite. If you specified a specific requester pipeline in the binding, CICS runs the request through that requester pipeline. If no requester pipeline is specified in the binding, CICS dynamically creates a requester pipeline for the request.

What to do next

You can test and validate that the service works as expected. You can view the BUNDLE resource and its contents using the IBM CICS Explorer®. You can also enable and disable the BUNDLE resource to manage all the resources together.