Merge pull request #1597 from afishbeck/ecl_help

Improve ECL command line help text

Reviewed-By: Richard Chapman <rchapman@hpccsystems.com>

ecl/eclcmd/eclcmd_core.cpp

@@ -266,7 +266,12 @@ public:
     }
     virtual void usage()
     {
-        fprintf(stdout,"\nUsage:\n\n"
+        fputs("\nUsage:\n"
+            "\n"
+            "The 'deploy' command creates a workunit on the HPCC system from the given ECL\n"
+            "text, file, archive, shared object, or dll.  The workunit will be created in\n"
+            "the 'compiled' state.\n"
+            "\n"
             "ecl deploy --cluster=<val> --name=<val> <ecl_file|->\n"
             "ecl deploy --cluster=<val> --name=<val> <archive|->\n"
             "ecl deploy [--cluster=<val>] [--name=<val>] <so|dll|->\n\n"
@@ -276,8 +281,8 @@ public:
             "   <so|dll|->             workunit dll or shared object to deploy\n"
             " Options:\n"
             "   -cl, --cluster=<val>   cluster to associate workunit with\n"
-            "   -n, --name=<val>       workunit job name\n"
-        );
+            "   -n, --name=<val>       workunit job name\n",
+            stdout);
         EclCmdWithEclTarget::usage();
     }
 private:
@@ -390,7 +395,14 @@ public:
     }
     virtual void usage()
     {
-        fprintf(stdout,"\nUsage:\n\n"
+        fputs("\nUsage:\n"
+            "\n"
+            "The 'publish' command creates a query in a queryset.  The query is created\n"
+            "by adding a workunit to a queryset and assigning it a query name.\n"
+            "\n"
+            "If the query is being created from an ECL file, archive, shared object, dll,\n"
+            "or text, a workunit is first created and then published to the queryset.\n"
+            "\n"
             "ecl publish [--cluster=<val>] [--name=<val>] [--activate] <wuid>\n"
             "ecl publish [--cluster=<val>] [--name=<val>] [--activate] <so|dll|->\n"
             "ecl publish --cluster=<val> --name=<val> [--activate] <archive|->\n"
@@ -405,8 +417,8 @@ public:
             "                          (defaults to cluster defined inside workunit)\n"
             "   -n, --name=<val>       query name to use for published workunit\n"
             "   -A, --activate         activates query when published\n"
-            "   --wait=<ms>            maximum time to wait for cluster finish updating\n"
-        );
+            "   --wait=<ms>            maximum time to wait for cluster to finish updating\n",
+            stdout);
         EclCmdWithEclTarget::usage();
     }
 private:
@@ -544,7 +556,14 @@ public:
     }
     virtual void usage()
     {
-        fprintf(stdout,"\nUsage:\n\n"
+        fputs("\nUsage:\n"
+            "\n"
+            "The 'run' command exectues an ECL workunit, text, file, archive, shared\n"
+            "object, or dll on the specified HPCC target cluster.\n"
+            "\n"
+            "Query input can be provided in xml form via the --input parameter.  Input\n"
+            "xml can be provided directly or by refrencing a file\n"
+            "\n"
             "ecl run [--cluster=<val>][--input=<file|xml>][--wait=<ms>] <wuid>\n"
             "ecl run [--cluster=<c>][--input=<file|xml>][--wait=<ms>] <queryset> <query>\n"
             "ecl run [--cluster=<c>][--name=<nm>][--input=<file|xml>][--wait=<i>] <dll|->\n"
@@ -560,8 +579,8 @@ public:
             "                          (defaults to cluster defined inside workunit)\n"
             "   -n, --name=<val>       job name\n"
             "   -in,--input=<file|xml> file or xml content to use as query input\n"
-            "   --wait=<ms>            time to wait for completion\n"
-        );
+            "   --wait=<ms>            time to wait for completion\n",
+            stdout);
         EclCmdWithEclTarget::usage();
     }
 private:
@@ -614,12 +633,16 @@ public:
     }
     virtual void usage()
     {
-        fprintf(stdout,"\nUsage:\n\n"
-            "ecl activate <queryset> <query>\n"
+        fputs("\nUsage:\n"
+            "\n"
+            "The 'activate' command assigns a query to the active alias with the same\n"
+            "name as the query.\n"
+            "\n"
+            "ecl activate <queryset> <query_id>\n"
             " Options:\n"
             "   <queryset>             name of queryset containing query to activate\n"
-            "   <query>                query to activate\n"
-        );
+            "   <query_id>             query to activate\n",
+            stdout);
         EclCmdWithQueryTarget::usage();
     }
 };
