com.ibm.dse.services.otma
Class OTMAConnection

java.lang.Object
  |
  +--com.ibm.dse.base.DSENotifier
        |
        +--com.ibm.dse.base.Service
              |
              +--com.ibm.dse.services.otma.OTMAConnection

public class OTMAConnection
extends Service
implements OTMAConnectionService

This class allows a local application, located in OS/390 to communicate with IMS V6.1 .

See Also:
Serialized Form

Field Summary
static java.lang.String COMPID
          The component id.
static java.lang.String OTMA_WRAPPER_DLL
           
 
Fields inherited from class com.ibm.dse.base.Service
externalizer
 
Fields inherited from class com.ibm.dse.base.DSENotifier
handlersList, name
 
Fields inherited from interface com.ibm.dse.services.otma.OTMAConnectionService
ALLOC, automaticConnectionEstablishment, CLOSE, disabled, enabled, FREE, IMSMemberName, IMSModName, LISTEN_THREAD, lterm, numberOfResponseSegments, OPEN, receiveLength, SAFgroupName, SENDRECEIVE, sessions, TpipePrefix, transaction, userId, XCFgroupName, XCFMemberName
 
Fields inherited from interface com.ibm.dse.services.comms.CommonCommunicationsService
CLOSED, DATA, DATASENT, ERROR, OPENED, RECEIVERC, TIMEOUT
 
Constructor Summary
OTMAConnection()
          This constructor creates an OTMAConnection object.
OTMAConnection(java.lang.String aName)
          This constructor creates an OTMAConnection object.
 
