2.5 SELECTROWS - copy rows from one table to another

This routine copies selected rows from an input table into a new output FITS table. In this example all the rows in the input table that have a value of the DENSITY column less that 3.0 are copied to the output table. This program illustrates several generally useful techniques, including:

• how to locate the end of a FITS file
• how to create a table when the total number of rows in the table is not known until the table is completed
• how to efficiently copy entire rows from one table to another.

This program is continued over 2 pages in this cookbook.

1. The STATUS parameter must always be initialized. See the WRITEIMAGE program for a more detailed discussion.
2. FTGIOU allocates a logical unit number for use when opening a file. See the WRITEIMAGE program for a more detailed discussion.
3. The input FITS file is opened with READONLY access, and the output FITS file is opened with WRITE access.
4. FTMAHD moves to the 3rd HDU (or the 2nd extension) in the input FITS file.
5. This do-loop illustrates how to move to the last extension in any FITS file. The call to FTMRHD moves one extension at a time through the FITS file until an `End-of-file' status value (= 107) is returned.
6. After locating the end of the FITS file, it is necessary to reset the status value to zero and also clear the internal error message stack in FITSIO. The previous `End-of-file' error will have produced an unimportant message on the error stack which can be cleared with the call to the FTCMSG routine (which has no arguments).
7. FTCRHD appends a new empty HDU on the output file.
8. FTGHSP returns the number of existing keywords in the header as well as the amount of space currently available for more keywords.
9. This do-loop of calls to FTGREC and FTPREC copies all the keywords from the input to the output FITS file. Notice that the specified number of rows in the output table, as given by the NAXIS2 keyword, will be incorrect. This value will be modified later after it is known how many rows will be in the table, so it does not matter how many rows are specified initially.
10. FTRDEF forces FITSIO to scan the keywords that have just been written to the output FITS file to determine the structure of the table. This must be known before FITSIO can write any data to the table.

      subroutine selectrows

C     select rows from an input table and copy them to the output table

      integer status,inunit,outunit,readwrite,blocksize,hdutype
      integer nkeys,nspace,naxes(2),nfound,colnum,frow,felem
      integer noutrows,irow,temp(100),i
      real nullval,density(6)
      character infilename*40,outfilename*40,record*80
      logical exact,anynulls

 1    status=0
C     Names of the FITS files:
      infilename='ATESTFILEZ.FITS'
      outfilename='BTESTFILEZ.FITS'

C     Get  unused Logical Unit Numbers to use to open the FITS files
 2    call ftgiou(inunit,status)
      call ftgiou(outunit,status)

C     open the FITS files, with the appropriate read/write access
      readwrite=0
 3    call ftopen(inunit,infilename,readwrite,blocksize,status)
      readwrite=1
      call ftopen(outunit,outfilename,readwrite,blocksize,status)

C     move to the 3rd HDU in the input file (a binary table in this case)
 4    call ftmahd(inunit,3,hdutype,status)

C     move to the last extension in the output file
 5    do while (status .eq. 0)
          call ftmrhd(outunit,1,hdutype,status)
      end do

      if (status .eq. 107)then
C         this is normal; it just means we hit the end of file
          status=0
 6        call ftcmsg
      end if

C     create a new empty extension in the output file
 7    call ftcrhd(outunit,status)

C     find the number of keywords in the input table header
 8    call ftghsp(inunit,nkeys,nspace,status)

C     copy all the keywords from the input to the output extension
 9    do i=1,nkeys
          call ftgrec(inunit,i,record,status)
          call ftprec(outunit,record,status)
      end do

C     force FITSIO to read the output file keywords to define the data structure
 10   call ftrdef(outunit,status)

SELECTROWS - (continued)

1. FTGKNJ is used to get the value of the NAXIS1 and NAXIS2 keywords, which define the width of the table in bytes, and the number of rows in the table.
2. FTGCNO gets the column number of the `DENSITY' column; the column number is needed when reading the data in the column. The EXACT parameter determines whether or not the match to the column names will be case sensitive.
3. FTGCVE reads all 6 rows of data in the `DENSITY' column. The number of rows in the table is given by NAXES(2). Any null values in the table will be returned with the corresponding value set to -99 (= the value of NULLVAL). The ANYNULLS parameter will be set to TRUE if any null values were found while reading the data values in the table.
4. FTGTBB and FTPTBB are low-level routines to read and write, respectively, a specified number of bytes in the table, starting at the specified row number and beginning byte within the row. These routines do not do any interpretation of the bytes, and simply pass them to or from the FITS file without any modification. This is a faster way of transferring large chunks of data from one FITS file to another, than reading and then writing each column of data individually. In this case an entire row of bytes (the row length is specified by the naxes(1) parameter) is transferred. The datatype of the buffer array (TEMP in this case) is immaterial so long as it is declared large enough to hold the required number of bytes.
5. After all the rows have been written to the output table, the FTMKYJ routine is used to overwrite the NAXIS2 keyword value with the correct number of rows. Specifying `&' for the comment string tells FITSIO to keep the current comment string in the keyword and only modify the value. Because the total number of rows in the table was unknown when the table was first created, any value (including 0) could have been used for the initial NAXIS2 keyword value.
6. The FITS file must always be closed before exiting the program.
7. Any unit numbers allocated with FTGIOU must be freed with FTFIOU. Giving -1 for the value of the first argument causes all previously allocated unit numbers to be released.
8. PRINTERROR is a general routine to print out error messages and is described later in the Utilities section of this cookbook.

C     get the width of the table (in bytes) and the number of rows
 11   call ftgknj(inunit,'NAXIS',1,2,naxes,nfound,status)

C     find which column contains the DENSITY values
      exact=.false.
 12   call ftgcno(inunit,exact,'DENSITY',colnum,status)

C     read the DENSITY column values
      frow=1
      felem=1
      nullval=-99.
 13   call ftgcve(inunit,colnum,frow,felem,naxes(2),nullval,
     &            density,anynulls,status)

C     If the density is less than 3.0, copy the row to the output table
      noutrows=0
 14   do irow=1,naxes(2)
          if (density(irow) .lt. 3.0)then
              noutrows=noutrows+1
 15           call ftgtbb(inunit,irow,1,naxes(1),temp,status)
              call ftptbb(outunit,noutrows,1,naxes(1),temp,status)
          end if
      end do

C     update the NAXIS2 keyword with the correct no. of rows in the output file
 16   call ftmkyj(outunit,'NAXIS2',noutrows,'&',status)

C     close the FITS file and free the unit numbers
 17   call ftclos(inunit, status)
      call ftclos(outunit, status)
      call ftfiou(-1, status)

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