Previous Next        Current Page: NeXtMidas User's Guide / Macros / Messages in Macros
back

Messages

There is no concept of a configured message in NeXtMidas. All messages are instead self-describing objects with named, not numbered, IDs. Messages are sent using a command that is syntactically similar to that recognized by X-Midas, as in

nM> mess send RMIF ,, OPEN ,, {ID=REMOTE,HP=host:port,RETRY=12}

or using the friendlier name=value syntax

nM> mess func=send ID=myplot Name=ZOOM data=(53.5e-3, 230e-3, 0, 50)

NeXtMidas macro execution often involves sending asynchronous, many-to-many messages among software agents, both within NeXtMidas itself and between NeXtMidas and external systems. To serve a purpose, a message must have both a source and a destination. Commonly, the source of a message is a non-macro command that creates and transmits the message via a library call or a macro containing one or more MESSAGE SEND commands. If the destination of a message is a macro, the Java method processMessage(...) is provided by the associated macro object; this transfers control to a processMessage procedure within the macro script itself. As a result, the macro writer gains high-level control over message handling.

NeXtMidas supports both targeted and broadcast messages. A targeted message is delivered to the message queue of a specified object. A broadcast message is delivered to the queues of all MessageHandler objects in the appropriate registry. Messages are a traditional Midas mechanism for communicating among different commands.

In NeXtMidas each message (msg) is treated as an object with the following properties:

S: msg.name The name of the message. See note below.
S: msg.tid The read-only ID of the message recipient (the "To ID").
S: msg.fid The read-only ID of the message sender (the "From ID").
L: msg.info Message-specific information (as a long integer).
O: msg.data Any data that accompanies the message.
O: msg.to The object/command of the message recipient (the "To").
O: msg.from The object/command of the message sender (the "From").

In X-Midas, message forwarding requires decomposition and reassembly. NeXtMidas uses an objectified approach to handling messages which significantly simplifies such tasks as message forwarding within a macro.

A NeXtMidas macro has a processMessage procedure that receives all messages sent to the macro. This procedure typically branches on message name, originator, or destination in an application-specific manner. A NeXtMidas macro concentrates message handling code in a single section that starts with a PROCEDURE processMessage statement and ends with RETURN. Look at the next example:

PROCEDURE processMessage msg
  IF msg.fid EQS MYPLOT
    ... 
  ELSEIF msg.name EQS OPEN
    ...
  ELSE
    WARNING "Unhandled message ^msg.name"
  ENDIF
RETURN

The above example detects messages sent by a command with the ID of MYPLOT and then looks for messages named OPEN. Finding neither, the example macro issues a warning that it's received an unhandled message.

All NeXtMidas commands derived from the Command class, including all intrinsics and primitives, inherit the ability to receive and process the following messages (this behavior can be altered by overriding the command's processMessage(...) method):

SET Set the KeyObject value(s) according to the name=value pairs passed in the message data.
GET Get the KeyObject value(s) corresponding to the name list passed in the message data and return them to message sender via a RET message.
SET.<key> Set the KeyObject whose name is <key> to the value passed in the message data.
GET.<key> Get the KeyObject value for <key> and return it to message sender via a RET.<key> message.


NOTE: Certain message names are reserved and have special uses. These names should be avoided when composing messages. Also, since command id's become the message name when interacting with the macro, users should not assign any commands an id with one of these reserved names:
   EXIT
   ERROR
   EXEC
   MACRO

back