Allow endpoint selection based on meid in message

[ric-plt/lib/rmr.git] / doc / src / man / rmr.7.xfm

diff --git a/doc/src/man/rmr.7.xfm b/doc/src/man/rmr.7.xfm
index 2f2e47d..ae49977 100644 (file)
--- a/doc/src/man/rmr.7.xfm
+++ b/doc/src/man/rmr.7.xfm
@@ -53,7 +53,7 @@ response relationship when needed.
 
 
 &h3(The Route Table)
-The library is supplied with a route table which maps message numbers to
+The library must be given a route table which maps message numbers to
 endpoint groups such that each time a message of type T is sent, the message
 is delivered to one member of each group associated with T.
 For example, message type 2 might route to two different groups where
@@ -66,6 +66,99 @@ belong to which groups, and which groups accept which message types.
 Once understood, the route table generator publishes a table that is ingested
 by RMr and used for mapping messages to end points.
 
+.sp
+The following is a simple route table which causes message types 0 through 9 to
+be routed to specific applications:
+
+&ex_start
+newrt|start
+   mse|0|-1| %meid
+   mse|1|-1|app10:4560,app11:4560
+   mse|2|-1|app12:4560
+   mse|3|-1|app14:4560
+   mse|4|-1|app18:4560
+   mse|5|-1|app01:4560
+   mse|6|-1|app02:4560
+   mse|7|-1|app03:4560
+   mse|8|-1|app04:4560
+   mse|9|-1|app05:4560
+newrt|end
+&ex_end
+&space
+The special endpoint "%meid" indicates that the message type (0 in this case) is
+to be routed to the endpoint which has been listed as the "owner" for the meid
+appearing in the message.
+MEID ownership is communicated to RMR using the same Route Table Manager interface
+and by supplying a "table" such as the one below:
+
+&ex_start
+meid_map | start
+   mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
+   mme_ar | control2 | meid100 meid101 meid102 meid103 
+meid_map | end | 2
+&ex_end
+
+This table indicates that the application (endpoint) &ital(control1) "owns" 6 MEIDs
+and &ital(control2) owns 4.  
+When message type 0 is sent, the MEID in the message will be used to select the 
+endpoint via this table. 
+
+&space
+The MEID table will update the existing owner relationships, and add new ones; it
+is necessary to send only the changes with the add/replace (mme_ar) entries in
+the table. 
+When necessary, MEIDs can be deleted by adding an &cw(mme_del) record to the table.
+The following example illustrates how this might look:
+
+&ex_start
+meid_map | start
+   mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
+   mme_ar | control2 | meid100 meid101 meid102 meid103 
+   mme_del| meid200 meid401
+meid_map | end | 1
+&ex_end
+
+&h3(Route Table Syntax)
+The following illustrates the syntax for both the route table.
+
+&space
+&ex_start
+newrt | start
+mse | <message-type>[,<sender-endpoint>] | <sub-id> <roud-robin-grp>[;<round-robin-grp>]...
+newrt | end
+&ex_end
+&space
+A round robin group is one or more endpoints from which one will be selected to receive
+the message. 
+When multiple endpoints are given in a group, they must be separated with a comma.
+An endpoint is the IP address and port (e.g. 192.158.4.30:8219) or DNS name and port of the
+application that should receive the message type.
+If multiple round-robin groups are given, they must be separated by a semicolon, and 
+
+&h3(MEID Map Syntax)
+The MEID map is similar to the route table. 
+Entries are used to add or replace the ownership of one or more MEIDs (mme_ar) or to 
+delete one or more MEIDs (mme_del).
+The following is the syntax for the MEID map.
+
+&space
+&ex_start
+meid_map | start
+mme_ar | <owner-endpoint> | <meid> [<meid>...]
+mme_del | <meid> [<meid>...]
+meid_map | end | <count>
+&ex_end
+
+&space
+The <count> on the end record indicates the number of mme_ar and mme_del records
+which were sent; if the count does not match the whole map is refused and dropped.
+The <owner-endpoint> is the endpoint which should receive the message when a message
+is routed based on the MEID it contains.
+A MEID may be "owned" by only one endpoint, and if supplied multiple times, the last
+observed relationship is used.
+Each of the lists of MEIDs are blank separated.
+
+
 &h3(Environment)
 To enable configuration of the library behaviour outside of direct user application
 control, RMr supports a number of environment variables which provide information
@@ -73,6 +166,7 @@ to the library.
 The following is a list of the various environment variables, what they control
 and the defaults which RMr uses if undefined.
 
+&space
 .** the list of environment vars supported
 .im &{lib}/man/env_var_list.im