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