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, 0 insertions, 5256 deletions
diff --git a/funtools/man/man3/funclose.3 b/funtools/man/man3/funclose.3 deleted file mode 100644 index dc8dbd2..0000000 --- a/funtools/man/man3/funclose.3 +++ /dev/null @@ -1,160 +0,0 @@ -.\" 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 deleted file mode 100644 index 2eda34b..0000000 --- a/funtools/man/man3/funcolumnactivate.3 +++ /dev/null @@ -1,330 +0,0 @@ -.\" 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 deleted file mode 100644 index 15c9c36..0000000 --- a/funtools/man/man3/funcolumnlookup.3 +++ /dev/null @@ -1,220 +0,0 @@ -.\" 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 deleted file mode 100644 index 88158c0..0000000 --- a/funtools/man/man3/funcolumnselect.3 +++ /dev/null @@ -1,664 +0,0 @@ -.\" 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 deleted file mode 100644 index 611dfc3..0000000 --- a/funtools/man/man3/funflush.3 +++ /dev/null @@ -1,212 +0,0 @@ -.\" 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 deleted file mode 100644 index 091765d..0000000 --- a/funtools/man/man3/funimageget.3 +++ /dev/null @@ -1,332 +0,0 @@ -.\" 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 deleted file mode 100644 index 9618944..0000000 --- a/funtools/man/man3/funimageput.3 +++ /dev/null @@ -1,225 +0,0 @@ -.\" 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 deleted file mode 100644 index 50a0979..0000000 --- a/funtools/man/man3/funimagerowget.3 +++ /dev/null @@ -1,215 +0,0 @@ -.\" 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 deleted file mode 100644 index e76bc7f..0000000 --- a/funtools/man/man3/funimagerowput.3 +++ /dev/null @@ -1,202 +0,0 @@ -.\" 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 deleted file mode 100644 index 6bb14c9..0000000 --- a/funtools/man/man3/funinfoget.3 +++ /dev/null @@ -1,335 +0,0 @@ -.\" 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 deleted file mode 100644 index 986fa9c..0000000 --- a/funtools/man/man3/funinfoput.3 +++ /dev/null @@ -1,246 +0,0 @@ -.\" 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 deleted file mode 100644 index 6b4456a..0000000 --- a/funtools/man/man3/funlib.3 +++ /dev/null @@ -1,525 +0,0 @@ -.\" 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 deleted file mode 100644 index f185ea5..0000000 --- a/funtools/man/man3/funopen.3 +++ /dev/null @@ -1,272 +0,0 @@ -.\" 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 deleted file mode 100644 index 1609aae..0000000 --- a/funtools/man/man3/funparamget.3 +++ /dev/null @@ -1,262 +0,0 @@ -.\" 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 deleted file mode 100644 index db90dcc..0000000 --- a/funtools/man/man3/funparamput.3 +++ /dev/null @@ -1,256 +0,0 @@ -.\" 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 deleted file mode 100644 index 7c6156a..0000000 --- a/funtools/man/man3/funref.3 +++ /dev/null @@ -1,287 +0,0 @@ -.\" 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 deleted file mode 100644 index 7554781..0000000 --- a/funtools/man/man3/funtablerowget.3 +++ /dev/null @@ -1,216 +0,0 @@ -.\" 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 deleted file mode 100644 index 533bd43..0000000 --- a/funtools/man/man3/funtablerowput.3 +++ /dev/null @@ -1,297 +0,0 @@ -.\" 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 |