NAME

       FunParamPut - put a Funtools param value

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)

DESCRIPTION

       The  four routines FunParamPutb(), FunParamPuti(), FunParamPutd(), and 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 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 name of the parameter.  ( In accordance with FITS standards, the special names
       COMMENT and HISTORY, as well as blank names, are output without the "= " value indicator in columns 9 and
       10.

       The third 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  defval  argument is the value to set.  Note that the data type of this argument is different
       for each specific FunParamPut() call. The comm argument is the comment  string  to  add  to  this  header
       parameter. Its value can be NULL.  The final 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 prec argument after the 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 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.

SEE ALSO

       See funtools(7) for a list of Funtools help pages

version 1.4.5                                    April 14, 2011                                   funparamput(3)