Current Page: NeXtMidas User's Guide Macros Messages in Macros
| ### 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