Method Summary
 void ccClose()
          Closes the communications channel.
 void ccOpen()
          Opens the communications channel.
 CCMessage ccReceiveData(long timeout)
          This method does´nt have sense for this service.
 void ccSendData(java.lang.String aData)
          This method does´nt have sense for this service.
 CCMessage ccSendReceive(java.lang.String aData, long timeout)
          Sends a String to communication services, and waits for a Timeout to receive the data.
 void closeConnection()
          This method closes OTMA connection .
 boolean getAutomaticConnectionEstablishment()
          Gets the automaticSessionEstablishment property (java.lang.Boolean) value.
 java.lang.String getCcClosedEventName()
          Gets the name of de close event.
 java.lang.String getCcDataReceivedEventName()
          Gets the name of de data received event.
 java.lang.String getCcErrorReceivedEventName()
          Gets the name of de error event.
 java.lang.String getCcOpenedEventName()
          Gets the name of de open event.
 java.lang.String getIMSModName()
          Returns IMSModName passed to IMS, optional.
 java.lang.String getIMSName()
          Returns Server IMS XCF member name for this member.
 boolean getInUse()
          Returns true if there is no available sessions.
 java.lang.String getLTERM()
          Returns LTERM passed to IMS, optional.
 int getNumberOfResponseSegments()
          Returns number of segments sent by IMS.
 int getReceiveBufferLength()
          Returns length of buffer available to receive message.
 java.lang.String getSAFgroupName()
          Returns The SAF(Security Access Facility) group name to be passed to OTMA.
 int getSessionsNumber()
          Returns number of parallel sessions that are intended to be supported with IMS.
 java.lang.String getTpipePrefix()
          Returns first 1 to 4 characters of the TPIPE names.
 java.lang.String getTransaction()
          Returns name of IMS transaction or command to be sent to IMS.
 java.lang.String getUserId()
          Returns The SAF(Security Access Facility) user ID to be passed to OTMA.
 java.lang.String getXCFgroupName()
          Returns OTMA XCF Group Name (1 to 8 chars).
 java.lang.String getXCFMemberName()
          Returns Client XCF Member Name.
 java.lang.Object initializeFrom(Tag aTag)
          Initializes a OTMAConnection object with the aTag attributes.
 void initInstance()
          Loads dynamic link library used for OTMA C/I native calls and opends a connection to IMS if automaticConnectionEstablishment selected.
 boolean isAutomaticConnectionEstablishment()
          Returns true if automaticConnectionEstablishment property is enabled.
 boolean isFree()
          Returns if the session is free
 boolean isOffline()
          Returns if the session is offline
 void openConnection()
          This method establishes a multi-session OTMA connection.
 OTMAMessage sendReceive(java.lang.String aTransaction, Context aContext, FormatElement aFormat, long timeout)
          Sends data over this session to IMS and receives the output produced.
 OTMAMessage sendReceive(java.lang.String aTransaction, Context aContext, java.lang.String aFormatName, long timeout)
          Sends data over this session to IMS and receives the output produced.
 OTMAMessage sendReceive(java.lang.String aTransaction, java.lang.String aData, byte[] session, int[] sendSegmentList, long timeout)
          Sends data over this session to IMS and receives the output produced.
 OTMAMessage sendReceive(java.lang.String aTransaction, java.lang.String aData, byte[] session, long timeout)
          Sends data over this session to IMS and receives the output produced.
 OTMAMessage sendReceive(java.lang.String aTransaction, java.lang.String aData, int[] sendSegmentList, long timeout)
          Sends data over this session to IMS and receives the output produced.
 OTMAMessage sendReceive(java.lang.String aTransaction, java.lang.String aData, long timeout)
          Sends data over this session to IMS and receives the output produced.
 void setAutomaticConnectionEstablishment(boolean newAutomaticConnectionEstablishment)
          Sets the automaticSessionEstablishment property (java.lang.Boolean) value.
 void setIMSModName(java.lang.String newIMSModName)
          Sets the value of the IMSModName property.
 void setIMSName(java.lang.String newIMSName)
          Sets the value of the IMSName property.
 void setInUse(boolean anInUse)
          Sets the inUse property (boolean) value.
 void setLTERM(java.lang.String newLTERM)
          Sets the value of the LTERM property.
 void setNumberOfResponseSegments(int newNumberOfResponseSegments)
          Sets the value of the numberOfResponseSegments property.
 void setReceiveBufferLength(int newReceiveBufferLength)
          Sets length of buffer available to receive message.
 void setSAFgroupName(java.lang.String newSAFGroupName)
          Sets the value of the SAFgroupName property.
 void setSessionsNumber(int newSessionsNumber)
          Sets the value of the sessionsNumber property.
 void setTpipePrefix(java.lang.String newTpipePrefix)
          Sets the value of the tpipePrefix property.
 void setTransaction(java.lang.String newTransaction)
          Sets name of IMS transaction or command to be sent to IMS.
 void setUserId(java.lang.String newUserId)
          Sets the SAF(Security Access Facility) user ID to be passed to OTMA.
 void setXCFGroupName(java.lang.String newGroupName)
          Sets the value of the XCFgroupName property.
 void setXCFMemberName(java.lang.String newPartnerName)
          Sets the value of the partnerName property.
 void terminate()
          Terminates the internal resources and closes the conversation.
 java.lang.String toString()
          Returns a visual representation of this object.
 
Methods inherited from class com.ibm.dse.base.Service
externalizer, getExternalizer, getTagName, readExternal, readExternal, readObject, removeExternal, setExternalizer, toStrings, toTags, writeExternal, writeExternal
 
Methods inherited from class com.ibm.dse.base.DSENotifier
addHandler, getHandlersList, getName, removeHandler, setName, signalEvent, signalEvent, signalEvent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COMPID

public static final java.lang.String COMPID
The component id. Is used in the trace facilities.

OTMA_WRAPPER_DLL

public static final java.lang.String OTMA_WRAPPER_DLL
Constructor Detail

OTMAConnection

public OTMAConnection()
This constructor creates an OTMAConnection object.

OTMAConnection

public OTMAConnection(java.lang.String aName)
               throws java.io.IOException
This constructor creates an OTMAConnection object.
Parameters:
aName - java.lang.String
Throws:
java.io.IOException -  
Method Detail

