B. FTOOLS developers guideline

Here is a guideline by the GSFC FTOOLS team for the programmers developing Suzaku FTOOLS. This guideline is particularly aimed for Japanese instrument members who are developing in the ANL environment and going to convert ANL modules into FTOOLS.

B.1 Items to be Delivered

The delivery to the GSFC Suzaku GOF/FTOOLS team should include the software and test example(s).

• Software
  • Source Codes
  • Parameter files (default)
  • Makefile
  • Documents: in plain ASCII text and IRAF ``lroff'' format.

• Examples:
  • Relevant input files and resulted output files.
  • Test parameter files or test script.

B.2 Source Codes

• Useful informations can be found at:
  http://heasarc.gsfc.nasa.gov/ftools/others/develop/develop.html
  (FTOOLS developer's guide, slightly outdated).
  http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html
  (CFITSIO HTML guide) and
  http://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/cfitsio.html
  (CFITSIO manual for C programmer)
• Use the languages of ANSI C, ANSI C++ and FORTRAN 77 only.

• For scripts, use Perl 5.0 or Tcl/Tk 8.0.

• Comply with the standards of ANSI C, ANSI C++ or Fortran 77; do not use system-dependent extensions or features.

• For codes of mixing FORTRAN and C(i.e, C calls Fortran and Fortran calls C), use cfortran.h from CERN.

• For C or FORTRAN FTOOLS, use the cdummyftool and fdummyftool as templates. They can be found in src/examples/src in FTOOLS release.

• Subroutine or function name must be unique. This is a requirement of packaging the FTOOLS.

• Do not use the hard-coded ``scanf'' or command line options to read in the parameter in C or Fortran codes. Use XPI parameter interface. The routines are documented in pfile.h for the C FTOOLS.

• Do not directly write the message to stdout, use the fcecho or fcerr routines in cFTOOLS and xpi libraries. Put messages into the stdout directly will prevent the task from being used in a pipeline. In case the use of fcecho/fcerr is undesirable in the development environment, as a compromise, a centralized output routine should be used whenever ``printf'' is necessary.

• Provide the English translations for the important comments written in other languages.

• For handling of FITS files, use cfitsio. Do not try to read/write the files using specialized routines.

• In C FTOOLS, do not use the obsolete fcfitsio routines, which are the wrapped Fortran fitsio routines, which are the wrapped cfitsio routines.

• Before calling the cfitsio routine, make sure the error status is set to zero, otherwise, the routine returns immediately.

• After calling the cfitsio routine, make sure that the error status still stays at zero. If not, provide the error handling and return gracefully.

• CFITSIO routine ``ffopen'' automatically handles the filename parsing, file existing tests etc. Do not use any parsing routine or file open routines before ffopen. It can hinder the abilities of cfitsio to open a network file or compressed file.

• ``stderr'' should only be used to output critical error messages, since the presence of stderr messages are used by many scripts as part of the error handling mechanism. This restriction does not apply to ``stdout,'' but even this should be used with restraint.

• The Suzaku FTOOLS defines the chatter levels in the softwares from 0 (min) to 5 (max) as does the Swift package. Each chatter level displays 0: critical error messages only, 1: warning messages, 2 (default): useful information, 3: debugging level 1, 4: debugging level 2, 5: maximum debugging level.

• Finally, do not try to be fancy and clever, do not reinvent the wheel, and KISS (Keep It Simple, Stupid).

B.3 Parameters

It is well documented in URL: http://heasarc.gsfc.nasa.gov/ftools/others/pfiles.html

B.4 Makefiles

For FTOOLS development, ``hmake'' is used, which is a version of the ``make'' utility developed locally by the HEASARC. It is not necessary for the developers to write the ``hmake'' style make file. However, developers should provide a makefile in one of the popular Unix platforms (OSF, Solaris, SunOS, HPUX, Linux or SGI, Apple/Darwin). the software and understand the dependencies between modules.

B.5 Documents

The help file should be provided in a plain ASCII text file with the extension .txt and a file with the IRAF ``lroff'' format and extension .hlp. The ``lroff'' format is quite similar to the UNIX nroff/troff. You can find it in any .hlp files in FTOOLS distribution.

The help file should include the following sections:

• Name: Name plus a one sentence description.

• Usage: Synnopsis of the tool

• Description: Detailed description of the tools.

• Parameters: Descriptions for parameters.

• Examples: Examples of using the tool.

• Bugs: Known bugs or features of the tool.

• See Also: References to other relevant tools.

• Author: Authorship, credits and e-mail address for questions and bug reports
  (It is usually ftoolshelp@olegacy.gsfc.nasa.gov or the help desk of the mission).