FXBWRITM

       Write multiple columns/rows to a disk FITS binary table file.

       A call to FXBWRITM will write multiple rows and multiple
       columns to a binary table in a single procedure call.  Up to
       fifty columns may be read in a single pass.  The file should
       have already been opened with FXBOPEN (with write access) or
       FXBCREATE.  FXBWRITM optimizes writing multiple columns by
       first writing a large chunk of data to the FITS file all at
       once.  FXBWRITM cannot write variable-length arrays; use
       FXBWRITE instead.
       The number of columns is limited to 50 if data are passed by
       positional argument.  However, this limitation can be overcome
       by passing pointers to FXBWRITM.  The user should set the PASS_METHOD
       keyword to 'POINTER'  as appropriate, and  an array of pointers to
       the data in the POINTERS keyword.  The user is responsible for freeing
        the pointers.

       FXBWRITM, UNIT, COL, D0, D1, D2, ..., [ ROW= , PASS_METHOD, NANVALUE=
                               POINTERS=,  BUFFERSIZE= ]

       UNIT    = Logical unit number corresponding to the file containing the
                 binary table.
       D0,..D49= An IDL data array to be written to the file, one for
                 each column.      These parameters will be igonred if data
                 is passed through the POINTERS keyword.
       COL     = Column in the binary table to place data in.   May be either
                 a list of column numbers where the first column is one, or
                 a string list of column names.

       ROW     = Either row number in the binary table to write data to,
                 starting from row one, or a two element array containing a
                 range of row numbers to write.  If not passed, then
                 the entire column is written.
       NANVALUE= Value signalling data dropout.  All points corresponding to
                 this value are set to be IEEE NaN (not-a-number).  Ignored
                 unless DATA is of type float, double-precision or complex.
       PASS_METHOD = A scalar string indicating method of passing
                 data to FXBWRITM.  One of 'ARGUMENT' (indicating
                 pass by positional argument),  or'POINTER' (indicating
                 passing an array of pointers by the POINTERS
                 keyword).
                 Default:  'ARGUMENT'
       POINTERS = If PASS_METHOD is 'POINTER' then the user must pass
                 an array of IDL pointers to this keyword, one for
                 each column.    Ultimately the user is responsible for
                 deallocating pointers.
       BUFFERSIZE = Data are transferred in chunks to conserve
                 memory.  This is the size in bytes of each chunk.
                 If a value of zero is given, then all of the data
                 are transferred in one pass.  Default is 32768 (32
                 kB).

       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 = ''
                       FXBWRITE, ERRMSG=ERRMSG, ...
                       IF ERRMSG NE '' THEN ...
       WARNMSG = Messages which are considered to be non-fatal
                 "warnings" are returned in this  output string.
       STATUS  = An output array containing the status for each
                 read, 1 meaning success and 0 meaning failure.

       HOST_TO_IEEE, PRODUCT()

      Write a binary table 'sample.fits' giving 43 X,Y positions and a
      21 x 21 PSF at each position:
      (1) First, create sample values
      x = findgen(43) & y = findgen(43)+1 & psf = randomn(seed,21,21,43)
      (2) Create primary header, write it to disk, and make extension header
      fxhmake,header,/initialize,/extend,/date
      fxwrite,'sample.fits',header
      fxbhmake,header,43,'TESTEXT','Test binary table extension'
      (3) Fill extension header with desired column names
      fxbaddcol,1,header,x[0],'X'             ;Use first element in each array
      fxbaddcol,2,header,y[0],'Y'             ;to determine column properties
      fxbaddcol,3,header,psf[*,*,0],'PSF'
      (4) Write extension header to FITS file
      fxbcreate,unit,'sample.fits',header
      (5) Use FXBWRITM to write all data to the extension in a single call
      fxbwritm,unit,['X','Y','PSF'], x, y, psf
      fxbfinish,unit                 ;Close the file

       Uses common block FXBINTABLE--see "fxbintable.pro" for more
       information.

       The binary table file must have been opened with FXBCREATE or
       FXBOPEN (with write access).
       The data must be consistent with the column definition in the binary
       table header.
       The row number must be consistent with the number of rows stored in the
       binary table header.
       A PASS_METHOD of POINTER does not use the EXECUTE() statement and can be
       used with the IDL Virtual Machine.   However, the EXECUTE() statement is
       used when the PASS_METHOD is by arguments.

       Data Handling, I/O, FITS, Generic.

       C. Markwardt, based on FXBWRITE and FXBREADM (ver 1), Jan 1999

       Craig Markwardt, GSFC, January 1999.

       Version 1, Craig Markwardt, GSFC 18 January 1999.
               Documented this routine, 18 January 1999.
       C. Markwardt, added ability to pass by handle or pointer.
               Some bug fixes, 20 July 2001
       W. Landsman/B.Schulz  Allow more than 50 arguments when using pointers
       W. Landsman  Remove pre-V5.0 HANDLE options      July 2004
       W. Landsman Remove EXECUTE() call with POINTERS   May 2005

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]