ccClose

public void ccClose()
             throws DSECCException
Closes the communications channel. It returns control immediately.
Throws:
DSECCException - .

ccOpen

public void ccOpen()
            throws DSECCException
Opens the communications channel. It returns control immediately.
Throws:
DSECCException - .

ccReceiveData

public CCMessage ccReceiveData(long timeout)
                        throws DSECCException
This method does´nt have sense for this service.
Tags copied from interface: CommonCommunicationsService
Parameters:
aTimeout - long

ccSendData

public void ccSendData(java.lang.String aData)
                throws DSECCException
This method does´nt have sense for this service.
Tags copied from interface: CommonCommunicationsService
Parameters:
aString - java.lang.String

ccSendReceive

public CCMessage ccSendReceive(java.lang.String aData,
                               long timeout)
                        throws DSECCException
Sends a String to communication services, and waits for a Timeout to receive the data.
Parameters:
aData, - Data to be sent to IMS.
timeout, - time interval to wait for this request.
Returns:
CCMessage
Throws:
DSECCException. -  

closeConnection

public void closeConnection()
                     throws DSEOTMAException
This method closes OTMA connection . It is called to free storage for communication and to leave XCF group. This function may be called when communications are in flight or an openConnection is processing. When connection is closed, event CLOSED is signaled.
Specified by:
closeConnection in interface OTMAConnectionService
Throws:
DSEOTMAException - if OTMA C/I error produced.

getAutomaticConnectionEstablishment

public boolean getAutomaticConnectionEstablishment()
Gets the automaticSessionEstablishment property (java.lang.Boolean) value. If automaticConnectionEstablishment set to true connection established automatically . Default to false.
Specified by:
getAutomaticConnectionEstablishment in interface OTMAConnectionService
Returns:
The automaticSessionEstablishment property value.
See Also:
#setAutomaticSessionEstablishment

getCcClosedEventName

public java.lang.String getCcClosedEventName()
Gets the name of de close event.
Returns:
java.lang.String. The name of the closed event.

getCcDataReceivedEventName

public java.lang.String getCcDataReceivedEventName()
Gets the name of de data received event.
Returns:
java.lang.String. The name of the data received event.

getCcErrorReceivedEventName

public java.lang.String getCcErrorReceivedEventName()
Gets the name of de error event.
Returns:
java.lang.String. The name of the error event.

getCcOpenedEventName

public java.lang.String getCcOpenedEventName()
Gets the name of de open event.
Returns:
java.lang.String. The name of the opened event.

getIMSModName

public java.lang.String getIMSModName()
Returns IMSModName passed to IMS, optional.
Specified by:
getIMSModName in interface OTMAConnectionService
Returns:
java.lang.String - The current value of IMSModName.

getIMSName

public java.lang.String getIMSName()
Returns Server IMS XCF member name for this member. (char[16]). Mandatory.
Specified by:
getIMSName in interface OTMAConnectionService
Returns:
java.lang.String - The current value of IMSName.

getInUse

public boolean getInUse()
Returns true if there is no available sessions.
Returns:
boolean

getLTERM

public java.lang.String getLTERM()
Returns LTERM passed to IMS, optional.
Specified by:
getLTERM in interface OTMAConnectionService
Returns:
java.lang.String

getNumberOfResponseSegments

public int getNumberOfResponseSegments()
Returns number of segments sent by IMS. Default value set to 4.
Specified by:
getNumberOfResponseSegments in interface OTMAConnectionService
Returns:
int

getReceiveBufferLength

public int getReceiveBufferLength()
Returns length of buffer available to receive message. If message received is longer that this length , the message is truncated. Default value set to 4096.
Specified by:
getReceiveBufferLength in interface OTMAConnectionService
Returns:
int

getSAFgroupName

public java.lang.String getSAFgroupName()
Returns The SAF(Security Access Facility) group name to be passed to OTMA. Optional.
Specified by:
getSAFgroupName in interface OTMAConnectionService
Returns:
java.lang.String - The current value of SAFgroupName.

