diff options
Diffstat (limited to 'funtools/doc/pod/funparamget.pod')
| -rw-r--r-- | funtools/doc/pod/funparamget.pod | 153 |
1 files changed, 0 insertions, 153 deletions
diff --git a/funtools/doc/pod/funparamget.pod b/funtools/doc/pod/funparamget.pod deleted file mode 100644 index 6d06d10..0000000 --- a/funtools/doc/pod/funparamget.pod +++ /dev/null @@ -1,153 +0,0 @@ -=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 |