com.ibm.ims.dli.tm

Interface MessageQueue

public interface MessageQueue

Use this interface to send and receive messages to an IMS Message Queue or to the Scratch Pad Area (SPA) for an application. The SPA is used in conversational transactions to store information between one step of the conversation and the next.

For a code example that shows how to write a JMP application to process a conversational transaction, see the topic "Conversational transactions" in the IMS Application Programming guide documentation.

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, the getUnique(IOMessage) method returns true if there is a message to retrieve from the queue and false if there is not.

See Also:

IOMessage, MessageDestinationSpec

Field Summary

Fields

Modifier and Type	Field and Description
static MessageDestinationSpec	DEFAULT_DESTINATION Using this constant value will send the message to the default destination of the transaction.

Method Summary

Modifier and Type	Method and Description
void	change(java.lang.String destinationName, java.lang.String altPCBName) Change the destination of a message to IMS.
AIB	getAIB() Returns the AIB instance associated with the most recent DL/I call.
boolean	getNext(java.nio.ByteBuffer buffer) Retrieves the next segment of the message from IMS.
boolean	getNext(IOMessage message) Retrieves the next segment of the message from IMS.
boolean	getUnique(java.nio.ByteBuffer buffer) Retrieves the first segment of an input message from IMS.
boolean	getUnique(IOMessage message) Retrieves the first segment of an input message from IMS.
void	insert(java.nio.ByteBuffer buffer) Send an output message to IMS.
void	insert(java.nio.ByteBuffer buffer, MessageDestinationSpec mds) Send an output message to IMS.
void	insert(java.nio.ByteBuffer buffer, java.lang.String alternatePcbName) Send an output message to IMS.
void	insert(java.nio.ByteBuffer buffer, java.lang.String alternatePcbName, java.lang.String modName)
void	insert(IOMessage message, MessageDestinationSpec mds) Send an output message to IMS.
void	purge(java.lang.String alternatePcbName) A PURG call tells IMS TM that the message built against the specified I/O PCB, or alternate PCB (with the ISRT call) is complete.
void	purge(java.lang.String alternatePcbName, IOMessage message) Use the PURG call to send output messages to several different terminals.
void	purge(java.lang.String alternatePcbName, IOMessage message, java.lang.String modName) Use the PURG call to send output messages to several different terminals.

Field Detail

DEFAULT_DESTINATION

static final MessageDestinationSpec DEFAULT_DESTINATION

Using this constant value will send the message to the default destination of the transaction. The value of this constant is null

Method Detail

getUnique

boolean getUnique(IOMessage message)
           throws DLIException

Retrieves the first segment of an input message from IMS. Use this method to retrieve the SPA if the program is conversational.

Parameters:

message - the IOMessage object to receive the message

Returns:

flag indicating whether a message has been retrieved

Throws:

TMException - if the operation fails

DLIException

getUnique

boolean getUnique(java.nio.ByteBuffer buffer)
           throws DLIException

Retrieves the first segment of an input message from IMS. Use this method to retrieve the SPA if the program is conversational.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

Parameters:

message - the ByteBuffer object to receive the message

Returns:

flag indicating whether a message has been retrieved

Throws:

TMException - if the operation fails

DLIException

See Also:

Application#get31BitDirectByteBuffer(int)}, ByteBuffer.allocateDirect(int)

getNext

boolean getNext(IOMessage message)
         throws DLIException

Retrieves the next segment of the message from IMS. Use this method to retrieve the remaining segments for a multi-segment message in the program.

For a code example that shows how to handle multi-segment messages, see the topic "Handling multi-segment messages" in the IMS Application Programming guide documentation.

Parameters:

message - the IOMessage object to receive the message

Returns:

true if the message was successfully retrieved, false if no more messages

Throws:

TMException - if the operation fails

DLIException

getNext

boolean getNext(java.nio.ByteBuffer buffer)
         throws DLIException

Retrieves the next segment of the message from IMS. Use this method to retrieve the remaining segments for a multi-segment message in the program.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

Parameters:

buffer - the ByteBuffer object to receive the message

Returns:

true if the message was successfully retrieved, false if no more messages

Throws:

TMException - if the operation fails

DLIException

See Also:

Application#get31BitDirectByteBuffer(int)}, ByteBuffer.allocateDirect(int)

insert

void insert(IOMessage message,
            MessageDestinationSpec mds)
     throws DLIException

Send an output message to IMS. Use this method to return the message to the default destination, perform immediate program switching to an alternate IOPCB, or perform deferred program switching.

The following code example shows how to return the message to the default destination:

    messageQueue.insert(outputMessage, MessageQueue.DEFAULT_DESTINATION);
 

The following code example shows how to perform immediate program switching to an alternate IOPCB:

    MessageDestinationSpec mds = new MessageDestinationSpec();
    mds.setAlternatePCBName("alternatePCBName");
    mds.setDestination("newDestination");
    messageQueue.insert(outputMessage, mds);
 

The following code example shows how to perform deferred program switching:

    spaMessage.setTrancodeName("newTran");
    messageQueue.insert(spaMessage, MessageQueue.DEFAULT_DESTINATION);
 

