The service requester can send the request message in a series
of containers using a channel when using DPL. You do not need to remodel your
flows or redeploy adapter services to use channels and containers.
You must have APAR PK32131 applied to pass the request message to CICS® SFR using channels
and containers.
- Decide which set of mandatory containers you want to use to pass
the request message. You can select one of the following options:
- Pass the request name of the adapter service
that you want to invoke in the DFHMAC-REQUESTV1 container, and the application
data in the DFHMAC-USERDATA container. The request name should match the PROCESSTYPE
resource that is defined in CICS SFR for
the adapter service. When you select this option, the runtime environment
processes the request message using default values. These defaults assume
that the process type is the same as the request name, and that the process
name can be uniquely generated by the DPL stub program. You can override these
default values using additional containers.
- Pass the request name and application data in the DFHWS-DATA container
as a Web service request. Use this option when you are exposing your adapter
service as a Web service provider application. For details on how to do this,
see Invoking an adapter service from a Web service.
- Pass the message header and application data in the DFHMAC-ALLPARMS
container. This container is primarily provided as a migration aid to help
you move from a COMMAREA to channels and containers. Use this container to
pass the DFHMAH header to CICS SFR.
You can pass the application data after the DFHMAH header in this container,
or pass it in DFHMAC-USERDATA instead.
- If your request message requires passthrough processing, use the DFHMAC-PASSTHRU
container. This container should contain the DFHMAH and DFHMAH2 headers and
should be followed by any screen vectors.
- Optional: If you choose to use the DFHMAC-REQUESTV1
or DFHWS-DATA container, you can use optional containers to override some
of the default values associated with the adapter service.
- If you want to process the request message using a different
process type, change the request name, or change the process name, use the
DFHMAC-SYSPARMV1 container.
- Specify a different process type to override the PROCESSTYPE resource
that is defined in CICS for the adapter service. By default the request name
that is passed in DFHMAC-REQUESTV1 matches the PROCESSTYPE resource of the
adapter service.
- Specify a different request name to override the value that is passed
in the DFHMAC-REQUESTV1 or DFHWS-DATA container.
- Specify a different process name. This should be a unique identifier.
By default, a unique identifier is generated by CICS when the BTS process
is created by the stub program.
This overrides the values associated with the adapter
service when the request message is received.
- If you want to pass in a state token to reuse an allocated Link3270
bridge facility, use the DFHMAC-LNK3270V1 container. If you do
not include this container, the Link3270 server adapter creates a new instance
of the Link3270 bridge facility.
- When you have decided on the correct container combination, use
the channel and containers CICS API commands in your service requester application
to create the required containers and link to the DFHMADPL stub program. For example, you could specify:
* Create base request container
EXEC CICS PUT CONTAINER(‘DFHMAC-REQUESTV1’)CHANNEL(MY-CHANNEL) FROM(…)
* Optionally create user data container
EXEC CICS PUT CONTAINER(‘DFHMAC-USERDATA’) CHANNEL(MY-CHANNEL) FROM(…)
* DPL to server adapter via CICS SFR
EXEC CICS LINK PROGRAM(‘DFHMADPL’) CHANNEL(MY-CHANNEL)
In the case of passthrough processing, DFHMADPL
invokes DFHMADPP to perform request processing. When the request message
has been processed, the response is placed in the appropriate container that
holds the application data. For example, if the service requester passed the
application data in DFHMAC-USERDATA, the response is placed in this container
for the service requester to retrieve. The message header is also updated.
If
an error occurs, the DHFMAC-ERROR container is passed back to the service
requester. This container holds the error message and other details that the
service requester can interpret. If you used DFHMAC-ALLPARMS or DFHMAC-PASSTHRU
the error is also reported in these containers.
- Use the channel and containers CICS API commands in your service
requester application to retrieve the response. For example,
you could specify:
* Retrieve error from container
EXEC CICS GET CONTAINER(‘DFHMAC-ERROR’) CHANNEL(MY-CHANNEL) SETPTR(…)
* Retrieve original request data from container
EXEC CICS GET CONTAINER(‘DFHMAC-REQUESTV1’) CHANNEL(MY-CHANNEL) SETPTR(…)
* Retrieve user data from container
EXEC CICS GET CONTAINER(‘DFHMAC-USERDATA’) CHANNEL(MY-CHANNEL) SETPR(…)
You should ensure that your service requester
can handle any error that is reported in the DFHMAC-ERROR container.