Refresh message cursor (-REFRESH)

Use the Refresh Message Cursor adapter command (-REFRESH) to ensure that higher-priority messages are enqueued in front of any existing messages with a lower priority so that the higher-priority messages can trigger the associated maps to run. This command is only used when using an IBM® MQ event input with the Launcher. If messages of a higher priority are enqueued after messages of a lower priority, the default behavior is that the higher priority messages would not trigger the maps.

-REFRESH [reset_time]
This is a non-negative integer defining the number of seconds that elapse before the message cursor is reset to the head of the queue.

The Refresh Message Cursor adapter command (-REFRESH) resets the message cursor of the source queue message event listener to the head of the queue after every listener cycle (detection of all messages currently on the queue) is completed. You can optionally specify a non-negative integer argument (reset_time) that defines the number of seconds that elapse before the messages cursor is reset to the head of the queue. If reset_time is set to zero, the message cursor will be constantly reset to the beginning of the queue after each event. Thus, the higher priority messages are processed as soon as possible. However, frequent repositioning of the cursor will degrade overall performance.

The Refresh Message Cursor adapter command (-REFRESH) is only needed when using an IBM MQ event input with the Launcher, and only in two specific situations:

  • When messages of higher priority are placed at the beginning of the queue that are not recognized because the message cursor has already begun moving towards the bottom of the queue.
  • When there is a possibility of the message cursor skipping the uncommitted messages on the queue. As an example, suppose that two applications, APP1 and APP2, simultaneously place messages on an empty queue and the following sequence of operations occurs (a possibility because APP1 and APP2 are independent and are executing concurrently):

    T0: APP1 PUT(M1)
    T1: APP2 PUT(M2)
    T2: APP2 COMMIT(M2)
    T3: APP1 COMMIT(M1)

    After T1 occurs, both messages have already been placed on the queue (with M1 in front of M2). However, they are not being recognized by the message cursor. After T2 occurs, the message cursor recognizes message M2 and it positions itself on that message. After T3 occurs, message M1 is also committed, but it is now beyond the message cursor. The message cursor will never be able to recognize that message unless it is repositioned to the beginning of the queue. Use the Refresh Message Cursor adapter command (-REFRESH) to accomplish this repositioning.

Using the Refresh Message Cursor adapter command (-REFRESH) may degrade event notification and mapping performance and should only be used when necessary. The adapter must be careful not to trigger the map more than once for the same input message. To ensure this, the adapter maintains a list of messages that have already been seen by the cursor. Each time the cursor is repositioned to the beginning of the queue, each message that the cursor finds on the queue is compared with all of the messages in this list. Only in situations in which this message is not in the adapter list is that message considered to be a new message to be used for the event notification. As part of this process, this new message will be added to the adapter list. To ensure that this list does not grow infinitely, there are two important limitations for the input cards that use the -REFRESH adapter command:
  • The Rollback option for the OnFailure setting should not be used.
  • The Keep option for the OnSuccess setting should also not be used.

If either of these two options is specified, running the Launcher for a long period of time with many messages being processed may cause excessive memory usage and may slow down processing time significantly, and eventually may cause the system to stop.

The reason for this is that messages once seen by the cursor are added to the internal list, and as long as they are not removed from the source queue, they are also not removed from the internal adapter's list so that they are not processed more than once. Messages are freed from the internal list only after they have been removed from the source queue.

In situations in which it is necessary to use the Refresh Message Cursor adapter command (-REFRESH) and to preserve the messages for the failed map, it is recommended that you use Error Queue Name adapter command (-EQN) in combination with -REFRESH adapter command for the input card. In this case, the Source > Transaction > OnSuccess setting should be Delete and the Source > Transaction > OnFailure setting should be Rollback. The messages for the map failure will be placed on the error queue and removed from the source queue. Thus, messages will be preserved (on the error queue), and no memory leak will occur because it will be possible to remove messages from the internal adapter's list upon moving them to the error queue. Note, however, that if, for some reason, messages cannot be stored on the error queue (for example, PUT is disabled for the error queue), the messages will remain on the input queue and in the internal adapter's list which again provides the possibility of a memory leak.