For more details on program switching in JMP and JBP applications, see the topic "Program switching in JMP and JBP applications" in the IMS Application Programming guide documentation.

Parameters:

message - the IOMessage object to send the message

mds - the MessageDestinationSpec object that specifies the destination to route the message to

Throws:

TMException - if the operation fails

DLIException

insert

void insert(java.nio.ByteBuffer buffer)
     throws DLIException

Send an output message to IMS. Use this method to return to the default destination.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code example shows how to return the message to the default destination:

    ByteBuffer buffer = ByteBuffer.allocate(40);
    InputMessage input = new InputMessage(buffer);
    input.setLL(10)
    input.setZZ(0)
    input.setInputData("SAMPLE")
    messageQueue.insert(buffer);
 

Parameters:

buffer - the ByteBuffer object to send the message

Throws:

TMException - if the operation fails

DLIException

See Also:

Application#get31BitDirectByteBuffer(int)}, ByteBuffer.allocateDirect(int)

insert

void insert(java.nio.ByteBuffer buffer,
            MessageDestinationSpec mds)
     throws DLIException

Send an output message to IMS. Use this method to return the message to the default destination, perform immediate program switching to an alternate IOPCB, or perform deferred program switching.

The following code example shows how to return the message to the default destination:

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

    messageQueue.insert(buffer, MessageQueue.DEFAULT_DESTINATION);
 

The following code example shows how to perform immediate program switching to an alternate IOPCB:

    MessageDestinationSpec mds = new MessageDestinationSpec();
    mds.setAlternatePCBName("alternatePCBName");
    mds.setDestination("newDestination");
    messageQueue.insert(buffer, mds);
 

For more details on program switching in JMP and JBP applications, see the topic "Program switching in JMP and JBP applications" in the IMS Application Programming guide documentation.

Parameters:

buffer - the ByteBuffer object to send the message

mds - the MessageDestinationSpec object that specifies the destination to route the message to

Throws:

TMException - if the operation fails

DLIException

See Also:

Application#get31BitDirectByteBuffer(int)}, ByteBuffer.allocateDirect(int)

insert

void insert(java.nio.ByteBuffer buffer,
            java.lang.String alternatePcbName)
     throws DLIException

Send an output message to IMS. Use this method to perform immediate program switching to an alternate IOPCB, or perform deferred program switching. To be used after a change call has set a destination within IMS

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code example shows how to perform immediate program switching to an alternate IOPCB:

 messageQueue.insert(buffer, "ALTPCB1");
 

For more details on program switching in JMP and JBP applications, see the topic "Program switching in JMP and JBP applications" in the IMS Application Programming guide documentation.

Parameters:

buffer - the ByteBuffer object to send the message

alternatePcbName - the name of the alternate PCB to be used for an insert

Throws:

TMException - if the operation fails

DLIException

See Also:

Application#get31BitDirectByteBuffer(int)}, ByteBuffer.allocateDirect(int)

insert

void insert(java.nio.ByteBuffer buffer,
            java.lang.String alternatePcbName,
            java.lang.String modName)
     throws DLIException

Throws:

DLIException

change

void change(java.lang.String destinationName,
            java.lang.String altPCBName)
     throws DLIException

Change the destination of a message to IMS. Use this method prior to issuing an insert with the intent of program switching without using the MessageDestinationSpec class

Parameters:

destinationName - The name of the destination to change to

altPCBName -

Throws:

DLIException

purge

void purge(java.lang.String alternatePcbName)
    throws DLIException

A PURG call tells IMS TM that the message built against the specified I/O PCB, or alternate PCB (with the ISRT call) is complete.

Parameters:

alternatePcbName -

Throws:

java.lang.Exception

DLIException

purge

void purge(java.lang.String alternatePcbName,
           IOMessage message)
    throws DLIException

Use the PURG call to send output messages to several different terminals. A PURG call tells IMS TM that the message built against the specified I/O PCB, or alternate PCB (with the ISRT call) is complete. IMS TM collects the message segments that have been inserted into one PCB as one message and sends the message to the destination specified by the destination name of the alternate PCB listed in the PURG call. If you specify an I/O area in the PURG call parameters, PURG acts as an ISRT call to insert the first segment of the next message. When you identify the I/O area, you can also specify a MOD name to change the screen format.

Parameters:

alternatePcbName -

message -

Throws:

java.lang.Exception

DLIException

purge

void purge(java.lang.String alternatePcbName,
           IOMessage message,
           java.lang.String modName)
    throws DLIException

Use the PURG call to send output messages to several different terminals. A PURG call tells IMS TM that the message built against the specified I/O PCB, or alternate PCB (with the ISRT call) is complete. IMS TM collects the message segments that have been inserted into one PCB as one message and sends the message to the destination specified by the destination name of the alternate PCB listed in the PURG call. If you specify an I/O area in the PURG call parameters, PURG acts as an ISRT call to insert the first segment of the next message. When you identify the I/O area, you can also specify a MOD name to change the screen format.

Parameters:

alternatePcbName -

message -

modName -

Throws:

DLIException

getAIB

AIB getAIB()

Returns the AIB instance associated with the most recent DL/I call. The AIB contains all the data attributes of the IMS application interface block.

Returns:

the AIB instance associated with the most recent DL/I call.