[an error occurred while processing this directive] FTOOLS Home

A Few Specifics

FORTRAN is the primary development language for the FTOOLS, although C is used in a considerable number of cases. When developing FTOOLS software in FORTRAN, make sure your code is consistent with the following.

• Comply with ANSI FORTRAN standards (Notice how often we mention this...).
• Use C instead of c as the comment character in first field
• Do not use FORTRAN STOP statements - this kills IRAF and may corrupt open FITS files
• Use INTEGER*2 only when absolutely necessary.
• Use variable and subroutine names having first 6 characters unique
• Declare all variables, but do not declare variables that are not used
• Subroutine names in all FTOOLS tasks must be unique. This is required by IRAF which links all tasks within a common package library
• Do not use PRINT* or WRITE statements for output; instead use a call to FCECHO to print the strings and warnings and FCERR to print error messages, otherwise the task will fail in IRAF
• Limit the number of files necessary to build the task to as few as possible
• Do not use the underscore character in FTOOLS tasks names
• Do not use string concatenations in function or subroutine calls, only with assignments

When developing FTOOLS software utilizing the C language, make sure that your code is consistent with the following. (Note that with the recent development of a native C version of FITSIO, these instructions are somewhat obsolete. A revised version of these will be produced soon, when we've worked out procedures to match the new setup.)

• The Main ``wrapper'' must be written in C and must make a call to a central subroutine having zero arguments; see earlier discussions
• Make all subroutine calls to the parameter file interface subroutines from FORTRAN
• Use only ANSI C. Period.
• Use the Header file cfortran.h to make calls to FORTRAN from C and visa versa; this is particularly important for passing arguments between the two languages; see below
• Do not pass C structures or arrays of characters to FORTRAN; cfortran.h doesn't directly support them

Since FTOOLS are ``FITS tools'' for manipulating FITS files, use the FITSIO library of routines to make all I/O calls to the data within the FITS file. This is necessary to maximize portability. Practically all computers have some differences in how they format numbers internally. FITS files have standardized the representation of data and the FITSIO library provides a machine independent means of accessing that data. Do not write code that reads in the data as bytes and does the conversion to the data type for one particular computer platform. This has already been taken care of with the FITSIO library routines. It is very important that any developer of FTOOLS style software understand the FITSIO library and use it. Documentation on using FITSIO is available from the anonymous FTP account on heasarc.gsfc.nasa.gov in the directory software/fitsio. In addition, adhere to these guidelines for using FITSIO.

• Test FITSIO status flags early and often
• Read in integer, real, etc. data types with any FITSIO subroutine. Type conversion is done automatically.
• Cleanly exit by closing all open FITS files with the FTCLOS routine; make sure that the status=0 prior to this call; failure to do this may corrupt the FITS file
• FITSIO treats the primary array as the first extension; the FTOOLS convention is that the primary array is the zeroth extension and that the first extension after the primary is the first extension
• Make calls to FITSIO for strings and arrays of strings from FORTRAN not C, then pass the necessary data back to C if writing FTOOLS with C code

The user interface for FTOOLS software is the parameter file. These parameter are read and written using routines having identical function and name found in both the XPI and IRAF libraries. The following coding practices for reading the parameter files are now an FTOOLS standard.

• Use FORTRAN to call interface subroutines that read and write to the parameter file
• Isolate all calls to the parameter file in one subroutine and make this the first process performed in the central FTOOLS routine when possible
• Read the parameter values from the parameter file in the same order that they appear in the parameter file
• Distribute parameter files for your FTOOLS with intelligent default values
• Make parameters that are unlikely to change hidden parameters

Finally, be sure that you make these general practices a part of your program,

• Document source code; consider using existing FTOOLS software as a template
• Dimension filename variables to 180 characters
• Central FTOOLS subroutine must use the IRAF 1st five + last character naming convention
• Include the task common block
• Include IRAF style help files with your FTOOLS
• Reuse existing code found in the misc.for FTOOLS library; see Appendix
• Use lots of in line comments

By far the best place to start down the road to developing FTOOLS style software is the FTOOLS distribution itself. The FTOOLS distribution comes complete with lots of examples from which to learn. I would recommend starting with one of the more simple tasks like flcol, fstatistic or ftabcopy. With a little practice you too will be churning out lots of nifty, unique FTOOLS for others to share.

FTOOLS Home

[an error occurred while processing this directive]