Declaration: | trigger
receiveMessage
|
Applies to: | Application Shell, Component |
Activation: | Activated by an asynchronous message in the application’s event input queue. The application-level trigger is activated only if the current component's trigger is empty or contains a $callup instruction. |
Default behavior: | On component level, fires trigger receiveMessage of the application shell. |
Behavior upon completion: | None |
Description
Use this trigger to handle real-time actions, such as updating rapidly changing information, or handling an incoming message from the license manager about a license about to expire, and so on.
Asynchronous messages can be trapped at component level in the component-level or at application level. The application-level receiveMessage trigger is activated only if the receiveMessage trigger for the component currently being processed is empty, or contains a $callup instruction. For more information, see $callup.
Asynchronous events can be generated by events such as:
- A 3GL program that uses functions of Uniface's 3GL interface to create an asynchronous interrupt.
- The user closing an application when the Close property of the application shell is defined as Async.
- A time-out notification generated when the assignment setting $TIMEOUT is present.
- A message sent with the postmessage ProcScript statement
- A mobile hot key that has been assigned an
async
action.
Note: If asynchronous messages can occur rapidly, it is wise to increase the value of the assignment file setting $MAX_QUE. This increases the size of the interrupt buffer.
Writing Messages
It is not possible to write to the application window from a receiveMessage trigger. This means that ProcScript in the trigger cannot directly write to fields defined in the application shell definitions, such as MESSAGE and FORMAREA. (If you want to write to the MESSAGE area, use the message statement.)
Activated by postmessage
When a receiveMessage trigger is activated by
postmessage, $result contains the string
"message"
and the $msgid contains the identifier sent with the
message.
$msgid can be used to
determine the exact type of message. In other cases, when activating the
receiveMessage trigger, $msgid contains
an empty string (""
) and the function $result indicates how the
trigger was activated.