Some more minor cleanups of --dvm

Since this is to mimic the "prun" equivalent, add the
system and system-first options as they may prove useful
going forward. Consolidate the help text for easier maintenance.

Signed-off-by: Ralph Castain <rhc@pmix.org>

src/mca/schizo/base/help-schizo-cli.txt

@@ -659,3 +659,48 @@ Supported process events include:
 -   PMIX_ERR_PROC_RESTART indicates that the specified process has been restarted.
     Additional information may include the hostname where the process is now
     executing.
+#
+#  DVM
+#
+[dvm]
+A required argument is passed to the "--dvm" directive to specify the
+location of the DVM controller (e.g., "--dvm pid:12345") or by passing
+the string "search" to instead search for an existing controller.
+
+Supported options include:
+
+search          directs the tool to search for available DVM controllers
+                it is authorized to use, connecting to the first such
+                candidate it finds.
+
+pid:<arg>       provides the PID of the target DVM controller. This can
+                be given as either the PID itself (arg = int) or the path
+                to a file that contains the PID (arg = file:<path>)
+
+file:<path>     provides the path to a PMIx rendezvous file that is
+                output by PMIx servers - the file contains all the
+                required information for completing the connection
+
+uri:<arg>       specifies the URI of the DVM controller, or the name of
+                the file (specified as file:filename) that contains that info
+
+ns:<arg>        specifies the namespace of the DVM controller
+
+system          exclusively find and use the system-level DVM controller
+
+system-first    look for a system-level DVM controller, fall back to searching
+                for an available DVM controller the command is authorized to
+                use if a system-level controller is not found
+
+Examples:
+  <command> --dvm file:dvm_uri.txt --np 4 ./a.out
+
+  <command> --dvm pid:12345 --np 4 ./a.out
+
+  <command> --dvm uri:file:dvm_uri.txt --np 4 ./a.out
+
+  <command> --dvm ns:prte-node1-2095 --np 4 ./a.out
+
+  <command> --dvm pid:file:prte_pid.txt --np 4 ./a.out
+
+  <command> --dvm search --np 4 ./a.out

src/mca/schizo/ompi/help-schizo-ompi.txt

@@ -198,47 +198,10 @@ Initiate an instance of the PMIx Reference RTE (PRRTE) DVM
 [dvm]
 Utilize an existing persistent DVM instead of instantiating an
 independent runtime infrastructure. This is provided as a convenience
-option for those wanting to embed "mpirun" in a script that can be
-optionally used to run either independently or under a persistent DVM.
+option for those wanting to embed the "mpirun" command in a script that
+can be optionally used to run either independently or under a persistent DVM.
 
-A required argument is passed to the "--dvm" directive to specify the
-location of the DVM controller (e.g., "--dvm pid:12345") or by passing
-the string "search" to instead search for an existing controller.
-
-Supported options include:
-
-search      directs "mpirun" to search for available DVM controllers it
-            is authorized to use, connecting to the first candidate it finds.
-
-pid:<arg>   provides the PID of the target DVM controller. This can
-            be given as either the PID itself (arg = int) or the path
-            to a file that contains the PID (arg = file:<path>)
-
-file:<path> provides the path to a PMIx rendezvous file that is
-            output by PMIx servers - the file contains all the
-            required information for completing the connection
-
-uri:<arg>   specifies the URI of the DVM controller, or the name of
-            the file (specified as file:filename) that contains that info
-
-ns:<arg>    specifies the namespace of the DVM controller
-
-Specifying "--dvm search" directs "mpirun" to search for available
-DVM controllers it is authorized to use, connecting to the first such
-candidate it finds.
-
-Examples:
-  mpirun --dvm file:dvm_uri.txt --np 4 ./a.out
-
-  mpirun --dvm pid:12345 --np 4 ./a.out
-
-  mpirun --dvm uri:file:dvm_uri.txt --np 4 ./a.out
-
-  mpirun --dvm ns:prte-node1-2095 --np 4 ./a.out
-
-  mpirun --dvm pid:file:prte_pid.txt --np 4 ./a.out
-
-  mpirun --dvm search --np 4 ./a.out
+#include#help-schizo-cli#dvm
 #
 [prtemca]
 Syntax: --prtemca <arg0> <arg1>

src/mca/schizo/prte/help-schizo-prterun.txt

@@ -139,45 +139,7 @@ but is provided as a convenience option for those wanting to embed
 the "prterun" command in a script that can be optionally used to
 run either independently or under a persistent DVM.
 
-A required argument are passed to the "--dvm" directive to specify the
-location of the DVM controller (e.g., "--dvm pid:12345") or by passing
-the string "search" to instead search for an existing controller.
-
-Supported options include:
-
-search      directs "prterun" to search for available DVM controllers it
-            is authorized to use, connecting to the first candidate it
-            finds
-
-pid:<arg>   provides the PID of the target DVM controller. This can
-            be given as either the PID itself (arg = int) or the path
-            to a file that contains the PID (arg = file:<path>)
-
-file:<path> provides the path to a PMIx rendezvous file that is
-            output by PMIx servers - the file contains all the
-            required information for completing the connection
-
-uri:<arg>   specifies the URI of the DVM controller, or the name of
-            the file (specified as file:filename) that contains that info
-
-ns:<arg>    specifies the namespace of the DVM controller
-
-Specifying "--dvm search" directs "prterun" to search for available
-DVM controllers it is authorized to use, connecting to the first such
-candidate it finds.
-
-Examples:
-  prterun --dvm file:dvm_uri.txt --np 4 ./a.out
-
-  prterun --dvm pid:12345 --np 4 ./a.out
-
-  prterun --dvm uri:file:dvm_uri.txt --np 4 ./a.out
-
-  prterun --dvm ns:prte-node1-2095 --np 4 ./a.out
-
-  prterun --dvm pid:file:prte_pid.txt --np 4 ./a.out
-
-  prterun --dvm search --np 4 ./a.out
+#include#help-schizo-cli#dvm
 #
 [prtemca]
 #include#help-schizo-cli#prtemca

src/tools/prte/prte.c

@@ -449,12 +449,24 @@ int main(int argc, char *argv[])
                 cptr = strdup(&opt->values[0][3]);
                 free(opt->values[0]);
                 opt->values[0] = cptr;
+            } else if (0 == strncasecmp(opt->values[0], "system", 6)) {
+                /* direct to search for a system server */
+                free(opt->key);
+                opt->key = strdup(PRTE_CLI_SYS_SERVER_ONLY);
+            } else if (0 == strncasecmp(opt->values[0], "system-first", 6)) {
+                /* direct to search for a system server first, and then
+                 * take the first available DVM */
+                free(opt->key);
+                opt->key = strdup(PRTE_CLI_NAMESPACE);
             } else if (0 != strncasecmp(opt->values[0], "search", 6)) {
                 /* "search" would mean to look for first available DVM,
                  * so we wouldn't have to adjust anything as the opt
-                 * key is already set to PRTE_CLI_DVM. However, if
-                 * this is not "search", then this is an unknown option
-                 * and must be reported to the user as an error */
+                 * key is already set to PRTE_CLI_DVM, which will be
+                 * ignored so that the PMIx_tool_init in prun_common
+                 * will conduct its standard server search.
+                 * However, if this is not "search", then this is an
+                 * unknown option and must be reported to the user as
+                 * an error */
                 pmix_show_help("help-prun.txt", "bad-dvm-option", true,
                                opt->values[0], prte_tool_basename);
                 return 1;