trigger receiveMessage

Reacts to asynchronous messages that come from outside the application.

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

Note:  If the receiveMessage trigger contains a putmess statement and the user is currently in the message frame, the putmess statement is ignored.

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.