Sending the request message in containers

The service requester can send the request message in a series of containers using a channel when using DPL. You do not have to remodel or redeploy your service flows to use channels and containers.

About this task

To send the request message in containers, follow these steps:

Procedure

  1. 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 service flow that you want to invoke in the DFHMAC-REQUESTV1 container, and the application data in the DFHMAC-USERDATA container. The request name must match the PROCESSTYPE resource that is defined in CICS SFR for the service flow. 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 CICS SFR interface 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 service flow as a Web service provider application. For details on how to do this, see Invoking a service flow 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.
  2. 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 service flow.
    1. To process the request message using a different process type, change the request name, or change the process name using the DFHMAC-SYSPARMV1 container.
      • Specify a different process type to override the PROCESSTYPE resource that is defined in CICS for the service flow. By default, the request name that is passed in DFHMAC-REQUESTV1 matches the PROCESSTYPE resource of the service flow.
      • 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 must be a unique identifier. By default, CICS generates a unique identifier when the BTS process is created by the interface program.
      Specifying one of these options overrides the values associated with the service flow when the request message is received.
    2. 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.
  3. 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 interface program DFHMADPL. For example, you could specify the following commands:
    * 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)
    When CICS SFR has processed the request message, DFHMADPL places the response in the appropriate container that holds the application data. For example, if the service requester passed the application data in DFHMAC-USERDATA, DFHMADPL places the response in this container for the service requester to retrieve. It also updates the message header. If an error occurs, DFHMADPL passes the DHFMAC-ERROR container 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, the error is also reported in these containers.
  4. Use the channel and containers CICS API commands in your service requester application to retrieve the response. For example, you could specify the following commands:
    * 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 must ensure that your service requester can handle any error that is reported in the DFHMAC-ERROR container.


dfhcr_sending_containers.html | Timestamp icon Last updated: Sunday, 4 June 2017