In a service provider pipeline, CICS® extracts the relative URI from the incoming message and places it in the DFHWS-URI container.
For example, if the URI of the web services is http://example.com/location/address or jms://queue?destination=INPUT.QUEUE&targetService=/location/address, the relative URI is /location/address.
In a service requester pipeline, CICS puts the URI that is specified on the INVOKE SERVICE command, or, if missing, the URI from the web service binding, in the DFHWS-URI container. You can override this URI by using a message handler in the pipeline.
A service can use an HTTP, HTTPS, JMS, or WMQ URI for external services. A service can also use a CICS URI for a service that is provided by another CICS application:
| URI | Query string | Description |
|---|---|---|
| cics://PROGRAM/program | ?options | The CICS transport handler uses an EXEC CICS LINK PROGRAM command to link to the specified program, passing the current channel and containers. No data transformation takes place on the application data. |
| cics://SERVICE/service | ?targetServiceUri=targetServiceUri&options | The CICS transport
handler uses the path of the service, expressed as the targetServiceUri,
to match a URIMAP resource to run the request through a provider pipeline. You must specify a value for the targetServiceUri parameter if you use this URI type. |
| cics://PIPELINE/pipeline | ?targetServiceUri=targetServiceUri | The CICS transport handler starts another service requester pipeline. |
You can add parameters to each type of CICS URI using the format parameter=value, where each parameter is separated by an ampersand. The following rules apply to the CICS URI:
The parameters on the query string determine how CICS processes the request at the end of the requester pipeline:
| Destination type | Parameters on URI | |
|---|---|---|
| PROGRAM | userid | Optional |
| transid | Optional | |
| maxCommareaLength | Optional | |
| newTask | Optional. Must be yes or not specified at all if you specify userid or transid. | |
| targetServiceUri | Not supported | |
| SERVICE | userid | Optional |
| transid | Optional | |
| maxCommareaLength | Not supported | |
| newTask | Optional. Must be yes or not specified at all if you specify userid or transid. | |
| targetServiceUri | Required | |
| PIPELINE | userid | Not supported |
| transid | Not supported | |
| maxCommareaLength | Not supported | |
| newTask | Not supported | |
| targetServiceUri | Required | |
cics://PROGRAM/testapp?newTask=yes&userid=user1The transport handler links to the CICS program called testapp, passing the channel and containers. No data transformation takes place, so the target program must be able to process the contents of the containers on the current channel. CICS links to the program under a new unit of work and a different user ID of user1.
In this second example, the DFHWS-URI container has the following URI by the time it reaches the end of the pipeline:
cics://SERVICE/getStockQuote?targetServiceUri=/stock/getQuote&newTask=yes&userid=user2
The transport handler replaces the URI in the DFHWS-URI container with the value /stock/getQuote, finds the URIMAP using the path in the targetServiceUri parameter to resolve the URI, and starts the provider pipeline under a new task and different user ID.
In this third example, the DFHWS-URI container has the following URI by the time it reaches the end of the pipeline:
cics://PIPELINE/reqpipeA?targetServiceUri=cics://PROGRAM/testapp?newTask=yes%26userid=user1The transport handler replaces the URI in the DFHWS-URI container with the value cics://PROGRAM/testapp?newTask=yes&userid=user1 and starts the requester pipeline called reqpipeA, passing the current channel and containers. The %26 characters escape the ampersand, so the transport handler puts the whole URI in the DFHWS-URI container.