FTOOLS
Home
To illustrate the fundamental requirement of an FTOOLS task, consider a hypothetical task called fdummyftool (the text and files for this exist in examples). Of course, the developer would replace dummy with the name associated with the task being developed. The use of a prefix ``f'' to the task name is optional and should be used to reflect a general FITS task. The first step in adding a new task is to create a directory to store the source files. For the recommended directory structure which is distributed, this would mean creating a directory named ~ftools/ftools/heasarc/src/fdummyftool/ (the ~ftools refers to the account) for a task to be integrated into the heasarc sub-package or a directory named ~ftools/ftools/futils/src/fdummyftool/ for a task to be integrated into the futils sub-package with the command (assuming this will be an heasarc task):
>mkdir ~ftools/ftools/heasarc/src/fdummyftool
Make this the current work directory:
>cd ~ftools/ftools/heasarc/src/fdummyftool
This directory typically contains 5 files:
The hfdummyftool.c, Makefile, mkpkg and make.com only differ by a couple of global string substitutions from their counterparts in other task directories, so it is recommended that you simply copy these from one of the other source files and make the necessary changes to them. The fdummyftool.f and fdummyftool.par contain the task specific source. The fdummyftool.f contains the FORTRAN 77 subroutine at the center of the task implementation. As a simple example let fdummyftool.f be the source for a subroutine that simply reads the dummy parameter from the fdummyftool.par file and prints the value to the terminal:
fdummyftool.f
C No argument passing to THIS TOP subroutine
subroutine fdummyftool()
character*80 dummy
integer status
C Setup common block for taskname
character*40 taskname
common /task/ taskname
C Get dummy value from parameter file using F77/VOS call
call gdummy(dummy,status)
C Pass parameter to PROCESSING subroutine
call dowork(dummy,status)
return
end
C Isolate calls to parameter files in one subroutine
subroutine gdummy(dummy,status)
character*80 dummy,contxt
integer status
call uclgst('dummy',dummy,status)
if (status .ne. 0) then
contxt = 'could not get INFIL1 parameter'
call fcerr(contxt)
goto 999
endif
999 continue
return
end
C subroutine where all the FITSIO and data manipulation occurs
subroutine dowork(dummy,status)
character*80 dummy
integer status
if (status .eq. 0) then
C IRAF remaps IO so a library function must be used to print
call fcecho(dummy)
else
call fcerr('error reading parameter')
endif
return
end
fdummyftool.par
dummy,s,a,"Hello World",,,"Enter a string"
mode,s,h,"ql",,,
Several points have already cropped up in the comments to this simple code. One which is not evident but very important is the naming convention used by calls in the IRAF spp main routine. Subroutines called by spp code must have a name less than or equal to six letters. However, the task name can be any length. To handle this, the spp main code matches the first 5 letters and the last letter of the task name to the subroutine name. For example, if the task name was flongname the FORTRAN subroutine name would have to be flonge. In addition, all the FTOOLS tasks in the IRAF version are linked together. This places the constraint that all subroutine names be distinct. The library routines that are used to interface with the parameter files were developed at STSCI and all developers are advised to reference the F77/VOS documentation on their proper use.
Assuming that you copied over the Makefile, mkpkg, make.com and hfdummyftool.c files from another FTOOLS task with commands like:
>cp ~ftools/ftools/futils/src/flcol/Makefile .
>cp ~ftools/ftools/futils/src/flcol/mkpkg .
>cp ~ftools/ftools/futils/src/flcol/make.com .
>cp ~ftools/ftools/futils/src/flcol/hflcol.c hfdummyftool.c
while in the fdummyftool directory. Then the Makefile, make.com and mkpkg
file can be made to work for the fdummyftool task by replacing all
occurrences of flcol with fdummyftool in these two files. The
hfdummyftool.c file is a bit more tricky. The string substitution for
flcol becoming fdummyftool still holds, but it must be case
sensitive. There is an additional replacement of FLCOL with
FDUMML which must occur in this file. This reflects the case where
the FTOOLS task name is longer than 6 letters. When you have a task
flongname for example, the two #define FLONGNAME macros must
reflect the actual subroutine name flonge, created by placing the
last letter of the name at the end of the first five letters (see the
fdummyftool.f FORTRAN source file).
FTOOLS
Home