getSessionsNumber

public int getSessionsNumber()
Returns number of parallel sessions that are intended to be supported with IMS. Long integer from 001 to 999. Default to 10.
Specified by:
getSessionsNumber in interface OTMAConnectionService
Returns:
int - The current value of sessionsNumber.

getTpipePrefix

public java.lang.String getTpipePrefix()
Returns first 1 to 4 characters of the TPIPE names. Mandatory.
Specified by:
getTpipePrefix in interface OTMAConnectionService
Returns:
java.lang.String - The current value of TpipePrefix.

getTransaction

public java.lang.String getTransaction()
Returns name of IMS transaction or command to be sent to IMS. If it's not specified in SGML file it has to be specified in the corresponding sendReceive method.
Specified by:
getTransaction in interface OTMAConnectionService
Returns:
java.lang.String

getUserId

public java.lang.String getUserId()
Returns The SAF(Security Access Facility) user ID to be passed to OTMA. For example RACF user ID. Optional.
Specified by:
getUserId in interface OTMAConnectionService
Returns:
java.lang.String

getXCFgroupName

public java.lang.String getXCFgroupName()
Returns OTMA XCF Group Name (1 to 8 chars). Mandatory.
Specified by:
getXCFgroupName in interface OTMAConnectionService
Returns:
java.lang.String - The current value of XCFgroupName.

getXCFMemberName

public java.lang.String getXCFMemberName()
Returns Client XCF Member Name. Mandatory.
Specified by:
getXCFMemberName in interface OTMAConnectionService
Returns:
java.lang.String - The current value of XCFMemberName.

initializeFrom

public java.lang.Object initializeFrom(Tag aTag)
                                throws java.io.IOException,
                                       DSEException
Initializes a OTMAConnection object with the aTag attributes.
Overrides:
initializeFrom in class Service
Parameters:
aTag - com.ibm.dse.base.Tag
Returns:
Object - An instance of OTMAConnection.
Throws:
java.io.IOException. -  
com.ibm.dse.base.DSEException. -  

initInstance

public void initInstance()
                  throws java.lang.UnsatisfiedLinkError,
                         DSEOTMAException
Loads dynamic link library used for OTMA C/I native calls and opends a connection to IMS if automaticConnectionEstablishment selected.
Specified by:
initInstance in interface OTMAConnectionService
Throws:
java.lang.UnsatisfiedLinkError - if dynamic Link Library not found in path.
DSEOTMAException - if automaticConnectionEstablishment enabled and an error is produced opening the connection.

isAutomaticConnectionEstablishment

public boolean isAutomaticConnectionEstablishment()
Returns true if automaticConnectionEstablishment property is enabled.
Returns:
boolean. The current value ofautomaticConnectionEstablishment.

isFree

public boolean isFree()
Returns if the session is free
Returns:
boolean

isOffline

public boolean isOffline()
Returns if the session is offline
Returns:
boolean

openConnection

public void openConnection()
                    throws DSEOTMAException
This method establishes a multi-session OTMA connection. The caller must call openConnection to connect when IMS is available. When IMS is not up or OTMA is not started the attempt will fail . Method openConnection is synchronous call and waits until the connection is completed or when the attempt has failed. When connection is opened, event OPEN is signaled. Otherwise event CLOSED is signaled.OpenConnection is synchronous call and waits until the connection is completed or when the attempt has failed.
Specified by:
openConnection in interface OTMAConnectionService
Throws:
DSEOTMAException - if OTMA C/I error produced.

sendReceive

public OTMAMessage sendReceive(java.lang.String aTransaction,
                               Context aContext,
                               FormatElement aFormat,
                               long timeout)
                        throws DSEOTMAException,
                               DSEException
