funparamput(3)

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

NAME

6       FunParamPut - put a Funtools param value
7

SYNOPSIS

9         #include <funtools.h>
10
11         int FunParamPutb(Fun fun, char *name, int n, int value, char *comm,
12                          int append)
13
14         int FunParamPuti(Fun fun, char *name, int n, int value, char *comm,
15                          int append)
16
17         int FunParamPutd(Fun fun, char *name, int n, double value, int prec,
18                          char *comm, int append)
19
20         int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm,
21                          int append)
22

DESCRIPTION

24       The four routines FunParamPutb(), FunParamPuti(), FunParamPutd(), and
25       FunParamPuts(), will set the value of a FITS header parameter as a
26       boolean, int, double, and string, respectively.
27
28       The first argument is the Fun handle associated with the FITS header
29       being accessed. Normally, the header is associated with the FITS exten‐
30       sion that you opened with FunOpen().  However, you can use FunInfoPut()
31       to specify that use of the primary header. In particular, if you set
32       the FUN_PRIMARYHEADER parameter to 1, then the primary header is used
33       for all parameter access until the value is reset to 0. For example:
34
35         int val;
36         FunParamPuti(fun, "NAXIS1", 0, 10, NULL, 1);       # current header
37         val=1;
38         FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0);       # switch to ...
39         FunParamPuti(fun, "NAXIS1", 0, 10, NULL, 1);       # primary header
40
41       (You also can use the deprecated FUN_PRIMARY macro, to access parame‐
42       ters from the primary header.)
43
44       The second argument is the name of the parameter.  ( In accordance with
45       FITS standards, the special names COMMENT and HISTORY, as well as blank
46       names, are output without the "= " value indicator in columns 9 and 10.
47
48       The third n argument, if non-zero, is an integer that will be added as
49       a suffix to the parameter name.  This makes it easy to use a simple
50       loop to process parameters having the same root name.  For example, to
51       set the values of TLMIN and TLMAX for each column in a binary table,
52       you can use:
53
54         for(i=0; i<got; i++){
55           FunParamPutd(fun, "TLMIN", i+1, tlmin[i], 7, "min column val", 1);
56           FunParamPutd(fun, "TLMAX", i+1, tlmax[i], 7, "max column val", 1);
57         }
58
59       The fourth defval argument is the value to set.  Note that the data
60       type of this argument is different for each specific FunParamPut()
61       call. The comm argument is the comment string to add to this header
62       parameter. Its value can be NULL.  The final append argument determines
63       whether the parameter is added to the header if it does not exist. If
64       set to a non-zero value, the header parameter will be appended to the
65       header if it does not exist.  If set to 0, the value will only be used
66       to change an existing parameter.
67
68       Note that the double precision routine FunParamPutd() supports an extra
69       prec argument after the value argument, in order to specify the preci‐
70       sion when converting the double value to ASCII. In general a 20.[prec]
71       format is used (since 20 characters are alloted to a floating point
72       number in FITS) as follows: if the double value being put to the header
73       is less than 0.1 or greater than or equal to 10**(20-2-[prec]), then
74       %20.[prec]e format is used (i.e., scientific notation); otherwise
75       %20.[prec]f format is used (i.e., numeric notation).
76
77       As a rule, parameters should be set before writing the table or image.
78       It is, however, possible to update the value of an existing parameter
79       after writing an image or table (but not to add a new one). Such updat‐
80       ing only works if the parameter already exists and if the output file
81       is seekable, i.e. if it is a disk file or is stdout being redirected to
82       a disk file.
83
84       It is possible to add a new parameter to a header after the data has
85       been written, but only if space has previously been reserved. To
86       reserve space, add a blank parameter whose value is the name of the
87       parameter you eventually will update. Then, when writing the new param‐
88       eter, specify a value of 2 for the append flag. The parameter writing
89       routine will first look to update an existing parameter, as usual. If
90       an existing parameter is not found, an appropriately-valued blank
91       parameter will be searched for and replaced.  For example:
92
93         /* add blank card to be used as a place holder for IPAR1 update */
94         FunParamPuts(fun, NULL, 0, "IPAR1", "INTEGER Param", 0);
95         ...
96         /* write header and data */
97         FunTableRowPut(fun, events, got, 0, NULL);
98         ...
99         /* update param in file after writing data -- note append = 2 here */
100         FunParamPuti(fun, "IPAR", 1, 400, "INTEGER Param", 2);
101
102       The parameter routines return a 1 if the routine was successful and a 0
103       on failure. In general, the major reason for failure is that you did
104       not set the append argument to a non-zero value and the parameter did
105       not already exist in the file.
106

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO