From 666721c7ada87b5dca878f76b0429e7b1e4c7ee7 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 6 Dec 2016 12:16:35 -0600 Subject: [PATCH] Document caput scalar arg's, update usage docs --- src/ca/CAref.html | 113 +++++++++++++++++++++++++++----------------- src/catools/caput.c | 8 ++-- 2 files changed, 75 insertions(+), 46 deletions(-) diff --git a/src/ca/CAref.html b/src/ca/CAref.html index 91bc6bed2..0b9af7b30 100644 --- a/src/ca/CAref.html +++ b/src/ca/CAref.html @@ -1146,16 +1146,10 @@ the output.

Wide mode "name timestamp value stat sevr" (read PVs as DBR_TIME_xxx) - - -n - Print DBF_ENUM values as number (default are enum strings) - -d <type> - Request specific dbr type; use string (DBR_ prefix may be omitted) - -

or number of one of the following types:

- + Request specific dbr type; use string (DBR_ prefix may be omitted)
+ or number of one of the following types:
@@ -1272,6 +1266,14 @@ the output.

+ + + Enum format: + + + -n + Print DBF_ENUM value as number (default is enum string) + Arrays: @@ -1303,15 +1305,15 @@ the output.

-e <nr> - Use %e format, with <nr> digits after the decimal point + Use %e format, with a precision of <nr> digits -f <nr> - Use %f format, with <nr> digits after the decimal point + Use %f format, with a precision of <nr> digits -g <nr> - Use %g format, with <nr> digits after the decimal point + Use %g format, with a precision of <nr> digits -s @@ -1349,6 +1351,14 @@ the output.

-0b Print as binary number + + + Alternate output field separator: + + + -F <ofs> + Use <ofs> as an alternate output field separator + @@ -1381,9 +1391,10 @@ the output.

Wait time, specifies longer CA timeout, default is 1.0 second - -m <mask> - Specify CA event mask to use, with <mask> being any combination - of 'v' (value), 'a' (alarm), 'l' (log), 'p' (property). Default: va + -m <msk> + Specify CA event mask to use. <msk> is any combination of
+ 'v' (value), 'a' (alarm), 'l' (log/archive), 'p' (property).
+ Default event mask is 'va' -p <prio> @@ -1405,8 +1416,8 @@ the output.

'n' = no timestamps
'r' = relative timestamps (time elapsed since start of program)
'i' = incremental timestamps (time elapsed since last update)
- 'I' = incremental timestamps (time elapsed since last update, by - channel) + 'I' = incremental timestamps (time since last update, by channel)
+ 'r', 'i' or 'I' require 's' or 'c' to select the time source @@ -1414,7 +1425,7 @@ the output.

-n - Print DBF_ENUM values as number (default are enum strings) + Print DBF_ENUM values as number (default is enum string) @@ -1422,16 +1433,15 @@ the output.

- Value format: Print number of requested values, then list of - values + Array values: Print number of elements, then list of values Default: - Print all values + Default: Request and print all elements (dynamic arrays supported) - -# <count> - Print first <count> elements of an array + -# <num> + Request and print up to <num> elements -S @@ -1439,23 +1449,23 @@ the output.

- Floating point type format: + Floating point format: Default: Use %g format - -e <nr> - Use %e format, with <nr> digits after the decimal point + -e <num> + Use %e format, with a precision of <num> digits - -f <nr> - Use %f format, with <nr> digits after the decimal point + -f <num> + Use %f format, with a precision of <num> digits - -g <nr> - Use %g format, with <nr> digits after the decimal point + -g <num> + Use %g format, with a precision of <num> digits -s @@ -1497,21 +1507,27 @@ the output.

caput

-
caput [options] <PV name> <value>
+
caput [options] <PV name> <value> ...
 caput -a [options] <PV name> <no of elements> <value> ...

 
 
Description

 
 
Put value to a PV.

 
-
The specified value is written to the PV (as a string). The PV value is read
-before and after the write operation and printed as "Old" and "new" values on
-stdout.

+
The specified value is written to the PV (as a string). The PV's value is
+read before and after the write operation and printed as "Old" and "New" values
+on stdout.

 
-
The array variant writes an array to the specified PV. The first numeric
-argument specifying the number of array elements is kept for compatibility with
-the array data format of caget - the actual number of values specified on the
-command line is used.

+
There are two variants to the arguments for this command. For the scalar
+variant without the -a flag, all the value arguments provided after
+the PV name are concatenated with a single space character between them, and the
+resulting string (up to 40 characters long unless the -S flag is
+given) is written to the specified PV.

+
+
The array variant with the -a flag writes an array of string
+values to the specified PV. The numeric argument giving the number of array
+elements is actually ignored, the array length to be written is actually
+controlled by the number of values provided on the command line.

 
 
@@ -1550,12 +1566,16 @@ command line is used.

+    
+      
+      
+    
-      
+      
@@ -1571,17 +1591,24 @@ command line is used.

-      
-      
+      
+      
-      
+      
-      
+      
+    
+    
+      
+      
+    
+    
+      
+      

   
       
-t
       Terse mode - print only successfully written value, without name
     
-lLong mode "name timestamp value stat sevr" (read PVs as DBR_TIME_xxx)

     

       
       Enum Format:
     

     
Default:
       Auto - try value as ENUM string, then as index number
     

     

       Arrays:
     

     
-aPut array dataDefault:Put scalar
     

     

       Value format: Print number of requested values, then list of
-      valuesValue format: all value arguments concatenated with spaces
     

     

       -SPut string as an array of char (long string)Put string as an array of chars (long string)
-aPut array
Value format: number of values, then list of values
     

   
 

diff --git a/src/catools/caput.c b/src/catools/caput.c
index 02182932d..715672958 100644
--- a/src/catools/caput.c
+++ b/src/catools/caput.c
@@ -56,7 +56,7 @@ static epicsEventId epId;
 
 void usage (void)
 {
-    fprintf (stderr, "\nUsage: caput [options]  \n"
+    fprintf (stderr, "\nUsage: caput [options]   ...\n"
     "       caput -a [options]    ...\n\n"
     "  -h: Help: Print this message\n"
     "Channel Access options:\n"
@@ -71,9 +71,11 @@ void usage (void)
     "  -n: Force interpretation of values as numbers\n"
     "  -s: Force interpretation of values as strings\n"
     "Arrays:\n"
+    "  Default: Put scalar\n"
+    "      Value format: all value arguments concatenated with spaces\n"
+    "  -S: Put string as an array of chars (long string)\n"
     "  -a: Put array\n"
-    "      Value format: number of requested values, then list of values\n"
-    "  -S: Put string as an array of char (long string)\n"
+    "      Value format: number of values, then list of values\n"
     "\nExample: caput my_channel 1.2\n"
     "  (puts 1.2 to my_channel)\n\n"
              , DEFAULT_TIMEOUT, CA_PRIORITY_MAX);