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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
|
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "funparamget 3"
.TH funparamget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
.SH "NAME"
FunParamGet \- get a Funtools param value
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <funtools.h>
.Ve
.PP
.Vb 1
\& int FunParamGetb(Fun fun, char *name, int n, int defval, int *got)
.Ve
.PP
.Vb 1
\& int FunParamGeti(Fun fun, char *name, int n, int defval, int *got)
.Ve
.PP
.Vb 1
\& double FunParamGetd(Fun fun, char *name, int n, double defval, int *got)
.Ve
.PP
.Vb 1
\& char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The four routines \fB\f(BIFunParamGetb()\fB\fR, \fB\f(BIFunParamGeti()\fB\fR,
\&\fB\f(BIFunParamGetd()\fB\fR, and \fB\f(BIFunParamGets()\fB\fR, return the value of
a \s-1FITS\s0 header parameter as a boolean, int, double, and string,
respectively. The string returned by \fB\f(BIFunParamGets()\fB\fR is a malloc'ed
copy of the header value and should be freed when no longer needed.
.PP
The first argument is the Fun handle associated with the \s-1FITS\s0 header
being accessed. Normally, the header is associated with the \s-1FITS\s0
extension that you opened with \fB\f(BIFunOpen()\fB\fR. However, you can use
\&\fIFunInfoPut()\fR to specify access of the primary header. In particular,
if you set the \s-1FUN_PRIMARYHEADER\s0 parameter to 1, then the primary
header is used for all parameter access until the value is reset to
0. For example:
.PP
.Vb 9
\& 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
.Ve
.PP
Alternatively, you can use the \s-1FUN_PRIMARY\s0 macro to access parameters
from the primary header on a per-parameter basis:
.PP
.Vb 2
\& FunParamGeti(fun, "NAXIS1", 0, 0, &got); # current header
\& FunParamGeti(FUN_PRIMARY(fun), "NAXIS1", 0, 0, &got); # primary header
.Ve
.PP
\s-1NB - \s0 \s-1FUN_PRIMARY\s0 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 \fIFunInfoPut()\fR to switch between the
extension header and the primary header.
.PP
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.
.PP
The second argument is the name of the parameter to access. The third
\&\fBn\fR 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 \s-1TLMIN\s0 and \s-1TLMAX\s0 for each column in a binary
table, you can use:
.PP
.Vb 4
\& 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);
\& }
.Ve
.PP
The fourth \fBdefval\fR 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 \fIFunParamGet()\fR call. The final
\&\fBgot\fR argument will be 0 if no param was found. Otherwise the
data type of the parameter is returned as follows: \s-1FUN_PAR_UNKNOWN\s0
('u'), \s-1FUN_PAR_COMMENT\s0 ('c'), \s-1FUN_PAR_LOGICAL\s0 ('l'), \s-1FUN_PAR_INTEGER\s0
('i'), \s-1FUN_PAR_STRING\s0 ('s'), \s-1FUN_PAR_REAL\s0 ('r'), \s-1FUN_PAR_COMPLEX\s0 ('x').
.PP
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.
.PP
By default, \fB\f(BIFunParamGets()\fB\fR returns the string value of the
named parameter. However, you can use \fIFunInfoPut()\fR to retrieve the
raw 80\-character \s-1FITS\s0 card instead. In particular, if you set the
\&\s-1FUN_RAWPARAM\s0 parameter to 1, then card images will be returned by
\&\fIFunParamGets()\fR until the value is reset to 0.
.PP
Alternatively, if the \s-1FUN_RAW\s0 macro is applied to the name, then the
80\-character raw \s-1FITS\s0 card is returned instead.
\s-1NB - \s0 \s-1FUN_RAW\s0 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 \fIFunInfoPut()\fR to switch between the
extension header and the primary header.
.PP
Note that in addition to the behaviors described above, the
routine \fB\f(BIFunParamGets()\fB\fR will return the 80 raw characters of the
\&\fBnth\fR \s-1FITS\s0 card (including the comment) if \fBname\fR is specified as
\&\s-1NULL\s0 and \fBn\fR is positive. For example, to loop through all \s-1FITS\s0
header cards in a given extension and print out the raw card, use:
.PP
.Vb 9
\& for(i=1; ;i++){
\& if( (s = FunParamGets(fun, NULL, i, NULL, &got)) ){
\& fprintf(stdout, "%.80s\en", s);
\& free(s);
\& }
\& else{
\& break;
\& }
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See funtools(7) for a list of Funtools help pages
|
