About the asynchronous API

CICS® TS 5.4 provides a set of new asynchronous API commands which allow application developers to use asynchronous programming model that can run child tasks asynchronously.

Elements of the asynchronous API

The asynchronous API consists of the following elements:

API commands to send requests and receive responses.
Parent tasks that issue EXEC CICS RUN TRANSID and EXEC CICS FETCH commands to start and interact with child tasks.
A FREE CHILD command to release the resources associated with a child prior to the parent program completing.
Child tasks that run asynchronously to the parent task as a separate unit of work. Each parent can have one or more children.
Channels that can be optionally used to pass data between parent and child tasks if required.

The asynchronous API manages the state of parent and child tasks, cleans up all associated resources, and manages data in channels as standard. Use of the API can have major benefits for historically long-running tasks, such as web services applications, who can instead create and free child tasks as and when required to minimize their system footprint.

How the asynchronous API works

A parent task is any task running a program which uses the EXEC CICS RUN TRANSID and EXEC CICS FETCH commands to start and interact with child tasks. This example parent program uses the EXEC CICS PUT CONTAINER command to create a container and a channel to communicate with the child program, and then creates a child task with the EXEC CICS RUN TRANSID command, which will run the child program defined by transid. The child program receives a copy of the channel specified and begins processing, leaving the parent program available to continue with any other logic. The EXEC CICS FETCH CHILD command can be issued by the parent when it requires the result or completion status of the child task. If the child task has successfully completed and passed a channel back, then the EXEC CICS GET CONTAINER command is used to retrieve the output.

EXEC CICS PUT CONTAINER(container) CHANNEL(channel)
                    FROM(struct)  FLENGTH(len_struct) BIT
                    RESP(reason) RESP2(response)

EXEC CICS RUN TRANSID(transid) CHILD(child)
            CHANNEL(channel) RESP(reason) RESP2(response)

…

EXEC CICS FETCH CHILD(child)
                  ABCODE(abcode)
                  COMPSTATUS(child_status)
                  CHANNEL(fetch_channel)
                  RESP(reason) RESP2(response)

EXEC CICS GET CONTAINER(container) CHANNEL(fetch_channel)
                      INTO(struct) FLENGTH(len_struct)
                      RESP(reason) RESP2(response)

A child program can use CICS API commands as normal, but will typically use the EXEC CICS GET CONTAINER and EXEC CICS PUT CONTAINER commands to interact with the parent program. This example child program uses the EXEC CICS GET CONTAINER command to retrieve the container passed by the parent program, runs some other logic to modify the contents (...), and then uses the EXEC CICS PUT CONTAINER command to send the result back to be consumed by the parent.

EXEC CICS GET CONTAINER(container) CHANNEL(channel)
                INTO(struct) FLENGTH(len_struct)
                RESP(reason) RESP2(response)

 ...

  EXEC CICS PUT CONTAINER(container) CHANNEL(channel)
                FROM(struct) FLENGTH(len_struct) BIT
                RESP(reason) RESP2(response)

Using channels to communicate between parent and child programs is optional. If a parent program only needs to know whether a child task has completed successfully, for example, then the EXEC CICS FETCH command is sufficient.