idlastro / FITS Binary Table Extensions I/O: FXBWRITM

[Source code]

NAME
FXBWRITM
PURPOSE
Write multiple columns/rows to a disk FITS binary table file.
EXPLANATION
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.
CALLING SEQUENCE
FXBWRITM, UNIT, COL, D0, D1, D2, ..., [ ROW= , PASS_METHOD, NANVALUE=
                       POINTERS=,  BUFFERSIZE= ]
INPUT PARAMETERS
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.  
OPTIONAL INPUT KEYWORDS
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.
OSCALE = If set, then TSCAL/TZERO values are ignored, and data is 
         written exactly as supplied. 
ASS_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'
OINTERS = 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.
UFFERSIZE = 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).
OPTIONAL OUTPUT KEYWORDS
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 ...
ARNMSG = Messages which are considered to be non-fatal
         "warnings" are returned in this  output string.
TATUS  = An output array containing the status for each
         read, 1 meaning success and 0 meaning failure.
PROCEDURE CALLS
None.
EXAMPLE
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
COMMON BLOCKS
Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
RESTRICTIONS
The binary table file must have been opened with FXBCREATE or
XBOPEN (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.
 PASS_METHOD of POINTER does not use the EXECUTE() statement and can be
sed with the IDL Virtual Machine.   However, the EXECUTE() statement is
sed when the PASS_METHOD is by arguments.      
CATEGORY
Data Handling, I/O, FITS, Generic.
PREVIOUS HISTORY
C. Markwardt, based on FXBWRITE and FXBREADM (ver 1), Jan 1999
WRITTEN
Craig Markwardt, GSFC, January 1999.
MODIFIED
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
C. Markwardt Allow the output table to have TSCAL/TZERO
   keyword values; if that is the case, then the passed values
   will be quantized to match those scale factors before being
   written.  Sep 2007
E. Hivon: write 64bit integer and double precision columns, Mar 2008
C. Markwardt Allow unsigned integers, which have special
   TSCAL/TZERO values.  Feb 2009
C. Markwardt Add support for files larger than 2 GB, 2012-04-17