Sends data over this session to IMS and receives the output produced.
Parameters:
aTransaction, - name of IMS transaction or command to be sent to IMS.
aContext - com.ibm.dse.base.Context
aFormat - com.ibm.dse.base.FormatElement
timeout, - time interval to wait for this request.
Returns:
OTMAMessage class is returned , containing all attributes returned by OTMA C/I for this request.
Throws:
DSEOTMAException - if OTMA C/I error produced.
DSEException - if OTMA C/I error produced.

sendReceive

public OTMAMessage sendReceive(java.lang.String aTransaction,
                               Context aContext,
                               java.lang.String aFormatName,
                               long timeout)
                        throws DSEException
Sends data over this session to IMS and receives the output produced.
Parameters:
aTransaction, - name of IMS transaction or command to be sent to IMS.
aContext - com.ibm.dse.base.Context
aFormat - com.ibm.dse.base.FormatElement
timeout, - time interval to wait for this request.
Returns:
OTMAMessage class is returned , containing all attributes returned by OTMA C/I for this request.
Throws:
DSEOTMAException - if OTMA C/I error produced.
DSEException - if OTMA C/I error produced.

sendReceive

public OTMAMessage sendReceive(java.lang.String aTransaction,
                               java.lang.String aData,
                               byte[] session,
                               int[] sendSegmentList,
                               long timeout)
                        throws DSEOTMAException
Sends data over this session to IMS and receives the output produced.
Specified by:
sendReceive in interface OTMAConnectionService
Parameters:
aTransaction, - name of IMS transaction or command to be sent to IMS.
aData, - Data to be sent to IMS.
session, - session handler returned by a previous interaction when inside a conversation.
sendSegmentList, - Array of lengths of message segments to be sent to IMS. First element is count of following segment lengths .
timeout, - time interval to wait for this request.
Returns:
OTMAMessage class is returned , containing all attributes returned by OTMA C/I for this request.
Throws:
DSEOTMAException - if OTMA C/I error produced.

sendReceive

public OTMAMessage sendReceive(java.lang.String aTransaction,
                               java.lang.String aData,
                               byte[] session,
                               long timeout)
                        throws DSEOTMAException
Sends data over this session to IMS and receives the output produced.
Specified by:
sendReceive in interface OTMAConnectionService
Parameters:
aTransaction, - name of IMS transaction or command to be sent to IMS.
aData, - Data to be sent to IMS.
session, - session handler returned by a previous interaction when inside a conversation.
timeout, - time interval to wait for this request.
Returns:
OTMAMessage class is returned , containing all attributes returned by OTMA C/I for this request.
Throws:
DSEOTMAException - if OTMA C/I error produced.

sendReceive

public OTMAMessage sendReceive(java.lang.String aTransaction,
                               java.lang.String aData,
                               int[] sendSegmentList,
                               long timeout)
                        throws DSEOTMAException
Sends data over this session to IMS and receives the output produced.
Specified by:
sendReceive in interface OTMAConnectionService
Parameters:
aTransaction, - name of IMS transaction or command to be sent to IMS.
aData, - Data to be sent to IMS.
sendSegmentList, - Array of lengths of message segments to be sent to IMS. First element is count of following segment lengths .
timeout, - time interval to wait for this request.
Returns:
OTMAMessage class is returned , containing all attributes returned by OTMA C/I for this request.
Throws:
DSEOTMAException - if OTMA C/I error produced.

sendReceive

public OTMAMessage sendReceive(java.lang.String aTransaction,
                               java.lang.String aData,
                               long timeout)
                        throws DSEOTMAException
Sends data over this session to IMS and receives the output produced.
Specified by:
sendReceive in interface OTMAConnectionService
Parameters:
aTransaction, - name of IMS transaction or command to be sent to IMS.
aData, - Data to be sent to IMS.
timeout, - time interval to wait for this request.
Returns:
OTMAMessage class is returned , containing all attributes returned by OTMA C/I for this request.
Throws:
DSEOTMAException - if OTMA C/I error produced.

setAutomaticConnectionEstablishment

