Using JCICS with the asynchronous API

The JCICS variant of the CICS asynchronous API is provided as a set of classes, and an implementation of the java.util.concurrent.Future interface.

Java variants of all the EXEC CICS asynchronous API commands are provided in the following classes:

AsyncService
AsyncServiceImpl
ChildResponse

To start a child transaction from a Java program, you must first get a new instance of AsyncService before starting the child transaction. No state is persisted in the AsyncServiceImpl class, so Future objects are not scoped to their instance of AsyncService.

AsyncService asService = new AsyncServiceImpl();
Future<ChildResponse> child = asService.runTransactionId("ABCD");

The resulting Future object can be used as normal, although methods that relate to the canceling of child tasks are not supported.

runTransactionId() is non-blocking, but get() is designed to comply with the Future interface and will block.

Unlike the CICS API implementation, the get() or getAny() invocation always attempts to retrieve a channel from the child, and ownership of the channel will be immediately transferred to the parent task.

To receive information back from a child task, you can use the get() method. For example:

ChildResponse response = child.get();

ChildResponse provides the following methods:

getAbendCode()
getChannel()
getCompletionStatus()

ChildResponse also includes an enum, CompletionStatus, to enumerate the possible CVDA values returned by the child task.

Table 1.
Java Class	Method	Equivalent CICS API
`AsyncService`	`runTransactionId(String transactionId)` `runTransactionId(String transactionId, Channel channel)`	RUN TRANSID RUN TRANSID CHANNEL
`AsyncService`	`freeChild(ChildResponse child)` `freeChild(Future<ChildResponse> child)`	FREE CHILD FREE CHILD
`ChildResponse`	`ChildResponse.getAny()` `ChildResponse.getAny(BlockingAction blockingAction)` `ChildResponse getAny(long timeout, TimeUnit timeUnit)`	FETCH ANY CHANNEL COMPSTATUS ABCODE FETCH ANY NOSUSPEND CHANNEL COMPSTATUS ABCODE FETCH ANY TIMEOUT CHANNEL COMPSTATUS ABCODE
`Future<ChildResponse>`	`get()` `get(long timeout, TimeUnit timeUnit)`	FETCH CHILD CHANNEL COMPSTATUS ABCODE FETCH CHILD CHANNEL COMPSTATUS ABCODE TIMEOUT
`Future<ChildResponse>`	`isDone()`	FETCH CHILD NOSUSPEND COMPSTATUS

Example

final String childTransaction = "ABCD";
AsyncService asService = new AsyncServiceImpl();

Future<ChildResponse> child = asService.runTransactionId(childTransaction);

// Logic here to be processed while the child runs asynchronously 

ChildResponse response = child.get();
if (response.getCompletionStatus().equals(CompletionStatus.NORMAL)) {
  System.out.println("Child task completed normally");
}