Rational Developer for System z

DFHWS-URI container

DFHWS-URI is a container of DATATYPE(CHAR) that contains the URI of the service.

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.

If you are using Web services addressing in your provider pipeline, this container will be created and updated in the following order:
  1. When the INVOKE SERVICE command runs, it creates the DFHWS-URI container and initiates it with the value of the WSDL service endpoint address. If the WSACONTEXT BUILD API command was used to create an addressing context, you must not specify the URI or URIMAP parameters on the INVOKE SERVICE command.
  2. When the Web services addressing handler (DFHWSADH) runs, if a <wsa:To> EPR exists in the addressing context with a non-anonymous URI, the URI in the DFHWS-URI container is overwritten with the value of the <wsa:To> EPR. The anonymous URI is ignored.

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:

maxCommareaLength=value
Specify the maximum size of the COMMAREA in bytes, that is required for the target application program. The value must not exceed 32 763. If this parameter is present in the query string, CICS links to the specified program using a COMMAREA. If this parameter is not present in the query string, CICS links to the specified program using a channel.
This parameter not case-sensitive and is valid only for the cics://PROGRAM URI.
newTask=yes|no
Specify whether the transport handler will run the request as a new task.
This parameter is not case-sensitive. cics://PROGRAM/testapp?newTask=yes and cics://PROGRAM/testapp?NEWTASK=Yes are the same.
targetServiceUri=uri
Specify the path of the service to be called. On a SERVICE destination type, the transport handler uses the value with host=localhost to locate the URIMAP resource to start a service provider pipeline. On a PIPELINE destination type, the transport handler uses the value to start another requester pipeline.
This parameter is case-sensitive.
transid=char(4)
Specify a transaction under which the request will run. The transport handler starts a request stream using the specified transaction ID.
This parameter is case-sensitive.
userid=char(8)
Specify a user ID under which the request will run. The transport handler starts a request stream using the specified user ID.
This parameter is not case-sensitive.
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

Examples of CICS URIs

In this first example, the DFHWS-URI container has the following URI by the time it reaches the end of the pipeline:
cics://PROGRAM/testapp?newTask=yes&userid=user1
The 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=user1 
The 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.

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)