1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
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
|
