diff options
Diffstat (limited to 'funtools/man/man3')
| -rw-r--r-- | funtools/man/man3/funclose.3 | 160 | ||||
| -rw-r--r-- | funtools/man/man3/funcolumnactivate.3 | 330 | ||||
| -rw-r--r-- | funtools/man/man3/funcolumnlookup.3 | 220 | ||||
| -rw-r--r-- | funtools/man/man3/funcolumnselect.3 | 664 | ||||
| -rw-r--r-- | funtools/man/man3/funflush.3 | 212 | ||||
| -rw-r--r-- | funtools/man/man3/funimageget.3 | 332 | ||||
| -rw-r--r-- | funtools/man/man3/funimageput.3 | 225 | ||||
| -rw-r--r-- | funtools/man/man3/funimagerowget.3 | 215 | ||||
| -rw-r--r-- | funtools/man/man3/funimagerowput.3 | 202 | ||||
| -rw-r--r-- | funtools/man/man3/funinfoget.3 | 335 | ||||
| -rw-r--r-- | funtools/man/man3/funinfoput.3 | 246 | ||||
| -rw-r--r-- | funtools/man/man3/funlib.3 | 525 | ||||
| -rw-r--r-- | funtools/man/man3/funopen.3 | 272 | ||||
| -rw-r--r-- | funtools/man/man3/funparamget.3 | 262 | ||||
| -rw-r--r-- | funtools/man/man3/funparamput.3 | 256 | ||||
| -rw-r--r-- | funtools/man/man3/funref.3 | 287 | ||||
| -rw-r--r-- | funtools/man/man3/funtablerowget.3 | 216 | ||||
| -rw-r--r-- | funtools/man/man3/funtablerowput.3 | 297 |
18 files changed, 5256 insertions, 0 deletions
diff --git a/funtools/man/man3/funclose.3 b/funtools/man/man3/funclose.3 new file mode 100644 index 0000000..dc8dbd2 --- /dev/null +++ b/funtools/man/man3/funclose.3 @@ -0,0 +1,160 @@ +.\" 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 "funclose 3" +.TH funclose 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunClose \- close a Funtools data file +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 1 +\& void FunClose(Fun fun) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunClose()\fB\fR routine closes a previously-opened Funtools data +file, freeing control structures. If a +Funtools reference handle +was passed to +the \fIFunOpen()\fR call for this file, +and if copy mode also was specified for that file, then +\&\fIFunClose()\fR also will copy the +remaining extensions from the input file to the output file (if the +input file still is open). Thus, we recommend always closing the +output Funtools file \fBbefore\fR the input file. (Alternatively, +you can call \fIFunFlush()\fR +explicitly). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funcolumnactivate.3 b/funtools/man/man3/funcolumnactivate.3 new file mode 100644 index 0000000..2eda34b --- /dev/null +++ b/funtools/man/man3/funcolumnactivate.3 @@ -0,0 +1,330 @@ +.\" 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 "funcolumnactivate 3" +.TH funcolumnactivate 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunColumnActivate \- activate Funtools columns +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 1 +\& void FunColumnActivate(Fun fun, char *s, char *plist) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunColumnActivate()\fB\fR routine determines which columns (set up +by \fIFunColumnSelect()\fR) +ultimately will be read and/or written. By default, all columns that +are selected using +\&\fIFunColumnSelect()\fR +are activated. The +\&\fIFunColumnActivate()\fR +routine can be used to turn off/off activation of specific columns. +.PP +The first argument is the Fun handle associated with this set of +columns. The second argument is a space-delimited list of columns to +activate or de\-activate. Columns preceded by \*(L"+\*(R" are activated and +columns preceded by a \*(L"\-\*(R" are de\-activated. If a column is named +without \*(L"+\*(R" or \*(L"\-\*(R", it is activated. The reserved strings \*(L"$region\*(R" +and '$n' are used to activate a special columns containing the filter +region value and row value, respectively, associated with +this row. For example, if a filter containing two circular regions is +specified as part of the Funtools file name, this column will contain +a value of 1 or 2, depending on which region that row was in. The +reserved strings \*(L"$x\*(R" and \*(L"$y\*(R" are used to activate the current +binning columns. Thus, if the columns \s-1DX\s0 and \s-1DY\s0 are specified as +binning columns: +.PP +.Vb 1 +\& [sh $] fundisp foo.fits[bincols=(DX,DY)] +.Ve +.PP +then \*(L"$x\*(R" and \*(L"$y\*(R" will refer to these columns in a call to +\&\fIFunColumnActivate()\fR. +.PP +In addition, if the activation string contains only columns to be +activated, then the routine will de-activate all other columns. +Similarly, if the activation string contains only +columns to de\-activate, then the routine will activate all other columns +before activating the list. This makes it simple to change the +activation state of all columns without having to know all of the +column names. For example: +.IP "\(bu" 4 +\&\fB\*(L"pi pha time\*(R"\fR # only these three columns will be active +.IP "\(bu" 4 +\&\fB\*(L"\-pi \-pha \-time\*(R"\fR # all but these columns will be active +.IP "\(bu" 4 +\&\fB\*(L"pi \-pha\*(R"\fR # only pi is active, pha is not, others are not +.IP "\(bu" 4 +\&\fB\*(L"+pi \-pha\*(R"\fR # same as above +.IP "\(bu" 4 +\&\fB\*(L"pi \-pha \-time\*(R"\fR # only pi is active, all others are not +.IP "\(bu" 4 +\&\fB\*(L"pi pha\*(R"\fR # pha and pi are active, all others are not +.IP "\(bu" 4 +\&\fB\*(L"pi pha \-x \-y\*(R"\fR # pha and pi are active, all others are not +.PP +You can use the column activation list to reorder columns, since +columns are output in the order specified. For example: +.PP +.Vb 9 +\& # default output order +\& fundisp snr.ev'[cir 512 512 .1]' +\& X Y PHA PI TIME DX DY +\& -------- -------- -------- -------- --------------------- -------- -------- +\& 512 512 6 7 79493997.45854475 578 574 +\& 512 512 8 9 79494575.58943175 579 573 +\& 512 512 5 6 79493631.03866175 578 575 +\& 512 512 5 5 79493290.86521725 578 575 +\& 512 512 8 9 79493432.00990875 579 573 +.Ve +.PP +.Vb 9 +\& # re-order the output by specifying explicit order +\& fundisp snr.ev'[cir 512 512 .1]' "time x y dy dx pi pha" +\& TIME X Y DY DX PI PHA +\& --------------------- -------- -------- -------- -------- -------- -------- +\& 79493997.45854475 512 512 574 578 7 6 +\& 79494575.58943175 512 512 573 579 9 8 +\& 79493631.03866175 512 512 575 578 6 5 +\& 79493290.86521725 512 512 575 578 5 5 +\& 79493432.00990875 512 512 573 579 9 8 +.Ve +.PP +A \*(L"+\*(R" sign by itself means to activate all columns, so that you can reorder +just a few columns without specifying all of them: +.PP +.Vb 9 +\& # reorder 3 columns and then output the rest +\& fundisp snr.ev'[cir 512 512 .1]' "time pi pha +" +\& TIME PI PHA Y X DX DY +\& --------------------- -------- -------- -------- -------- -------- -------- +\& 79493997.45854475 7 6 512 512 578 574 +\& 79494575.58943175 9 8 512 512 579 573 +\& 79493631.03866175 6 5 512 512 578 575 +\& 79493290.86521725 5 5 512 512 578 575 +\& 79493432.00990875 9 8 512 512 579 573 +.Ve +.PP +The column activation/deactivation is performed in the order of the +specified column arguments. This means you can mix \*(L"+\*(R", \*(L"\-\*(R" (which +de-activates all columns) and specific column names to reorder and +select columns in one command. For example, consider the following: +.PP +.Vb 9 +\& # reorder and de-activate +\& fundisp snr.ev'[cir 512 512 .1]' "time pi pha + \-x \-y" +\& TIME PI PHA DX DY +\& --------------------- -------- -------- -------- -------- +\& 79493997.45854475 7 6 578 574 +\& 79494575.58943175 9 8 579 573 +\& 79493631.03866175 6 5 578 575 +\& 79493290.86521725 5 5 578 575 +\& 79493432.00990875 9 8 579 573 +.Ve +.PP +We first activate \*(L"time\*(R", \*(L"pi\*(R", and \*(L"pha\*(R" so that they are output first. +We then activate all of the other columns, and then de-activate \*(L"x\*(R" and \*(L"y\*(R". +Note that this is different from: +.PP +.Vb 9 +\& # probably not what you want ... +\& fundisp snr.ev'[cir 512 512 .1]' "time pi pha \-x \-y +" +\& TIME PI PHA Y X DX DY +\& --------------------- -------- -------- -------- -------- -------- -------- +\& 79493997.45854475 7 6 512 512 578 574 +\& 79494575.58943175 9 8 512 512 579 573 +\& 79493631.03866175 6 5 512 512 578 575 +\& 79493290.86521725 5 5 512 512 578 575 +\& 79493432.00990875 9 8 512 512 579 573 +.Ve +.PP +Here, \*(L"x\*(R" and \*(L"y\*(R" are de\-activated, but then all columns including \*(L"x\*(R" and +\&\*(L"y\*(R" are again re\-activated. +.PP +Typically, +\&\fIFunColumnActivate()\fR uses a +list of columns that are passed into the program from the command line. For +example, the code for funtable contains the following: +.PP +.Vb 1 +\& char *cols=NULL; +.Ve +.PP +.Vb 3 +\& /* open the input FITS file */ +\& if( !(fun = FunOpen(argv[1], "rc", NULL)) ) +\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); +.Ve +.PP +.Vb 3 +\& /* set active flag for specified columns */ +\& if( argc >= 4 ) cols = argv[3]; +\& FunColumnActivate(fun, cols, NULL); +.Ve +.PP +The \fIFunOpen()\fR call sets the +default columns to be all columns in the input file. The +\&\fIFunColumnActivate()\fR call +then allows the user to control which columns ultimately will be +activated (i.e., in this case, written to the new file). For example: +.PP +.Vb 1 +\& funtable test.ev foo.ev "pi pha time" +.Ve +.PP +will process only the three columns mentioned, while: +.PP +.Vb 1 +\& funtable test.ev foo.ev "\-time" +.Ve +.PP +will process all columns except \*(L"time\*(R". +.PP +If \fIFunColumnActivate()\fR +is called with a null string, then the environment variable +\&\fB\s-1FUN_COLUMNS\s0\fR will be used to provide a global value, if present. +This is the reason why we call the routine even if no columns +are specified on the command line (see example above), instead +of calling it this way: +.PP +.Vb 4 +\& /* set active flag for specified columns */ +\& if( argc >= 4 ){ +\& FunColumnActivate(fun, argv[3], NULL); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funcolumnlookup.3 b/funtools/man/man3/funcolumnlookup.3 new file mode 100644 index 0000000..15c9c36 --- /dev/null +++ b/funtools/man/man3/funcolumnlookup.3 @@ -0,0 +1,220 @@ +.\" 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 "funcolumnlookup 3" +.TH funcolumnlookup 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunColumnLookup \- lookup a Funtools column +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 3 +\& int FunColumnLookup(Fun fun, char *s, int which, +\& char **name, int *type, int *mode, +\& int *offset, int *n, int *width) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunColumnLookup()\fB\fR routine returns information about a named +(or indexed) column. The first argument is the Fun handle associated +with this set of columns. The second argument is the name of the +column to look up. If the name argument is \s-1NULL\s0, the argument that +follows is the zero-based index into the column array of the column +for which information should be returned. The next argument is a +pointer to a char *, which will contain the name of the column. The +arguments that follow are the addresses of int values into which +the following information will be returned: +.IP "\(bu" 4 +\&\fBtype\fR: data type of column: +.RS 4 +.IP "\(bu" 4 +A: \s-1ASCII\s0 characters +.IP "\(bu" 4 +B: unsigned 8-bit char +.IP "\(bu" 4 +I: signed 16-bit int +.IP "\(bu" 4 +U: unsigned 16-bit int (not standard \s-1FITS\s0) +.IP "\(bu" 4 +J: signed 32-bit int +.IP "\(bu" 4 +V: unsigned 32-bit int (not standard \s-1FITS\s0) +.IP "\(bu" 4 +E: 32-bit float +.IP "\(bu" 4 +D: 64-bit float +.RE +.RS 4 +.RE +.IP "\(bu" 4 +\&\fBmode\fR: bit flag status of column, including: +.RS 4 +.IP "\(bu" 4 +\&\s-1COL_ACTIVE\s0 1 is column activated? +.IP "\(bu" 4 +\&\s-1COL_IBUF\s0 2 is column in the raw input data? +.IP "\(bu" 4 +\&\s-1COL_PTR\s0 4 is column a pointer to an array? +.IP "\(bu" 4 +\&\s-1COL_READ\s0 010 is read mode selected? +.IP "\(bu" 4 +\&\s-1COL_WRITE\s0 020 is write mode selected? +.IP "\(bu" 4 +\&\s-1COL_REPLACEME\s0 040 is this column being replaced by user data? +.RE +.RS 4 +.RE +.IP "\(bu" 4 +\&\fBoffset\fR: byte offset in struct +.IP "\(bu" 4 +\&\fBn\fR: number of elements (i.e. size of vector) in this column +.IP "\(bu" 4 +\&\fBwidth\fR: size in bytes of this column +.PP +If the named column exists, the routine returns a positive integer, +otherwise zero is returned. (The positive integer is the index+1 into +the column array where this column was located.) +.PP +If \s-1NULL\s0 is passed as the return address of one (or more) of these +values, no data is passed back for that information. For +example: +.PP +.Vb 2 +\& if( !FunColumnLookup(fun, "phas", 0, NULL NULL, NULL, NULL, &npha, NULL) ) +\& gerror(stderr, "can't find phas column\en"); +.Ve +.PP +only returns information about the size of the phas vector. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funcolumnselect.3 b/funtools/man/man3/funcolumnselect.3 new file mode 100644 index 0000000..88158c0 --- /dev/null +++ b/funtools/man/man3/funcolumnselect.3 @@ -0,0 +1,664 @@ +.\" 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 "funcolumnselect 3" +.TH funcolumnselect 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunColumnSelect \- select Funtools columns +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 5 +\& int FunColumnSelect(Fun fun, int size, char *plist, +\& char *name1, char *type1, char *mode1, int offset1, +\& char *name2, char *type2, char *mode2, int offset2, +\& ..., +\& NULL) +.Ve +.PP +.Vb 3 +\& int FunColumnSelectArr(Fun fun, int size, char *plist, +\& char **names, char **types, char **modes, +\& int *offsets, int nargs); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunColumnSelect()\fB\fR routine is used to select the columns +from a Funtools binary table extension or raw event file for +processing. This routine allows you to specify how columns in a file +are to be read into a user record structure or written from a user +record structure to an output \s-1FITS\s0 file. +.PP +The first argument is the Fun handle associated with this set of +columns. The second argument specifies the size of the user record +structure into which columns will be read. Typically, the \fIsizeof()\fR +macro is used to specify the size of a record structure. The third +argument allows you to specify keyword directives for the selection +and is described in more detail below. +.PP +Following the first three required arguments is a variable length list of +column specifications. Each column specification will consist of four +arguments: +.IP "\(bu" 4 +\&\fBname\fR: the name of the column +.IP "\(bu" 4 +\&\fBtype\fR: the data type of the column as it will be stored in +the user record struct (not the data type of the input file). The +following basic data types are recognized: +.RS 4 +.IP "\(bu" 4 +A: \s-1ASCII\s0 characters +.IP "\(bu" 4 +B: unsigned 8-bit char +.IP "\(bu" 4 +I: signed 16-bit int +.IP "\(bu" 4 +U: unsigned 16-bit int (not standard \s-1FITS\s0) +.IP "\(bu" 4 +J: signed 32-bit int +.IP "\(bu" 4 +V: unsigned 32-bit int (not standard \s-1FITS\s0) +.IP "\(bu" 4 +E: 32-bit float +.IP "\(bu" 4 +D: 64-bit float +.RE +.RS 4 +.Sp +The syntax used is similar to that which defines the \s-1TFORM\s0 parameter +in \s-1FITS\s0 binary tables. That is, a numeric repeat value can precede +the type character, so that \*(L"10I\*(R" means a vector of 10 short ints, \*(L"E\*(R" +means a single precision float, etc. Note that the column value from +the input file will be converted to the specified data type as the +data is read by +\&\fIFunTableRowGet()\fR. +.Sp +[ A short digression regarding bit\-fields: Special attention is +required when reading or writing the \s-1FITS\s0 bit-field type +(\*(L"X\*(R"). Bit-fields almost always have a numeric repeat character +preceding the 'X' specification. Usually this value is a multiple of 8 +so that bit-fields fit into an integral number of bytes. For all +cases, the byte size of the bit-field B is (N+7)/8, where N is the +numeric repeat character. +.Sp +A bit-field is most easily declared in the user struct as an array of +type char of size B as defined above. In this case, bytes are simply +moved from the file to the user space. If, instead, a short or int +scalar or array is used, then the algorithm for reading the bit-field +into the user space depends on the size of the data type used along +with the value of the repeat character. That is, if the user data +size is equal to the byte size of the bit\-field, then the data is +simply moved (possibly with endian-based byte\-swapping) from one to +the other. If, on the other hand, the data storage is larger than the +bit-field size, then a data type cast conversion is performed to move +parts of the bit-field into elements of the array. Examples will help +make this clear: +.IP "\(bu" 4 +If the file contains a 16X bit-field and user space specifies a 2B +char array[2], then the bit-field is moved directly into the char array. +.IP "\(bu" 4 +If the file contains a 16X bit-field and user space specifies a 1I +scalar short int, then the bit-field is moved directly into the short int. +.IP "\(bu" 4 +If the file contains a 16X bit-field and user space specifies a 1J +scalar int, then the bit-field is type-cast to unsigned int before +being moved (use of unsigned avoids possible sign extension). +.IP "\(bu" 4 +If the file contains a 16X bit-field and user space specifies a 2J +int array[2], then the bit-field is handled as 2 chars, each of which +are type-cast to unsigned int before being moved (use of unsigned +avoids possible sign extension). +.IP "\(bu" 4 +If the file contains a 16X bit-field and user space specifies a 1B +char, then the bit-field is treated as a char, i.e., truncation will +occur. +.IP "\(bu" 4 +If the file contains a 16X bit-field and user space specifies a 4J +int array[4], then the results are undetermined. +.RE +.RS 4 +.Sp +For all user data types larger than char, the bit-field is byte-swapped +as necessary to convert to native format, so that bits in the +resulting data in user space can be tested, masked, etc. in the same +way regardless of platform.] +.Sp +In addition to setting data type and size, the \fBtype\fR +specification allows a few ancillary parameters to be set, using the +full syntax for \fBtype\fR: +.Sp +.Vb 1 +\& [@][n]<type>[[['B']poff]][:[tlmin[:tlmax[:binsiz]]]] +.Ve +.Sp +The special character \*(L"@\*(R" can be prepended to this specification to +indicated that the data element is a pointer in the user record, +rather than an array stored within the record. +.Sp +The [n] value is an integer that specifies the +number of elements that are in this column (default is 1). \s-1TLMIN\s0, +\&\s-1TLMAX\s0, and \s-1BINSIZ\s0 values also can be specified for this column after +the type, separated by colons. If only one such number is specified, +it is assumed to be \s-1TLMAX\s0, and \s-1TLMIN\s0 and \s-1BINSIZ\s0 are set to 1. +.Sp +The [poff] value can be used to specify the offset into an +array. By default, this offset value is set to zero and the data +specified starts at the beginning of the array. The offset usually +is specified in terms of the data type of the column. Thus an offset +specification of [5] means a 20\-byte offset if the data type is a +32-bit integer, and a 40\-byte offset for a double. If you want to +specify a byte offset instead of an offset tied to the column data type, +precede the offset value with 'B', e.g. [B6] means a 6\-bye offset, +regardless of the column data type. +.Sp +The [poff] is especially useful in conjunction with the pointer @ +specification, since it allows the data element to anywhere stored +anywhere in the allocated array. For example, a specification such as +\&\*(L"@I[2]\*(R" specifies the third (i.e., starting from 0) element in the +array pointed to by the pointer value. A value of \*(L"@2I[4]\*(R" specifies +the fifth and sixth values in the array. For example, consider the +following specification: +.Sp +.Vb 12 +\& typedef struct EvStruct{ +\& short x[4], *atp; +\& } *Event, EventRec; +\& /* set up the (hardwired) columns */ +\& FunColumnSelect( fun, sizeof(EventRec), NULL, +\& "2i", "2I ", "w", FUN_OFFSET(Event, x), +\& "2i2", "2I[2]", "w", FUN_OFFSET(Event, x), +\& "at2p", "@2I", "w", FUN_OFFSET(Event, atp), +\& "at2p4", "@2I[4]", "w", FUN_OFFSET(Event, atp), +\& "atp9", "@I[9]", "w", FUN_OFFSET(Event, atp), +\& "atb20", "@I[B20]", "w", FUN_OFFSET(Event, atb), +\& NULL); +.Ve +.Sp +Here we have specified the following columns: +.IP "\(bu" 4 +2i: two short ints in an array which is stored as part the +record +.IP "\(bu" 4 +2i2: the 3rd and 4th elements of an array which is stored +as part of the record +.IP "\(bu" 4 +an array of at least 10 elements, not stored in the record but +allocated elsewhere, and used by three different columns: +.RS 4 +.IP "\(bu" 4 +at2p: 2 short ints which are the first 2 elements of the allocated array +.IP "\(bu" 4 +at2p4: 2 short ints which are the 5th and 6th elements of +the allocated array +.IP "\(bu" 4 +atp9: a short int which is the 10th element of the allocated array +.RE +.RS 4 +.RE +.IP "\(bu" 4 +atb20: a short int which is at byte offset 20 of another allocated array +.RE +.RS 4 +.Sp +In this way, several columns can be specified, all of which are in a +single array. \fB\s-1NB\s0\fR: it is the programmer's responsibility to +ensure that specification of a positive value for poff does not point +past the end of valid data. +.RE +.IP "\(bu" 4 +\&\fBread/write mode\fR: \*(L"r\*(R" means that the column is read from an +input file into user space by +\&\fIFunTableRowGet()\fR, \*(L"w\*(R" means that +the column is written to an output file. Both can specified at the same +time. +.IP "\(bu" 4 +\&\fBoffset\fR: the offset into the user data to store +this column. Typically, the macro \s-1FUN_OFFSET\s0(recname, colname) is used +to define the offset into a record structure. +.PP +When all column arguments have been specified, a final \s-1NULL\s0 argument +must added to signal the column selection list. +.PP +As an alternative to the varargs +\&\fIFunColumnSelect()\fR +routine, a non-varargs routine called +\&\fIFunColumnSelectArr()\fR +also is available. The first three arguments (fun, size, plist) of this +routine are the same as in +\&\fIFunColumnSelect()\fR. +Instead of a variable +argument list, however, +\&\fIFunColumnSelectArr()\fR +takes 5 additional arguments. The first 4 arrays arguments contain the +names, types, modes, and offsets, respectively, of the columns being +selected. The final argument is the number of columns that are +contained in these arrays. It is the user's responsibility to free +string space allocated in these arrays. +.PP +Consider the following example: +.PP +.Vb 5 +\& typedef struct evstruct{ +\& int status; +\& float pi, pha, *phas; +\& double energy; +\& } *Ev, EvRec; +.Ve +.PP +.Vb 6 +\& FunColumnSelect(fun, sizeof(EvRec), NULL, +\& "status", "J", "r", FUN_OFFSET(Ev, status), +\& "pi", "E", "r", FUN_OFFSET(Ev, pi), +\& "pha", "E", "r", FUN_OFFSET(Ev, pha), +\& "phas", "@9E", "r", FUN_OFFSET(Ev, phas), +\& NULL); +.Ve +.PP +Each time a row is read into the Ev struct, the \*(L"status\*(R" column is +converted to an int data type (regardless of its data type in the +file) and stored in the status value of the struct. Similarly, \*(L"pi\*(R" +and \*(L"pha\*(R", and the phas vector are all stored as floats. Note that the +\&\*(L"@\*(R" sign indicates that the \*(L"phas\*(R" vector is a pointer to a 9 element +array, rather than an array allocated in the struct itself. The row +record can then be processed as required: +.PP +.Vb 9 +\& /* get rows -- let routine allocate the row array */ +\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ +\& /* process all rows */ +\& for(i=0; i<got; i++){ +\& /* point to the i'th row */ +\& ev = ebuf+i; +\& ev->pi = (ev->pi+.5); +\& ev->pha = (ev->pi-.5); +\& } +.Ve +.PP +\&\fIFunColumnSelect()\fR +can also be called to define \*(L"writable\*(R" columns in order to generate a \s-1FITS\s0 +Binary Table, without reference to any input columns. For +example, the following will generate a 4\-column \s-1FITS\s0 binary table when +\&\fIFunTableRowPut()\fR is used to +write Ev records: +.PP +.Vb 5 +\& typedef struct evstruct{ +\& int status; +\& float pi, pha +\& double energy; +\& } *Ev, EvRec; +.Ve +.PP +.Vb 6 +\& FunColumnSelect(fun, sizeof(EvRec), NULL, +\& "status", "J", "w", FUN_OFFSET(Ev, status), +\& "pi", "E", "w", FUN_OFFSET(Ev, pi), +\& "pha", "E", "w", FUN_OFFSET(Ev, pha), +\& "energy", "D", "w", FUN_OFFSET(Ev, energy), +\& NULL); +.Ve +.PP +All columns are declared to be write\-only, so presumably the column +data is being generated or read from some other source. +.PP +In addition, +\&\fIFunColumnSelect()\fR +can be called to define \fBboth\fR \*(L"readable\*(R" and \*(L"writable\*(R" columns. +In this case, the \*(L"read\*(R" columns +are associated with an input file, while the \*(L"write\*(R" columns are +associated with the output file. Of course, columns can be specified as both +\&\*(L"readable\*(R" and \*(L"writable\*(R", in which case they are read from input +and (possibly modified data values are) written to the output. +The +\&\fIFunColumnSelect()\fR +call itself is made by passing the input Funtools handle, and it is +assumed that the output file has been opened using this input handle +as its +Funtools reference handle. +.PP +Consider the following example: +.PP +.Vb 5 +\& typedef struct evstruct{ +\& int status; +\& float pi, pha, *phas; +\& double energy; +\& } *Ev, EvRec; +.Ve +.PP +.Vb 7 +\& FunColumnSelect(fun, sizeof(EvRec), NULL, +\& "status", "J", "r", FUN_OFFSET(Ev, status), +\& "pi", "E", "rw", FUN_OFFSET(Ev, pi), +\& "pha", "E", "rw", FUN_OFFSET(Ev, pha), +\& "phas", "@9E", "rw", FUN_OFFSET(Ev, phas), +\& "energy", "D", "w", FUN_OFFSET(Ev, energy), +\& NULL); +.Ve +.PP +As in the \*(L"read\*(R" example above, each time an row is read into the Ev +struct, the \*(L"status\*(R" column is converted to an int data type +(regardless of its data type in the file) and stored in the status +value of the struct. Similarly, \*(L"pi\*(R" and \*(L"pha\*(R", and the phas vector +are all stored as floats. Since the \*(L"pi\*(R", \*(L"pha\*(R", and \*(L"phas\*(R" variables +are declared as \*(L"writable\*(R" as well as \*(L"readable\*(R", they also will be +written to the output file. Note, however, that the \*(L"status\*(R" variable +is declared as \*(L"readable\*(R" only, and hence it will not be written to +an output file. Finally, the \*(L"energy\*(R" column is declared as +\&\*(L"writable\*(R" only, meaning it will not be read from the input file. In +this case, it can be assumed that \*(L"energy\*(R" will be calculated in the +program before being output along with the other values. +.PP +In these simple cases, only the columns specified as \*(L"writable\*(R" will +be output using +\&\fIFunTableRowPut()\fR. However, +it often is the case that you want to merge the user columns back in +with the input columns, even in cases where not all of the input +column names are explicitly read or even known. For this important +case, the \fBmerge=[type]\fR keyword is provided in the plist string. +.PP +The \fBmerge=[type]\fR keyword tells Funtools to merge the columns from +the input file with user columns on output. It is normally used when +an input and output file are opened and the input file provides the +Funtools reference handle +for the output file. In this case, each time +\&\fIFunTableRowGet()\fR is called, the +raw input rows are saved in a special buffer. If +\&\fIFunTableRowPut()\fR then is called +(before another call to +\&\fIFunTableRowGet()\fR), the contents +of the raw input rows are merged with the user rows according to the +value of \fBtype\fR as follows: +.IP "\(bu" 4 +\&\fBupdate\fR: add new user columns, and update value of existing ones (maintaining the input data type) +.IP "\(bu" 4 +\&\fBreplace\fR: add new user columns, and replace the data type +and value of existing ones. (Note that if tlmin/tlmax values are not +specified in the replacing column, but are specified in the original +column being replaced, then the original tlmin/tlmax values are used +in the replacing column.) +.IP "\(bu" 4 +\&\fBappend\fR: only add new columns, do not \*(L"replace\*(R" or \*(L"update\*(R" existing ones +.PP +Consider the example above. If \fBmerge=update\fR is specified in the +plist string, then \*(L"energy\*(R" will be added to the input columns, and +the values of \*(L"pi\*(R", \*(L"pha\*(R", and \*(L"phas\*(R" will be taken from the user +space (i.e., the values will be updated from the original values, if +they were changed by the program). The data type for \*(L"pi\*(R", \*(L"pha\*(R", and +\&\*(L"phas\*(R" will be the same as in the original file. If +\&\fBmerge=replace\fR is specified, both the data type and value of +these three input columns will be changed to the data type and value +in the user structure. If \fBmerge=append\fR is specified, none of +these three columns will be updated, and only the \*(L"energy\*(R" column will +be added. Note that in all cases, \*(L"status\*(R" will be written from the +input data, not from the user record, since it was specified as read\-only. +.PP +Standard applications will call +\&\fIFunColumnSelect()\fR +to define user columns. However, if this routine is not called, the +default behavior is to transfer all input columns into user space. For +this purpose a default record structure is defined such that each data +element is properly aligned on a valid data type boundary. This +mechanism is used by programs such as fundisp and funtable to process +columns without needing to know the specific names of those columns. +It is not anticipated that users will need such capabilities (contact +us if you do!) +.PP +By default, \fIFunColumnSelect()\fR +reads/writes rows to/from an \*(L"array of structs\*(R", where each struct contains +the column values for a single row of the table. This means that the +returned values for a given column are not contiguous. You can +set up the \s-1IO\s0 to return a \*(L"struct of arrays\*(R" so that each of the +returned columns are contiguous by specifying \fBorg=structofarrays\fR +(abbreviation: \fBorg=soa\fR) in the plist. +(The default case is \fBorg=arrayofstructs\fR or \fBorg=aos\fR.) +.PP +For example, the default setup to retrieve rows from a table would be +to define a record structure for a single event and then call + \fIFunColumnSelect()\fR +as follows: +.PP +.Vb 6 +\& typedef struct evstruct{ +\& short region; +\& double x, y; +\& int pi, pha; +\& double time; +\& } *Ev, EvRec; +.Ve +.PP +.Vb 7 +\& got = FunColumnSelect(fun, sizeof(EvRec), NULL, +\& "x", "D:10:10", mode, FUN_OFFSET(Ev, x), +\& "y", "D:10:10", mode, FUN_OFFSET(Ev, y), +\& "pi", "J", mode, FUN_OFFSET(Ev, pi), +\& "pha", "J", mode, FUN_OFFSET(Ev, pha), +\& "time", "1D", mode, FUN_OFFSET(Ev, time), +\& NULL); +.Ve +.PP +Subsequently, each call to +\&\fIFunTableRowGet()\fR +will return an array of structs, one for each returned row. If instead you +wanted to read columns into contiguous arrays, you specify \fBorg=soa\fR: +.PP +.Vb 6 +\& typedef struct aevstruct{ +\& short region[MAXROW]; +\& double x[MAXROW], y[MAXROW]; +\& int pi[MAXROW], pha[MAXROW]; +\& double time[MAXROW]; +\& } *AEv, AEvRec; +.Ve +.PP +.Vb 7 +\& got = FunColumnSelect(fun, sizeof(AEvRec), "org=soa", +\& "x", "D:10:10", mode, FUN_OFFSET(AEv, x), +\& "y", "D:10:10", mode, FUN_OFFSET(AEv, y), +\& "pi", "J", mode, FUN_OFFSET(AEv, pi), +\& "pha", "J", mode, FUN_OFFSET(AEv, pha), +\& "time", "1D", mode, FUN_OFFSET(AEv, time), +\& NULL); +.Ve +.PP +Note that the only modification to the call is in the plist string. +.PP +Of course, instead of using statically allocated arrays, you also can specify +dynamically allocated pointers: +.PP +.Vb 7 +\& /* pointers to arrays of columns (used in struct of arrays) */ +\& typedef struct pevstruct{ +\& short *region; +\& double *x, *y; +\& int *pi, *pha; +\& double *time; +\& } *PEv, PEvRec; +.Ve +.PP +.Vb 8 +\& got = FunColumnSelect(fun, sizeof(PEvRec), "org=structofarrays", +\& "$region", "@I", mode, FUN_OFFSET(PEv, region), +\& "x", "@D:10:10", mode, FUN_OFFSET(PEv, x), +\& "y", "@D:10:10", mode, FUN_OFFSET(PEv, y), +\& "pi", "@J", mode, FUN_OFFSET(PEv, pi), +\& "pha", "@J", mode, FUN_OFFSET(PEv, pha), +\& "time", "@1D", mode, FUN_OFFSET(PEv, time), +\& NULL); +.Ve +.PP +Here, the actual storage space is either allocated by the user or by the +\&\fIFunColumnSelect()\fR call). +.PP +In all of the above cases, the same call is made to retrieve rows, e.g.: +.PP +.Vb 1 +\& buf = (void *)FunTableRowGet(fun, NULL, MAXROW, NULL, &got); +.Ve +.PP +However, the individual data elements are accessed differently. +For the default case of an \*(L"array of structs\*(R", the +individual row records are accessed using: +.PP +.Vb 5 +\& for(i=0; i<got; i++){ +\& ev = (Ev)buf+i; +\& fprintf(stdout, "%.2f\et%.2f\et%d\et%d\et%.4f\et%.4f\et%21.8f\en", +\& ev->x, ev->y, ev->pi, ev->pha, ev->dx, ev->dy, ev->time); +\& } +.Ve +.PP +For a struct of arrays or a struct of array pointers, we have a single struct +through which we access individual columns and rows using: +.PP +.Vb 6 +\& aev = (AEv)buf; +\& for(i=0; i<got; i++){ +\& fprintf(stdout, "%.2f\et%.2f\et%d\et%d\et%.4f\et%.4f\et%21.8f\en", +\& aev->x[i], aev->y[i], aev->pi[i], aev->pha[i], +\& aev->dx[i], aev->dy[i], aev->time[i]); +\& } +.Ve +.PP +Support for struct of arrays in the +\&\fIFunTableRowPut()\fR +call is handled analogously. +.PP +See the evread example code +and +evmerge example code +for working examples of how +\&\fIFunColumnSelect()\fR is used. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funflush.3 b/funtools/man/man3/funflush.3 new file mode 100644 index 0000000..611dfc3 --- /dev/null +++ b/funtools/man/man3/funflush.3 @@ -0,0 +1,212 @@ +.\" 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 "funflush 3" +.TH funflush 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunFlush \- flush data to output file +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 1 +\& void FunFlush(Fun fun, char *plist) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBFunFlush\fR routine will flush data to a \s-1FITS\s0 output file. In +particular, it can be called after all rows have been written (using +the \fIFunTableRowPut()\fR routine) +in order to add the null padding that is required to complete a \s-1FITS\s0 +block. It also should be called after completely writing an image using +\&\fIFunImagePut()\fR or after writing +the final row of an image using +\&\fIFunTableRowPut()\fR. +.PP +The \fBplist\fR (i.e., parameter list) argument is a string +containing one or more comma-delimited \fBkeyword=value\fR +parameters. If the plist string contains the parameter +\&\*(L"copy=remainder\*(R" and the file was opened with a reference file, which, +in turn, was opened for extension copying (i.e. the input +\&\fIFunOpen()\fR mode also was \*(L"c\*(R" or \*(L"C\*(R"), +then FunFlush also will copy the remainder of the \s-1FITS\s0 extensions from +the input reference file to the output file. This normally would be +done only at the end of processing. +.PP +Note that \fIFunFlush()\fR is called +with \*(L"copy=remainder\*(R" in the mode string by \fIFunClose()\fR. This means +that if you close the output file before the reference input file, it +is not necessary to call +\&\fIFunFlush()\fR explicitly, unless you +are writing more than one extension. See the +evmerge example code. However, it is safe to +call \fIFunFlush()\fR more than once +without fear of re-writing either the padding or the copied +extensions. +.PP +In addition, if \fIFunFlush()\fR is +called on an output file with the plist set to \*(L"copy=reference\*(R" and if +the file was opened with a reference file, the reference extension is +written to the output file. This mechanism provides a simple way to +copy input extensions to an output file without processing the former. +For example, in the code fragment below, an input extension is set to +be the reference file for a newly opened output extension. If that +reference extension is not a binary table, it is written to the output +file: +.PP +.Vb 22 +\& /* process each input extension in turn */ +\& for(ext=0; ;ext++){ +\& /* get new extension name */ +\& sprintf(tbuf, "%s[%d]", argv[1], ext); +\& /* open input extension -- if we cannot open it, we are done */ +\& if( !(ifun=FunOpen(tbuf, "r", NULL)) ) +\& break; +\& /* make the new extension the reference handle for the output file */ +\& FunInfoPut(ofun, FUN_IFUN, &ifun, 0); +\& /* if its not a binary table, just write it out */ +\& if( !(s=FunParamGets(ifun, "XTENSION", 0, NULL, &got)) || +\& strcmp(s, "BINTABLE")){ +\& if( s ) free(s); +\& FunFlush(ofun, "copy=reference"); +\& FunClose(ifun); +\& continue; +\& } +\& else{ +\& /* process binary table */ +\& .... +\& } +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funimageget.3 b/funtools/man/man3/funimageget.3 new file mode 100644 index 0000000..091765d --- /dev/null +++ b/funtools/man/man3/funimageget.3 @@ -0,0 +1,332 @@ +.\" 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 "funimageget 3" +.TH funimageget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunImageGet \- get an image or image section +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 1 +\& void *FunImageGet(Fun fun, void *buf, char *plist) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunImageGet()\fB\fR routine returns an binned image array of the +specified section of a Funtools data file. If the input data are +already of type image, the array is generated by extracting the +specified image section and then binning it according to the specified +bin factor. If the input data are contained in a binary table or raw +event file, the rows are binned on the columns specified by the +\&\fBbincols=\fR keyword (using appropriate default columns as +necessary), after which the image section and bin factors are +applied. In both cases, the data is automatically converted from \s-1FITS\s0 +to native format, if necessary. +.PP +The first argument is the Funtools handle returned by +\&\fIFunOpen()\fR. The second \fBbuf\fR +argument is a pointer to a data buffer to fill. If \s-1NULL\s0 is specified, +FunImageGet will allocate a buffer of the appropriate size. Generally +speaking, you always want Funtools to allocate the buffer because +the image dimensions will be determined by +Funtools image sectioning +on the command line. +.PP +The third \fBplist\fR (i.e., parameter list) argument is a string +containing one or more comma-delimited \fBkeyword=value\fR +parameters. It can be used to specify the return data type using the +\&\fBbitpix=\fR keyword. If no such keyword is specified in the plist +string, the data type of the returned image is the same as the data type +of the original input file, or is of type int for \s-1FITS\s0 binary tables. +.PP +If the \fBbitpix=\fR keyword is supplied in the plist string, the data +type of the returned image will be one of the supported \s-1FITS\s0 image +data types: +.IP "\(bu" 4 +8 unsigned char +.IP "\(bu" 4 +16 short +.IP "\(bu" 4 +32 int +.IP "\(bu" 4 +\&\-32 float +.IP "\(bu" 4 +\&\-64 double +.PP +For example: +.PP +.Vb 4 +\& void *buf; +\& /* extract data section into an image buffer */ +\& if( !(buf = FunImageGet(fun, NULL, NULL)) ) +\& gerror(stderr, "could not FunImageGet: %s\en", iname); +.Ve +.PP +will allocate buf and retrieve the image in the file data format. In +this case, you will have to determine the data type (using the +\&\s-1FUN_SECT_BITPIX\s0 value in the +\&\fIFunInfoGet()\fR +routine) +and then use a switch statement to process each data type: +.PP +.Vb 17 +\& int bitpix; +\& void *buf; +\& unsigned char *cbuf; +\& short *sbuf; +\& int *ibuf; +\& ... +\& buf = FunImageGet(fun, NULL, NULL); +\& FunInfoGet(fun, FUN_SECT_BITPIX, &bitpix, 0); +\& /* set appropriate data type buffer to point to image buffer */ +\& switch(bitpix){ +\& case 8: +\& cbuf = (unsigned char *)buf; break; +\& case 16: +\& sbuf = (short *)buf; break; +\& case 32: +\& ibuf = (int *)buf; break; +\& ... +.Ve +.PP +See the +imblank example code +for more details on how to process an image when the data type is not +specified beforehand. +.PP +It often is easier to specify the data type directly: +.PP +.Vb 4 +\& double *buf; +\& /* extract data section into a double image buffer */ +\& if( !(buf = FunImageGet(fun, NULL, "bitpix=-64")) ) +\& gerror(stderr, "could not FunImageGet: %s\en", iname); +.Ve +.PP +will extract the image while converting to type double. +.PP +On success, a pointer to the image buffer is returned. (This will be +the same as the second argument, if \s-1NULL\s0 is not passed to the latter.) +On error, \s-1NULL\s0 is returned. +.PP +In summary, to retrieve image or row data into a binned image, you simply +call \fIFunOpen()\fR followed by +\&\fIFunImageGet()\fR. Generally, you +then will want to call +\&\fIFunInfoGet()\fR +to retrieve the +axis dimensions (and data type) of the section you are processing +(so as to take account of sectioning and blocking of the original data): +.PP +.Vb 4 +\& double *buf; +\& int i, j; +\& int dim1, dim2; +\& ... other declarations, etc. +.Ve +.PP +.Vb 3 +\& /* open the input FITS file */ +\& if( !(fun = FunOpen(argv[1], "rc", NULL)) ) +\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); +.Ve +.PP +.Vb 3 +\& /* extract and bin the data section into a double float image buffer */ +\& if( !(buf = FunImageGet(fun, NULL, "bitpix=-64")) ) +\& gerror(stderr, "could not FunImageGet: %s\en", argv[1]); +.Ve +.PP +.Vb 2 +\& /* get dimension information from funtools structure */ +\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); +.Ve +.PP +.Vb 4 +\& /* loop through pixels and reset values below limit to value */ +\& for(i=0; i<dim1*dim2; i++){ +\& if( buf[i] <= blimit ) buf[i] = bvalue; +\& } +.Ve +.PP +Another useful plist string value is \*(L"mask=all\*(R", which returns an +image populated with regions id values. Image pixels within a region +will contain the associated region id (region values start at 1), and +otherwise will contain a 0 value. Thus, the returned image is a +region mask which can be used to process the image data (which +presumably is retrieved by a separate call to FunImageGet) pixel by +pixel. +.PP +If a \s-1FITS\s0 binary table or a non-FITS raw event file is being binned +into an image, it is necessary to specify the two columns that will be +used in the 2D binning. This usually is done on the command line +using the \fBbincols=(x,y)\fR keyword: +.PP +.Vb 1 +\& funcnts "foo.ev[EVENTS,bincols=(detx,dety)]" +.Ve +.PP +The full form of the \fBbincols=\fR specifier is: +.PP +.Vb 1 +\& bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]]) +.Ve +.PP +where the tlmin, tlmax, and binsiz specifiers determine the image binning +dimensions: +.PP +.Vb 2 +\& dim = (tlmax - tlmin)/binsiz (floating point data) +\& dim = (tlmax - tlmin)/binsiz + 1 (integer data) +.Ve +.PP +These tlmin, tlmax, and binsiz specifiers can be omitted if \s-1TLMIN\s0, +\&\s-1TLMAX\s0, and \s-1TDBIN\s0 header parameters (respectively) are present in the +\&\s-1FITS\s0 binary table header for the column in question. Note that if +only one parameter is specified, it is assumed to be tlmax, and tlmin +defaults to 1. If two parameters are specified, they are assumed to be +tlmin and tlmax. +.PP +If \fBbincols\fR is not specified on the command line, Funtools tries +to use appropriate defaults: it looks for the environment variable +\&\s-1FITS_BINCOLS\s0 (or \s-1FITS_BINKEY\s0). Then it looks for the Chandra +parameters \s-1CPREF\s0 (or \s-1PREFX\s0) in the \s-1FITS\s0 binary table header. Failing +this, it looks for columns named \*(L"X\*(R" and \*(L"Y\*(R" and if these are not +found, it looks for columns containing the characters \*(L"X\*(R" and \*(L"Y\*(R". +.PP +See Binning \s-1FITS\s0 Binary Tables and +Non-FITS Event Files for more information. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funimageput.3 b/funtools/man/man3/funimageput.3 new file mode 100644 index 0000000..9618944 --- /dev/null +++ b/funtools/man/man3/funimageput.3 @@ -0,0 +1,225 @@ +.\" 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 "funimageput 3" +.TH funimageput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunImagePut \- put an image to a Funtools file +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 2 +\& int FunImagePut(Fun fun, void *buf, int dim1, int dim2, int bitpix, +\& char *plist) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunImagePut()\fB\fR routine outputs an image array to a \s-1FITS\s0 +file. The image is written either as a primary header/data unit or as +an image extension, depending on whether other data have already been +written to the file. That is, if the current file position is at the +beginning of the file, a primary \s-1HDU\s0 is written. Otherwise, an +image extension is written. +.PP +The first argument is the Funtools handle returned by +\&\fIFunOpen()\fR. The second \fBbuf\fR +argument is a pointer to a data buffer to write. The \fBdim1\fRand +\&\fBdim2\fR arguments that follow specify the dimensions of the image, +where dim1 corresponds to naxis1 and dim2 corresponds to naxis2. The +\&\fBbitpix\fR argument specifies the data type of the image and can +have the following FITS-standard values: +.IP "\(bu" 4 +8 unsigned char +.IP "\(bu" 4 +16 short +.IP "\(bu" 4 +32 int +.IP "\(bu" 4 +\&\-32 float +.IP "\(bu" 4 +\&\-64 double +.PP +When \fIFunTableRowPut()\fR is first +called for a given image, Funtools checks to see if the primary header +has already been written (by having previously written an image or a +binary table.) If not, this image is written to the primary \s-1HDU\s0. +Otherwise, it is written to an image extension. +.PP +Thus, a simple program to generate a \s-1FITS\s0 image might look like this: +.PP +.Vb 16 +\& int i; +\& int dim1=512, dim2=512; +\& double *dbuf; +\& Fun fun; +\& dbuf = malloc(dim1*dim2*sizeof(double)); +\& /* open the output FITS image, preparing to copy input params */ +\& if( !(fun = FunOpen(argv[1], "w", NULL)) ) +\& gerror(stderr, "could not FunOpen output file: %s\en", argv[1]); +\& for(i=0; i<(dim1*dim2); i++){ +\& ... fill dbuf ... +\& } +\& /* put the image (header will be generated automatically */ +\& if( !FunImagePut(fun, buf, dim1, dim2, \-64, NULL) ) +\& gerror(stderr, "could not FunImagePut: %s\en", argv[1]); +\& FunClose(fun); +\& free(dbuf); +.Ve +.PP +In addition, if a +Funtools reference handle +was specified when this table was opened, the +parameters from this +Funtools reference handle +are merged into the new image +header. Furthermore, if a reference image was specified during +\&\fIFunOpen()\fR, the values of +\&\fBdim1\fR, \fBdim2\fR, and \fBbitpix\fR in the calling sequence +can all be set to 0. In this case, default values are taken from the +reference image section. This is useful if you are reading an image +section in its native data format, processing it, and then writing +that section to a new \s-1FITS\s0 file. See the +imblank example code. +.PP +The data are assumed to be in the native machine format and will +automatically be swapped to \s-1FITS\s0 big-endian format if necessary. This +behavior can be over-ridden with the \fBconvert=[true|false]\fR +keyword in the \fBplist\fR param list string. +.PP +When you are finished writing the image, you should call +\&\fIFunFlush()\fR to write out the \s-1FITS\s0 +image padding. However, this is not necessary if you subsequently call +\&\fIFunClose()\fR without doing any other I/O to the \s-1FITS\s0 file. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funimagerowget.3 b/funtools/man/man3/funimagerowget.3 new file mode 100644 index 0000000..50a0979 --- /dev/null +++ b/funtools/man/man3/funimagerowget.3 @@ -0,0 +1,215 @@ +.\" 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 "funimagerowget 3" +.TH funimagerowget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunImageRowGet \- get row(s) of an image +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 2 +\& void *FunImageRowGet(Fun fun, void *buf, int rstart, int rstop, +\& char *plist) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunImageRowGet()\fB\fR routine returns one or more image rows +from the specified section of a Funtools data file. If the input data +are of type image, the array is generated by extracting the specified +image rows and then binning them according to the specified bin +factor. If the input data are contained in a binary table or raw +event file, the rows are binned on the columns specified by the +\&\fBbincols=\fR keyword (using appropriate default columns as needed), +after which the image section and bin factors are applied. +.PP +The first argument is the Funtools handle returned by +\&\fIFunOpen()\fR. The second \fBbuf\fR +argument is a pointer to a data buffer to fill. If \s-1NULL\s0 is specified, +\&\fIFunImageGet()\fR will allocate a buffer of the appropriate size. +.PP +The third and fourth arguments specify the first and last row to +retrieve. Rows are counted starting from 1, up to the value of +\&\s-1FUN_YMAX\s0(fun). The final \fBplist\fR (i.e., parameter list) argument +is a string containing one or more comma-delimited +\&\fBkeyword=value\fR parameters. It can be used to specify the return +data type using the \fBbitpix=\fR keyword. If no such keyword is +specified in the plist string, the data type of the image is the same +as the data type of the original input file, or is of type int for +\&\s-1FITS\s0 binary tables. +.PP +If the \fBbitpix=\fRvalue is supplied in the plist string, the data +type of the returned image will be one of the supported \s-1FITS\s0 image +data types: +.IP "\(bu" 4 +8 unsigned char +.IP "\(bu" 4 +16 short +.IP "\(bu" 4 +32 int +.IP "\(bu" 4 +\&\-32 float +.IP "\(bu" 4 +\&\-64 double +.PP +For example: +.PP +.Vb 17 +\& double *drow; +\& Fun fun; +\& ... open files ... +\& /* get section dimensions */ +\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); +\& /* allocate one line's worth */ +\& drow = malloc(dim1*sizeof(double)); +\& /* retrieve and process each input row (starting at 1) */ +\& for(i=1; i <= dim2; i++){ +\& if( !FunImageRowGet(fun, drow, i, i, "bitpix=-64") ) +\& gerror(stderr, "can't FunImageRowGet: %d %s\en", i, iname); +\& /* reverse the line */ +\& for(j=1; j<=dim1; j++){ +\& ... process drow[j-1] ... +\& } +\& } +\& ... +.Ve +.PP +On success, a pointer to the image buffer is returned. (This will be +the same as the second argument, if \s-1NULL\s0 is not passed to the latter.) +On error, \s-1NULL\s0 is returned. Note that the considerations described +above for specifying binning columns in +\&\fIFunImageGet()\fR also apply to +\&\fB\f(BIFunImageRowGet()\fB\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funimagerowput.3 b/funtools/man/man3/funimagerowput.3 new file mode 100644 index 0000000..e76bc7f --- /dev/null +++ b/funtools/man/man3/funimagerowput.3 @@ -0,0 +1,202 @@ +.\" 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 "funimagerowput 3" +.TH funimagerowput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunImageRowPut \- put row(s) of an image +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 2 +\& void *FunImageRowPut(Fun fun, void *buf, int rstart, int rstop, +\& int dim1, int dim2, int bitpix, char *plist) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunImageRowPut()\fB\fR routine writes one or more image rows to +the specified \s-1FITS\s0 image file. The first argument is the Funtools +handle returned by \fIFunOpen()\fR. +The second \fBbuf\fR argument is a pointer to the row data buffer, +while the third and fourth arguments specify the starting and ending +rows to write. Valid rows values range from 1 to dim2, i.e., row is +one\-valued. +.PP +The \fBdim1\fRand \fBdim2\fR arguments that follow specify the +dimensions, where dim1 corresponds to naxis1 and dim2 corresponds to +naxis2. The \fBbitpix\fR argument data type of the image and can +have the following FITS-standard values: +.IP "\(bu" 4 +8 unsigned char +.IP "\(bu" 4 +16 short +.IP "\(bu" 4 +32 int +.IP "\(bu" 4 +\&\-32 float +.IP "\(bu" 4 +\&\-64 double +.PP +For example: +.PP +.Vb 16 +\& double *drow; +\& Fun fun, fun2; +\& ... open files ... +\& /* get section dimensions */ +\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); +\& /* allocate one line's worth */ +\& drow = malloc(dim1*sizeof(double)); +\& /* retrieve and process each input row (starting at 1) */ +\& for(i=1; i <= dim2; i++){ +\& if( !FunImageRowGet(fun, drow, i, i, "bitpix=-64") ) +\& gerror(stderr, "can't FunImageRowGet: %d %s\en", i, iname); +\& ... process drow ... +\& if( !FunImageRowPut(fun2, drow, i, i, 64, NULL) ) +\& gerror(stderr, "can't FunImageRowPut: %d %s\en", i, oname); +\& } +\& ... +.Ve +.PP +The data are assumed to be in the native machine format and will +automatically be swapped to big-endian \s-1FITS\s0 format if necessary. This +behavior can be over-ridden with the \fBconvert=[true|false]\fR +keyword in the \fBplist\fR param list string. +.PP +When you are finished writing the image, you should call +\&\fIFunFlush()\fR to write out the \s-1FITS\s0 +image padding. However, this is not necessary if you subsequently call +\&\fIFunClose()\fR without doing any other I/O to the \s-1FITS\s0 file. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funinfoget.3 b/funtools/man/man3/funinfoget.3 new file mode 100644 index 0000000..6bb14c9 --- /dev/null +++ b/funtools/man/man3/funinfoget.3 @@ -0,0 +1,335 @@ +.\" 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 "funinfoget 3" +.TH funinfoget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunInfoGet \- get information from Funtools struct +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 1 +\& int FunInfoGet(Fun fun, int type, char *addr, ...) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunInfoGet()\fB\fR routine returns information culled from the +Funtools structure. The first argument is the Fun handle from which +information is to be retrieved. This first required argument is followed +by a variable length list of pairs of arguments. Each pair consists +of an integer representing the type of information to retrieve and the +address where the information is to be stored. The list is terminated by a 0. +The routine returns the number of get actions performed. +.PP +The full list of available information is described below. Please note +that only a few of these will be useful to most application developers. +For imaging applications, the most important types are: +.PP +.Vb 3 +\& FUN_SECT_DIM1 int /* dim1 for section */ +\& FUN_SECT_DIM2 int /* dim2 for section */ +\& FUN_SECT_BITPIX int /* bitpix for section */ +.Ve +.PP +These would be used to determine the dimensions and data type of image +data retrieved using the +\&\fIFunImageGet()\fR routine. For +example: +.PP +.Vb 17 +\& /* extract and bin the data section into an image buffer */ +\& buf = FunImageGet(fun, NULL, NULL); +\& /* get required information from funtools structure. +\& this should come after the FunImageGet() call, in case the call +\& changed sect_bitpix */ +\& FunInfoGet(fun, +\& FUN_SECT_BITPIX, &bitpix, +\& FUN_SECT_DIM1, &dim1, +\& FUN_SECT_DIM2, &dim2, +\& 0); +\& /* loop through pixels and reset values below limit to value */ +\& for(i=0; i<dim1*dim2; i++){ +\& switch(bitpix){ +\& case 8: +\& if( cbuf[i] <= blimit ) cbuf[i] = bvalue; +\& ... +\& } +.Ve +.PP +It is important to bear in mind that the call to +\&\fIFunImageGet()\fR +can change the value of \s-1FUN_SECT_BITPIX\s0 (e.g. if \*(L"bitpix=n\*(R" is passed +in the param list). Therefore, a call to +\&\fIFunInfoGet()\fR +should be made \fBafter\fR the call to +\&\fIFunImageGet()\fR, +in order to retrieve the updated bitpix value. +See the imblank example code for more +details. +.PP +It also can be useful to retrieve the World Coordinate System +information from the Funtools structure. Funtools uses the the \s-1WCS\s0 +Library developed by Doug Mink at \s-1SAO\s0, which is available +here. +(More information about the WCSTools project in general can be found +here.) +The \fIFunOpen()\fR routine initializes +two \s-1WCS\s0 structures that can be used with this \s-1WCS\s0 Library. +Applications can retrieve either of these two \s-1WCS\s0 structures using +\&\fB\f(BIFunInfoGet()\fB\fR: +.PP +.Vb 2 +\& FUN_WCS struct WorldCoor * /* wcs structure, for image coordinates*/ +\& FUN_WCS0 struct WorldCoor * /* wcs structure, for physical coordinates */ +.Ve +.PP +The structure retrieved by \s-1FUN_WCS\s0 is a \s-1WCS\s0 library handle containing +parameters suitable for use with image coordinates, regardless of whether the +data are images or tables. For this structure, the \s-1WCS\s0 reference point +(\s-1CRPIX\s0) has been converted to image coordinates if the underlying file +is a table (and therefore in physical coordinates). You therefore must +ensure that the positions being passed to a routine like pix2wcs are in +image coordinates. The \s-1FUN_WCS0\s0 structure has not had its \s-1WCS\s0 +reference point converted to image coordinates. It therefore is useful +when passing processing physical coordinates from a table. +.PP +Once a \s-1WCS\s0 structure has been retrieved, it can be used as the first +argument to the \s-1WCS\s0 library routines. (If the structure is \s-1NULL\s0, no +\&\s-1WCS\s0 information was contained in the file.) The two important \s-1WCS\s0 routines +that Funtools uses are: +.PP +.Vb 5 +\& #include <wcs.h> +\& void pix2wcs (wcs,xpix,ypix,xpos,ypos) +\& struct WorldCoor *wcs; /* World coordinate system structure */ +\& double xpix,ypix; /* x and y coordinates in pixels */ +\& double *xpos,*ypos; /* RA and Dec in degrees (returned) */ +.Ve +.PP +which converts pixel coordinates to sky coordinates, and: +.PP +.Vb 5 +\& void wcs2pix (wcs, xpos, ypos, xpix, ypix, offscl) +\& struct WorldCoor *wcs; /* World coordinate system structure */ +\& double xpos,ypos; /* World coordinates in degrees */ +\& double *xpix,*ypix; /* coordinates in pixels */ +\& int *offscl; /* 0 if within bounds, else off scale */ +.Ve +.PP +which converts sky coordinates to pixel coordinates. Again, please note +that the wcs structure returned by \s-1FUN_WCS\s0 assumes that image coordinates +are passed to the pix2wcs routine, while \s-1FUN_WCS0\s0 assumes that physical +coordinates are passed. +.PP +Note that funtools.h file automatically includes wcs.h. An example +program that utilizes these \s-1WCS\s0 structure to call \s-1WCS\s0 Library routines +is twcs.c. +.PP +The following is the complete list of information that can be returned: +.PP +.Vb 52 +\& name type comment +\& --------- -------- --------------------------------------------- +\& FUN_FNAME char * /* file name */ +\& FUN_GIO GIO /* gio handle */ +\& FUN_HEADER FITSHead /* fitsy header struct */ +\& FUN_TYPE int /* TY_TABLE,TY_IMAGE,TY_EVENTS,TY_ARRAY */ +\& FUN_BITPIX int /* bits/pixel in file */ +\& FUN_MIN1 int /* tlmin of axis1 -- tables */ +\& FUN_MAX1 int /* tlmax of axis1 -- tables */ +\& FUN_MIN2 int /* tlmin of axis2 -- tables */ +\& FUN_MAX2 int /* tlmax of axis2 -- tables */ +\& FUN_DIM1 int /* dimension of axis1 */ +\& FUN_DIM2 int /* dimension of axis2 */ +\& FUN_ENDIAN int /* 0=little, 1=big endian */ +\& FUN_FILTER char * /* supplied filter */ +\& FUN_IFUN FITSHead /* pointer to reference header */ +\& FUN_IFUN0 FITSHead /* same as above, but no reset performed */ +\& /* image information */ +\& FUN_DTYPE int /* data type for images */ +\& FUN_DLEN int /* length of image in bytes */ +\& FUN_DPAD int /* padding to end of extension */ +\& FUN_DOBLANK int /* was blank keyword defined? */ +\& FUN_BLANK int /* value for blank */ +\& FUN_SCALED int /* was bscale/bzero defined? */ +\& FUN_BSCALE double /* bscale value */ +\& FUN_BZERO double /* bzero value */ +\& /* table information */ +\& FUN_NROWS int /* number of rows in file (naxis2) */ +\& FUN_ROWSIZE int /* size of user row struct */ +\& FUN_BINCOLS char * /* specified binning columns */ +\& FUN_OVERFLOW int /* overflow detected during binning? */ +\& /* array information */ +\& FUN_SKIP int /* bytes to skip in array header */ +\& /* section information */ +\& FUN_SECT_X0 int /* low dim1 value of section */ +\& FUN_SECT_X1 int /* hi dim1 value of section */ +\& FUN_SECT_Y0 int /* low dim2 value of section */ +\& FUN_SECT_Y1 int /* hi dim2 value of section */ +\& FUN_SECT_BLOCK int /* section block factor */ +\& FUN_SECT_BTYPE int /* 's' (sum), 'a' (average) for binning */ +\& FUN_SECT_DIM1 int /* dim1 for section */ +\& FUN_SECT_DIM2 int /* dim2 for section */ +\& FUN_SECT_BITPIX int /* bitpix for section */ +\& FUN_SECT_DTYPE int /* data type for section */ +\& FUN_RAWBUF char * /* pointer to raw row buffer */ +\& FUN_RAWSIZE int /* byte size of raw row records */ +\& /* column information */ +\& FUN_NCOL int /* number of row columns defined */ +\& FUN_COLS FunCol /* array of row columns */ +\& /* WCS information */ +\& FUN_WCS struct WorldCoor * /* wcs structure, converted for images*/ +\& FUN_WCS0 struct WorldCoor * /* wcs structure, not converted */ +.Ve +.PP +Row applications would not normally need any of this information. +An example of how these values can be used in more complex programs is +the evnext example code. In this program, the +time value for each row is changed to be the value of the succeeding +row. The program thus reads the time values for a batch of rows, +changes the time values to be the value for the succeeding row, and +then merges these changed time values back with the other columns to +the output file. It then reads the next batch, etc. +.PP +This does not work for the last row read in each batch, since there +is no succeeding row until the next batch is read. Therefore, the +program saves that last row until it has read the next batch, then +processes the former before starting on the new batch. In order to +merge the last row successfully, the code uses \s-1FUN_RAWBUF\s0 to save +and restore the raw input data associated with each batch of +rows. Clearly, this requires some information about how funtools +works internally. We are happy to help you write such programs as the +need arises. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funinfoput.3 b/funtools/man/man3/funinfoput.3 new file mode 100644 index 0000000..986fa9c --- /dev/null +++ b/funtools/man/man3/funinfoput.3 @@ -0,0 +1,246 @@ +.\" 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 "funinfoput 3" +.TH funinfoput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunInfoPut \- put information into a Funtools struct +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 1 +\& int FunInfoPut(Fun fun, int type, char *addr, ...) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunInfoPut()\fB\fR routine puts information into a Funtools +structure. The first argument is the Fun handle from which +information is to be retrieved. After this first required argument +comes a variable length list of pairs of arguments. Each pair consists +of an integer representing the type of information to store and the +address of the new information to store in the struct. The variable +list is terminated by a 0. The routine returns the number of put +actions performed. +.PP +The full list of available information is described above with the +\&\fIFunInfoPut()\fR routine. Although +use of this routine is expected to be uncommon, there is one +important situation in which it plays an essential part: writing +multiple extensions to a single output file. +.PP +For input, multiple extensions are handled by calling +\&\fIFunOpen()\fR for each extension to be +processed. When opening multiple inputs, it sometimes is the case that +you will want to process them and then write them (including their +header parameters) to a single output file. To accomplish this, you +open successive input extensions using +\&\fIFunOpen()\fR and then call +\&\fB\f(BIFunInfoPut()\fB\fR to set the +Funtools reference handle +of the output file to that of the newly opened input extension: +.PP +.Vb 4 +\& /* open a new input extension */ +\& ifun=FunOpen(tbuf, "r", NULL)) ) +\& /* make the new extension the reference handle for the output file */ +\& FunInfoPut(ofun, FUN_IFUN, &ifun, 0); +.Ve +.PP +Resetting \s-1FUN_IFUN\s0 has same effect as when a funtools handle is passed +as the final argument to +\&\fIFunOpen()\fR. The state of the output +file is reset so that a new extension is ready to be written. +Thus, the next I/O call on the output extension will output the +header, as expected. +.PP +For example, in a binary table, after resetting \s-1FUN_IFUN\s0 you can then +call \fIFunColumnSelect()\fR to +select the columns for output. When you then call +\&\fIFunImagePut()\fR or <A +HREF=\*(L"./library.html#funtablerowput\*(R">\fIFunTableRowPut()\fR, a new +extension will be written that contains the header parameters from the +reference extension. Remember to call +\&\fIFunFlush()\fR to complete output of a +given extension. +.PP +A complete example of this capability is given +in the evcol example code. +The central algorithm is: +.IP "\(bu" 4 +open the output file without a reference handle +.IP "\(bu" 4 +loop: open each input extension in turn +.RS 4 +.IP "\(bu" 4 +set the reference handle for output to the newly opened input extension +.IP "\(bu" 4 +read the input rows or image and perform processing +.IP "\(bu" 4 +write new rows or image to the output file +.IP "\(bu" 4 +flush the output +.IP "\(bu" 4 +close input extension +.RE +.RS 4 +.RE +.IP "\(bu" 4 +close output file +.PP +Note that \fIFunFlush()\fR is called +after processing each input extension in order to ensure that the +proper padding is written to the output file. A call to +\&\fIFunFlush()\fR also ensures that the +extension header is written to the output file in the case where there +are no rows to output. +.PP +If you wish to output a new extension without using a +Funtools reference handle, you can +call \fIFunInfoPut()\fR to reset the \s-1FUN_OPS\s0 value directly. For a binary +table, you would then call \fIFunColumnSelect()\fR to set up the columns for +this new extension. +.PP +.Vb 6 +\& /* reset the operations performed on this handle */ +\& int ops=0; +\& FunInfoPut(ofun, FUN_OPS, &ops, 0); +\& FunColumnSelect(fun, sizeof(EvRec), NULL, +\& "MYCOL", "J", "w", FUN_OFFSET(Ev, mycol), +\& NULL); +.Ve +.PP +Once the \s-1FUN_OPS\s0 variable has been reset, the next I/O call on the +output extension will output the header, as expected. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funlib.3 b/funtools/man/man3/funlib.3 new file mode 100644 index 0000000..6b4456a --- /dev/null +++ b/funtools/man/man3/funlib.3 @@ -0,0 +1,525 @@ +.\" 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 "funlib 3" +.TH funlib 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunLib \- the Funtools Programming Interface +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +A description of the Funtools library. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBIntroduction to the Funtools Programming Interface\fR +.PP +To create a Funtools application, you need to include +the funtools.h definitions file in your code: +.PP +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +You then call Funtools subroutines and functions to access Funtools data. +The most important routines are: +.IP "\(bu" 4 +FunOpen: open a Funtools file +.IP "\(bu" 4 +FunInfoGet: get info about an image or table +.IP "\(bu" 4 +FunImageGet: retrieve image data +.IP "\(bu" 4 +FunImageRowGet: retrieve image data by row +.IP "\(bu" 4 +FunImagePut: output image data +.IP "\(bu" 4 +FunImageRowPut: output image data by row +.IP "\(bu" 4 +FunColumnSelect: select columns in a table for access +.IP "\(bu" 4 +FunTableRowGet: retrieve rows from a table +.IP "\(bu" 4 +FunTableRowPut: output rows to a table +.IP "\(bu" 4 +FunClose: close a Funtools file +.PP +Your program must be linked against the libfuntools.a library, +along with the math library. The following libraries also might be required +on your system: +.IP "\(bu" 4 +\&\-lsocket \-lnsl for socket support +.IP "\(bu" 4 +\&\-ldl for dynamic loading +.PP +For example, on a Solaris system using gcc, use the following link line: +.PP +.Vb 1 +\& gcc \-o foo foo.c \-lfuntools \-lsocket \-lnsl \-ldl \-lm +.Ve +.PP +On a Solaris system using Solaris cc, use the following link line: +.PP +.Vb 1 +\& gcc \-o foo foo.c \-lfuntools \-lsocket \-lnsl \-lm +.Ve +.PP +On a Linux system using gcc, use the following link line: +.PP +.Vb 1 +\& gcc \-o foo foo.c \-lfuntools \-ldl \-lm +.Ve +.PP +Once configure has built a Makefile on your platform, the required +\&\*(L"extra\*(R" libraries (aside from \-lm, which always is required) are +specified in that file's \s-1EXTRA_LIBS\s0 variable. For example, under +Linux you will find: +.PP +.Vb 3 +\& grep EXTRA_LIBS Makefile +\& EXTRA_LIBS = \-ldl +\& ... +.Ve +.PP +The Funtools library contains both the zlib library +(http://www.gzip.org/zlib/) and Doug Mink's \s-1WCS\s0 library +(http://tdc\-www.harvard.edu/software/wcstools/). It is not necessary +to put these libraries on a Funtools link line. Include files +necessary for using these libraries are installed in the Funtools +include directory. +.PP +\&\fBFuntools Programming Tutorial\fR +.PP +The +\&\fIFunOpen()\fR +function is used to open a \s-1FITS\s0 file, an array, or a raw event file: +.PP +.Vb 4 +\& /* open the input FITS file for reading */ +\& ifun = FunOpen(iname, "r", NULL); +\& /* open the output FITS file for writing, and connect it to the input file */ +\& ofun = FunOpen(iname, "w", ifun); +.Ve +.PP +A new output file can inherit header parameters automatically from +existing input file by passing the input Funtools handle as the last +argument to the new file's +\&\fIFunOpen()\fR +call as shown above. +.PP +For image data, you then can call +\&\fIFunImageGet()\fR +to read an image into memory. +.PP +.Vb 3 +\& float buf=NULL; +\& /* extract and bin the data section into an image buffer */ +\& buf = FunImageGet(fun, NULL, "bitpix=-32"); +.Ve +.PP +If the (second) buf argument to this call is \s-1NULL\s0, buffer space is allocated +automatically. The (third) plist argument can be used to specify the +return data type of the array. If \s-1NULL\s0 is specified, the data type of +the input file is used. +.PP +To process an image buffer, you would generally make a call to +\&\fIFunInfoGet()\fR to determine the +dimensions of the image (which may have been changed from the original +file dimensions due to Funtools image +sectioning on the command line). In a \s-1FITS\s0 image, the index along +the dim1 axis varies most rapidly, followed by the dim2 axis, etc. +Thus, to access each pixel in an 2D image, use a double loop such as: +.PP +.Vb 7 +\& buf = FunImageGet(fun, NULL, "bitpix=-32"); +\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); +\& for(i=1; i<=dim2; i++){ +\& for(j=1; j<=dim1; j++){ +\& ... process buf[((i-1)*dim1)+(j-1)] ... +\& } +\& } +.Ve +.PP +or: +.PP +.Vb 5 +\& buf = FunImageGet(fun, NULL, "bitpix=-32"); +\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); +\& for(i=0; i<(dim1*dim2); i++){ +\& ... process buf[i] ... +\& } +.Ve +.PP +Finally, you can write the resulting image to disk using +\&\fIFunImagePut()\fR: +.PP +.Vb 1 +\& FunImagePut(fun2, buf, dim1, dim2, \-32, NULL); +.Ve +.PP +Note that Funtools automatically takes care of book-keeping tasks such as +reading and writing \s-1FITS\s0 headers (although you can, of course, write +your own header or add your own parameters to a header). +.PP +For binary tables and raw event files, a call to +\&\fIFunOpen()\fR +will be followed by a call to the +\&\fIFunColumnSelect()\fR +routine to select columns to be read from the input file and/or +written to the output file: +.PP +.Vb 8 +\& typedef struct evstruct{ +\& double time; +\& int time2; +\& } *Ev, EvRec; +\& FunColumnSelect(fun, sizeof(EvRec), NULL, +\& "time", "D", "rw", FUN_OFFSET(Ev, time), +\& "time2", "J", "w", FUN_OFFSET(Ev, time2), +\& NULL); +.Ve +.PP +Columns whose (third) mode argument contains an \*(L"r\*(R" are \*(L"readable\*(R", +i.e., columns will be read from the input file and converted into the +data type specified in the call's second argument. These columns +values then are stored in the specified offset of the user record +structure. Columns whose mode argument contains a \*(L"w\*(R" are +\&\*(L"writable\*(R", i.e., these values will be written to the output file. +The +\&\fIFunColumnSelect()\fR +routine also offers the option of automatically merging user +columns with the original input columns when writing the output +rows. +.PP +Once a set of columns has been specified, you can retrieve rows using +\&\fIFunTableRowGet()\fR, +and write the rows using +\&\fIFunTableRowPut()\fR: +.PP +.Vb 17 +\& Ev ebuf, ev; +\& /* get rows -- let routine allocate the array */ +\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ +\& /* process all rows */ +\& for(i=0; i<got; i++){ +\& /* point to the i'th row */ +\& ev = ebuf+i; +\& /* time2 is generated here */ +\& ev->time2 = (int)(ev->time+.5); +\& /* change the input time as well */ +\& ev->time = -(ev->time/10.0); +\& } +\& /* write out this batch of rows with the new column */ +\& FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL); +\& /* free row data */ +\& if( ebuf ) free(ebuf); +\& } +.Ve +.PP +The input rows are retrieved into an array of user structs, which +can be accessed serially as shown above. Once again, Funtools +automatically takes care of book-keeping tasks such as reading and writing +\&\s-1FITS\s0 headers (although you can, of course, write your own header or +add your own parameters to a header). +.PP +When all processing is done, you can call +\&\fIFunClose()\fR +to close the file(s): +.PP +.Vb 2 +\& FunClose(fun2); +\& FunClose(fun); +.Ve +.PP +These are the basics of processing \s-1FITS\s0 files (and arrays or raw event +data) using Funtools. The routines in these examples are described in +more detail below, along with a few other routines that support +parameter access, data flushing, etc. +.PP +\&\fBCompiling and Linking\fR +.PP +To create a Funtools application, a software developer will include +the funtools.h definitions file in Funtools code: +.PP +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +The program is linked against the libfuntools.a library, along with the +math library (and the dynamic load library, if the latter is available +on your system): +.PP +.Vb 1 +\& gcc \-o foo foo.c \-lfuntools \-ldl \-lm +.Ve +.PP +If gcc is used, Funtools filtering can be performed using dynamically +loaded shared objects that are built at run\-time. Otherwise, filtering +is performed using a slave process. +.PP +Funtools has been built on the following systems: +.IP "\(bu" 4 +Sun/Solaris 5.X +.IP "\(bu" 4 +Linux/RedHat Linux 5.X,6.X,7.X +.IP "\(bu" 4 +Dec Alpha/OSF1 V4.X +.IP "\(bu" 4 +WindowsNT/Cygwin 1.0 +.IP "\(bu" 4 +\&\s-1SGI/IRIX64\s0 6.5 +.PP +\&\fBA Short Digression on Subroutine Order\fR +.PP +There is a natural order for all I/O access libraries. You would not +think of reading a file without first opening it, or writing a file +after closing it. A large part of the experiment in funtools is to use +the idea of \*(L"natural order\*(R" as a means of making programming +easier. We do this by maintaining the state of processing for a given +funtools file, so that we can do things like write headers and flush +extension padding at the right time, without you having to do it. +.PP +For example, if you open a new funtools file for writing using +\&\fIFunOpen()\fR, +then generate an array of image data and call +\&\fIFunImagePut()\fR, +funtools knows to write the image header automatically. +There is no need to think about writing a standard header. +Of course, you can add parameters to the file first by +calling one of the +\&\fIFunParamPut()\fR +routines, and these parameters will automatically be added +to the header when it is written out. There still is no +need to write the header explicitly. +.PP +Maintaining state in this way means that there are certain rules of +order which should be maintained in any funtools program. In particular, +we strongly recommend the following ordering rules be adhered to: +.IP "\(bu" 4 +When specifying that input extensions be copied to an output file +via a reference handle, open the output file \fBbefore\fR reading the +input file. (Otherwise the initial copy will not occur). +.IP "\(bu" 4 +Always write parameters to an output file using one of the +\&\fIFunParamPut()\fR calls +\&\fBbefore\fR writing any data. (This is a good idea for all \s-1FITS\s0 +libraries, to avoid having to recopy data is the \s-1FITS\s0 header needs +to be extended by adding a single parameter.) +.IP "\(bu" 4 +If you retrieve an image, and need to know the data +type, use the \s-1FUN_SECT_BITPIX\s0 option of +\&\fIFunInfoGet()\fR, +\&\fBafter\fR calling +\&\fIFunImageGet()\fR, since +it is possible to change the value of \s-1BITPIX\s0 from the latter. +.IP "\(bu" 4 +When specifying that input extensions be copied to an output file +via a reference handle, close the output file \fBbefore\fR closing +input file, or else use +\&\fIFunFlush()\fR +explicitly on the output file +\&\fBbefore\fR closing the input file. (Otherwise the final copy will +not occur). +.PP +We believe that these are the natural rules that are implied in most +\&\s-1FITS\s0 programming tasks. However, we recognize that making explicit use +of \*(L"natural order\*(R" to decide what automatic action to take on behalf +of the programmer is experimental. Therefore, if you find that your +needs are not compatible with our preferred order, please let us know +\&\*(-- it will be most illuminating for us as we evaluate this experiment. +.PP +\&\fBFuntools Programming Examples\fR +.PP +The following complete coding examples are provided to illustrate the +simplicity of Funtools applications. They can be found in the funtest +subdirectory of the Funtools distribution. In many cases, you should +be able to modify one of these programs to generate your own Funtools +program: +.IP "\(bu" 4 +evread.c: read and write binary tables +.IP "\(bu" 4 +evcols.c: add column and rows to binary tables +.IP "\(bu" 4 +evmerge.c: merge new columns with existing columns +.IP "\(bu" 4 +evnext.c: manipulate raw data pointers +.IP "\(bu" 4 +imblank.c: blank out image values below a threshold +.IP "\(bu" 4 +asc2fits.c: convert a specific \s-1ASCII\s0 table to \s-1FITS\s0 binary table +.PP +\&\fBThe Funtools Programming Reference Manual\fR +.PP +#include <funtools.h> +.PP +Fun FunOpen(char *name, char *mode, Fun ref) +.PP +void *FunImageGet(Fun fun, void *buf, char *plist) +.PP +int FunImagePut(Fun fun, void *buf, int dim1, int dim2, int bitpix, char *plist) +.PP +void * FunImageRowGet(Fun fun, void *buf, int rstart, int rstop, char *plist) +.PP +void * FunImageRowPut(Fun fun, void *buf, int rstart, int rstop, int dim1, int dim2, int bitpix, char *plist) +.PP +int FunColumnSelect(Fun fun, int size, char *plist, ...) +.PP +void FunColumnActivate(Fun fun, char *s, char *plist) +.PP +int FunColumnLookup(Fun fun, char *s, int which, char **name, int *type, int *mode, int *offset, int *n, int *width) +.PP +void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist, int *nrow) +.PP +int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist) +.PP +int FunParamGetb(Fun fun, char *name, int n, int defval, int *got) +.PP +int FunParamGeti(Fun fun, char *name, int n, int defval, int *got) +.PP +double FunParamGetd(Fun fun, char *name, int n, double defval, int *got) +.PP +char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got) +.PP +int FunParamPutb(Fun fun, char *name, int n, int value, char *comm, int append) +.PP +int FunParamPuti(Fun fun, char *name, int n, int value, char *comm, int append) +.PP +int FunParamPutd(Fun fun, char *name, int n, double value, int prec, char *comm, int append) +.PP +int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm, int append) +.PP +int FunInfoGet(Fun fun, int type, ...) +.PP +int FunInfoPut(Fun fun, int type, ...) +.PP +void FunFlush(Fun fun, char *plist) +.PP +void FunClose(Fun fun) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funopen.3 b/funtools/man/man3/funopen.3 new file mode 100644 index 0000000..f185ea5 --- /dev/null +++ b/funtools/man/man3/funopen.3 @@ -0,0 +1,272 @@ +.\" 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 "funopen 3" +.TH funopen 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunOpen \- open a Funtools data file +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 1 +\& Fun FunOpen(char *name, char *mode, Fun ref); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunOpen()\fB\fR routine opens a Funtools data file for reading or +appending, or creates a new \s-1FITS\s0 file for writing. The \fBname\fR +argument specifies the name of the Funtools data file to open. You can +use IRAF-style bracket notation to specify +Funtools Files, Extensions, and Filters. +A separate call should be made each time a different \s-1FITS\s0 extension is +accessed: +.PP +.Vb 7 +\& Fun fun; +\& char *iname; +\& ... +\& if( !(fun = FunOpen(iname, "r", NULL)) ){ +\& fprintf(stderr, "could not FunOpen input file: %s\en", iname); +\& exit(1); +\& } +.Ve +.PP +If \fBmode\fR is \*(L"r\*(R", the file is opened for reading, and processing +is set up to begin at the specified extension. For reading, +\&\fBname\fR can be \fBstdin\fR, in which case the standard input is read. +.PP +If \fBmode\fR is \*(L"w\*(R", the file is created if it does not exist, or +opened and truncated for writing if it does exist. Processing starts +at the beginning of the file. The \fBname\fR can be \fBstdout\fR, +in which case the standard output is readied for processing. +.PP +If \fBmode\fR is \*(L"a\*(R", the file is created if it does not exist, or +opened if it does exist. Processing starts at the end of the file. +The \fBname\fR can be \fBstdout\fR, in which case the standard +output is readied for processing. +.PP +When a Funtools file is opened for writing or appending, a previously +opened Funtools reference +handle can be specified as the third argument. This handle +typically is associated with the input Funtools file that will be used +to generate the data for the output data. When a reference file is +specified in this way, the output file will inherit the (extension) +header parameters from the input file: +.PP +.Vb 8 +\& Fun fun, fun2; +\& ... +\& /* open input file */ +\& if( !(fun = FunOpen(argv[1], "r", NULL)) ) +\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); +\& /* open the output FITS image, inheriting params from input */ +\& if( !(fun2 = FunOpen(argv[2], "w", fun)) ) +\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); +.Ve +.PP +Thus, in the above example, the output \s-1FITS\s0 binary table file will +inherit all of the parameters associated with the input binary table +extension. +.PP +A file opened for writing with a +Funtools reference handle also +inherits the selected columns (i.e. those columns chosen for +processing using the +\&\fIFunColumnSelect()\fR routine) +from the reference file as its default columns. This makes it easy to +open an output file in such a way that the columns written to the +output file are the same as the columns read in the input file. Of +course, column selection can easily be tailored using the +\&\fIFunColumnSelect()\fR routine. +In particular, it is easy to merge user-defined columns with the input +columns to generate a new file. See the +evmerge for a complete example. +.PP +In addition, when a +Funtools reference handle +is supplied in a \fIFunOpen()\fR call, +it is possible also to specify that all other extensions from the +reference file (other than the input extension being processed) should +be copied from the reference file to the output file. This is useful, +for example, in a case where you are processing a \s-1FITS\s0 binary table +or image and you want to copy all of the other extensions to +the output file as well. Copy of other extensions is controlled by +adding a \*(L"C\*(R" or \*(L"c\*(R" to the mode string of the +\&\fIFunOpen()\fR call of the input +reference file. If \*(L"C\*(R" is specified, then other extensions are +\&\fBalways\fR copied (i.e., copy is forced by the application). If +\&\*(L"c\*(R" is used, then other extensions are copied if the user requests +copying by adding a plus sign \*(L"+\*(R" to the extension name in the bracket +specification. For example, the \fBfuntable\fR program utilizes +\&\*(L"c\*(R" mode, giving users the option of copying all other extensions: +.PP +.Vb 6 +\& /* open input file -- allow user copy of other extensions */ +\& if( !(fun = FunOpen(argv[1], "rc", NULL)) ) +\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); +\& /* open the output FITS image, inheriting params from input */ +\& if( !(fun2 = FunOpen(argv[2], "w", fun)) ) +\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); +.Ve +.PP +Thus, \fBfuntable\fR supports either of these command lines: +.PP +.Vb 4 +\& # copy only the EVENTS extension +\& csh> funtable "test.ev[EVENTS,circle(512,512,10)]" foo.ev +\& # copy ALL extensions +\& csh> funtable "test.ev[EVENTS+,circle(512,512,10)]" foo.ev +.Ve +.PP +Use of a Funtools reference +handle implies that the input file is opened before the output +file. However, it is important to note that if copy mode (\*(L"c\*(R" or \*(L"C\*(R") +is specified for the input file, the actual input file open is delayed +until just after the output file is opened, since the copy of prior +extensions to the output file takes place while Funtools is seeking to +the specified input extension. This implies that the output file +should be opened before any I/O is done on the input file or else the +copy will fail. Note also that the copy of subsequent extension will +be handled automatically by +\&\fIFunClose()\fR +if the output file is +closed before the input file. Alternatively, it can be done explicitly +by \fIFunFlush()\fR, but again, this +assumes that the input file still is open. +.PP +Upon success \fIFunOpen()\fR returns a +Fun handle that is used in subsequent Funtools calls. On error, \s-1NULL\s0 +is returned. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funparamget.3 b/funtools/man/man3/funparamget.3 new file mode 100644 index 0000000..1609aae --- /dev/null +++ b/funtools/man/man3/funparamget.3 @@ -0,0 +1,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 diff --git a/funtools/man/man3/funparamput.3 b/funtools/man/man3/funparamput.3 new file mode 100644 index 0000000..db90dcc --- /dev/null +++ b/funtools/man/man3/funparamput.3 @@ -0,0 +1,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 diff --git a/funtools/man/man3/funref.3 b/funtools/man/man3/funref.3 new file mode 100644 index 0000000..7c6156a --- /dev/null +++ b/funtools/man/man3/funref.3 @@ -0,0 +1,287 @@ +.\" 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 "funref 3" +.TH funref 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunRef \- the Funtools Reference Handle +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +A description of how to use a Funtools reference handle to connect a +Funtools input file to an output file. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The Funtools reference handle connects a Funtools input file to a +Funtools output file so that parameters (or even whole extensions) can +be copied from the one to the other. To make the connection, the Funtools +handle of the input file is passed to the +final argument of the +\&\fIFunOpen()\fR call for the output file: +.PP +.Vb 4 +\& if( !(ifun = FunOpen(argv[1], "r", NULL)) ) +\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); +\& if( !(ofun = FunOpen(argv[2], "w", ifun)) ) +\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); +.Ve +.PP +It does not matter what type of input or output file (or extension) is +opened, or whether they are the same type. When the output image or +binary table is written using +\&\fIFunImagePut()\fR +or +\&\fIFunTableRowPut()\fR +an appropriate header will be written first, with parameters copied +from the input extension. Of course, invalid parameters will be +removed first, e.g., if the input is a binary table and the output is +an image, then binary table parameters such as \s-1TFORM\s0, \s-1TUNIT\s0, +etc. parameters will not be copied to the output. +.PP +Use of a reference handle also allows default values to be passed +to +\&\fIFunImagePut()\fR in order to +write out an output image with the same dimensions and data type +as the input image. To use the defaults from the input, a value +of 0 is entered for dim1, dim2, and bitpix. For example: +.PP +.Vb 5 +\& fun = FunOpen(argv[1], "r", NULL); +\& fun2 = FunOpen(argv[2], "w", fun); +\& buf = FunImageGet(fun, NULL, NULL); +\& ... process image data ... +\& FunImagePut(fun2, buf, 0, 0, 0, NULL); +.Ve +.PP +Of course, you often want to get information about the data type +and dimensions of the image for processing. The above code +is equivalent to the following: +.PP +.Vb 7 +\& fun = FunOpen(argv[1], "r", NULL); +\& fun2 = FunOpen(argv[2], "w", fun); +\& buf = FunImageGet(fun, NULL, NULL); +\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, +\& FUN_SECT_BITPIX, &bitpix, 0); +\& ... process image data ... +\& FunImagePut(fun2, buf, dim1, dim2, bitpix, NULL); +.Ve +.PP +It is possible to change the reference handle for a given output Funtools +handle using the +\&\fIFunInfoPut()\fR routine: +.PP +.Vb 2 +\& /* make the new extension the reference handle for the output file */ +\& FunInfoPut(fun2, FUN_IFUN, &fun, 0); +.Ve +.PP +When this is done, Funtools specially resets the output file to start +a new output extension, which is connected to the new input reference +handle. You can use this mechanism to process multiple input extensions +into a single output file, by successively opening the former and +setting the reference handle for the latter. For example: +.PP +.Vb 18 +\& /* open a new output FITS file */ +\& if( !(fun2 = FunOpen(argv[2], "w", NULL)) ) +\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); +\& /* process each input extension in turn */ +\& for(ext=0; ;ext++){ +\& /* get new extension name */ +\& sprintf(tbuf, "%s[%d]", argv[1], ext); +\& /* open it -- if we cannot open it, we are done */ +\& if( !(fun=FunOpen(tbuf, "r", NULL)) ) +\& break; +\& /* make the new extension the reference handle for the output file */ +\& FunInfoPut(fun2, FUN_IFUN, &fun, 0); +\& ... process ... +\& /* flush output extension (write padding, etc.) */ +\& FunFlush(fun2, NULL); +\& /* close the input extension */ +\& FunClose(fun); +\& } +.Ve +.PP +In this example, the output file is opened first. Then each successive +input extension is opened, and the output reference handle is set to +the newly opened input handle. After data processing is performed, the +output extension is flushed and the input extension is closed, in +preparation for the next input extension. +.PP +Finally, a reference handle can be used to copy other extensions from +the input file to the output file. Copy of other extensions is +controlled by adding a \*(L"C\*(R" or \*(L"c\*(R" to the mode string of the +\&\fIFunOpen()\fR +call \fBof the input reference file\fR. If \*(L"C\*(R" is specified, then +other extensions are \fBalways\fR copied (i.e., copy is forced by the +application). If \*(L"c\*(R" is used, then other extensions are copied if the +user requests copying by adding a plus sign \*(L"+\*(R" to the extension name +in the bracket specification. For example, the \fBfuntable\fR +program utilizes user-specified \*(L"c\*(R" mode so that the second example +below will copy all extensions: +.PP +.Vb 4 +\& # copy only the EVENTS extension +\& csh> funtable "test.ev[EVENTS,circle(512,512,10)]" foo.ev +\& # copy ALL extensions +\& csh> funtable "test.ev[EVENTS+,circle(512,512,10)]" foo.ev +.Ve +.PP +When extension copy is specified in the input file, the call to +\&\fIFunOpen()\fR +on the input file delays the actual file open until the output file +also is opened (or until I/O is performed on the input file, which +ever happens first). Then, when the output file is opened, the input +file is also opened and input extensions are copied to the output +file, up to the specific extension being opened. Processing of input +and output extensions then proceed. +.PP +When extension processing is complete, the remaining extensions need to +be copied from input to output. This can be done explicitly, using the +\&\fIFunFlush()\fR +call with the \*(L"copy=remaining\*(R" plist: +.PP +.Vb 1 +\& FunFlush(fun, "copy=remaining"); +.Ve +.PP +Alternatively, this will happen automatically, if the output file +is closed \fBbefore\fR the input file: +.PP +.Vb 5 +\& /* we could explicitly flush remaining extensions that need copying */ +\& /* FunFlush(fun2, "copy=remaining"); */ +\& /* but if we close output before input, end flush is done automatically */ +\& FunClose(fun2); +\& FunClose(fun); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funtablerowget.3 b/funtools/man/man3/funtablerowget.3 new file mode 100644 index 0000000..7554781 --- /dev/null +++ b/funtools/man/man3/funtablerowget.3 @@ -0,0 +1,216 @@ +.\" 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 "funtablerowget 3" +.TH funtablerowget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunTableRowGet \- get Funtools rows +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 2 +\& void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist, +\& int *nrow) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunTableRowGet()\fB\fR routine retrieves rows from a Funtools +binary table or raw event file, and places the values of columns +selected by \fIFunColumnSelect()\fR +into an array of user structs. Selected column values are +automatically converted to the specified user data type (and to native +data format) as necessary. +.PP +The first argument is the Fun handle associated with this row data. +The second \fBrows\fR argument is the array of user structs into +which the selected columns will be stored. If \s-1NULL\s0 is passed, the +routine will automatically allocate space for this array. (This +includes proper allocation of pointers within each struct, if the \*(L"@\*(R" +pointer type is used in the selection of columns. Note that if you +pass \s-1NULL\s0 in the second argument, you should free this space using the +standard \fIfree()\fR system call when you are finished with the array of +rows.) The third \fBmaxrow\fR argument specifies the maximum number +of rows to be returned. Thus, if \fBrows\fR is allocated by the +user, it should be at least of size maxrow*sizeof(evstruct). +.PP +The fourth \fBplist\fR argument is a param list string. Currently, +the keyword/value pair \*(L"mask=transparent\*(R" is supported in the plist +argument. If this string is passed in the call's plist argument, then +all rows are passed back to the user (instead of just rows passing +the filter). This is only useful when +\&\fIFunColumnSelect()\fR also is +used to specify \*(L"$region\*(R" as a column to return for each row. In +such a case, rows found within a region have a returned region value +greater than 0 (corresponding to the region id of the region in which +they are located), rows passing the filter but not in a region have +region value of \-1, and rows not passing any filter have region +value of 0. Thus, using \*(L"mask=transparent\*(R" and the returned region +value, a program can process all rows and decide on an action based +on whether a given row passed the filter or not. +.PP +The final argument is a pointer to an int variable that will return +the actual number of rows returned. The routine returns a pointer to +the array of stored rows, or \s-1NULL\s0 if there was an error. (This pointer +will be the same as the second argument, if the latter is non\-NULL). +.PP +.Vb 16 +\& /* get rows -- let routine allocate the row array */ +\& while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ +\& /* process all rows */ +\& for(i=0; i<got; i++){ +\& /* point to the i'th row */ +\& ev = buf+i; +\& /* rearrange some values. etc. */ +\& ev->energy = (ev->pi+ev->pha)/2.0; +\& ev->pha = \-ev->pha; +\& ev->pi = \-ev->pi; +\& } +\& /* write out this batch of rows */ +\& FunTableRowPut(fun2, buf, got, 0, NULL); +\& /* free row data */ +\& if( buf ) free(buf); +\& } +.Ve +.PP +As shown above, successive calls to +\&\fIFunTableRowGet()\fR will return the +next set of rows from the input file until all rows have been read, +i.e., the routine behaves like sequential Unix I/O calls such as +\&\fIfread()\fR. See evmerge example code for a +more complete example. +.PP +Note that \fIFunTableRowGet()\fR also can be called as \fIFunEventsGet()\fR, for +backward compatibility. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funtablerowput.3 b/funtools/man/man3/funtablerowput.3 new file mode 100644 index 0000000..533bd43 --- /dev/null +++ b/funtools/man/man3/funtablerowput.3 @@ -0,0 +1,297 @@ +.\" 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 "funtablerowput 3" +.TH funtablerowput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunTableRowPut \- put Funtools rows +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist) +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunTableRowPut()\fB\fR routine writes rows to a \s-1FITS\s0 binary +table, taking its input from an array of user structs that contain +column values selected by a previous call to +\&\fIFunColumnSelect()\fR. Selected +column values are automatically converted from native data format to +\&\s-1FITS\s0 data format as necessary. +.PP +The first argument is the Fun handle associated with this row data. +The second \fBrows\fR argument is the array of user structs to +output. The third \fBnrow\fR argument specifies the number number of +rows to write. The routine will write \fBnrow\fR records, starting +from the location specified by \fBrows\fR. +.PP +The fourth \fBidx\fR argument is the index of the first raw input +row to write, in the case where rows from the user buffer are +being merged with their raw input row counterparts (see below). Note +that this \fBidx\fR value is has nothing to do with the +row buffer specified in argument 1. It merely matches the row +being written with its corresponding (hidden) raw row. Thus, if you +read a number of rows, process them, and then write them out all at +once starting from the first user row, the value of \fBidx\fR +should be 0: +.PP +.Vb 14 +\& Ev ebuf, ev; +\& /* get rows -- let routine allocate the row array */ +\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ +\& /* process all rows */ +\& for(i=0; i<got; i++){ +\& /* point to the i'th row */ +\& ev = ebuf+i; +\& ... +\& } +\& /* write out this batch of rows, starting with the first */ +\& FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL); +\& /* free row data */ +\& if( ebuf ) free(ebuf); +\& } +.Ve +.PP +On the other hand, if you write out the rows one at a time (possibly +skipping rows), then, when writing the i'th row from the input +array of rows, set \fBidx\fR to the value of i: +.PP +.Vb 14 +\& Ev ebuf, ev; +\& /* get rows -- let routine allocate the row array */ +\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ +\& /* process all rows */ +\& for(i=0; i<got; i++){ +\& /* point to the i'th row */ +\& ev = ebuf+i; +\& ... +\& /* write out the current (i.e., i'th) row */ +\& FunTableRowPut(fun2, (char *)ev, 1, i, NULL); +\& } +\& /* free row data */ +\& if( ebuf ) free(ebuf); +\& } +.Ve +.PP +The final argument is a param list string that is not currently used. +The routine returns the number of rows output. This should be equal +to the value passed in the third nrow</B argument. +.PP +When \fIFunTableRowPut()\fR is first +called for a given binary table, Funtools checks to see of the primary +header has already been written (either by writing a previous row +table or by writing an image.) If not, a dummy primary header is +written to the file specifying that an extension should be expected. +After this, a binary table header is automatically written containing +information about the columns that will populate this table. In +addition, if a +Funtools reference handle +was specified when this table was opened, the parameters from this +Funtools reference handle +are merged into the new binary table header. +.PP +In a typical Funtools row loop, you read rows using +\&\fIFunTableRowGet()\fR() and write +rows using \fIFunTableRowPut()\fR. The columns written by +\&\fIFunTableRowPut()\fR() are those defined as writable by a previous call to +\&\fIFunColumnSelect()\fR. If +that call to FunColumnSelect also specified +\&\fBmerge=[update|replace|append]\fR, then the entire corresponding +raw input row record will be merged with the output row according +to the \fBmerge\fR specification (see +\&\fIFunColumnSelect()\fR above). +.PP +A call to write rows can either be done once, after all rows in +the input batch have been processed, or it can be done (slightly less +efficiently) one row at a time (or anything in between). We do +recommend that you write all rows associated with a given batch of +input rows before reading new rows. This is \fBrequired\fR if +you are merging the output rows with the raw input rows (since +the raw rows are destroyed with each successive call to get new rows). +.PP +For example: +.PP +.Vb 13 +\& Ev buf, ev; +\& ... +\& /* get rows -- let routine allocate the row array */ +\& while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ +\& /* point to the i'th row */ +\& ev = buf + i; +\& .... process +\& } +\& /* write out this batch of rows */ +\& FunTableRowPut(fun2, buf, got, 0, NULL); +\& /* free row data */ +\& if( buf ) free(buf); +\& } +.Ve +.PP +or +.PP +.Vb 16 +\& Ev buf, ev; +\& ... +\& /* get rows -- let routine allocate the row array */ +\& while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ +\& /* process all rows */ +\& for(i=0; i<got; i++){ +\& /* point to the i'th row */ +\& ev = buf + i; +\& ... process +\& /* write out this batch of rows with the new column */ +\& if( dowrite ) +\& FunTableRowPut(fun2, buf, 1, i, NULL); +\& } +\& /* free row data */ +\& if( buf ) free(buf); +\& } +.Ve +.PP +Note that the difference between these calls is that the first one +outputs \fBgot\fR rows all at once and therefore passes +\&\fBidx=0\fR in argument four, so that merging starts at the first raw +input row. In the second case, a check it made on each row to see +if it needs to be output. If so, the value of \fBidx\fR is passed as +the value of the \fBi\fR variable which points to the current row +being processed in the batch of input rows. +.PP +As shown above, successive calls to +\&\fIFunTableRowPut()\fR will write +rows sequentially. When you are finished writing all rows in a +table, you should call +\&\fIFunFlush()\fR to write out the \s-1FITS\s0 +binary table padding. However, this is not necessary if you +subsequently call \fIFunClose()\fR without doing any other I/O to the \s-1FITS\s0 +file. +.PP +Note that \fIFunTableRowPut()\fR also can be called as \fIFunEventsPut()\fR, for +backward compatibility. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages |