MESSAGE
Jump to navigation
Jump to search
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