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 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.
  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 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.
  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 adapter service.
    1. 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.
    2. 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.
  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 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.

  4. 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.