diff options
Diffstat (limited to 'funtools/doc/pod/funparamget.pod')
-rw-r--r-- | funtools/doc/pod/funparamget.pod | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/funtools/doc/pod/funparamget.pod b/funtools/doc/pod/funparamget.pod new file mode 100644 index 0000000..6d06d10 --- /dev/null +++ b/funtools/doc/pod/funparamget.pod @@ -0,0 +1,153 @@ +=pod + +=head1 NAME + + + +B<FunParamGet - get a Funtools param value> + + + +=head1 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) + + + + + +=head1 DESCRIPTION + + + + +The four routines B<FunParamGetb()>, B<FunParamGeti()>, +B<FunParamGetd()>, and B<FunParamGets()>, return the value of +a FITS header parameter as a boolean, int, double, and string, +respectively. The string returned by B<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 B<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 + +B<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 +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 +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 B<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 +B<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, B<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. +B<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 B<FunParamGets()> will return the 80 raw characters of the +B<nth> FITS card (including the comment) if B<name> is specified as +NULL and B<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; + } + } + + + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + +=cut |