FXBWRITM
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.
NOSCALE = If set, then TSCAL/TZERO values are ignored, and data is
written exactly as supplied.
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).
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 ...
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.
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
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.
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 precison 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