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