Progress
External Program
Interfaces


Message Consumer Objects

The 4GL application uses a Message Consumer to receive messages from a destination or to receive asynchronous error messages.

A single Message Consumer object can be passed:

The life cycle of a Message Consumer object includes these general steps:

  1. An application implements a procedure to handle the messages.
  2. The application creates the message consumer, specifying the message-handling procedure.
  3. The application uses the Message Consumer object to do one of the following: subscribe (Pub/Sub) or receive (PTP) messages from the queue, set it an error handle and receive error messages asynchronously from SonicMQ through the SonicMQ Adapter, or receive replies in a request/reply cycle.
  4. After using the Message Consumer object, the application can activate it by getting into a WAIT FOR state (or any IO blocking state where the application processes events).
  5. When the Message Consumer finishes processing all of the messages of interest, the application calls deleteConsumer to release the resources in the 4GL application and the SonicMQ Adapter and SonicMQ broker.

An application creates a messageConsumer object by calling createMessageConsumer in a Session object. The application must pass to createMessageConsumer, the name of an internal procedure (procName) for handling messages and a handle to a procedure that contains procName (procHandle). The new Message Consumer object is returned in consumerHandle:

SYNTAX
PROCEDURE createMessageConsumer. 
DEFINE INPUT PARAMETER procHandle AS HANDLE.  
DEFINE INPUT PARAMETER procName AS CHAR.     
DEFINE OUTPUT PARAMETER consumerHandle AS HANDLE.  

Setting Context

The 4GL application can use setApplicationContext to pass context to the message handler. The handler parameter is typically a handle to a persistent procedure implemented by the application. When the message handler is called, it gets that handler and uses it, for example, to deposit error information in the application’s context by calling a specific handler’s internal procedure:

SYNTAX
PROCEDURE setApplicationContext. 
DEFINE INPUT PARAMETER handler AS HANDLE. 

Setting Reply Properties

The following procedures set reply properties when the message consumer is passed to requestReply.

The following procedure sets the priority of the reply messages; the range of values is 0–9; the default is 4. The setReplyPriority procedure can be called only once:

SYNTAX
PROCEDURE setReplyPriority. 
DEFINE INPUT PARAMETER priority AS INT. 

The following procedure sets the time to live value. The default is JMS system-dependent; the SonicMQ default value is 0. The replyTimeToLive values can be set only once. The fractional part of the decimal value is truncated. If the value does not fit in a Java long value, Java rules for decimal-to-long conversion apply:

SYNTAX
PROCEDURE setReplyTimeToLive. 
DEFINE INPUT PARAMETER millis AS DECIMAL. 

The following procedure sets the value for message persistency. The allowed values are: PERSISTENT, NON_PERSISTENT, NON_PERSISTENT_ASYNC, and UNKNOWN; the default value is PERSISTENT. The evaluation is case insensitive. A call with an UNKNOWN value has no effect. The replyPersistency value can be set only once:

SYNTAX
PROCEDURE setReplyPersistency. 
DEFINE INPUT PARAMETER deliveryMode AS CHAR. 

NOTE: NON_PERSISTENT_ASYNC is a SonicMQ extension.

The following procedure specifies whether all reply messages are to be automatically deleted. If set to true, then all reply messages returned through the message handler’s OUPUT parameter are automatically deleted after being sent. The default value is false: (See the "Message Handler" section in this chapter.)

SYNTAX
PROCEDURE setReplyAutoDelete. 
DEFINE INPUT PARAMETER val AS LOGICAL. 

Getting Message Handler Properties

The following functions return the properties of the message handler and the application context:

SYNTAX
FUNCTION getProcHandle RETURNS HANDLE. 
FUNCTION getProcName RETURNS CHAR. 
FUNCTION getApplicationContext RETURNS HANDLE. 

The following function returns the name of the destination that messages arrive from when the message consumer was passed to subscribe or to receiveFromQueue:

SYNTAX
FUNCTION getDestinationName RETURNS CHAR. 

One of the following functions returns true when called from a message handler. That allows the application to determine whether it is handling an error message, a subscription (or queue) message, a reply message, or a queue browsing message. The value returned from the function when the application is not currently in any of these message handling states is not determined:

