diff options
Diffstat (limited to 'funtools/doc/pod/funparamput.pod')
-rw-r--r-- | funtools/doc/pod/funparamput.pod | 147 |
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 |