public void setAutomaticConnectionEstablishment(boolean newAutomaticConnectionEstablishment)
Sets the automaticSessionEstablishment property (java.lang.Boolean) value. If automaticConnectionEstablishment set to true connection established automatically . Default to false.
Specified by:
setAutomaticConnectionEstablishment in interface OTMAConnectionService
Parameters:
newAutomaticConnectionEstablishment - boolean

setIMSModName

public void setIMSModName(java.lang.String newIMSModName)
Sets the value of the IMSModName property.
Specified by:
setIMSModName in interface OTMAConnectionService
Parameters:
newIMSModName - java.lang.String

setIMSName

public void setIMSName(java.lang.String newIMSName)
Sets the value of the IMSName property.
Specified by:
setIMSName in interface OTMAConnectionService
Parameters:
newIMSName - java.lang.String

setInUse

public void setInUse(boolean anInUse)
Sets the inUse property (boolean) value.
Parameters:
anInUse - The new value for the property.
See Also:
getInUse()

setLTERM

public void setLTERM(java.lang.String newLTERM)
Sets the value of the LTERM property.
Specified by:
setLTERM in interface OTMAConnectionService
Parameters:
newLTERM - java.lang.String

setNumberOfResponseSegments

public void setNumberOfResponseSegments(int newNumberOfResponseSegments)
Sets the value of the numberOfResponseSegments property.
Specified by:
setNumberOfResponseSegments in interface OTMAConnectionService
Parameters:
newNumberOfResponseSegments - int

setReceiveBufferLength

public void setReceiveBufferLength(int newReceiveBufferLength)
Sets length of buffer available to receive message. If message received is longer that this length , the message is truncated. Default value set to 4096.
Specified by:
setReceiveBufferLength in interface OTMAConnectionService
Parameters:
newReceiveBufferLength - int

setSAFgroupName

public void setSAFgroupName(java.lang.String newSAFGroupName)
Sets the value of the SAFgroupName property.
Specified by:
setSAFgroupName in interface OTMAConnectionService
Parameters:
newSAFGroupName - java.lang.String

setSessionsNumber

public void setSessionsNumber(int newSessionsNumber)
Sets the value of the sessionsNumber property.
Specified by:
setSessionsNumber in interface OTMAConnectionService
Parameters:
newSessionsNumber - int

setTpipePrefix

public void setTpipePrefix(java.lang.String newTpipePrefix)
Sets the value of the tpipePrefix property.
Specified by:
setTpipePrefix in interface OTMAConnectionService
Parameters:
newTpipePrefix - java.lang.String

setTransaction

public void setTransaction(java.lang.String newTransaction)
Sets name of IMS transaction or command to be sent to IMS.
Specified by:
setTransaction in interface OTMAConnectionService
Parameters:
newTransaction - java.lang.String

setUserId

public void setUserId(java.lang.String newUserId)
Sets the SAF(Security Access Facility) user ID to be passed to OTMA. For example RACF user ID. Optional.
Specified by:
setUserId in interface OTMAConnectionService
Parameters:
newUserId - java.lang.String

setXCFGroupName

public void setXCFGroupName(java.lang.String newGroupName)
Sets the value of the XCFgroupName property.
Specified by:
setXCFGroupName in interface OTMAConnectionService
Parameters:
newGroupName - java.lang.String

setXCFMemberName

public void setXCFMemberName(java.lang.String newPartnerName)
Sets the value of the partnerName property.
Specified by:
setXCFMemberName in interface OTMAConnectionService
Parameters:
newPartnerName - java.lang.String

terminate

public void terminate()
Terminates the internal resources and closes the conversation. This method is automatically invoked when context where the OTMAConnection is located, is unchained.
Specified by:
terminate in interface OTMAConnectionService
Overrides:
terminate in class Service

toString

public java.lang.String toString()
Returns a visual representation of this object.
Overrides:
toString in class Service
Returns:
java.lang.String - The object visual representation.