SYNTAX
FUNCTION inErrorHandling RETURNS LOGICAL. 
FUNCTION inMessageHandling RETURNS LOGICAL. 
FUNCTION inReplyHandling RETURNS LOGICAL. 
FUNCTION inQueueBrowsing RETURNS LOGICAL. 

The following function returns a handle to the session:

SYNTAX
FUNCTION getSession RETURNS HANDLE. 

The following function returns the setReplyPriority value (4 if setReplyPriority was not called):

SYNTAX
FUNCTION getReplyPriority RETURNS INT. 

The following function returns the setReplyTimeToLive value (UNKNOWN if setReplyTimeToLive was not called):

SYNTAX
FUNCTION getReplyTimeToLive RETURNS DECIMAL. 

The following function returns the setReplyPersistency value (PERSISTENT if setReplyPersistency was not called):

SYNTAX
FUNCTION getReplyPersistency RETURNS CHAR. 

The following function returns the value set by setReplyAutoDelete:

SYNTAX
Function getReplyAutoDelete RETURNS LOGICAL. 

Terminating the Message Consumer

The following procedure ends the life of the Message Consumer object. It cancels the subscription (in the Pub/Sub domain) or the association with a queue (in the PTP domain) and deletes the messageConsumer Object:

SYNTAX
PROCEDURE deleteConsumer. 

NOTE: This procedure executes remotely (sends a message to the SonicMQ Adapter).

Acknowledge and Forward

Imagine the following scenario:

  1. A client retrieves a message from a broker’s queue.
  2. The broker wants to be notified when the message reaches its ultimate destination.
  3. The ultimate destination is a remote queue.
  4. The client sends the message on its way.

To acknowledge receipt of a message whose ultimate destination is a remote queue, you might enclose the message and acknowledgment in a single transaction. But this introduces the overhead and complexity of transaction processing. SonicMQ provides a cleaner solution, embodied in the following steps:

  1. Run the setSingleMessageAcknowledgement method to set the session to SINGLE_MESSAGE_ACKNOWLEDGE.
  2. Run the acknowledgeAndForward method within the message event handler, specifying a destination queue name, the original message handle, and optional message-delivery properties (priority, time-to-live, and persistency). If the method is successful, the message is forwarded and acknowledged in a single, atomic operation.

The singleMessageAcknowledgement method sets the acknowledgement setting of a client session. Its syntax is:

SYNTAX
PROCEDURE setSingleMessageAcknowledgement. 
DEFINE INPUT PARAMETER ackMethod as LOGICAL. 

The getSingleMessageAcknowledgement method returns the acknowledgement setting of a client session. Its syntax is:

SYNTAX
FUNCTION getSingleMessageAcknowledegment RETURNS LOGICAL. 

The acknowledgeAndForward method, to be run within a message event handler, causes a message to be forwarded and acknowledged in a single, atomic operation. Its syntax is:

SYNTAX
PROCEDURE acknowledgeAndForward. 
DEFINE INPUT PARAMETER destinationName AS CHARACTER. 
DEFINE INPUT PARAMETER messageH        AS HANDLE. 
DEFINE INPUT PARAMETER priority        AS INTEGER. 
DEFINE INPUT PARAMETER timeToLive      AS DECIMAL. 
DEFINE INPUT PARAMETER persistency     AS CHARACTER. 

Stopping Acknowledgement

The following procedure instructs the 4GL–JMS implementation not to acknowledge this message. This call should be made, for example, if the 4GL application fails to use the data in a message and needs to receive the message again. This call is an error if the session is transacted for receiving. If the messageConsumer object is used to handle error messages or for queue browsing, this call has no effect:

SYNTAX
PROCEDURE setNoAcknowledge. 

The following function returns true if setNoAcknowledge was called:

SYNTAX
FUNCTION getNoAcknowledge RETURNS LOGICAL. 

Specifying Message Reuse

The following procedure instructs the Message Consumer object not to create a new message for each received message. Calling setReuseMessage improves performance: if the procedure is not called, the Message Consumer object creates a new message for each received message. A message that is being reused should not be deleted before the session is deleted:

SYNTAX
PROCEDURE setReuseMessage. 

The following function returns true if setReuseMessage was called; if not, it returns false:

SYNTAX
FUNCTION getReuseMessage RETURNS LOGICAL. 


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095