Progress
External Program
Interfaces
Message-reception Issues
The following sections discuss several message-reception issues in the Pub/Sub and PTP domains.
Stopping and Starting Message Reception
To actually start receiving messages, the 4GL application must call the startReceiveMessages procedure in the Session object. One call to startReceiveMessages is sufficient for the session. The application typically calls the startReceiveMessages procedure after subscribing to all topics of interest (in the Pub/Sub domain) or registering Message Consumer objects with the queues of interest (in the PTP domain).
The application can also call stopReceiveMessages to temporarily stop the reception of messages. The application can then call the startReceiveMessages procedure again to resume message reception.
In the Pub/Sub domain, calling stopReceiveMessages does not cancel any existing subscription, but if the subscription is not durable, messages published while reception is stopped are not delivered.
In the PTP domain, the messages are queued while the client is in a stopReceiveMessages state and are delivered to the client after startReceiveMessages is called again.
Stopping the reception of messages is recommended when an application is not going to process messages for a while. If stopReceiveMessages is not called, messages are queued in a 4GL–JMS temporary queue on the server side, potentially consuming a large amount of memory.
NOTE: After calling stopReceiveMessages, the 4GL client might receive one message that was sent from the server prior to the execution of the stopReceiveMessages call.Message Consumer Scope
A messageConsumer object can be used to handle only one subscription (in the Pub/Sub domain) or receive messages from one queue (in the PTP domain). When its deleteConsumer procedure is called, message reception is canceled and the messageConsumer object is deleted.
NOTE: To delete a durable subscription (in the Pub/Sub domain), the cancelDurableSubscription() procedure inpubsubsession.p
must be called as well, since deleteConsumer only suspends the subscription in the current session. There is no equivalent to a durable subscription in the PTP domain.
It is an error to call cancelDurableSubscription() if there is an active message consumer for that subscription. First call deleteConsumer to delete the message consumer.When a messageConsumer object is used for receiving replies through the requestReply call, it can be used many times; there is no need to create one for every call. The deleteSession call deletes all messageConsumer objects for that session.
4GL Interpreter Message Processing States
A 4GL application receives and processes messages when it is in an I/O blocking state. The same rules that determine when ASYNC completion procedures are fired also determine when message handlers are called. The 4GL application should typically use the WAIT–FOR statement or the waitForMessages API session call, for processing messages as well as for other events.
The waitForMessages call is a convenient way to write message-handling code that is independent of the environment in which the 4GL application is executed (GUI, CHUI, batch, AppServer, or WebSpeed). It allows the application to specify when to stop waiting and it processes all events that occur while waiting, including user-interface events and ASYNC call events.
The waitForMessages call takes three input parameters: a procedure handle, a name of a user-defined function in the procedure that returns LOGICAL, and a timeOut INTEGER. The waitForMessages call waits and processes events as long as the user-defined function returns true and there is no period of more than timeOut seconds in which no messages are received.
The user-defined function is evaluated by the 4GL–JMS API after the message handler is executed. Typically, the 4GL application should have logic for changing the return value of the function in the message handler.
Synchronous Message Reception
The 4GL does not explicitly support receiving messages synchronously. The same effect can be achieved by using the WAIT–FOR statement (or a waitForMessages call), which waits for a user-defined event. When the desired message is received, the message handler can trigger the termination of the WAIT–FOR statement (or the waitForMessages call) by, for example, applying the user-defined event the WAIT–FOR statement is waiting for.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |