Connection interfaces (overview)

BeanConnect provides the following connection interfaces:

• EISConnection

• EISOltpConnection

• EISUpicConnection (only if the EIS partner is an UTM application)

The EISOltpConnection interface extends the EISConnection interface by providing additional features such as data structure characteristics, for details see "Additional functionality provided by the EISOltpConnection interface").

The EISUpicConnection interface extends the EISConnection interface by providing additional features such as data structure features (for details see "Additional functionality provided by the EISUpicConnection interface").

It is recommended that you use the EISOltpConnection and EISUpicConnection interfaces only if you use the additional functionality offered by these interfaces.

Communication methods provided by the EISConnection interface

The EISConnection interface is extended by a number of interfaces. Each of them provides methods for outbound communication between the EJB and the EIS application. For data exchange, these methods are snd(), rcv(), call() and a number of variants of snd() and rcv() such as sndString() or rcvRecord().

The communication methods offered by these interfaces differ in the data format on which the methods are based:

• For byte-array-oriented access to EIS applications:

  EISConnectionByteArray

• For byte-container-oriented access to EIS applications:

  EISConnectionByteContainer

  An application may use the EISConnectionByteContainer interface and implement the ByteContainer interface if it wants to exchange structured objects containing text and binary information with a service in a partner application. Code conversion needs to be performed for the text information of this object within the class that implements the ByteContainer interface.

  By providing an appropriate ByteContainer object, byte stream to string conversion is handled while executing the sndRecord(), rcvRecord() or call() methods. The objects you can obtain from Cobol2Java are objects that use this feature (see Cobol2Java).

• For OLTP message-oriented access to EIS applications:

  EISConnectionOltpMessage

  Objects of type OltpMessage are exchanged with the EISapplication over this interface. The OltpMessage object serves as a container for the message content, which is assembled from one or more OltpMessageRecord objects and/or one or more OltpMessagePart objects. While an OltpMessageRecord is of arbitrary length, an OltpMessagePart may not exceed 32,767 bytes. OltpMessagePart objects are mapped to message parts by an UTM partner application.

  OltpMessageRecord objects and OltpMessagePart objects accept the following data types:

  • byte[]

  • String

  • ByteContainer

• For string-oriented access to EIS applications:

  EISConnectionString

For code conversion in the course of the communication process the EncodingDef interface is available.

For detailed information concerning these interfaces, please refer to the JavaDoc of BeanConnect.

Additional functionality provided by the EISOltpConnection interface

The EISOltpConnection interface extends the EISConnection interface by providing the following additional functionality:

• Methods that are specific for asynchronous communication (see "Asynchronous communication" in Communication using the connection interfaces): setDelayTime(), getDelayTime()

• The method setEndConversation()
  The method specifies whether the EIS partner application may or may not terminate the current conversation with the next send...() call.

To make use of the additional functionality offered by the EISOltpConnection interface you have to cast the EISConnection object, which you obtain when you call the object EISConnectionFactory with getConnection(), as type

con = (EISOltpConnection)cf.getConnection(...);

Additional functionality provided by the EISUpicConnection interface

The EISUpicConnection interface is only relevant if the EIS partner is an UTM application. It extends the EISConnection interface by providing the following additional functionality:

• "Emulation" of terminal functions

  UTM conversations which were programmed for terminals can also be addressed with the aid of BeanConnect. “Emulation” of terminal functions is only possible with the EISUpicConnection interface. Terminal functions such as function keys and cursor positions can be handled using this interface.

• Using format names (format identifiers) when sending or receiving data

  When data is exchanged between the resource adapter and the UTM partner application, it is possible to also send format names (format identifiers). Thus the resource adapter can send to or receive from the UTM partner structure information about the data along with the user data itself. This function is only supported if the requested service uses the KDCS interface.

• Restart functionality

  The UTM partner application performs an automatic service restart for userIDs that have been defined with the USER control statement in conjunction with the RESTART=YES operand.

• The method isInTransaction() which is used to query the transaction status at the EIS partner.

To make use of the additional functionality offered by the EISUpicConnection interface, you have to cast the EISConnection object (which you get calling the getConnection() method on the EISConnectionFactory object) to the type EISUpicConnection:

con = (EISUpicConnection)cf.getConnection(...);