MESSAGE

From ICE Enterprises
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