RMSG

Remote Midas InterFace (RMIF) message constructor/destructor and sender.

<verb>   - Function to perform (SEND,T2R,R2T)
<addr>   - Remote Address (NODE:PORT or 0X?? form)
<func>   - Packet Function (SET,GET,RET,ACK)
<info>   - Info field
<data>   - Data Table {KEY1=VALUE1,KEY2=VALUE2,...)
<prefix> - Prefix of results to hold table data (max of 32 characters)

This command is a helper function for macros dealing with RMIF/PKT messages. The
SET, RET, GET, and ACK messages are often tables which are not easily dealt with
in X-Midas.  This function translates those messages from tables to results
(T2R) constructs that are easier to deal with in the X-Midas macro language.
The SEND function also makes it easy to send the above supported message types
over RMIF to the desired remote address (hostname/IP:port or hexadecimal form).

To get RMIF to pass PKT messages to the macro use the /PKTMSG switch on RMIF.
To get RMIF to pass KEY messages to the macro use the /KEYMSG switch on RMIF.

The macro should have a global switch /RMIFID=N where n is the id of the RMIF
primitive.  This switch will get picked up by RMSG wherever it appears in the
macro for all functions that need to talk to the RMIF primitive.

  startmacro/rmifid=10

    res l:rmif_id /rmifid

    xpipe on
    waveform _cb
    rmif/id=rmif_id/pktmsg port _cb
    xpipe off

  endmacro

A NeXtMidas table has the form:

 {KEY1=Value1,KEY2=Value2,...KEYN=ValueN}

The RMSG command can be used to construct and send a message of this form.

 rmsg SEND <addr> "ACK" <info> {FREQ=^MYFREQ,AMP=^MYAMP,MOD=FM}

where the table can be up to 1024 characters in length.

When a macro gets a message from RMIF, it can be parsed into results parameters
with a named prefix.  For example with <prefix> = R_ :

  R_NK = N
  R_K1 = KEY1
  R_V1 = VALUE1
  R_K2 = KEY2
  R_V2 = VALUE2
  ...
  R_KN = KEYN
  R_VN = VALUEN

When a macro gets a message from RMIF, use the T2R function to parse the table
into individual results parameters for each key=value pair.  The macro can then
loop through the individual key/value pairs and execute the necessary functions.

  message get /M/
  if M.name eq "RMIF"
    rmsg T2R ,,,, M.RPKT.data R_
    loop R_NK nn
      say "Message ^M.RPKT.func of key=^{R_K^nn} to value=^{R_V^nn}"
    endloop
  else
  endif

Since 3.1.3, T2R supports X-Midas Tables utilizing the H: or h: syntax.
'H' is the type letter for X-Midas Table; they could not use 'T:' since that
was already used for the widget tags type. Instead 'H:' for hash was used. For
a listing of most Midas types, see NeXtMidas Training/Getting Started-Part 2/
Advanced Results Parameters/Typecasting.

If M.RPKT.func is a SET, the individual key values may be adjusted to an
allowable value, and all of them sent back in an ACK message to the sender using
the SEND function with the <data> field blank and <prefix> defined. For
examples, see the SD360 macro.  Here is an excerpt:

  else if M.RPKT.func eqs "GET"
    rmsg "T2R" ,,,, M.RPKT.data d_
    loop d_nk nn   ! loop through table entries
      res  d_v^nn P_^{d_k^nn}
    endloop
    rmsg "SEND" M.RPKT.addr "RET" M.info ,, d_

If <prefix> is defined when sending a message, the message data is built by
reversing the T2R function to build the table for the data object.  If  <prefix>
is not entered, it is assumed that the <data> entry is a table in serialized
form built on the command line.  For example:

    rmsg "SEND" "MYNODE:9001" "SET" 0 {FREQ=1e6,DEMOD=FM}

Switches:
  /RMIFID=n - the ID of the RMIF primitive in this macro