Implementing the session interface

You can set the session on a terminal by either using the setSession method, or by passing the session object as part of a send or connect method.

null is also accepted as a session, meaning that you have no listening object in place for replies and exceptions, and that all calls are synchronous.

The session interface defines two methods that must be implemented: getSyncType and handleReply. The following code shows a sample implementation:

import com.ibm.ctg.epi.*;
public class myASession implements Session {
    public int getSyncType() {
        return Session.async;
    }
    public void handleReply(TerminalInterface term) {
        System.out.println(
          "Reply received Terminal state = " + term.getState());
    }
    public void handleException(TerminalInterface a, Exception e) {
       System.out.println("Exception received:" + e.getMessage());
    }
}

This example defines the session as an asynchronous session, because it returns Session.async on the getSyncType call. To make the session a synchronous session, you return Session.sync.

The example shows the handleReply and handleException methods:

handleReply

You must implement the handleReply method. It is called for each transmission received from CICS®. Depending on the design of the CICS server program, a Terminal send call can result in one or more replies. The Terminal state property indicates whether the server has finished sending replies:

Terminal.server

Indicates that the CICS server program is still running and has further data to send. The client application can process the current screen contents immediately, or simply wait for further replies. The application cannot delete the terminal, or send the screen to CICS, or start a new transaction.

Terminal.client

Indicates that the CICS server program is now waiting for a response. The client application should process the screen contents and send a reply. The application cannot delete the terminal or start a new transaction.

Terminal.idle

Indicates that the CICS server program has completed. The client application should process the screen contents and either delete the terminal or start a further transaction.

Terminal.failed

Indicates that the transaction has failed to start or complete for some reason, for example, a conversion transaction has timed-out waiting for a response from the application. Call the endReason and endReasonString methods for more information.

Terminal.discon

Indicates that the terminal has been deleted. Call the endReason and endReasonString methods for more information.

Terminal.error

Indicates that the terminal is in error state and cannot be used. Try to delete the terminal to ensure that all terminal resources are cleaned up.

Most Java™ Client applications wait until the CICS server program has finished sending data (that is, the Terminal state is client or idle) before processing the screen. However, some long-running server programs might send intermediate results or progress information that can usefully be accessed while the Terminal state is still server.

The implementation of the handleReply method can read and process data from the Screen object, update fields as required, set the cursor position and AID key in preparation for the return transmission to CICS, and then use the Terminal send method to drive the server application.

In synchronous mode, handleReply executes on the same thread that invoked the send. In asynchronous mode, handleReply executes on a separate thread.

Note: The handleReply method should never attempt to delete a terminal. The disconnect call might make the application hang if called from handleReply.

handleException

The handleException method is not specified as part of the session interface and is optional unless you are using asynchronous mode sends, when it must be implemented. The compiler does not force implementation of the method. The Terminal class calls this method if it is present in the Session object.

It is recommended that you also implement the handleException method for synchronous mode sends with Automatic Transaction Initiation (ATI) enabled.

For the handleReply method, the Terminal state property shows information about the terminal connection.

Exceptions are passed in the Exception object. See Exception handling, for a list of the exceptions that can occur.