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");
}