Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Libraries  >  ASTROLIB  >  FXBWRITM

FXBWRITM

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 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



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us