Context switch within a service provider pipeline

When a service provider pipeline runs, it is possible for a context switch to occur. This happens only when the terminal handler (<terminal_handler>) is one of the CICS®-provided SOAP handlers. The context switch causes the program named in the <apphandler> element to run in a separate task.

A context switch occurs if any of the following conditions are met:

The user ID is changed by supplying a new value in the DFHWS-USERID container. Note that the user ID could be changed by the CICS <wsse_handler> if WS-Security is being used.
The transaction ID is changed by supplying a new value in the DFHWS-TRANID container.
The web service request requires use of Web Services Atomic Transactions (WS-AT).

The context switched task can run locally in the same region or remotely over an MRO connection. The TRANSACTION definition for the context switched task must exist. CICS always ensures that the correct program is executed for the context switched task so the PROGRAM attribute can be set to XXXXXXXX. This allows the same transaction id to be used for multiple different web service requests if needed.

Considerations for running the context switched task locally

When the context switched task runs locally, consider the following:

Each web service request requires two tasks, the initial pipeline task and the context switched task. You need to ensure that the MXT is sized appropriately to allow for the correct number of tasks to run based on the expected number of concurrent requests. Note that while the context switched task runs, the initial pipeline task will be suspended on resource PIIS RZCBNOTI. For example, to process 50 concurrent requests, you need to set the MXT to at least 100.
The TCLASS is a useful mechanism to prevent the CICS region from being flooded by web service requests. If a TCLASS is used, when a context switch occurs, it is essential that the transaction ID is changed. If the transaction ID is not changed, it's possible that a flood of requests might fill the available TCLASS slots with initial pipeline tasks. When this occurs, the context switched tasks will be suspended waiting for a TCLASS slot in order to run. This has the effect of deadlocking the system. Note that only the initial pipeline tasks need to be in a TCLASS. The context switched tasks are naturally limited by the number of initial pipeline tasks that can run.
Set a suitable DTIMOUT value for the initial pipeline tasks. This ensures that the task eventually times out if the context switched task is not responsive or leaves the system unexpectedly.

Considerations for running the context switched task remotely

When the context switched task runs remotely, consider the following:

You will need to install the PIPELINE and WEBSERVICE resources in the target remote region.
When the context switched task runs in a remote region the origin data for the initial pipeline task is not sent to that region.

Changing the transaction ID of the context switched task

If you need to change the transaction ID of the context switched task, you have to use a PIPELINE handler program or a SOAP header handler program to do that. The PIPELINE configuration file needs to be updated with the details of the handler program.

Here is an example PIPELINE handler program to change the transaction ID.

*ASM     XOPTS(CICS,SP)
DFHEISTG DSECT
#TRAN    DS    CL4
#LEN     DS    F
TRNHND   DFHEIENT
TRNHND   RMODE ANY
TRNHND   AMODE 31
         MVC  #TRAN,=CL4'CTXT'
         EXEC CICS GET CONTAINER('DFHFUNCTION') SET(6) FLENGTH(#LEN)
         CLC  0(15,6),=C'RECEIVE-REQUEST'
         BNE  RETURN
         EXEC CICS PUT CONTAINER('DFHWS-TRANID') FROM(#TRAN) FLENGTH(4)
         EXEC CICS DELETE CONTAINER('DFHRESPONSE')
RETURN   DS   0H
         EXEC CICS RETURN
         END