next up previous FTOOLS Home
Next: Task Integration Up: Developer's Guide Previous: Task Design

Task Development

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:

  • fdummyftool.f - the FORTRAN source
  • hfdummyftool.c - the C main wrapper for Host Version
  • fdummyftool.par - the parameter file
  • Makefile - the Host make file
  • mkpkg - the IRAF make package file
  • make.com - the VMS build command file

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).


next up previous FTOOLS Home
Next: Task Integration Up: Developer's Guide Previous: Task Design

Web Page Maintained by: Dr. Lawrence E. Brown elwin@redshift.gsfc.nasa.gov

FTOOLS HELP DESK

If FTOOLS has been useful in your research, please reference this site (http://heasarc.gsfc.nasa.gov/ftools) and use the ASCL reference for HEASoft [ascl:1408.004] or the ASCL reference for the original FTOOLs paper [ascl:9912.002]:

Blackburn, J. K. 1995, in ASP Conf. Ser., Vol. 77, Astronomical Data Analysis Software and Systems IV, ed. R. A. Shaw, H. E. Payne, and J. J. E. Hayes (San Francisco: ASP), 367.

Web page maintained by: Bryan K. Irby