casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
BinTable.h
Go to the documentation of this file.
00001 //# BinTable.h: The class BinaryTable converts a FITS binary table into an aips++ Table.
00002 //# Copyright (C) 1995,1996,1999
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: BinTable.h 18093 2004-11-30 17:51:10Z ddebonis $
00027 
00028 #ifndef FITS_BINTABLE_H
00029 #define FITS_BINTABLE_H
00030 
00031 
00032 //# Includes
00033 
00034 #include <casa/aips.h>
00035 #include <fits/FITS/hdu.h>
00036 #include <tables/Tables/Table.h>
00037 #include <tables/Tables/TableRecord.h>
00038 #include <casa/Containers/SimOrdMap.h>
00039 
00040 namespace casa { //# NAMESPACE CASA - BEGIN
00041 
00042 // <summary> 
00043 // BinaryTable is used to translate a FITS binary table to an aips++ Table.
00044 // </summary>
00045 
00046 // <use visibility=export>
00047 
00048 // <reviewed reviewer="" date="" tests="tBinTable">
00049 
00050 // <prerequisite>
00051 //# Classes you should understand before using this one.
00052 //   <li> FitsInput
00053 //   <li> HeaderDataUnit
00054 //   <li> BinaryTableExtension
00055 //   <li> Tables module
00056 // </prerequisite>
00057 //
00058 // <etymology>
00059 // BinaryTable inherits from the FITS BinaryTableExtension class and its
00060 // primary use is to convert that class to an aips++ Table.  This explains
00061 // it's use but not its name.  A better name should be found.
00062 // </etymology>
00063 //
00064 // <synopsis> 
00065 // The class starts with an already existing FitsInput object, which should
00066 // be set at a BinaryTableExtension HDU.   Member functions provide a TableDesc 
00067 // appropriate for the FITS data (to help in constructing an aips++ Table
00068 // compatible with the BinaryTableExtension), a Table containing the
00069 // current row of FITS data and a Table containing the next row of FITS data
00070 // (which can be used to step through the FitsInput, copying each row
00071 // using the RowCopier class), and a Table containin the entire FITS binary 
00072 // table from the current row to the end of the table.
00073 // </synopsis> 
00074 //
00075 // <motivation>
00076 // We need a way to get FITS data into aips++ Tables.
00077 // </motivation>
00078 //
00079 // <example>
00080 // open a FitsInput from a disk file, if the HDU is a BinaryTableExtension,
00081 // then instantiate a BinTable object and get the entire table.  A fair 
00082 // amount of error checking has been eliminated from this example.
00083 // <srcblock>
00084 //    FitsInput infits("myFITSFile", FITS::Disk);
00085 //    switch (infits.hdutype()) {
00086 //       case FITS::BinaryTableHDU:
00087 //          BinaryTable bintab(infits);
00088 //          Table tab = bintable.fullTable("myTable");
00089 //          break;
00090 //    }
00091 // </srcblock>
00092 // There would obviously be other cases to the switch to deal with any
00093 // other HDUs (e.g. skip them via infits.skip_hdu()).  The Table destructor
00094 // would write "myTable" to disk.
00095 // </example>
00096 //
00097 //
00098 // <todo asof="1995/04/10">
00099 //# A List of bugs, limitations, extensions or planned refinements.
00100 //   <li> It would be nice to construct this directly from the BinaryTableExtension.
00101 //   <li> When random access FITS becomes available, this needs to be able to deal with that.
00102 //   <li> A corresponding class is needed for conversion from aips++ Tables to FITS.
00103 //   <li> Throw exceptions rather than send messages to cout : however the entire FITS
00104 //        module behaves this way, so it should all remain consistent.
00105 //   <li> The following types of columns are not dealt with very well or at all
00106 //          (Bit, Byte, 0-length columns).
00107 //   <li> No attempt use any TDIM columns or keywords to shape arrays.
00108 // </todo>
00109 
00110 class BinaryTable : public BinaryTableExtension
00111 {
00112 public: 
00113 
00114     //   The only constructor is from a FitsInput, you can also optionally
00115     //   provide a FITS error handler.  If useMiriadSM is True, use
00116     //   the Miriad storage manager for all columns, otherwise AipsIO.
00117     //   If sdfits is True, all non-reserved and some reserved keyword
00118     //   are treated as if they were columns with constant values
00119     //   "virtual columns" in the sdfits convention.
00120     BinaryTable(FitsInput &,
00121                 FITSErrorHandler errhandler = FITSError::defaultHandler, 
00122                 Bool useMiriadSM = False, Bool sdfits = False);
00123 
00124     ~BinaryTable();
00125 
00126     // Get the full table, using the supplied arguments to construct the table.
00127     // The table will contain all data from the current row to the end of the
00128     // BinarTableExtension.If useMiriadSM is True, use the Miriad storage
00129     // manager for all columns, otherwise AipsIO.
00130     Table fullTable(const String& tabName, 
00131                     const Table::TableOption = Table::NewNoReplace,
00132                     Bool useMiriadSM = False);
00133 
00134     // This version  of the fullTable return a Memory based table
00135     // Its recommended if its being used as a temporary
00136 
00137     Table fullTable();
00138 
00139     //  Get an appropriate TableDesc (this is the same TableDesc used to 
00140     // construct any Table objects returned by this class.
00141     const TableDesc& getDescriptor();
00142 
00143     //  Return the Table keywords (this is the same TableRecord used
00144     //  in any Table objects returned by this class.
00145     TableRecord& getKeywords();
00146 
00147     // Get a Table with a single row, the current row of the FITS table.
00148     // The returned Table is a Scratch table.
00149     // The standard BinaryTableExtension manipulation functions are
00150     // available to position the FITS input at the desired location.
00151     const Table &thisRow();
00152 
00153     // Get a Table with a single row, the next row of the FITS table.
00154     // The returned Table is a Scratch table.
00155     // The FITS input is positioned to the next row and the values translated
00156     // and returned in a Table object.
00157     const Table &nextRow();
00158 
00159 
00160 private:
00161 
00162     //# Data Members
00163     // This is the Scratch table containing the current row
00164     Table* currRowTab;
00165     // The number of elements for each column of the BinaryTableExtension
00166     Int *nelem;
00167     // This is a map from column number to column name
00168     SimpleOrderedMap<Int, String> *colNames;
00169 
00170     TableRecord kwSet;
00171 
00172     // These are used by any VADesc columns
00173     FITS::ValueType *vatypes_p;
00174     void **vaptr_p;
00175     VADescFitsField *va_p;
00176     char *theheap_p;
00177 
00178     // this is the function that fills each row in as needed
00179     void fillRow();
00180 };
00181 
00182 
00183 } //# NAMESPACE CASA - END
00184 
00185 #endif