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
|
.\" 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 "funparamput 3"
.TH funparamput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
.SH "NAME"
FunParamPut \- put a Funtools param value
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <funtools.h>
.Ve
.PP
.Vb 2
\& int FunParamPutb(Fun fun, char *name, int n, int value, char *comm,
\& int append)
.Ve
.PP
.Vb 2
\& int FunParamPuti(Fun fun, char *name, int n, int value, char *comm,
\& int append)
.Ve
.PP
.Vb 2
\& int FunParamPutd(Fun fun, char *name, int n, double value, int prec,
\& char *comm, int append)
.Ve
.PP
.Vb 2
\& int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm,
\& int append)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The four routines \fB\f(BIFunParamPutb()\fB\fR, \fB\f(BIFunParamPuti()\fB\fR,
\&\fB\f(BIFunParamPutd()\fB\fR, and \fB\f(BIFunParamPuts()\fB\fR, will set the value
of a \s-1FITS\s0 header parameter as a boolean, int, double, and string,
respectively.
.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 that use 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 5
\& int val;
\& FunParamPuti(fun, "NAXIS1", 0, 10, NULL, 1); # current header
\& val=1;
\& FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0); # switch to ...
\& FunParamPuti(fun, "NAXIS1", 0, 10, NULL, 1); # primary header
.Ve
.PP
(You also can use the deprecated \s-1FUN_PRIMARY\s0 macro, to access
parameters from the primary header.)
.PP
The second argument is the \fBname\fR of the parameter. (
In accordance with \s-1FITS\s0 standards, the special names \fB\s-1COMMENT\s0\fR
and \fB\s-1HISTORY\s0\fR, as well as blank names, are output without the \*(L"= \*(R"
value indicator in columns 9 and 10.
.PP
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 set the 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; i<got; i++){
\& FunParamPutd(fun, "TLMIN", i+1, tlmin[i], 7, "min column val", 1);
\& FunParamPutd(fun, "TLMAX", i+1, tlmax[i], 7, "max column val", 1);
\& }
.Ve
.PP
The fourth \fBdefval\fR argument is the value to set. Note that the
data type of this argument is different for each specific
\&\fIFunParamPut()\fR call. The \fBcomm\fR argument is the comment
string to add to this header parameter. Its value can be \s-1NULL\s0. The
final \fBappend\fR argument determines whether the parameter is added
to the header if it does not exist. If set to a non-zero value, the
header parameter will be appended to the header if it does not exist.
If set to 0, the value will only be used to change an existing parameter.
.PP
Note that the double precision routine \fIFunParamPutd()\fR supports an
extra \fBprec\fR argument after the \fBvalue\fR argument, in order
to specify the precision when converting the double value to \s-1ASCII\s0. In
general a 20.[prec] format is used (since 20 characters are alloted to
a floating point number in \s-1FITS\s0) as follows: if the double value being
put to the header is less than 0.1 or greater than or equal to
10**(20\-2\-[prec]), then \f(CW%20\fR.[prec]e format is used (i.e., scientific
notation); otherwise \f(CW%20\fR.[prec]f format is used (i.e., numeric
notation).
.PP
As a rule, parameters should be set before writing the table or image.
It is, however, possible to update the value of an \fBexisting\fR
parameter after writing an image or table (but not to add a new
one). Such updating only works if the parameter already exists and if
the output file is seekable, i.e. if it is a disk file or is stdout
being redirected to a disk file.
.PP
It is possible to add a new parameter to a header after the data has
been written, but only if space has previously been reserved. To reserve
space, add a blank parameter whose value is the name of the parameter you
eventually will update. Then, when writing the new parameter, specify a
value of 2 for the append flag. The parameter writing routine will
first look to update an existing parameter, as usual. If an existing
parameter is not found, an appropriately-valued blank parameter will be
searched for and replaced. For example:
.PP
.Vb 8
\& /* add blank card to be used as a place holder for IPAR1 update */
\& FunParamPuts(fun, NULL, 0, "IPAR1", "INTEGER Param", 0);
\& ...
\& /* write header and data */
\& FunTableRowPut(fun, events, got, 0, NULL);
\& ...
\& /* update param in file after writing data -- note append = 2 here */
\& FunParamPuti(fun, "IPAR", 1, 400, "INTEGER Param", 2);
.Ve
.PP
The parameter routines return a 1 if the routine was successful and a 0 on
failure. In general, the major reason for failure is that you did not
set the append argument to a non-zero value and the parameter did not
already exist in the file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See funtools(7) for a list of Funtools help pages
|
