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

version 1.4.5                                    April 14, 2011                                   funparamget(3)