
Developing for asynchronous requests
When you develop applications for use with the CICS® asynchronous API, you will need to consider the flow of the asynchronous API commands and the available options for each command. Channel handling must also be considered if you want to pass input or receive responses as part of an asynchronous request.
Using the asynchronous API commands
You can develop a CICS application using the asynchronous API commands to start one or more child tasks and fetch responses from them.
In the example on this page, we use a credit card application to demonstrate how the commands can be used.
Start the credit check child tasks
- Put the customer details onto a new channel:.
EXEC CICS PUT CONTAINER('CUSTDETAILS') CHANNEL(customerDetails) - Call the first credit check service with a channel:
EXEC CICS RUN TRANSID('CRD1') CHILD(creditCheck1_tkn) CHANNEL(customerDetails) - Call the second credit check service with the same channel:
EXEC CICS RUN TRANSID('CRD2') CHILD(creditCheck2_tkn) CHANNEL(customerDetails)
A parent program can continue with other processing after issuing an EXEC CICS RUN TRANSID command, and can issue an EXEC CICS FETCH command at any point afterward to retrieve the results of a child task.
Getting a response from a specific child task
- Fetch the response from the first
child:
EXEC CICS FETCH CHILD(creditCheck1_tkn) CHANNEL(credReply1_chan) COMPSTATUS(credReply1_status)In this case, parent processing is blocked until the child task returns a result. Use of the optional parameters NOSUSPEND and TIMEOUT can prevent or limit blocking as preferred.
- Check the response code of the EXEC CICS FETCH CHILD command to ensure the command executed normally.
- If the EXEC CICS FETCH CHILD command executed normally, then check the
COMPSTATUS of the child to ensure it completed successfully.
- If COMPSTATUS indicates that the child task completed successfully, then get
the response from the reply
channel.
EXEC CICS GET CONTAINER('RESULT') CHANNEL(credReply1_chan) - If COMPSTATUS indicates that the child task abended, then the logic of the parent application should decide what to do. CICS will clean up all resources when the parent transaction completes.
- If COMPSTATUS indicates that the child task completed successfully, then get
the response from the reply
channel.
- Repeat steps 1 through 3 for the second child task.
Getting a response from any completed child task
It's also possible to fetch a response from any completed child task using the EXEC CICS FETCH ANY command, which will return the result of whichever child task completed first:
EXEC CICS FETCH ANY(creditCheck_tkn) CHANNEL(credReply_chan) COMPSTATUS(credReply_status)
Check the completion of the FETCH ANY command and the child's COMPSTATUS as normal.
Freeing a child
As part of your parent task, you can choose to free child tasks, which will tidy up the associated resources and keep system storage use to a minimum, which is especially useful for long-running parent tasks. If, for example, you started three child tasks, but only need the results of one, then you can clean up the remaining two child tasks using FREE CHILD.
EXEC CICS FREE CHILD(creditCheck1_tkn)
EXEC CICS FREE CHILD(creditCheck2_tkn)
Optional parameters
EXEC CICS RUN TRANSID- CHANNEL is optional. Use it to:
- Pass data to a child.
- Receive data from a child.
- Both pass and receive data to and from a child.
- RESP is optional. Use it to see if a command executed successfully.
- CHANNEL is optional. You can use it to receive data from a child task, as long as a channel was supplied on the initial RUN TRANSID command.
- NOSUSPEND is optional. Use it to stop a FETCH command from blocking: the command will return immediately regardless of whether a child task has completed.
- TIMEOUT is optional. Use it to make a FETCH command wait for a specified amount of time before returning.
- ABCODE is optional. If COMPSTATUS indicates that a child has abended, then ABCODE will contain the abend code of the child.
Using channels with asynchronous API commands
The following steps are an example of how input and output are passed between parent and child tasks using channels.
- The parent task, PROGP1, passes input to a child task in a channel, and then
links it to another
program.
EXEC CICS PUT CONTAINER('REQ') FROM(REQUEST) CHANNEL('ASYNC-CHANNEL') EXEC CICS RUN TRANISD('CHILD') CHANNEL('ASYNC-CHANNEL') CHILD(CHILD-TOKEN) EXEC CICS LINK PROGRAM('PROGP2')A copy of the ASYNC-CHANNEL created by the parent is passed to the child, and the copy becomes the current channel for the child's initial program. The name of the channel is retained by the copying process, so if the child program PROGC1 issued EXEC CICS ASSIGN CHANNEL then ASYNC-CHANNEL would be returned.
- The child task, PROGC1, gets the input from its current
channel:
EXEC CICS GET CONTAINER('REQ')The child will then continue with its logic, generate a response for the parent task, and then put it into a container within its current channel:
EXEC CICS PUT CONTAINER('RESP') FROM(RESPONSE) EXEC CICS RETURN - The parent task, PROGP2, fetches the child response and continues with some
business logic before returning to
PROGP1:
EXEC CICS FETCH CHILD(CHILD-TOKEN) CHANNEL (FETCHED-CHANNEL) EXEC CICS GET CONTAINER('RESP') CHANNEL(FETCHED-CHANNEL)When the parent task fetches the response channel from the child, CICS generates a unique channel name and binds the channel to the current program link level. In this example, the fetched channel will be owned by PROGP2. When PROGP2 returns to PROGP1, the fetched channel will be deleted by CICS. A child's response channel can only be fetched once by the parent task.
