NAME¶
FunParamGet - get a Funtools param value
SYNOPSIS¶
#include <funtools.h>
int FunParamGetb(Fun fun, char *name, int n, int defval, int *got)
int FunParamGeti(Fun fun, char *name, int n, int defval, int *got)
double FunParamGetd(Fun fun, char *name, int n, double defval, int *got)
char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got)
DESCRIPTION¶
The four routines
FunParamGetb(),
FunParamGeti() ,
FunParamGetd() , and
FunParamGets() , return the value of a FITS header
parameter as a boolean, int, double, and string, respectively. The string
returned by
FunParamGets() is a malloc'ed copy of
the header value and should be freed when no longer needed.
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 access 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;
FunParamGeti(fun, "NAXIS", 1, 0, &got); # current header
val=1;
FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0); # switch to ...
FunParamGeti(fun, "NAXIS", 1, 0, &got); # ... primary header
FunParamGeti(fun, "NAXIS", 2, 0, &got); # ... primary header
val=0;
FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0); # switch back to ...
FunParamGeti(fun, "NAXIS", 2, 0, &got); # current header
Alternatively, you can use the FUN_PRIMARY macro to access parameters from the
primary header on a per-parameter basis:
FunParamGeti(fun, "NAXIS1", 0, 0, &got); # current header
FunParamGeti(FUN_PRIMARY(fun), "NAXIS1", 0, 0, &got); # primary header
NB - FUN_PRIMARY is deprecated. It makes use of a global parameter and therefore
will not not appropriate for threaded applications, when we make funtools
thread\-safe. We recommend use of
FunInfoPut() to switch between the
extension header and the primary header.
For output data, access to the primary header is only possible until the header
is written out, which usually takes place when the first data are written.
The second argument is the name of the parameter to access. 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 gather up all values of TLMIN and
TLMAX for each column in a binary table, you can use:
for(i=0, got=1; got; i++){
fun->cols[i]->tlmin = (int)FunParamGeti(fun, "TLMIN", i+1, 0.0, &got);
fun->cols[i]->tlmax = (int)FunParamGeti(fun, "TLMAX", i+1, 0.0, &got);
}
The fourth
defval argument is the default value to return if the
parameter does not exist. Note that the data type of this parameter is
different for each specific
FunParamGet() call. The final
got
argument will be 0 if no param was found. Otherwise the data type of the
parameter is returned as follows: FUN_PAR_UNKNOWN ('u'), FUN_PAR_COMMENT
('c'), FUN_PAR_LOGICAL ('l'), FUN_PAR_INTEGER ('i'), FUN_PAR_STRING ('s'),
FUN_PAR_REAL ('r'), FUN_PAR_COMPLEX ('x').
These routines return the value of the header parameter, or the specified
default value if the header parameter does not exist. The returned value is a
malloc'ed string and should be freed when no longer needed.
By default,
FunParamGets() returns the string value
of the named parameter. However, you can use
FunInfoPut() to retrieve
the raw 80\-character FITS card instead. In particular, if you set the
FUN_RAWPARAM parameter to 1, then card images will be returned by
FunParamGets() until the value is reset to 0.
Alternatively, if the FUN_RAW macro is applied to the name, then the
80\-character raw FITS card is returned instead. NB - FUN_RAW is deprecated.
It makes use of a global parameter and therefore will not not appropriate for
threaded applications, when we make funtools thread\-safe. We recommend use of
FunInfoPut() to switch between the extension header and the primary
header.
Note that in addition to the behaviors described above, the routine
FunParamGets() will return the 80 raw characters
of the
nth FITS card (including the comment) if
name is
specified as NULL and
n is positive. For example, to loop through all
FITS header cards in a given extension and print out the raw card, use:
for(i=1; ;i++){
if( (s = FunParamGets(fun, NULL, i, NULL, &got)) ){
fprintf(stdout, "%.80s\n", s);
free(s);
}
else{
break;
}
}
SEE ALSO¶
See
funtools(7) for a list of Funtools help pages