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