@@ -668,12 +691,15 @@ public:
     }
     virtual void usage()
     {
-        fprintf(stdout,"\nUsage:\n\n"
-            "ecl unpublish <queryset> <query>\n"
+        fputs("\nUsage:\n"
+            "\n"
+            "The 'unpublish' command removes a query from a queryset.\n"
+            "\n"
+            "ecl unpublish <queryset> <query_id>\n"
             " Options:\n"
-            "   <queryset>             name of queryset containing query to unpublish\n"
-            "   <query>                query to remove from query set\n"
-        );
+            "   <queryset>             name of queryset containing the query to remove\n"
+            "   <query_id>             query to remove from the queryset\n",
+            stdout);
         EclCmdWithQueryTarget::usage();
     }
 };
@@ -722,12 +748,16 @@ public:
     }
     virtual void usage()
     {
-        fprintf(stdout,"\nUsage:\n\n"
-            "ecl deactivate <queryset> <query>\n"
+        fputs("\nUsage:\n"
+            "\n"
+            "The 'deactivate' command removes an active query alias from the given queryset.\n"
+            "\n"
+            "ecl deactivate <queryset> <active_alias>\n"
+            "\n"
             " Options:\n"
             "   <queryset>             queryset containing alias to deactivate\n"
-            "   <query>                query to deactivate (delete)\n"
-        );
+            "   <active_alias>         active alias to be removed from the queryset\n",
+            stdout);
         EclCmdWithQueryTarget::usage();
     }
 };

ecl/eclcmd/queries/ecl-queries.cpp

@@ -214,7 +214,13 @@ public:
     }
     virtual void usage()
     {
-        fprintf(stdout,"\nUsage:\n\n"
+        fputs("\nUsage:\n"
+            "\n"
+            "The 'queries list' command displays a list of the queries in one or more\n"
+            "querysets. If a cluster is provided the querysets associated with that\n"
+            "cluster will be shown. If no queryset or cluster is specified all querysets\n"
+            "are shown.\n"
+            "\n"
             "ecl queries list [<queryset>][--cluster=<cluster>][--show=<flags>]\n\n"
             " Options:\n"
             "   <queryset>             name of queryset to get list of queries for\n"
@@ -225,8 +231,8 @@ public:
             "   S                      query is suspended in queryset\n"
 //not yet   "   X                      query is suspended on selected cluster\n"
             "   U                      query with no flags set\n"
-            " Common Options:\n"
-        );
+            " Common Options:\n",
+            stdout);
         EclCmdCommon::usage();
     }
 private:
@@ -311,17 +317,29 @@ public:
     }
     virtual void usage()
     {
-        fprintf(stdout,"\nUsage:\n\n"
-            "ecl queries copy <from querypath> <to queryset> [--activate]\n\n"
+        fputs("\nUsage:\n"
+            "\n"
+            "The 'queries copy' command copies a query from one queryset to another.\n"
+            "\n"
+            "A query can be copied from one HPCC environment to another by using a path\n"
+            "which begins with '//' followed by the IP and Port of the source EclWatch\n"
+            "and then followed by the source queryset and query.\n"
+            "\n"
+            "ecl queries copy <source_query_path> <target_queryset> [--activate]\n"
+            "\n"
+            "ecl queries copy //IP:Port/queryset/query <target_queryset> [--activate]\n"
+            "ecl queries copy queryset/query <target_queryset> [--activate]\n"
+            "\n"
             " Options:\n"
-            "   <from querypath>       path of query to copy\n"
-            "                          format: [//ip:port/]queryset/query\n"
-            "   <to queryset>          name of queryset to copy the query into\n"
-            "   -cl, --cluster         Local cluster to associate with remote workunit\n"
+            "   <source_query_path>    path of query to copy\n"
+            "                          in the form: //ip:port/queryset/query\n"
+            "                          or: queryset/query\n"
+            "   <target_queryset>      name of queryset to copy the query into\n"
+            "   -cl, --cluster=<name>  Local cluster to associate with remote workunit\n"
             "   -A, --activate         Activate the new query\n"
             "   --wait=<ms>            Max time to wait in milliseconds\n"
-            " Common Options:\n"
-        );
+            " Common Options:\n",
+            stdout);
         EclCmdCommon::usage();
     }
 private: