CICS resources for web services

PIPELINE, WEBSERVICE, URIMAP and TCPIPSERVICE resources support web services in CICS®.

PIPELINE

A PIPELINE resource definition is required for every web service. It provides information about the message handler programs that act on a service request and on the response. Typically, a single PIPELINE resource definition defines an infrastructure that can be used by many applications. The information about the message handlers is supplied indirectly: the PIPELINE resource definition specifies the name of a z/OS® UNIX file that contains an XML description of the handlers and their configuration.

A PIPELINE resource that is created for a service requester cannot be used for a service provider, and vice versa. The two sorts of PIPELINE definitions are distinguished by the contents of the pipeline configuration file that is specified in the CONFIGFILE attribute: for a service provider, the top-level element is <provider_pipeline>; for a service requester, it is <requester_pipeline>.

WEBSERVICE

A WEBSERVICE resource definition is required only when the mapping between application data structure and SOAP messages has been generated using the CICS web services assistant. It defines aspects of the runtime environment for a CICS application program deployed in a web services setting.

Although CICS provides the usual resource definition mechanisms for WEBSERVICE resources, they are typically created automatically from a web service binding file when the pickup directory for the PIPELINE resource definition is scanned. This can occur when the PIPELINE resource is installed or as a result of a PERFORM PIPELINE SCAN command. The attributes applied to the WEBSERVICE resource in this case come from a web services binding file, which is created by the web services assistant; information in the binding file comes from the web service description, or is supplied as a parameter of the web services assistant.

A WEBSERVICE resource that is created for a service requester cannot be used for a service provider, and vice versa. The two sorts of WEBSERVICE resource are distinguished by the PROGRAM attribute in the resource definition: for a service provider, the attribute must be specified; for a service requester, it must be omitted.

URIMAP

A URIMAP definition is required in a service provider when it contains information that maps the URI of an inbound web service request to the other resources (such as the PIPELINE resource) that will service the request. This URIMAP definition is also required if you are using HTTP basic authentication, because the URIMAP resource definition specifies that the service requester user ID information is passed in an HTTP authorization header to the service provider.

A second optional URIMAP definition can exist in a service provider for WSDL discovery. This URIMAP resource definition contains information that maps the URI of an inbound request for the WSDL document or documents associated with the web service.

For service providers deployed using the CICS web services assistant, although CICS provides the usual resource definition mechanisms, the URIMAP resources are typically created automatically when the pick directory is scanned. This scan occurs when the PIPELINE resource is installed or as a result of a PERFORM PIPELINE SCAN command. The URIMAP resource that provides CICS with the information to associate the WEBSERVICE resource with a specific URI is a required resource. The attributes for this resource are specified by a web service binding file in the pickup directory. The URIMAP resource that provides CICS with the information to associate the WSDL archive file or WSDL document with a specific URI is an optional resource and is created if either a WSDL file or WSDL archive file are present in the pickup directory. For more information about creating URIMAP resources for web service providers, see Creating a web service provider by using the web services assistant.

For service requesters, CICS does not create any URIMAP resources automatically when the PIPELINE resource is installed or as a result of a PERFORM PIPELINE SCAN command. Service requesters are not required to use URIMAP resources when they make requests; they can specify the URI of the outbound request directly in the application program. However, if you create a URIMAP resource for the client request, and your service requesters use the URIMAP resource to provide the URI, you gain these advantages:

System administrators can manage any changes to the endpoint of the connection, so you do not need to recompile your applications if the URI of a service provider changes.
You can choose to make CICS keep the connections that were opened with the URIMAP resource open after use, and place them in a pool for reuse by the application for subsequent requests, or by another application that calls the same service. Connection pooling is only available when you specify a URIMAP resource that has the SOCKETCLOSE attribute set. For more information about the performance benefits of connection pooling, see Connection pooling for HTTP client performance.

Configuring URIMAP resource attributes in a certain way might enable inbound requests being processed by directly attached user transactions, and bypassing the web attach task. For more information, see HTTP requests are processed by directly attached user transactions.

TCPIPSERVICE

A TCPIPSERVICE definition is required in a service provider that uses the HTTP transport. It contains information about the port on which inbound requests are received.

The resources that are required to support a particular application program depend on the following criteria:

Whether the application program is a service provider or a service requester.
Whether the application is deployed with the CICS web services assistant.

Service requester or provider	CICS web services assistant used	PIPELINE required	WEBSERVICE required	URIMAP required	TCPIPSERVICE required
Provider	Yes	Yes	Yes (but see note 1)	Yes (but see note 1)	See note 2
Provider	No	Yes	No	Yes	See note 2
Requester	Yes	Yes	Yes	See note 3	No
Requester	No	Yes	No	3	No

Notes:

When the CICS web services assistant is used to deploy an application program, the WEBSERVICE and two URIMAP resources can be created automatically when the pickup directory of the PIPELINE is scanned. The first URIMAP resource is required and provides CICS with the information to associate the WEBSERVICE resource with a specific URI. The second URIMAP resource is optional and provides CICS with the information to associate the WSDL archive file or WSDL document with a specific URI so that external requesters can use the URI to discover the WSDL archive file or WSDL document. The pickup directory of the PIPELINE scan occurs when the PIPELINE resource is installed or as a result of a PERFORM PIPELINE SCAN command.
A TCPIPSERVICE resource is required when the HTTP transport is used. When the WebSphere® MQ transport is used, a TCPIPSERVICE resource is not required.
A URIMAP resource is optional for a service requester, and the CICS web services assistant does not generate one automatically. When you define your own URIMAP resources for service requesters to use, you can implement connection pooling, and manage changes to the URIs for service providers.

Configuring TCPIP resource attributes in a certain way might enable inbound requests being processed by directly attached user transactions, and bypassing the web attach task. For more information, see HTTP requests are processed by directly attached user transactions.

Typically, when you deploy many web services applications in a CICS system, you have more than one of each type of resource. In this case, you can share some resources between applications. Each web services file or resource is associated with one or more CICS resources of other types.

Table 1. Other CICS resources that are associated with each web services file and resource
Web services file or resource	Associated resources
Pipeline configuration file	More than one PIPELINE resource that refers to the file.
PIPELINE	More than one URIMAP resource that refers to the PIPELINE resource. More than one WEBSERVICE resource that refers to the PIPELINE resource. More than one web service binding file in the pickup directory of the PIPELINE resource.
Web service binding file	One URIMAP resource that is automatically generated from the binding file. You can define further URIMAP resources for a service provider, and you can define URIMAP resources for a service requester. One WEBSERVICE resource that is automatically generated from the binding file. You can define further WEBSERVICE resources if you need to.
WEBSERVICE	More than one URIMAP resource. If the WEBSERVICE resource is automatically generated from the binding file for a service provider, CICS generates one corresponding URIMAP resource. You can define further URIMAP resources for a service provider, and you can define URIMAP resources for a service requester.
URIMAP	Just one TCPIPSERVICE resource when it is explicitly named in the URIMAP resource.
TCPIPSERVICE	Many URIMAP resources.