[irods/irods#6465] py_remote now recognizes INST_NAME tag

In the second parameter of the remote execution microservice, we can
now use INST_NAME to specify which rule engine plugin instance on
the remote host should be used to execute the given rule text.

Author: d-w-moore

README.md

@@ -58,13 +58,22 @@ This version of the Python Rule Engine Plugin uses the Python 2.7 interpreter.
 
 # Remote Execution
 
-There exists a requirement for the implementation of a different ```remote``` microservice call for every rule language.  Given the possibility of a namespace collision with more than one rule language being configured simultaneously, the name of the microservice to use for the python language is ```py_remote()```.
+There exists a requirement for the implementation of a different `remote` microservice call for every rule language.  Given the possibility of a namespace collision with more than one rule language being configured simultaneously, the name of the microservice to use for the python language is `py_remote()`.  As with remote execution via the native rule engine, this microservice runs the given rule text on the remote host using `exec_rule_text`.   This can be done on any iRODS host (inside or outside the local zone) where the invoking user is authenticated.
+
+The microservice's signature is: `py_remote(hostname, hints, code, recovery)`.
+
+Its four parameters are strings:
+   - `hostname`. The name of the iRODS server where the code is to be executed.
+   - `hints`.  A string containing optional XML tags. Currently scanned only for the `INST_NAME` tag, and other tags - if used - will be ignored. This
+      includes <ZONE>, since the zone (whether remote or local) is inferred from the `hostname` parameter.
+   - `code`. The Python source code to be executed, in the form of a complete rule, i.e.: `def main(rule_args,callback,rei): ...`
+   - `recovery`.  This is currently unused.
 
 For example:
 ```
 def main(rule_args, callback, rei):
     rule_code = "def main(rule_args, callback, rei):\n    print('This is a test of the Python Remote Rule Execution')"
-    callback.py_remote('icat.example.org', '', rule_code, '')
+    callback.py_remote('icat.example.org', '<INST_NAME>irods_rule_engine_plugin-python-instance</INST_NAME>', rule_code, '')
 INPUT null
 OUTPUT ruleExecOut
 ```

irods_rule_engine_plugin-python.cxx

@@ -5,6 +5,8 @@
 #include <fstream>
 #include <list>
 #include <string>
+#include <vector>
+#include <map>
 #include <memory>
 #include <mutex>
 
@@ -25,6 +27,9 @@
 #include "msParam.h"
 #include "rsExecMyRule.hpp"
 
+// Can delete this in favor of #include <irods/reFuncDefs.hpp> , on resolution of irods/irods #6545:
+std::map<std::string, std::vector<std::string>> getTaggedValues(const char *str);
+
 #include "irods_rule_engine_plugin-python.hpp"
 
 #define register
@@ -98,11 +103,22 @@ static int remote_exec_msvc(
         META_STR_LEN,
         "%s", rule_text.c_str());
 
+     // TODO:
+     // It is not yet known whether execCondition is actually used by rsExecMyRule or
+     // any functions it calls. If in resolution of [irods/irods#6567] we find it is
+     // unused, the following addKeyVal call may be unnecessary.
      addKeyVal(
          &exec_inp.condInput,
          "execCondition",
          static_cast<char*>(_pa->inOutStruct));
 
+    auto taggedValues = getTaggedValues(static_cast<char*>(_pa->inOutStruct));
+    auto it = taggedValues.find("INST_NAME");
+    if ( it != taggedValues.end() ) {
+        addKeyVal( &exec_inp.condInput, INSTANCE_NAME_KW, it->second.front().c_str());
+        taggedValues.erase(it);
+    }
+
     msParamArray_t *out_arr = NULL;
     return rsExecMyRule(
                _rei->rsComm,