funparamput(3)

💖 funparamput(3) — like, the whole manual, bestie 💖

okay so this is a page from the SAORD Documentation set, and it's literally all about FunParamPut — putting a Funtools param value. yes, that's the NAME section, we're doing this properly. periodt.

---

✨ NAME ✨

FunParamPut — put a Funtools param value 🎀

---

🦋 SYNOPSIS 🦋

#include <funtools.h>

int FunParamPutb(Fun fun, char *name, int n, int value, char *comm,
                 int append)

int FunParamPuti(Fun fun, char *name, int n, int value, char *comm,
                 int append)

int FunParamPutd(Fun fun, char *name, int n, double value, int prec,
                 char *comm, int append)

int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm,
                 int append)

---

🌸 DESCRIPTION 🌸

so there's not one, not two, but four of these babies: FunParamPutb(), FunParamPuti(), FunParamPutd(), and FunParamPuts(). they set the value of a FITS header parameter as a boolean, int, double, and string respectively. one for every flavor, we love a full set 💅

🫶 the first argument — the Fun handle

first arg is the Fun handle that's associated with the FITS header you're poking at. normally that header is the one attached to the FITS extension you opened with FunOpen(). BUT — plot twist — you can use FunInfoPut() to say "actually, use the primary header". specifically, if you set the FUN_PRIMARYHEADER parameter to 1, then the primary header gets used for all parameter access until you reset that value to 0. like so:

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

(also, if you're feeling retro, there's the deprecated FUN_PRIMARY macro, which also gets you parameters from the primary header. it's giving legacy code, no cap.)

🎀 the second argument — the parameter name

second arg = the name of the parameter. and here's the FITS-standards tea: the special names COMMENT and HISTORY, plus blank names, get output without the "= " value indicator in columns 9 and 10. that's just how FITS do. 🙈

🧚 the third argument — n, the suffix situation

the third argument, n, if it's non-zero, is an integer that gets tacked on as a suffix to the parameter name. this is the glow-up that makes a simple loop able to chew through a bunch of parameters sharing the same root name. for example, to set the values of TLMIN and TLMAX for each column in a binary table, you'd do:

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);
}

look at that. iconic. 🔥

💜 the fourth defval argument (and friends)

the fourth argument, defval, is the value you're setting. heads up though — the data type of this argument is different for each specific FunParamPut() call, so don't come for me when FunParamPutb() wants a boolean and FunParamPutd() wants a double.

the comm argument is the comment string you add to this header parameter, and yeah, its value can be NULL. no comment, no problem.

the final append argument decides whether the parameter gets added to the header if it doesn't already exist. set it to a non-zero value and the header parameter gets appended if it's missing. set it to 0 and the value only gets used to change an existing parameter. that's the whole vibe check right there.

👑 the extra prec argument on FunParamPutd()

note that the double precision routine FunParamPutd() supports an extra prec argument right after the value argument, so you can specify the precision when converting the double value to ASCII. in general a 20.[prec] format is used (because 20 characters are alloted to a floating point number in FITS, that's the rule) and it goes like this: 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 %20.[prec]e format is used (i.e., scientific notation); otherwise %20.[prec]f format is used (i.e., numeric notation). math is math, bestie 🍓

⭐ setting vs. updating — read this part, fr fr

as a rule, parameters should be set before writing the table or image. HOWEVER — it is possible to update the value of an existing parameter after writing an image or table (but not to add a new one). and that updating only works if the parameter already exists AND if the output file is seekable, i.e. if it's a disk file or if it's stdout being redirected to a disk file. no seekable output, no update. that's just the deal. 💀

🌈 reserving space for a post-data param add

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 that space, add a blank parameter whose value is the name of the parameter you eventually will update. then, when you write the new parameter, specify a value of 2 for the append flag. here's the sequence: the parameter writing routine first looks to update an existing parameter, as usual. if an existing parameter isn't found, an appropriately-valued blank parameter gets searched for and replaced. like this:

/* 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);

manifesting that placeholder card. ✨

💅 return values

these parameter routines return a 1 if the routine was successful and a 0 on failure. and in general, the major reason for failure is that you didn't set the append argument to a non-zero value and the parameter didn't already exist in the file. so like… if it flops, check your append. that's the whole story. 🫶

---

🔍 SEE ALSO 🔍

see funtools(7) for a list of Funtools help pages 📚

---

okay that's the page!! this was SAORD Documentation's funparamput(3), version 1.4.5, dated April 14, 2011 — shoutout to the 2011 era for giving us this. you're gonna slay those headers, bestie, mwah 💖🎀✨