1 files changed, 147 insertions, 0 deletions
diff --git a/funtools/doc/pod/funparamput.pod b/funtools/doc/pod/funparamput.pod
new file mode 100644
index 0000000..65d1b55
--- /dev/null
+++ b/funtools/doc/pod/funparamput.pod
@@ -0,0 +1,147 @@
+=pod
+
+=head1 NAME
+
+
+
+B<FunParamPut - put a Funtools param value>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+
+  #include <funtools.h>
+
+  int FunParamPutb(Fun fun, char *name, int n, int value, char *comm,
+                   int append)
+
+  int FunParamPuti(Fun fun, char *name, int n, int value, char *comm,
+                   int append)
+
+  int FunParamPutd(Fun fun, char *name, int n, double value, int prec,
+                   char *comm, int append)
+
+  int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm,
+                   int append)
+
+
+
+
+
+=head1 DESCRIPTION
+
+
+
+
+The four routines B<FunParamPutb()>, B<FunParamPuti()>,
+B<FunParamPutd()>, and B<FunParamPuts()>, will set the value
+of a FITS header parameter as a boolean, int, double, and string,
+respectively.
+
+
+The first argument is the Fun handle associated with the FITS header
+being accessed. Normally, the header is associated with the FITS
+extension that you opened with B<FunOpen()>.
+However, you can use FunInfoPut() to specify that use of the primary
+header. In particular, if you set the FUN_PRIMARYHEADER parameter to
+1, then the primary header is used for all parameter access until the
+value is reset to 0. For example:
+
+  int val;
+  FunParamPuti(fun, "NAXIS1", 0, 10, NULL, 1);       # current header
+  val=1;
+  FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0);       # switch to ...
+  FunParamPuti(fun, "NAXIS1", 0, 10, NULL, 1);       # primary header
+
+(You also can use the deprecated FUN_PRIMARY macro, to access
+parameters from the primary header.)
+
+
+The second argument is the B<name> of the parameter.  (
+In accordance with FITS standards, the special names B<COMMENT>
+and B<HISTORY>, as well as blank names, are output without the "= "
+value indicator in columns 9 and 10.
+
+
+The third B<n> argument, if non-zero, is an integer that will be
+added as a suffix to the parameter name.  This makes it easy to use a
+simple loop to process parameters having the same root name.  For
+example, to set the values of TLMIN and TLMAX for each column in a
+binary table, you can use:
+
+  for(i=0; i<got; i++){
+    FunParamPutd(fun, "TLMIN", i+1, tlmin[i], 7, "min column val", 1);
+    FunParamPutd(fun, "TLMAX", i+1, tlmax[i], 7, "max column val", 1);
+  }
+
+
+
+The fourth B<defval> argument is the value to set.  Note that the
+data type of this argument is different for each specific
+FunParamPut() call. The B<comm> argument is the comment
+string to add to this header parameter. Its value can be NULL.  The
+final B<append> argument determines whether the parameter is added
+to the header if it does not exist. If set to a non-zero value, the
+header parameter will be appended to the header if it does not exist.
+If set to 0, the value will only be used to change an existing parameter.
+
+
+Note that the double precision routine FunParamPutd() supports an
+extra B<prec> argument after the B<value> argument, in order
+to specify the precision when converting the double value to ASCII. In
+general a 20.[prec] format is used (since 20 characters are alloted to
+a floating point number in FITS) as follows: if the double value being
+put to the header is less than 0.1 or greater than or equal to
+10**(20-2-[prec]), then %20.[prec]e format is used (i.e., scientific
+notation); otherwise %20.[prec]f format is used (i.e., numeric
+notation).
+
+
+As a rule, parameters should be set before writing the table or image.
+It is, however, possible to update the value of an B<existing>
+parameter after writing an image or table (but not to add a new
+one). Such updating only works if the parameter already exists and if
+the output file is seekable, i.e. if it is a disk file or is stdout
+being redirected to a disk file.
+
+
+It is possible to add a new parameter to a header after the data has
+been written, but only if space has previously been reserved. To reserve
+space, add a blank parameter whose value is the name of the parameter you
+eventually will update. Then, when writing the new parameter, specify a 
+value of 2 for the append flag. The parameter writing routine will
+first look to update an existing parameter, as usual. If an existing
+parameter is not found, an appropriately-valued blank parameter will be
+searched for and replaced.  For example:
+
+  /* add blank card to be used as a place holder for IPAR1 update */
+  FunParamPuts(fun, NULL, 0, "IPAR1", "INTEGER Param", 0);
+  ...
+  /* write header and data */
+  FunTableRowPut(fun, events, got, 0, NULL);
+  ...
+  /* update param in file after writing data -- note append = 2 here */
+  FunParamPuti(fun, "IPAR", 1, 400, "INTEGER Param", 2);
+
+
+
+The parameter routines return a 1 if the routine was successful and a 0 on
+failure. In general, the major reason for failure is that you did not
+set the append argument to a non-zero value and the parameter did not
+already exist in the file.
+
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+=cut