funparamget(3)							SAORD Documentation						    funparamget(3)

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 exam-
       ple:

	 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 suf-
       fix 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 Fun-
       ParamGets() 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
", s);
	     free(s);
	   }
	   else{
	     break;
	   }
	 }

SEE ALSO

       See funtools(7) for a list of Funtools help pages

version 1.4.2							  January 2, 2008						    funparamget(3)