2.1 WRITEIMAGE - write a FITS 2-D image

This routine creates a new FITS 2-dimensional image.

1. The STATUS parameter must be initialized before using FITSIO. A positive value of STATUS is returned whenever a serious error occurs. FITSIO uses an `inherited status' convention, which means that if a subroutine is called with a positive input value of STATUS, then the subroutine will exit immediately, preserving the status value. Thus if one passes the status value returned from each FITSIO subroutine as input to the next FITSIO subroutine, then whenever an error occurs all further FITSIO processing will cease. This convention simplifies the error checking in an application program because it is not necessary to check the returned status value after every FITSIO call. The status values are distinctive, so it is usually possible to determine which FITSIO subroutine originally returned the non-zero error status. See the PRINTERROR subroutine for further discussion of the error status values and the related error message stack in FITSIO. For simplicity, this program only checks the status value at the end of the program, but it is usually better practice to check the status value more frequently.

2. The DELETEFILE routine (described later in the Utilities section of the Cookbook) simply deletes the FITS file if it already exists so that we can then regenerate it.

3. FTGIOU returns an unused Fortran logical unit number for use when opening a file. This routine must only be used if ALL unit numbers used by the program are allocated though it, because it will have no knowledge of any other unit numbers that the program may have otherwise used. Use of this routine is not required, and programmers may use some other technique to allocate unit numbers in their programs if preferred.

4. FTINIT creates an new empty FITS file with the specified name and blocksize. Normally the default blocksize of 1 (= 2880 bytes) should be used.

5. FTPHPR writes all the required header keywords for the primary array. BITPIX = 16 means that the image pixels will consist of 16-bit integers. The size of the image is given by the NAXES values. The EXTEND = TRUE parameter indicates that the FITS file may contain extensions following the primary array.

6. FTPPRJ writes the image pixel values to the FITS primary array. The last letter of the subroutine name defines the datatype of the array argument; in this case the 'J' indicates that the array has an integer*4 datatype.
7. FTPKYJ illustrates how to write an optional keyword to the header. In this case, the EXPOSURE keyword has a value of 1500 with a comment string = `Total Exposure Time'.
8. The FITS file must always be closed before exiting the program. Any unit numbers allocated with FTGIOU must be freed with FTFIOU.
9. PRINTERROR is a general routine to print out error messages and is described later in the Utilities section of this cookbook.

      subroutine writeimage

C     Create a FITS primary array containing a 2-D image

      integer status,unit,blocksize,bitpix,naxis,naxes(2)
      integer i,j,group,fpixel,nelements,array(300,200)
      character filename*80
      logical simple,extend

 1    status=0
C     Name of the FITS file to be created:
      filename='ATESTFILEZ.FITS'

C     Delete the file if it already exists, so we can then recreate it
 2    call deletefile(filename,status)

C     Get an unused Logical Unit Number to use to open the FITS file
 3    call ftgiou(unit,status)

C     create the new empty FITS file
      blocksize=1
 4    call ftinit(unit,filename,blocksize,status)

C     initialize parameters about the FITS image (300 x 200 16-bit integers)
      simple=.true.
      bitpix=16
      naxis=2
      naxes(1)=300
      naxes(2)=200
      extend=.true.

C     write the required header keywords
 5    call ftphpr(unit,simple,bitpix,naxis,naxes,0,1,extend,status)

C     initialize the values in the image with a linear ramp function
      do j=1,naxes(2)
          do i=1,naxes(1)
              array(i,j)=i+j
          end do
      end do

C     write the array to the FITS file
      group=1
      fpixel=1
      nelements=naxes(1)*naxes(2)
 6    call ftpprj(unit,group,fpixel,nelements,array,status)

C     write another optional keyword to the header
 7    call ftpkyj(unit,'EXPOSURE',1500,'Total Exposure Time',status)

C     close the file and free the unit number
 8    call ftclos(unit, status)
      call ftfiou(unit, status)

C     check for any error, and if so print out error messages
 9    if (status .gt. 0)call printerror(status)
      end