com.ibm.ims.application
Class IMSMessageQueue

java.lang.Object
  |
  +--com.ibm.ims.application.IMSMessageQueue

public final class IMSMessageQueue
extends java.lang.Object

IMSMessageQueue provides services to send and receive messages to an IMS message queue or to the application's Scratch Pad Area (SPA). The SPA is used in conversational transactions to store information between one step of the conversation and the next.

IMSMessageQueue also supports sending messages to another application if an alternate PCB for that application is specified on the IMSMessageQueue constructor.

In a non-conversational transaction, it is possible to code the application with a message loop that retrieves messages until IMS indicates that no more messages exist on the queue. To support this style of programming, IMSMessageQueue.getUniqueMessage returns true if a message could be returned from the queue and false if it could not. The application is required to call IMSTransaction.commit prior to receiving the second full message.

The following code snippet demonstrates this style of programming:

 // Read the first segment of the input message
 while(messageQueue.getUniqueMessage(inputMessage1)) {

 	// Read the second segment of the input message
 	messageQueue.getNextMessage(inputMessage2);

 	// Add logic here

  // Insert reply back to the message queue
  messageQueue.insertMessage(outputMessage);

 	// Commit the transaction.
 	trans.commit();
 } // end while
 

See Also:
IMSFieldMessage, DLIBaseSegment, DLITypeInfo, IMSTransaction

Constructor Summary
IMSMessageQueue()
          Creates a new IMSMessageQueue which sends and receives messages to and from a terminal.
IMSMessageQueue(java.lang.String alternatePCBName)
          Creates a new IMSMessageQueue with the alternate PCB Name to send messages to a different terminal or application program.
 
Method Summary
 AIB getAIB()
          Returns the Application Interface Block (AIB) used by the message queue.
 boolean getNextMessage(IMSFieldMessage message)
          Receives the next segment of the message from IMS.
 boolean getUniqueMessage(IMSFieldMessage message)
          Receives the first segment of an input message from IMS.
 void insertMessage(IMSFieldMessage message)
          Send an output message to IMS.
 void insertMessage(IMSFieldMessage message, boolean isLast)
          Send the SPA to IMS and end the conversation if isLast is true.
 void insertMessage(IMSFieldMessage message, java.lang.String modName)
          Send an output message to IMS, specifying the Message Output Descriptor to format the output message.
 void insertMessage(IMSFieldMessage message, java.lang.String modName, boolean isLast)
          Send the SPA to IMS with the Message Output Descriptor specified and end the conversation if isLast is true.
 void setModifiableAlternatePCB(java.lang.String destination)
          Sets the destination in the modifiable alternate PCB.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IMSMessageQueue

public IMSMessageQueue()
Creates a new IMSMessageQueue which sends and receives messages to and from a terminal.

IMSMessageQueue

public IMSMessageQueue(java.lang.String alternatePCBName)
Creates a new IMSMessageQueue with the alternate PCB Name to send messages to a different terminal or application program.
Parameters:
alternatePCBName - - the alternate PCB Name where the message is sent.
Method Detail

getAIB

public final AIB getAIB()
Returns the Application Interface Block (AIB) used by the message queue.
Returns:
AIB The Application Interface Block (AIB).

getNextMessage

public boolean getNextMessage(IMSFieldMessage message)
                       throws IMSException
Receives the next segment of the message from IMS. This will receive the remaining segments for a multisegments message in the program.
Parameters:
message - - the IMSFieldMessage object to receive the message
Returns:
true if the message was successfully retrieved, false if no more messages
Throws:
IMSException - if a non-blank status code is returned from the GN call

getUniqueMessage

public boolean getUniqueMessage(IMSFieldMessage message)
                         throws IMSException
Receives the first segment of an input message from IMS. It is also used to retrieve the SPA if the program is conversational.
Returns:
flag telling whether a message has been retrieved
Throws:
IMSException - if a non-blank status code is returned from the GU call or if getUniqueMessage is called without commiting the previous changes.

insertMessage

public void insertMessage(IMSFieldMessage message)
                   throws IMSException
Send an output message to IMS. The default formatting will be used.
Parameters:
message - - the message to send
Throws:
IMSException - if a non-blank status code is returned from the ISRT call

insertMessage

public void insertMessage(IMSFieldMessage message,
                          java.lang.String modName)
                   throws IMSException
Send an output message to IMS, specifying the Message Output Descriptor to format the output message.
Parameters:
message - - the message to send
modName - - the Message Output Descriptor (MOD) for formatting the output message
Throws:
IMSException - if a non-blank status code is returned from the ISRT call

insertMessage

public void insertMessage(IMSFieldMessage message,
                          java.lang.String modName,
                          boolean isLast)
                   throws IMSException
Send the SPA to IMS with the Message Output Descriptor specified and end the conversation if isLast is true. This method is used in convesational programs only.
Parameters:
message - - the message to send
modName - - the Message Output Descriptor (MOD) for formatting
isLast - - flag indicating whether this is the last segment for the conversation
Throws:
IMSException - if a non-blank status code is returned from the ISRT call

insertMessage

public void insertMessage(IMSFieldMessage message,
                          boolean isLast)
                   throws IMSException
Send the SPA to IMS and end the conversation if isLast is true. This method should be used in convesational programs only.
Parameters:
message - - the message to send
isLast - - flag indicating whether this is the last segment for the conversation
Throws:
IMSException - if a non-blank status code is returned from the ISRT call

setModifiableAlternatePCB

public void setModifiableAlternatePCB(java.lang.String destination)
                               throws IMSException
Sets the destination in the modifiable alternate PCB. Call this method prior to inserting a message to another program or logical terminal.
Parameters:
destination - - transaction or logical terminal to send message to


(C) International Business Machines Corporation 2004. All rights reserved.