funparamget(3)

1funparamget(3)                SAORD Documentation               funparamget(3)
2
3
4

NAME

6       FunParamGet - get a Funtools param value
7

SYNOPSIS

9         #include <funtools.h>
10
11         int FunParamGetb(Fun fun, char *name, int n, int defval, int *got)
12
13         int FunParamGeti(Fun fun, char *name, int n, int defval, int *got)
14
15         double FunParamGetd(Fun fun, char *name, int n, double defval, int *got)
16
17         char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got)
18

DESCRIPTION

20       The four routines FunParamGetb(), FunParamGeti(), FunParamGetd(), and
21       FunParamGets(), return the value of a FITS header parameter as a bool‐
22       ean, int, double, and string, respectively. The string returned by Fun‐
23       ParamGets() is a malloc'ed copy of the header value and should be freed
24       when no longer needed.
25
26       The first argument is the Fun handle associated with the FITS header
27       being accessed. Normally, the header is associated with the FITS exten‐
28       sion that you opened with FunOpen(). However, you can use FunInfoPut()
29       to specify access of the primary header. In particular, if you set the
30       FUN_PRIMARYHEADER parameter to 1, then the primary header is used for
31       all parameter access until the value is reset to 0. For example:
32
33         int val;
34         FunParamGeti(fun, "NAXIS", 1, 0, &got);              # current header
35         val=1;
36         FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0);         # switch to ...
37         FunParamGeti(fun, "NAXIS", 1, 0, &got);              # ... primary header
38         FunParamGeti(fun, "NAXIS", 2, 0, &got);              # ... primary header
39         val=0;
40         FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0);         # switch back to ...
41         FunParamGeti(fun, "NAXIS", 2, 0, &got);              # current header
42
43       Alternatively, you can use the FUN_PRIMARY macro to access parameters
44       from the primary header on a per-parameter basis:
45
46         FunParamGeti(fun, "NAXIS1", 0, 0, &got);              # current header
47         FunParamGeti(FUN_PRIMARY(fun), "NAXIS1", 0, 0, &got); # primary header
48
49       NB: FUN_PRIMARY is deprecated.  It makes use of a global parameter and
50       therefore will not not appropriate for threaded applications, when we
51       make funtools thread-safe. We recommend use of FunInfoPut() to switch
52       between the extension header and the primary header.
53
54       For output data, access to the primary header is only possible until
55       the header is written out, which usually takes place when the first
56       data are written.
57
58       The second argument is the name of the parameter to access.  The third
59       n argument, if non-zero, is an integer that will be added as a suffix
60       to the parameter name.  This makes it easy to use a simple loop to
61       process parameters having the same root name.  For example, to gather
62       up all values of TLMIN and TLMAX for each column in a binary table, you
63       can use:
64
65         for(i=0, got=1; got; i++){
66           fun->cols[i]->tlmin = (int)FunParamGeti(fun, "TLMIN", i+1, 0.0, &got);
67           fun->cols[i]->tlmax = (int)FunParamGeti(fun, "TLMAX", i+1, 0.0, &got);
68         }
69
70       The fourth defval argument is the default value to return if the param‐
71       eter does not exist. Note that the data type of this parameter is dif‐
72       ferent for each specific FunParamGet() call. The final got argument
73       will be 0 if no param was found. Otherwise the data type of the parame‐
74       ter is returned as follows: FUN_PAR_UNKNOWN ('u'), FUN_PAR_COMMENT
75       ('c'), FUN_PAR_LOGICAL ('l'), FUN_PAR_INTEGER ('i'), FUN_PAR_STRING
76       ('s'), FUN_PAR_REAL ('r'), FUN_PAR_COMPLEX ('x').
77
78       These routines return the value of the header parameter, or the speci‐
79       fied default value if the header parameter does not exist.  The
80       returned value is a malloc'ed string and should be freed when no longer
81       needed.
82
83       By default, FunParamGets() returns the string value of the named param‐
84       eter.  However, you can use FunInfoPut() to retrieve the raw 80-charac‐
85       ter FITS card instead.  In particular, if you set the FUN_RAWPARAM
86       parameter to 1, then card images will be returned by FunParamGets()
87       until the value is reset to 0.
88
89       Alternatively, if the FUN_RAW macro is applied to the name, then the
90       80-character raw FITS card is returned instead.  NB: FUN_RAW is depre‐
91       cated.  It makes use of a global parameter and therefore will not not
92       appropriate for threaded applications, when we make funtools
93       thread-safe. We recommend use of FunInfoPut() to switch between the
94       extension header and the primary header.
95
96       Note that in addition to the behaviors described above, the routine
97       FunParamGets() will return the 80 raw characters of the nth FITS card
98       (including the comment) if name is specified as NULL and n is positive.
99       For example, to loop through all FITS header cards in a given extension
100       and print out the raw card, use:
101
102         for(i=1; ;i++){
103           if( (s = FunParamGets(fun, NULL, i, NULL, &got)) ){
104             fprintf(stdout, "%.80s\n", s);
105             free(s);
106           }
107           else{
108             break;
109           }
110         }
111

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO