Name

---

        FXBGROW

Purpose

---

      Increase the number of rows in a binary table.

Explanation

---

      Call FXBGROW to increase the size of an already-existing FITS
      binary table. The number of rows increases to NROWS; however
      the table cannot shrink by this operation. This procedure is
      useful when a table with an unknown number of rows must be
      created. The caller would then call FXBCREATE to construct a
      table of some base size, and follow with calls to FXBGROW to
      lengthen the table as needed. The extension being enlarged
      need not be the last extension in the file. If subsequent
      extensions exist in the file, they will be shifted properly.

Calling Sequence

---

      FXBGROW, UNIT, HEADER, NROWS[, ERRMSG= , NOZERO= , BUFFERSIZE= ]

Input Parameters

---

      UNIT = Logical unit number of an already-opened file.
      HEADER = String array containing the FITS binary table extension
                  header. The header is modified in place.
      NROWS = New number of rows, always more than the previous
                  number.

Optional Input Keywords

---

      NOZERO = when set, FXBGROW will not zero-pad the new data if
                  it doesn't have to.
      ERRMSG = If defined and passed, then any error messages will be
                  returned to the user in this parameter rather than
                  depending on the MESSAGE routine in IDL. If no errors are
                  encountered, then a null string is returned. In order to
                  use this feature, ERRMSG must be defined first, e.g.
                      ERRMSG = ''
                      FXBGROW, ERRMSG=ERRMSG, ...
                      IF ERRMSG NE '' THEN ...
      BUFFERSIZE = Size in bytes for intermediate data transfers
                    (default 32768)

Calls

---

      FXADDPAR, FXHREAD, BLKSHIFT
  Common :
      Uses common block FXBINTABLE--see "fxbintable.pro" for more
      information.

Restrictions

---

      The file must be open with write permission.
      The binary table extension in question must already by written
      to the file (using FXBCREATE).
      A table can never shrink via this operation.

Side Effects

---

      The FITS file will grow in size, and heap areas are
      preserved by moving them to the end of the file.
      The header is modified to reflect the new number of rows.

Category

---

      Data Handling, I/O, FITS, Generic.
      Initially written, C. Markwardt, GSFC, Nov 1998
      Added ability to enlarge arbitrary extensions and tables with
        variable sized rows, not just the last extension in a file,
        CM, April 2000
      Fix bug in the zeroing of the output file, C. Markwardt, April 2005