MESSAGE
From ICE Enterprises
send or get a message to/from a message queue
<FUNC> function to perform [QUERY]
<ID> message queue ID
<MSG> name of message object (to be) stored in results table
<NAME> message name
<INFO> message info field
<DATA> message data object
Keyword-Only Parameters:
[FROM] sender object template
[QUALS] Additional message qualifiers for SEND and REPLACE function.
(Since NeXtMidas 2.7.2)
The MESSAGE intrinsic performs numerous message handling functions at the macro
level according to the value of <FUNC>.
Not all parameters are required with every <FUNC>. Common command variations
include:
0. MESSAGE SEND[x] <ID> <MSG>
1. MESSAGE SEND[x] REPLY <MSG>
2. MESSAGE SEND[x] <ID> , , <NAME> <INFO> <DATA>
3. MESSAGE SEND[x] <ID> NAME=<NAME> INFO=<INFO> DATA=<DATA>
4. MESSAGE GET , , <MSG>
5. MESSAGE GET[x] , , <MSG> <NAME> FROM= /WAIT=
6. MESSAGE PASS <ID> <MSG>
7. MESSAGE PRUNE , , <MSG>
8. MESSAGE SYNC <ID>
9. MESSAGE QUERY
Of the above options, the two most common are #2 and #3 are the most commonly
used with #2 seen more in older code and #3 seen more in newer code.
<ID> is the id value given to a target primitive as specified by the /ID=<id>
switch on the primitive's command line. The id name can a string of any length
composed of letters, numbers, or the underscore (e.g. "MAP", "WORLD_MAP", etc.).
The use of numeric-only ids (e.g. "7") is discouraged, except when running an
X-Midas host primitive via XBC (X-Midas required numeric ids). The id of "MAIN"
is reserved for the macro that created the local registry. The list of active
ids can be seen via the REGISTRY command. The id of "REPLY" is reserved for the
macro to respond back to the sender of the message.
Messages can be sent to:
"<id>" - A command in the macro's registry with /ID=<id> or "MAIN"
for the macro itself.
"GLOBAL.<id>" - A command in the global registry. (Since NeXtMidas 3.3.0)
"PARENT.<id>" - A command in the macro's parent's registry or "PARENT.MAIN".
for the parent macro itself. (Since NeXtMidas 3.3.0)
"XM.<id>" - The X-Midas global message queue slot number <id>. Note that
this only works when using NeXtOpt; XBC is not restricted to
use of slots in a global message queue and can send messages
directly to X-Midas host primitives.
----------------------------------------------------------------------------
"REPLY" - Sends a reply back to a sender, with optional alteration of
the <NAME>, <INFO>, and <DATA> fields. (<MSG> is required
when "REPLY" is used since MESSAGE it bypasses the normal
registry ID look-up and uses the <MSG>.FROM object as the
destination in this situation, unlike the above options
REPLY only works with the MESSAGE command.)
THIS.MSGID - The registered message handler for this macro as set by the
/MSGID= switch when the macro was called. This is used as a
generic way to send messages back to target message handler
for this macro. (Since NeXtMidas 3.3.1)
A message object has the following fields:
S: msg.name the name of the message
S: msg.tid the ID of the message recipient (read-only convenience field)
S: msg.fid the ID of the message sender (read-only convenience field)
L: msg.info message-specific information encoded in an integer
O: msg.data the data object, often a table containing multiple values
O: msg.to the object/command of the message recipient
O: msg.from the object/command of the message sender
O: msg.quals the message qualifiers object, often null or a table containing
multiple key/values (since NeXtMidas 2.7.2)
Normally messages sent to a macro are written to a result named MSG and
processed by the processMessage procedure (see the "NeXtMidas Training" for
detailed discussion and examples of using processMessage). The MESSAGE command's
GET[x] function is for special handling and rarely used.
There are several reserved <NAME> values that should not be used, as they can
cause unexpected behavior in your macro, including:
ERROR
EXEC
EXIT
MACRO
Due to legacy behavior, a few messages have special behavior when sent to RMIF,
including:
ADDR - Messages sent to RMIF with this <NAME> are treated as a SENDW
OPEN - Messages sent to RMIF with this <NAME> are treated as a SENDW
Special note for XBC users:
When using XBC to send messages to/from host primitives the <DATA> will be a
Table matching the structure of a configured message or a Table with the
values for an unconfigured message. Unconfigured messages need to be sent
with TYPE= and ARGS= specified. See the XBC section in the "NeXtMidas User's
Guide" for more details. Be sure to set /MSGID=MAIN for the host primitive
in order to see the messages in the macro.
Functions:
SEND[xwr] send a message to a message queue
SYNTAX:
MESSAGE SEND <ID> , , <NAME> <INFO> <DATA> [QUALS=]
MESSAGE SEND , , <MSG> [<NAME>] [<INFO>] [<DATA>] [QUALS=]
MESSAGE SEND REPLY <MSG> [<NAME>] [<INFO>] [<DATA>] [QUALS=]
- Appending an 'X' causes the message handler to send the
message directly from the current thread, bypassing the
message queue. The handler may put it on its own queue so
this does not guarantee execution of the message.
- Appending a 'W' causes the command to wait for a maximum time
given in seconds by the value of the /WAIT switch for the
message to be executed. If no /WAIT switch is present, it
defaults to one second. This is the same as following a SEND
with a SYNC.
- Appending a 'R' causes the command to try to replace first
matching message (name and from) in queue with this message.
If not found, then message is sent normally.
Note, that option 'X' to send message directly to the handler
takes precedence over this and hence cannot be used with this
replace option. If the message was replaced, the replaced
message is put back into results named specified by <MSG>.
(Since NeXtMidas 3.3.0)
GET[wnf] read a message from a message queue
SYNTAX:
MESSAGE GET , , <MSG>
MESSAGE GET , , <MSG> <NAME> FROM= /WAIT=
- Appending a 'W' causes the command to wait for a maximum time
given in seconds by the value of the /WAIT switch before
timing out.
- Appending an 'N' forces the next message to be fetched to
match <NAME>
- Appending an 'F' forces the next message to be fetched to
match FROM=
PASS Pass a message to a different message queue
SYNTAX: MESSAGE PASS <ID> <MSG>
PRUNE Purge messages in the queue
SYNTAX: MESSAGE PRUNE , , <MSG>
QUERY Report owner and availability of command's message queue
SYNTAX: MESSAGE QUERY
REPLACE Replaces matching message (name and from) in the queue with <MSG>
SYNTAX:
MESSAGE REPLACE , , <MSG>
MESSAGE REPLACE <ID> , , <NAME> <INFO> <DATA> [QUALS=]
Replaced message is put back into results named <MSG>, null if no
message was replaced. (Since NeXtMidas 3.3.0)
SYNC Put a null message on a queue and wait for it to be processed
SYNTAX: MESSAGE SYNC <ID>
More than one suffix letter can be appended to a given SEND or GET command.
For example, GETW waits for a message to arrive, and GETN means that the
message must have a specific name. Therefore GETWN means to wait until a
message with a specific name arrives.
In most cases, the MESSAGE intrinsic quietly ignores stray characters
following the <FUNC> values shown above; however, dependence on this fact is
discouraged to minimize the chance of future macro breakage.
Examples:
1. Get the next message off the macro queue:
nM> message GET ,, msg
The message fields are now accessible from the macro language using the
standard syntax for keyable objects:
nM> say "Got a ^msg.name message from ^msg.fid"
nM> say " the info is ^msg.info and data is ^msg.data"
2. Send a message to another primitive, use the /ID= of the receiving
primitive:
nM> plot/id=plot1 ...
nM> message send "PLOT1" ,, "OPENFILE" 1 mapdata
3. To pass a zoom message from one plot to another:
nM> message get ,, msg "ZOOM"
nM> if msg.tid eqs "PLOT1" then
nM> set msg.name "ZOOMX"
nM> message pass "PLOT2" msg
nM> endif
Switches:
/WAIT=<n> Max number of seconds to wait in GETW (indefinitely if < 0).
SENDW wait time < 0 means no wait. [GETW DEF=0; SENDW DEF=1.0]
/XMTYPE=<s> Specifies the message type to use if sending the message
to X-Midas (this is ignored for normal NeXtMidas messaging).
Options include:
NEXTMIDAS - Normal NeXtMidas message.
CONFIGURED - Configured X-Midas message.
UNCONFIGURED - Un-configured X-Midas message.
AUTO - Automatic configured or un-configured X-Midas
message. (default)
See Also: SENDTO, REGISTRY, nxm.sys.lib.Message
