casacore
Table.h
Go to the documentation of this file.
1 //# Table.h: Main interface classes to tables
2 //# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,2001,2002,2003
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have receied a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef TABLES_TABLE_H
29 #define TABLES_TABLE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/Tables/BaseTable.h>
35 #include <casacore/tables/Tables/TableLock.h>
36 #include <casacore/tables/Tables/RowNumbers.h>
37 #include <casacore/tables/DataMan/TSMOption.h>
38 #include <casacore/casa/Arrays/ArrayFwd.h>
39 #include <casacore/casa/Utilities/DataType.h>
40 #include <casacore/casa/Utilities/Sort.h>
41 
42 #ifdef HAVE_MPI
43 #include <mpi.h>
44 #endif
45 
46 namespace casacore { //# NAMESPACE CASACORE - BEGIN
47 
48 //# Forward Declarations
49 class SetupNewTable;
50 class TableDesc;
51 class ColumnDesc;
52 class TableRecord;
53 class Record;
54 class TableExprNode;
55 class DataManager;
56 class IPosition;
57 template<class T> class Block;
58 template<class T> class CountedPtr;
59 
60 
61 // <summary>
62 // Main interface class to a read/write table
63 // </summary>
64 
65 // <use visibility=export>
66 
67 // <reviewed reviewer="TPPR" date="08.11.94" tests="tTable.cc">
68 // </reviewed>
69 
70 // <prerequisite>
71 //# Classes you should understand before using this one.
72 // <li> <linkto class=SetupNewTable>SetupNewTable</linkto>
73 // <li> <linkto class=TableDesc>TableDesc</linkto>
74 // <li> <linkto class=TableColumn>TableColumn</linkto>
75 // <li> <linkto class=ScalarColumn>ScalarColumn</linkto>
76 // <li> <linkto class=ArrayColumn>ArrayColum</linkto>
77 // <li> <linkto class=TableLock>TableLock</linkto>
78 // </prerequisite>
79 
80 // <synopsis>
81 // Class Table can be used to create a new table or to access an existing
82 // table in read/write or readonly mode.
83 //
84 // To access the data in a Table, objects have to be created
85 // to access the columns. These objects are TableColumn,
86 // ScalarColumn<T> and ArrayColumn<T>, which can be created
87 // via their constructors.
88 // Furthermore the Table has a TableRecord object for holding keywords
89 // which can be read or written using the appropriate functions.
90 //
91 // To open an existing table, a simple Table constructor can be used.
92 // The possible construct options are:
93 // <ul>
94 // <li> Old readonly table (default option)
95 // <li> Update update existing table
96 // <li> Delete delete table
97 // </ul>
98 // The function <src>openTable</src> makes it possible to open a subtable
99 // of a table in a convenient way, even if the table is only a reference
100 // to another table (e.g., a selection).
101 //
102 // Creating a new table requires more work, because columns have
103 // to be bound to storage managers or virtual column engines.
104 // Class SetupNewTable is needed for this purpose. The Tables module
105 // documentation explains in more detail how to create a table.
106 // When creating a table, it can be specified which endian format to use.
107 // By default it uses the format specified in the aipsrc variable
108 // <code>table.endianformat</code> which defaults to
109 // <code>Table::LocalEndian</code> (thus the endian format of the
110 // machine being used).
111 //
112 // It is possible to create a Table object as the virtual concatenation of
113 // Tables having identical table descriptions. Subtables of those tables
114 // can optionally be concatenated as well.
115 // E.g. if a MeasurementSet is partioned in time, this mechanism makes it
116 // possible to view it as a single table. Furthermore, a subtable like
117 // SYSCAL can be concatenated as well, while the other subtables are identical
118 // in all partitions and are taken from the first table only.
119 //
120 // Other Table objects can be created from a Table using
121 // the select, project and sort functions. The result in so-called
122 // reference tables. In this way a subset of a table can be created and
123 // can be read/written in the same way as a normal Table. Writing has the
124 // effect that the underlying table gets written.
125 // </synopsis>
126 
127 // <example>
128 // <srcblock>
129 // // Open a table to be updated.
130 // Table myTable ("theTable", Table::Update);
131 // // Write the column containing the scalar RA.
132 // ScalarColumn<double> raColumn(myTable, "RA");
133 // rownr_t nrrow = myTable.nrow();
134 // for (rownr_t i=0; i<nrrow; i++) {
135 // raColumn.put (i, i+10); // Put value i+10 into row i
136 // }
137 // </srcblock>
138 // </example>
139 
140 // <motivation>
141 // Table is the envelope for the underlying counted referenced
142 // classes derived from BaseTable. In this way no pointers have
143 // to be used to get polymorphism.
144 // </motivation>
145 
146 // <todo asof="$DATE:$">
147 //# A List of bugs, limitations, extensions or planned refinements.
148 // <li> add, remove, rename columns.
149 // <li> virtual concatenation of tables (if still necessary).
150 // <li> maybe an isAttached function.
151 // </todo>
152 
153 
154 class Table
155 {
156 friend class TableColumn;
157 friend class BaseTable;
158 friend class PlainTable;
159 friend class MemoryTable;
160 friend class RefTable;
161 friend class ConcatTable;
162 friend class TableIterator;
163 friend class RODataManAccessor;
164 friend class TableExprNode;
165 friend class TableExprNodeRep;
166 
167 public:
168  // Define the possible options how a table can be opened.
169  enum TableOption {
170  // existing table
171  Old=1,
172  // create table
174  // create table (may not exist)
176  // new table, which gets marked for delete
178  // update existing table
180  // delete table
181  Delete
182  };
183 
184  // Define the possible table types.
185  enum TableType {
186  // plain table (stored on disk)
188  // table held in memory
189  Memory
190  };
191 
192  // Define the possible endian formats in which table data can be stored.
194  // store table data in big endian (e.g. SUN) format
196  // store table data in little endian (e.g. Intel) format
198  // store data in the endian format of the machine used
200  // use endian format defined in the aipsrc variable table.endianformat
201  // If undefined, it defaults to LocalEndian.
203  };
204 
205 
206  // Define the signature of the function being called when the state
207  // of a scratch table changes (i.e. created, closed, renamed,
208  // (un)markForDelete).
209  // <br>- <src>isScratch=True</src> indicates that a scratch table
210  // is created (<src>oldName</src> is empty) or renamed
211  // (<src>oldName</src> is not empty).
212  // <br>- <src>isScratch=False</src> indicates that a scratch table
213  // with name <src>name</src> is not scratch anymore (because it is
214  // closed or because its state is set to non-scratch).
215  typedef void ScratchCallback (const String& name, Bool isScratch,
216  const String& oldName);
217 
218  // Set the pointer to the ScratchCallback function.
219  // It returns the current value of the pointer.
220  // This function is called when changing the state of a table
221  // (i.e. create, close, rename, (un)markForDelete).
223 
224 
225  // Create a null Table object (i.e. a NullTable is attached).
226  // The sole purpose of this constructor is to allow construction
227  // of an array of Table objects.
228  // The assignment operator can be used to make a null object
229  // reference a proper table.
230  Table();
231 
232  // Create a table object for an existing table.
233  // The only options allowed are Old, Update, and Delete.
234  // If the name of a table description is given, it is checked
235  // if the table has that description.
236  // Locking options can be given (see class
237  // <linkto class=TableLock>TableLock</linkto>.
238  // If the table with this name was already opened in this process,
239  // the existing and new locking options are merged using
240  // <src>TableLock::merge</src>.
241  // The default locking mechanism is DefaultLocking. If the table
242  // is not open yet, it comes to AutoLocking with an inspection interval
243  // of 5 seconds. Otherwise DefaultLocking keeps the locking options
244  // of the already open table.
245  // <group>
247  const TSMOption& = TSMOption());
249  TableOption = Table::Old, const TSMOption& = TSMOption());
250  Table (const String& tableName, const String& tableDescName,
251  TableOption = Table::Old, const TSMOption& = TSMOption());
252  Table (const String& tableName, const String& tableDescName,
254  const TSMOption& = TSMOption());
255  // </group>
256 
257  // Make a new empty table (plain (scratch) or memory type).
258  // Columns should be added to make it a real one.
259  // Note that the endian format is only relevant for plain tables.
261  const TSMOption& = TSMOption());
262 
263  // Make a table object for a new table, which can thereafter be used
264  // for reading and writing.
265  // If there are unbound columns, default storage managers an/ord virtual
266  // column engines will be created and bound to those columns.
267  // Create the table with the given nr of rows. If a storage manager
268  // is used which does not allow addition of rows, the number of rows
269  // in the table must already be given here.
270  // Optionally the rows can be initialized with the default
271  // values as defined in the column descriptions.
272  // Locking options can be given (see class
273  // <linkto class=TableLock>TableLock</linkto>.
274  // The default locking mechanism is AutoLocking with a default
275  // inspection interval of 5 seconds.
276  // <br>The data will be stored in the given endian format.
277  // <group>
278  explicit Table (SetupNewTable&, rownr_t nrrow = 0, Bool initialize = False,
280  const TSMOption& = TSMOption());
282  rownr_t nrrow = 0, Bool initialize = False,
285  rownr_t nrrow = 0, Bool initialize = False,
288  rownr_t nrrow = 0, Bool initialize = False,
291  rownr_t nrrow = 0, Bool initialize = False,
293 #ifdef HAVE_MPI
294  explicit Table (MPI_Comm mpiComm, TableType, EndianFormat = Table::AipsrcEndian,
295  const TSMOption& = TSMOption());
296  explicit Table (MPI_Comm mpiComm, SetupNewTable&, rownr_t nrrow = 0,
297  Bool initialize = False,
299  const TSMOption& = TSMOption());
300  Table (MPI_Comm mpiComm, SetupNewTable&, TableType,
301  rownr_t nrrow = 0, Bool initialize = False,
303  Table (MPI_Comm mpiComm, SetupNewTable&, TableType, const TableLock& lockOptions,
304  rownr_t nrrow = 0, Bool initialize = False,
307  rownr_t nrrow = 0, Bool initialize = False,
309  Table (MPI_Comm mpiComm, SetupNewTable&, const TableLock& lockOptions,
310  rownr_t nrrow = 0, Bool initialize = False,
312 #endif
313  // </group>
314 
315  // Create a table object as the virtual concatenation of
316  // one or more of existing tables. The descriptions of all those tables
317  // must be exactly the same.
318  // <br>The keywordset of the virtual table is the set of the first table
319  // including its subtables. However, it is possible to specify the names
320  // of the subtables that have to be concantenated as well.
321  // <br>In this way a concatenation of multiple MS-s can be made, where it
322  // can be specified that, say, the SYSCAL table has to be concatenated too.
323  // <br> When a concatenated table is written and if a non-empty
324  // <src>subDirName</src> is given, the tables to be concatenated will be
325  // moved to that subdirectory in the directory of the concatenated table.
326  // This option is mainly used by the MSS structure used in CASA.
327  // <br>
328  // The only open options allowed are Old and Update.
329  // Locking options can be given (see class
330  // <linkto class=TableLock>TableLock</linkto>.
331  // They apply to all underlying tables.
332  // If a table was already opened in this process,
333  // the existing and new locking options are merged using
334  // <src>TableLock::merge</src>.
335  // The default locking mechanism is DefaultLocking. If the table
336  // is not open yet, it comes to AutoLocking with an inspection interval
337  // of 5 seconds. Otherwise DefaultLocking keeps the locking options
338  // of the already open table.
339  // <group>
340  explicit Table (const Block<Table>& tables,
341  const Block<String>& subTables = Block<String>(),
342  const String& subDirName = String());
343  explicit Table (const Block<String>& tableNames,
344  const Block<String>& subTables = Block<String>(),
346  const String& subDirName = String());
347  Table (const Block<String>& tableNames,
348  const Block<String>& subTables,
349  const TableLock& lockOptions,
350  TableOption = Table::Old, const TSMOption& = TSMOption());
351  // </group>
352 
353  // Copy constructor (reference semantics).
354  Table (const Table&);
355 
356  // The destructor flushes (i.e. writes) the table if it is opened
357  // for output and not marked for delete.
358  // It will flush if the destructor is called due to an exception,
359  // because the Table object may not be correct.
360  // Of course, in that case the flush function could be called explicitly.
361  // <br>It is virtual, so an object of a derived class like MeasurementSet
362  // is destructed correctly through a Table pointer.
363  virtual ~Table();
364 
365  // Assignment (reference semantics).
367 
368  // Try to open a table. The name of the table can contain subtable names
369  // using :: as separator. In this way it is possible to directly open a
370  // subtable of a RefTable or ConcatTable, which is not possible if the
371  // table name is specified with slashes.
372  // <br>The open process is as follows:
373  // <ul>
374  // <li> It is tried to open the table with the given name.
375  // <li> If unsuccessful, the name is split into its parts using ::
376  // The first part is the main table which will be opened temporarily.
377  // The other parts are the successive subtable names (usually one).
378  // Each subtable is opened by looking it up in the keywords of the
379  // table above. The final subtable is returned.
380  // </ul>
381  // <br>An exception is thrown if the table cannot be opened.
382  // <example>
383  // Open the ANTENNA subtable of an MS which might be a selection of
384  // a real MS.
385  // <srcblock>
386  // Table tab(Table::openTable ("sel.ms::ANTENNA");
387  // </srcblock>
388  // </example>
389  // <group>
390  static Table openTable (const String& tableName,
392  const TSMOption& = TSMOption());
393  static Table openTable (const String& tableName,
394  const TableLock& lockOptions,
396  const TSMOption& = TSMOption());
397  // </group>
398 
399  // Get the names of the tables this table consists of.
400  // For a plain table it returns its name,
401  // for a RefTable the name of the parent, and
402  // for a ConcatTable the names of all its parts.
403  // <br>Note that a part can be any type of table (e.g. a ConcatTable).
404  // The recursive switch tells how to deal with that.
406 
407  // Is the root table of this table the same as that of the other one?
408  Bool isSameRoot (const Table& other) const;
409 
410  // Can the table be deleted?
411  // If true, function deleteTable can safely be called.
412  // If not, message contains the reason why (e.g. 'table is not writable').
413  // It checks if the table is writable, is not open in this process
414  // and is not open in another process.
415  // <br>If <src>checkSubTables</src> is set, it also checks if
416  // a subtable is not open in another process.
417  // <group>
419  Bool checkSubTables=False);
420  static Bool canDeleteTable (String& message, const String& tableName,
421  Bool checkSubTables=False);
422  // </group>
423 
424  // Delete the table.
425  // An exception is thrown if the table cannot be deleted because
426  // its is not writable or because it is still open in this or
427  // another process.
428  // <br>If <src>checkSubTables</src> is set, it is also checked if
429  // a subtable is used in another process.
430  static void deleteTable (const String& tableName,
431  Bool checkSubTables=False);
432 
433  // Close all open subtables.
434  void closeSubTables() const;
435 
436  // Try to reopen the table for read/write access.
437  // An exception is thrown if the table is not writable.
438  // Nothing is done if the table is already open for read/write.
439  void reopenRW();
440 
441  // Get the endian format in which the table is stored.
443 
444  // Get the storage option used for the table.
445  const StorageOption& storageOption() const;
446 
447  // Is the table used (i.e. open) in this process.
448  static Bool isOpened (const String& tableName);
449 
450  // Is the table used (i.e. open) in another process.
451  // If <src>checkSubTables</src> is set, it is also checked if
452  // a subtable is used in another process.
453  Bool isMultiUsed (Bool checkSubTables=False) const;
454 
455  // Get the locking options.
456  const TableLock& lockOptions() const;
457 
458  // Has this process the read or write lock, thus can the table
459  // be read or written safely?
460  // <group>
462  Bool hasLock (Bool write) const;
463  // </group>
464 
465  // Try to lock the table for read or write access (default is write).
466  // The number of attempts (default = forever) can be specified when
467  // acquiring the lock does not succeed immediately. If nattempts>1,
468  // the system waits 1 second between each attempt, so nattempts
469  // is more or less equal to a wait period in seconds.
470  // The return value is false if acquiring the lock failed.
471  // If <src>PermanentLocking</src> is in effect, a lock is already
472  // present, so nothing will be done.
473  // <group>
475  Bool lock (Bool write, uInt nattempts = 0);
476  // </group>
477 
478  // Unlock the table. This will also synchronize the table data,
479  // thus force the data to be written to disk.
480  // If <src>PermanentLocking</src> is in effect, nothing will be done.
481  void unlock();
482 
483  // Determine the number of locked tables opened with the AutoLock option
484  // (Locked table means locked for read and/or write).
485  static uInt nAutoLocks();
486 
487  // Unlock locked tables opened with the AutoLock option.
488  // If <src>all=True</src> all such tables will be unlocked.
489  // If <src>all=False</src> only tables requested by another process
490  // will be unlocked.
492 
493  // Get the names of tables locked in this process.
494  // By default all locked tables are given (note that a write lock
495  // implies a read lock), but it is possible to select on lock type
496  // FileLocker::Write and on option (TableLock::AutoLocking,
497  // TableLock::ReadLocking, or TableLock::PermanentLocking).
499  int lockOption=-1);
500 
501  // Determine if column or keyword table data have changed
502  // (or is being changed) since the last time this function was called.
504 
505  // Flush the table, i.e. write out the buffers. If <src>sync=True</src>,
506  // it is ensured that all data are physically written to disk.
507  // Nothing will be done if the table is not writable.
508  // At any time a flush can be executed, even if the table is marked
509  // for delete.
510  // If the table is marked for delete, the destructor will remove
511  // files written by intermediate flushes.
512  // Note that if necessary the destructor will do an implicit flush,
513  // unless it is executed due to an exception.
514  // <br>If <src>fsync=True</src> the file contents are fsync-ed to disk,
515  // thus ensured that the system buffers are actually written to disk.
516  // <br>If <src>recursive=True</src> all subtables are flushed too.
517  void flush (Bool fsync=False, Bool recursive=False);
518 
519  // Resynchronize the Table object with the table file.
520  // This function is only useful if no read-locking is used, ie.
521  // if the table lock option is UserNoReadLocking or AutoNoReadLocking.
522  // In that cases the table system does not acquire a read-lock, thus
523  // does not synchronize itself automatically.
524  void resync();
525 
526  // Test if the object is null, i.e. does not reference a proper table.
527  // This is the case if the default constructor is used.
528  Bool isNull() const
529  { return (baseTabPtr_p == 0 ? True : baseTabPtr_p->isNull()); }
530 
531  // Throw an exception if the object is null, i.e.
532  // if function isNull() is True.
533  void throwIfNull() const;
534 
535  // Test if the given data type is native to the table system.
536  // If not, a virtual column engine is needed to store data with that type.
537  // With the function DataType::whatType it can be used in a templated
538  // function like:
539  // <srcblock>
540  // if (Table::isNativeDataType (whatType(static_cast<T*>(0)))) {
541  // </srcblock>
542  static Bool isNativeDataType (DataType dtype);
543 
544  // Make the table file name.
545  static String fileName (const String& tableName);
546 
547  // Test if a table with the given name exists and is readable.
548  // If not, an exception is thrown if <src>throwIf==True</src>.
549  static Bool isReadable (const String& tableName, bool throwIf=False);
550 
551  // Return the layout of a table (i.e. description and #rows).
552  // This function has the advantage that only the minimal amount of
553  // information required is read from the table, thus it is much
554  // faster than a normal table open.
555  // <br> The number of rows is returned. The description of the table
556  // is stored in desc (its contents will be overwritten).
557  // <br> An exception is thrown if the table does not exist.
558  static rownr_t getLayout (TableDesc& desc, const String& tableName);
559 
560  // Get the table info of the table with the given name.
561  // An empty object is returned if the table is unknown.
562  static TableInfo tableInfo (const String& tableName);
563 
564  // Show the structure of the table.
565  // It shows the columns (with types), the data managers, and the subtables.
566  // Optionally the columns can be sorted alphabetically.
567  void showStructure (std::ostream&,
568  Bool showDataMans=True,
569  Bool showColumns=True,
570  Bool showSubTables=False,
571  Bool sortColumns=False,
572  Bool cOrder=False) const;
573 
574  // Show the table and/or column keywords, possibly also of all subtables.
575  // Maximum <src>maxVal</src> values of Arrays will be shown.
576  void showKeywords (std::ostream&,
577  Bool showSubTables=False,
578  Bool showTabKey=True,
579  Bool showColKey=False,
580  Int maxVal=25) const;
581 
582  // Show the table and/or column keywords of this table.
583  // Maximum <src>maxVal</src> values of Arrays will be shown.
584  void showKeywordSets (std::ostream&,
585  Bool showTabKey, Bool showColKey,
586  Int maxVal) const;
587 
588  // Test if a table with the given name exists and is writable.
589  static Bool isWritable (const String& tableName, bool throwIf=False);
590 
591  // Find the non-writable files in a table.
593 
594  // Test if this table is the root table (ie. if it is not the subset
595  // of another table).
596  Bool isRootTable() const;
597 
598  // Test if this table is opened as writable.
599  Bool isWritable() const;
600 
601  // Test if the given column is writable.
602  // <group>
603  Bool isColumnWritable (const String& columnName) const;
604  Bool isColumnWritable (uInt columnIndex) const;
605  // </group>
606 
607  // Test if the given column is stored (otherwise it is virtual).
608  // <group>
609  Bool isColumnStored (const String& columnName) const;
610  Bool isColumnStored (uInt columnIndex) const;
611  // </group>
612 
613  // Get readonly access to the table keyword set.
614  // If UserLocking is used, it will automatically acquire
615  // and release a read lock if the table is not locked.
616  const TableRecord& keywordSet() const;
617 
618  // Get read/write access to the table keyword set.
619  // This requires that the table is locked (or it gets locked
620  // if using AutoLocking mode).
622 
623  // Get access to the TableInfo object.
624  // <group>
625  const TableInfo& tableInfo() const;
626  TableInfo& tableInfo();
627  // </group>
628 
629  // Write the TableInfo object.
630  // Usually this is not necessary, because it is done automatically
631  // when the table gets written (by table destructor or flush function).
632  // This function is only useful if the table info has to be written
633  // before the table gets written (e.g. when another process reads
634  // the table while it gets filled).
635  void flushTableInfo() const;
636 
637  // Get the table description.
638  // This can be used to get nr of columns, etc..
639  // <src>tableDesc()</src> gives the table description used when
640  // constructing the table, while <src>actualTableDesc()</src> gives the
641  // actual description, thus with the actual data managers used.
642  // <group>
643  const TableDesc& tableDesc() const;
645  // </group>
646 
647  // Return all data managers used and the columns served by them.
648  // The info is returned in a record. It contains a subrecord per
649  // data manager. Each subrecord contains the following fields:
650  // <dl>
651  // <dt> TYPE
652  // <dd> a string giving the type of the data manager.
653  // <dt> NAME
654  // <dd> a string giving the name of the data manager.
655  // <dt> COLUMNS
656  // <dd> a vector of strings giving the columns served by the data manager.
657  // </dl>
658  // Data managers may return some additional fields (e.g. BUCKETSIZE).
660 
661  // Get the table name.
662  const String& tableName() const;
663 
664  // Rename the table and all its subtables.
665  // The following options can be given:
666  // <dl>
667  // <dt> Table::Update
668  // <dd> A table with this name must already exists, which will be
669  // overwritten. When succesfully renamed, the table is unmarked
670  // for delete (if necessary).
671  // <dt> Table::New
672  // <dd> If a table with this name exists, it will be overwritten.
673  // When succesfully renamed, the table is unmarked
674  // for delete (if necessary).
675  // <dt> Table::NewNoReplace
676  // <dd> If a table with this name already exists, an exception
677  // is thrown. When succesfully renamed, the table
678  // is unmarked for delete (if necessary).
679  // <dt> Table::Scratch
680  // <dd> Same as Table::New, but followed by markForDelete().
681  // </dl>
682  // The scratchCallback function is called when needed.
683  void rename (const String& newName, TableOption);
684 
685  // Copy the table and all its subtables.
686  // Especially for RefTables <src>copy</src> and <src>deepCopy</src> behave
687  // differently. <src>copy</src> makes a bitwise copy of the table, thus
688  // the result is still a RefTable. On the other hand <src>deepCopy</src>
689  // makes a physical copy of all referenced table rows and columns, thus
690  // the result is a PlainTable.
691  // <br>For PlainTables <src>deepCopy</src> is the same as <src>copy</src>
692  // unless <src>valueCopy==True</src> is given. In that case the values
693  // are copied which takes longer, but reorganizes the data files to get
694  // rid of gaps in the data. Also if specific DataManager info is given
695  // or if no rows have to be copied, a deep copy is made.
696  // <br>The following options can be given:
697  // <dl>
698  // <dt> Table::New
699  // <dd> If a table with this name exists, it will be overwritten.
700  // <dt> Table::NewNoReplace
701  // <dd> If a table with this name already exists, an exception
702  // is thrown.
703  // <dt> Table::Scratch
704  // <dd> Same as Table::New, but followed by markForDelete().
705  // </dl>
706  // <group>
707  // The new table gets the given endian format. Note that the endian option
708  // is only used if a true deep copy of a table is made.
709  // <br>When making a deep copy, it is possible to specify the data managers
710  // using the <src>dataManagerInfo</src> argument.
711  // See <src>getDataManagerInfo</src> for more info about that record.
712  // <br>If <src>noRows=True</src> no rows are copied. Also no rows are
713  // copied in all subtables. It is useful if one wants to make a copy
714  // of only the Table structure.
715  void copy (const String& newName, TableOption, Bool noRows=False) const;
716  void deepCopy (const String& newName,
717  TableOption, Bool valueCopy=False,
719  Bool noRows=False) const;
720  void deepCopy (const String& newName, const Record& dataManagerInfo,
721  TableOption, Bool valueCopy=False,
723  Bool noRows=False) const;
724  void deepCopy (const String& newName, const Record& dataManagerInfo,
725  const StorageOption&,
726  TableOption, Bool valueCopy=False,
728  Bool noRows=False) const;
729  // </group>
730 
731  // Make a copy of a table to a MemoryTable object.
732  // Use the given name for the memory table.
733  Table copyToMemoryTable (const String& name, Bool noRows=False) const;
734 
735  // Get the table type.
736  TableType tableType() const;
737 
738  // Get the table option.
739  int tableOption() const;
740 
741  // Mark the table for delete.
742  // This means that the underlying table gets deleted when it is
743  // actually destructed.
744  // The scratchCallback function is called when needed.
745  void markForDelete();
746 
747  // Unmark the table for delete.
748  // This means the underlying table does not get deleted when destructed.
749  // The scratchCallback function is called when needed.
750  void unmarkForDelete();
751 
752  // Test if the table is marked for delete.
753  Bool isMarkedForDelete() const;
754 
755  // Get the number of rows.
756  // It is unsynchronized meaning that it will not check if another
757  // process updated the table, thus possible increased the number of rows.
758  // If one wants to take that into account, he should acquire a
759  // read-lock (using the lock function) before using nrow().
760  rownr_t nrow() const;
761 
762  // Test if it is possible to add a row to this table.
763  // It is possible if all storage managers used for the table
764  // support it.
765  Bool canAddRow() const;
766 
767  // Add one or more rows at the end of the table.
768  // This will fail for tables not supporting addition of rows.
769  // Optionally the rows can be initialized with the default
770  // values as defined in the column descriptions.
771  void addRow (rownr_t nrrow = 1, Bool initialize = False);
772 
773  // Test if it is possible to remove a row from this table.
774  // It is possible if all storage managers used for the table
775  // support it.
776  Bool canRemoveRow() const;
777 
778  // Remove the given row(s).
779  // The latter form can be useful with the select and rowNumbers functions
780  // to remove some selected rows from the table.
781  // <br>It will fail for tables not supporting removal of rows.
782  // <note role=warning>
783  // The following code fragments do NOT have the same result:
784  // <srcblock>
785  // tab.removeRow (10); // remove row 10
786  // tab.removeRow (20); // remove row 20, which was 21
787  // Vector<rownr_t> vec(2);
788  // vec(0) = 10;
789  // vec(1) = 20;
790  // tab.removeRow (vec); // remove row 10 and 20
791  // </srcblock>
792  // because in the first fragment removing row 10 turns the former
793  // row 21 into row 20.
794  // </note>
795  // <group>
796  void removeRow (rownr_t rownr);
797  void removeRow (const RowNumbers& rownrs);
798  // </group>
799 
800  // Create a TableExprNode object for a column or for a keyword
801  // in the table keyword set.
802  // This can be used in selecting rows from a table using
803  // <src>operator()</src> described below.
804  // <br>The functions taking the fieldNames vector are meant for
805  // the cases where the keyword or column contains records.
806  // The fieldNames indicate which field to take from that record
807  // (which can be a record again, etc.).
808  // <group name=keycol>
809  TableExprNode key (const String& keywordName) const;
810  TableExprNode key (const Vector<String>& fieldNames) const;
811  TableExprNode col (const String& columnName) const;
812  TableExprNode col (const String& columnName,
813  const Vector<String>& fieldNames) const;
814  TableExprNode keyCol (const String& name,
815  const Vector<String>& fieldNames) const;
816  // </group>
817 
818  // Create a TableExprNode object for the rownumber function.
819  // 'origin' Indicates which rownumber is the first.
820  // C++ uses origin = 0 (default)
821  // Glish and TaQL both use origin = 1
822  TableExprNode nodeRownr (rownr_t origin=0) const;
823 
824  // Create a TableExprNode object for the rand function.
826 
827  // Select rows from a table using an select expression consisting
828  // of TableExprNode objects.
829  // Basic TableExprNode objects can be created with the functions
830  // <linkto file="Table.h#keycol">key</linkto> and especially
831  // <linkto file="Table.h#keycol">col</linkto>.
832  // Composite TableExprNode objects, representing an expression,
833  // can be created by applying operations (like == and +)
834  // to the basic ones. This is described in class
835  // <linkto class="TableExprNode:description">TableExprNode</linkto>.
836  // For example:
837  // <srcblock>
838  // Table result = tab(tab.col("columnName") > 10);
839  // </srcblock>
840  // All rows for which the expression is true, will be selected and
841  // "stored" in the result.
842  // You need to include ExprNode.h for this purpose.
843  // <br>The first <src>offset</src> matching rows will be skipped.
844  // <br>If <src>maxRow>0</src>, the selection process will stop
845  // when <src>maxRow</src> rows are selected.
846  // <br>The TableExprNode argument can be empty (null) meaning that only
847  // the <src>maxRow/offset</src> arguments are taken into account.
848  Table operator() (const TableExprNode&, rownr_t maxRow=0, rownr_t offset=0) const;
849 
850  // Select rows using a vector of row numbers.
851  // This can, for instance, be used to select the same rows as
852  // were selected in another table (using the rowNumbers function).
853  // <srcblock>
854  // Table result = thisTable (otherTable.rowNumbers());
855  // </srcblock>
856  Table operator() (const RowNumbers& rownrs) const;
857 
858  // Select rows using a mask block.
859  // The length of the block must match the number of rows in the table.
860  // If an element in the mask is True, the corresponding row will be
861  // selected.
863 
864  // Project the given columns (i.e. select the columns).
865  Table project (const Block<String>& columnNames) const;
866 
867  //# Virtually concatenate all tables in this column.
868  //# The column cells must contain tables with the same description.
869 //#// Table concatenate (const String& columnName) const;
870 
871  // Do logical operations on a table.
872  // It can be used for row-selected or projected (i.e. column-selected)
873  // tables. The tables involved must come from the same root table or
874  // be the root table themselves.
875  // <group>
876  // Intersection with another table.
877  Table operator& (const Table&) const;
878  // Union with another table.
879  Table operator| (const Table&) const;
880  // Subtract another table.
881  Table operator- (const Table&) const;
882  // Xor with another table.
883  Table operator^ (const Table&) const;
884  // Take complement.
885  Table operator! () const;
886  // </group>
887 
888  // Sort a table on one or more columns of scalars.
889  // Per column a compare function can be provided. By default
890  // the standard compare function defined in Compare.h will be used.
891  // Default sort order is ascending.
892  // Default sorting algorithm is the parallel sort.
893  // <group>
894  // Sort on one column.
895  Table sort (const String& columnName,
896  int = Sort::Ascending,
897  int = Sort::ParSort) const;
898  // Sort on multiple columns. The principal column has to be the
899  // first element in the Block of column names.
900  Table sort (const Block<String>& columnNames,
901  int = Sort::Ascending,
902  int = Sort::ParSort) const;
903  // Sort on multiple columns. The principal column has to be the
904  // first element in the Block of column names.
905  // The order can be given per column.
906  Table sort (const Block<String>& columnNames,
907  const Block<Int>& sortOrders,
908  int = Sort::ParSort) const;
909  // Sort on multiple columns. The principal column has to be the
910  // first element in the Block of column names.
911  // The order can be given per column.
912  // Provide some special comparisons via CountedPtrs of compare objects.
913  // A null CountedPtr means using the standard compare object
914  // from class <linkto class="ObjCompare:description">ObjCompare</linkto>.
915  Table sort (const Block<String>& columnNames,
916  const Block<CountedPtr<BaseCompare> >& compareObjects,
917  const Block<Int>& sortOrders,
918  int = Sort::ParSort) const;
919  // </group>
920 
921  // Get a vector of row numbers in the root table of rows in this table.
922  // In case the table is a subset of the root table, this tells which
923  // rows of the root table are part of the subset.
924  // In case the table is the root table itself, the result is a vector
925  // containing the row numbers 0 .. #rows-1.
926  // <br>Note that in general it is better to use the next
927  // <src>rowNumbers(Table)</src> function.
929 
930  // Get a vector of row numbers in that table of rows in this table.
931  // In case the table is a subset of that table, this tells which
932  // rows of that table are part of the subset.
933  // In case the table is that table itself, the result is a vector
934  // containing the row numbers 0 .. #rows-1.
935  // <note role=caution>This function is in principle meant for cases
936  // where this table is a subset of that table. However, it can be used
937  // for any table. In that case the returned vector contains a very high
938  // number (max_uint) for rows in this table not part of that table.
939  // In that way they are invalid if used elsewhere.
940  // <br>In the general case creating the row number vector can be slowish,
941  // because it has to do two mappings. However, if this table is a subset
942  // of that table and if they are in the same order, the mapping can be done
943  // in a more efficient way. The argument <src>tryFast</src> can be used to
944  // tell the function to try a fast conversion first. If that cannot be done,
945  // it reverts to the slower way at the expense of an unsuccessful fast
946  // attempt.
947  // </note>
948  // <srcblock>
949  // Table tab("somename");
950  // Table subset = tab(some_select_expression);
951  // RowNumbers rownrs = subset.rowNumbers(tab);
952  // </srcblock>
953  // Note that one cannot be sure that table "somename" is the root
954  // (i.e. original) table. It may also be a subset of another table.
955  // In the latter case doing
956  // <br> <src> RowNumbers rownrs = subset.rowNumbers()</src>
957  // does not give the row numbers in <src>tab</src>, but in the root table
958  // (which is probably not what you want).
959  RowNumbers rowNumbers (const Table& that, Bool tryFast=False) const;
960 
961  // Add a column to the table.
962  // The data manager used for the column depend on the function used.
963  // Exceptions are thrown if the column already exist or if the
964  // table is not writable.
965  // <br>If this table is a reference table (result of selection) and if
966  // <src>addToParent=True</src> the column is also added to the parent
967  // table.
968  // <group>
969  // Use the first appropriate existing storage manager.
970  // If there is none, a data manager is created using the default
971  // data manager in the column description.
972  void addColumn (const ColumnDesc& columnDesc,
973  Bool addToParent = True);
974  // Use an existing data manager with the given name or type.
975  // If the flag byName is True, a name is given, otherwise a type.
976  // If a name is given, an exception is thrown if the data manager is
977  // unknown or does not allow addition of columns.
978  // If a type is given, a storage manager of the given type will be
979  // created if there is no such data manager allowing addition of rows.
980  void addColumn (const ColumnDesc& columnDesc,
981  const String& dataManager, Bool byName,
982  Bool addToParent = True);
983  // Use the given data manager (which is a new one).
984  void addColumn (const ColumnDesc& columnDesc,
985  const DataManager& dataManager,
986  Bool addToParent = True);
987  // </group>
988 
989  // Add a bunch of columns using the given new data manager.
990  // All columns and possible hypercolumn definitions in the given table
991  // description will be copied and added to the table.
992  // This can be used in case of specific data managers which need to
993  // be created with more than one column (e.g. the tiled hypercube
994  // storage managers).
995  // <br>The data manager can be given directly or by means of a record
996  // describing the data manager in the standard way with the fields
997  // TYPE, NAME, and SPEC. The record can contain those fields itself
998  // or it can contain a single subrecord with those fields.
999  // <br>If this table is a reference table (result of selection) and if
1000  // <src>addToParent=True</src> the columns are also added to the parent
1001  // table.
1002  // <group>
1003  void addColumn (const TableDesc& tableDesc,
1004  const DataManager& dataManager,
1005  Bool addToParent = True);
1006  void addColumn (const TableDesc& tableDesc,
1007  const Record& dataManagerInfo,
1008  Bool addToParent = True);
1009  // </group>
1010 
1011  // Test if columns can be removed.
1012  // It can if the columns exist and if the data manager it is using
1013  // supports removal of columns or if all columns from a data manager
1014  // would be removed..
1015  // <br>You can always remove columns from a reference table.
1016  // <group>
1017  Bool canRemoveColumn (const String& columnName) const;
1018  Bool canRemoveColumn (const Vector<String>& columnNames) const;
1019  // </group>
1020 
1021  // Remove columns.
1022  // <br>When removing columns from a reference table, the columns
1023  // are NOT removed from the underlying table.
1024  // <group>
1025  void removeColumn (const String& columnName);
1026  void removeColumn (const Vector<String>& columnName);
1027  // </group>
1028 
1029  // Test if a column can be renamed.
1030  Bool canRenameColumn (const String& columnName) const;
1031 
1032  // Rename a column.
1033  // An exception is thrown if the old name does not exist or
1034  // if the name already exists.
1035  // <note role=caution>
1036  // Renaming a column should be done with care, because other
1037  // columns may be referring this column. Also a hypercolumn definition
1038  // might be using the old name.
1039  // Finally if may also invalidate persistent selections of a table,
1040  // because the reference table cannot find the column anymore.
1041  // </note>
1042  void renameColumn (const String& newName, const String& oldName);
1043 
1044  void renameHypercolumn (const String& newName, const String& oldName);
1045 
1046  // Write a table to AipsIO (for <src>TypedKeywords<Table></src>).
1047  // This will only write the table name.
1048  friend AipsIO& operator<< (AipsIO&, const Table&);
1049 
1050  // Read a table from AipsIO (for <src>TypedKeywords<Table></src>).
1051  // This will read the table name and open the table as writable
1052  // if the table file is writable, otherwise as readonly.
1054 
1055  // Read a table from AipsIO (for <src>TableKeywords</src>).
1056  // This will read the table name and open the table as writable
1057  // if the switch is set and if the table file is writable.
1058  // otherwise it is opened as readonly.
1059  void getTableKeyword (AipsIO&, Bool openWritable);
1060 
1061  // Write a table to ostream (for <src>TypedKeywords<Table></src>).
1062  // This only shows its name and number of columns and rows.
1063  friend ostream& operator<< (ostream&, const Table&);
1064 
1065  // Find the data manager with the given name or for the given column name.
1066  DataManager* findDataManager (const String& name,
1067  Bool byColumn=False) const;
1068 
1069 
1070 protected:
1071  BaseTable* baseTabPtr_p; //# ptr to table representation
1072  //# The isCounted_p flag is normally true.
1073  //# Only for internally used Table objects (i.e. in the DataManager)
1074  //# this flag is False, otherwise a mutual dependency would exist.
1075  //# The DataManager has a Table object, which gets deleted by the
1076  //# DataManager destructor. The DataManager gets deleted by the
1077  //# PlainTable destructor, which gets called when the last Table
1078  //# object gets destructed. That would never be the case if this
1079  //# internally used Table object was counted.
1081  //# Counter of last call to hasDataChanged.
1083  //# Pointer to the ScratchCallback function.
1085 
1086 
1087  // Construct a Table object from a BaseTable*.
1088  // By default the object gets counted.
1089  Table (BaseTable*, Bool countIt = True);
1090 
1091  // Open an existing table.
1092  void open (const String& name, const String& type, int tableOption,
1093  const TableLock& lockOptions, const TSMOption& tsmOpt);
1094 
1095 
1096 private:
1097  // Construct a BaseTable object from the table file.
1098  static BaseTable* makeBaseTable (const String& name, const String& type,
1099  int tableOption,
1100  const TableLock& lockOptions,
1101  const TSMOption& tsmOpt,
1102  Bool addToCache, uInt locknr);
1103 
1104 
1105  // Get the pointer to the underlying BaseTable.
1106  // This is needed for some friend classes.
1107  BaseTable* baseTablePtr() const;
1108 
1109  // Look in the cache if the table is already open.
1110  // If so, check if table option matches.
1111  // If needed reopen the table for read/write and merge the lock options.
1113  const TableLock& tableInfo);
1114 
1115  // Try if v1 is a subset of v2 and fill rows with its indices in v2.
1116  // Return False if not a proper subset.
1118  Vector<rownr_t>& rows) const;
1119 
1120  // Show the info of the given columns.
1121  // Sort the columns if needed.
1122  void showColumnInfo (ostream& os, const TableDesc&, uInt maxNameLength,
1123  const Array<String>& columnNames, Bool sort) const;
1124 };
1125 
1126 
1127 
1128 inline Bool Table::isSameRoot (const Table& other) const
1129  { return baseTabPtr_p->root() == other.baseTabPtr_p->root(); }
1130 
1131 inline void Table::reopenRW()
1132  { baseTabPtr_p->reopenRW(); }
1133 inline void Table::flush (Bool fsync, Bool recursive)
1134  { baseTabPtr_p->flush (fsync, recursive); }
1135 inline void Table::resync()
1136  { baseTabPtr_p->resync(); }
1137 
1139  { return baseTabPtr_p->storageOption(); }
1140 inline Bool Table::isMultiUsed(Bool checkSubTables) const
1141  { return baseTabPtr_p->isMultiUsed(checkSubTables); }
1142 inline const TableLock& Table::lockOptions() const
1143  { return baseTabPtr_p->lockOptions(); }
1144 inline Bool Table::lock (FileLocker::LockType type, uInt nattempts)
1145  { return baseTabPtr_p->lock (type, nattempts); }
1146 inline Bool Table::lock (Bool write, uInt nattempts)
1147 {
1149  nattempts);
1150 }
1151 inline void Table::unlock()
1152  { baseTabPtr_p->unlock(); }
1154  { return baseTabPtr_p->hasLock (type); }
1155 inline Bool Table::hasLock (Bool write) const
1156 {
1158 }
1159 
1160 inline Bool Table::isRootTable() const
1161  { return baseTabPtr_p == baseTabPtr_p->root(); }
1162 
1163 inline Bool Table::isWritable() const
1164  { return baseTabPtr_p->isWritable(); }
1165 inline Bool Table::isColumnWritable (const String& columnName) const
1166  { return baseTabPtr_p->isColumnWritable (columnName); }
1167 inline Bool Table::isColumnWritable (uInt columnIndex) const
1168  { return baseTabPtr_p->isColumnWritable (columnIndex); }
1169 
1170 inline Bool Table::isColumnStored (const String& columnName) const
1171  { return baseTabPtr_p->isColumnStored (columnName); }
1172 inline Bool Table::isColumnStored (uInt columnIndex) const
1173  { return baseTabPtr_p->isColumnStored (columnIndex); }
1174 
1175 inline void Table::rename (const String& newName, TableOption option)
1176  { baseTabPtr_p->rename (newName, option); }
1177 inline void Table::deepCopy (const String& newName,
1178  const Record& dataManagerInfo,
1179  TableOption option,
1180  Bool valueCopy,
1181  EndianFormat endianFormat,
1182  Bool noRows) const
1184  option, valueCopy,
1185  endianFormat, noRows); }
1186 inline void Table::deepCopy (const String& newName,
1187  const Record& dataManagerInfo,
1188  const StorageOption& stopt,
1189  TableOption option,
1190  Bool valueCopy,
1191  EndianFormat endianFormat,
1192  Bool noRows) const
1193  { baseTabPtr_p->deepCopy (newName, dataManagerInfo, stopt,
1194  option, valueCopy,
1195  endianFormat, noRows); }
1197  { baseTabPtr_p->markForDelete (True, ""); }
1199  { baseTabPtr_p->unmarkForDelete(True, ""); }
1201  { return baseTabPtr_p->isMarkedForDelete(); }
1202 
1203 inline rownr_t Table::nrow() const
1204  { return baseTabPtr_p->nrow(); }
1206  { return baseTabPtr_p; }
1207 inline const TableDesc& Table::tableDesc() const
1208  { return baseTabPtr_p->tableDesc(); }
1209 inline const TableRecord& Table::keywordSet() const
1210  { return baseTabPtr_p->keywordSet(); }
1211 
1212 inline TableInfo Table::tableInfo (const String& tableName)
1213  { return BaseTable::tableInfo (tableName); }
1214 inline const TableInfo& Table::tableInfo() const
1215  { return baseTabPtr_p->tableInfo(); }
1217  { return baseTabPtr_p->tableInfo(); }
1218 inline void Table::flushTableInfo() const
1220 
1221 inline const String& Table::tableName() const
1222  { return baseTabPtr_p->tableName(); }
1224  { return TableType(baseTabPtr_p->tableType()); }
1225 inline int Table::tableOption() const
1226  { return baseTabPtr_p->tableOption(); }
1227 
1228 inline Bool Table::canAddRow() const
1229  { return baseTabPtr_p->canAddRow(); }
1231  { return baseTabPtr_p->canRemoveRow(); }
1232 inline Bool Table::canRemoveColumn (const Vector<String>& columnNames) const
1233  { return baseTabPtr_p->canRemoveColumn (columnNames); }
1234 inline Bool Table::canRenameColumn (const String& columnName) const
1235  { return baseTabPtr_p->canRenameColumn (columnName); }
1236 
1237 inline void Table::addRow (rownr_t nrrow, Bool initialize)
1238  { baseTabPtr_p->addRow (nrrow, initialize); }
1239 inline void Table::removeRow (rownr_t rownr)
1240  { baseTabPtr_p->removeRow (rownr); }
1241 inline void Table::removeRow (const RowNumbers& rownrs)
1242  { baseTabPtr_p->removeRow (rownrs); }
1243 inline void Table::addColumn (const ColumnDesc& columnDesc, Bool addToParent)
1244  { baseTabPtr_p->addColumn (columnDesc, addToParent); }
1245 inline void Table::addColumn (const ColumnDesc& columnDesc,
1246  const String& dataManager, Bool byName,
1247  Bool addToParent)
1248  { baseTabPtr_p->addColumn (columnDesc, dataManager, byName, addToParent); }
1249 inline void Table::addColumn (const ColumnDesc& columnDesc,
1250  const DataManager& dataManager, Bool addToParent)
1251  { baseTabPtr_p->addColumn (columnDesc, dataManager, addToParent); }
1252 inline void Table::addColumn (const TableDesc& tableDesc,
1253  const DataManager& dataManager, Bool addToParent)
1254  { baseTabPtr_p->addColumn (tableDesc, dataManager, addToParent); }
1255 inline void Table::addColumn (const TableDesc& tableDesc,
1256  const Record& dataManagerInfo, Bool addToParent) { baseTabPtr_p->addColumns (tableDesc, dataManagerInfo, addToParent); }
1257 inline void Table::removeColumn (const Vector<String>& columnNames)
1258  { baseTabPtr_p->removeColumn (columnNames); }
1259 inline void Table::renameColumn (const String& newName, const String& oldName)
1260  { baseTabPtr_p->renameColumn (newName, oldName); }
1261 inline void Table::renameHypercolumn (const String& newName, const String& oldName)
1262  { baseTabPtr_p->renameHypercolumn (newName, oldName); }
1263 
1265  Bool byColumn) const
1266 {
1267  return baseTabPtr_p->findDataManager (name, byColumn);
1268 }
1269 
1270 inline void Table::showStructure (std::ostream& os,
1271  Bool showDataMans,
1272  Bool showColumns,
1273  Bool showSubTables,
1274  Bool sortColumns,
1275  Bool cOrder) const
1276  { baseTabPtr_p->showStructure (os, showDataMans, showColumns,
1277  showSubTables, sortColumns, cOrder); }
1278 
1279 
1280 
1281 } //# NAMESPACE CASACORE - END
1282 
1283 #endif
virtual void renameHypercolumn(const String &newName, const String &oldName)=0
Rename a hypercolumn.
virtual void flushTableInfo()
Write the TableInfo object.
virtual const TableLock & lockOptions() const =0
Get the locking info.
void unmarkForDelete(Bool callback, const String &oldName)
Unmark the table for delete.
virtual void reopenRW()=0
Reopen the table for read/write.
virtual Bool isNull() const
Is the table a null table? By default it is not.
virtual void renameColumn(const String &newName, const String &oldName)=0
Rename a column.
Bool isMarkedForDelete() const
Test if the table is marked for delete.
Definition: BaseTable.h:268
const TableDesc & tableDesc() const
Get the table description.
Definition: BaseTable.h:272
TableInfo & tableInfo()
Get access to the TableInfo object.
Definition: BaseTable.h:298
virtual Bool lock(FileLocker::LockType, uInt nattempts)=0
Try to lock the table for read or write access.
Bool isColumnWritable(const String &columnName) const
Test if the given column is writable.
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const =0
Test if columns can be removed.
virtual void addColumn(const ColumnDesc &columnDesc, Bool addToParent)
Add one or more columns to the table.
virtual void removeColumn(const Vector< String > &columnNames)=0
Remove columns.
virtual TableRecord & keywordSet()=0
Get readonly access to the table keyword set.
virtual void removeRow(rownr_t rownr)
Remove rows.
virtual void addRow(rownr_t nrrow=1, Bool initialize=True)
Add one or more rows and possibly initialize them.
virtual Bool isMultiUsed(Bool checkSubTables) const =0
Is the table in use (i.e.
const String & tableName() const
Get the table name.
Definition: BaseTable.h:195
virtual Bool canRenameColumn(const String &columnName) const =0
Test if a column can be renamed.
Bool isColumnStored(const String &columnName) const
Test if the given column is stored (otherwise it is virtual).
virtual Bool isWritable() const =0
Test if this table is writable.
virtual void resync()=0
Resync the Table object with the table file.
virtual void rename(const String &newName, int tableOption)
Rename the table.
virtual Bool canAddRow() const
Test if it is possible to add a row to this table.
rownr_t nrow() const
Get number of rows.
Definition: BaseTable.h:309
int tableOption() const
Get the table option.
Definition: BaseTable.h:253
virtual void unlock()=0
Unlock the table.
void markForDelete(Bool callback, const String &oldName)
Mark the table for delete.
virtual BaseTable * root()
Get pointer to root table (i.e.
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table.
virtual Bool hasLock(FileLocker::LockType) const =0
Has this process the read or write lock, thus can the table be read or written safely?
void addColumns(const TableDesc &tableDesc, const Record &dmInfo, Bool addToParent)
Add one or more columns to the table.
virtual void flush(Bool fsync, Bool recursive)=0
Flush the table, i.e.
virtual int tableType() const
Get the table type.
virtual DataManager * findDataManager(const String &name, Bool byColumn) const =0
Find the data manager with the given name or for the given column.
virtual const StorageOption & storageOption() const =0
Get the storage option used for the table.
virtual void deepCopy(const String &newName, const Record &dataManagerInfo, const StorageOption &, int tableOption, Bool valueCopy, int endianFormat, Bool noRows) const
void showStructure(std::ostream &, Bool showDataMan, Bool showColumns, Bool showSubTables, Bool sortColumns, Bool cOrder)
Show the table structure (implementation of Table::showStructure).
simple 1-D array
Definition: Block.h:200
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
Abstract base class for a data manager.
Definition: DataManager.h:218
LockType
Define the possible lock types.
Definition: FileLocker.h:95
@ Write
Acquire a write lock.
Definition: FileLocker.h:99
@ Read
Acquire a read lock.
Definition: FileLocker.h:97
Create a new table - define shapes, data managers, etc.
Definition: SetupNewTab.h:341
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Abstract base class for a node in a table column expression tree.
Definition: ExprNodeRep.h:158
LockOption
Define the possible table locking options.
Definition: TableLock.h:81
static Bool isOpened(const String &tableName)
Is the table used (i.e.
Table(SetupNewTable &, const TableLock &lockOptions, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
Table(SetupNewTable &, TableType, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
void copy(const String &newName, TableOption, Bool noRows=False) const
Copy the table and all its subtables.
Bool hasLock(FileLocker::LockType=FileLocker::Write) const
Has this process the read or write lock, thus can the table be read or written safely?
Definition: Table.h:1153
const TableLock & lockOptions() const
Get the locking options.
Definition: Table.h:1142
void unlock()
Unlock the table.
Definition: Table.h:1151
void renameHypercolumn(const String &newName, const String &oldName)
Definition: Table.h:1261
Table(const Block< Table > &tables, const Block< String > &subTables=Block< String >(), const String &subDirName=String())
Create a table object as the virtual concatenation of one or more of existing tables.
static void deleteTable(const String &tableName, Bool checkSubTables=False)
Delete the table.
Bool isMarkedForDelete() const
Test if the table is marked for delete.
Definition: Table.h:1200
TableType tableType() const
Get the table type.
Definition: Table.h:1223
Table(const String &tableName, const String &tableDescName, const TableLock &lockOptions, TableOption=Table::Old, const TSMOption &=TSMOption())
Table sort(const Block< String > &columnNames, const Block< CountedPtr< BaseCompare > > &compareObjects, const Block< Int > &sortOrders, int=Sort::ParSort) const
Sort on multiple columns.
int tableOption() const
Get the table option.
Definition: Table.h:1225
void ScratchCallback(const String &name, Bool isScratch, const String &oldName)
Define the signature of the function being called when the state of a scratch table changes (i....
Definition: Table.h:215
Bool isNull() const
Test if the object is null, i.e.
Definition: Table.h:528
Table sort(const String &columnName, int=Sort::Ascending, int=Sort::ParSort) const
Sort a table on one or more columns of scalars.
Table(const String &tableName, const String &tableDescName, TableOption=Table::Old, const TSMOption &=TSMOption())
Table & operator=(const Table &)
Assignment (reference semantics).
Bool isColumnWritable(const String &columnName) const
Test if the given column is writable.
Definition: Table.h:1165
static Bool isNativeDataType(DataType dtype)
Test if the given data type is native to the table system.
void unmarkForDelete()
Unmark the table for delete.
Definition: Table.h:1198
Table operator()(const TableExprNode &, rownr_t maxRow=0, rownr_t offset=0) const
Select rows from a table using an select expression consisting of TableExprNode objects.
const TableDesc & tableDesc() const
Get the table description.
Definition: Table.h:1207
Table(MPI_Comm mpiComm, SetupNewTable &, TableType, const TableLock &lockOptions, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
static String fileName(const String &tableName)
Make the table file name.
Bool fastRowNumbers(const Vector< rownr_t > &v1, const Vector< rownr_t > &v2, Vector< rownr_t > &rows) const
Try if v1 is a subset of v2 and fill rows with its indices in v2.
void closeSubTables() const
Close all open subtables.
Bool isSameRoot(const Table &other) const
Is the root table of this table the same as that of the other one?
Definition: Table.h:1128
DataManager * findDataManager(const String &name, Bool byColumn=False) const
Find the data manager with the given name or for the given column name.
Definition: Table.h:1264
static ScratchCallback * setScratchCallback(ScratchCallback *)
Set the pointer to the ScratchCallback function.
void renameColumn(const String &newName, const String &oldName)
Rename a column.
Definition: Table.h:1259
Bool isCounted_p
Definition: Table.h:1080
Table(MPI_Comm mpiComm, SetupNewTable &, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
Table(TableType, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
Make a new empty table (plain (scratch) or memory type).
const String & tableName() const
Get the table name.
Definition: Table.h:1221
Table(const Block< String > &tableNames, const Block< String > &subTables, const TableLock &lockOptions, TableOption=Table::Old, const TSMOption &=TSMOption())
Bool canRemoveRow() const
Test if it is possible to remove a row from this table.
Definition: Table.h:1230
static rownr_t getLayout(TableDesc &desc, const String &tableName)
Return the layout of a table (i.e.
RowNumbers rowNumbers() const
Get a vector of row numbers in the root table of rows in this table.
static Table openTable(const String &tableName, TableOption=Table::Old, const TSMOption &=TSMOption())
Try to open a table.
EndianFormat
Define the possible endian formats in which table data can be stored.
Definition: Table.h:193
@ AipsrcEndian
use endian format defined in the aipsrc variable table.endianformat If undefined, it defaults to Loca...
Definition: Table.h:202
@ LocalEndian
store data in the endian format of the machine used
Definition: Table.h:199
@ BigEndian
store table data in big endian (e.g.
Definition: Table.h:195
@ LittleEndian
store table data in little endian (e.g.
Definition: Table.h:197
static uInt nAutoLocks()
Determine the number of locked tables opened with the AutoLock option (Locked table means locked for ...
static ScratchCallback * scratchCallback_p
Definition: Table.h:1084
TableOption
Define the possible options how a table can be opened.
Definition: Table.h:169
@ Scratch
new table, which gets marked for delete
Definition: Table.h:177
@ New
create table
Definition: Table.h:173
@ Update
update existing table
Definition: Table.h:179
@ NewNoReplace
create table (may not exist)
Definition: Table.h:175
@ Old
existing table
Definition: Table.h:171
@ Delete
delete table
Definition: Table.h:181
rownr_t nrow() const
Get the number of rows.
Definition: Table.h:1203
static Bool isWritable(const String &tableName, bool throwIf=False)
Test if a table with the given name exists and is writable.
Table(SetupNewTable &, TableLock::LockOption, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
void flushTableInfo() const
Write the TableInfo object.
Definition: Table.h:1218
Bool canAddRow() const
Test if it is possible to add a row to this table.
Definition: Table.h:1228
Bool lock(FileLocker::LockType=FileLocker::Write, uInt nattempts=0)
Try to lock the table for read or write access (default is write).
Definition: Table.h:1144
Bool hasDataChanged()
Determine if column or keyword table data have changed (or is being changed) since the last time this...
Table operator&(const Table &) const
Do logical operations on a table.
static Bool isReadable(const String &tableName, bool throwIf=False)
Test if a table with the given name exists and is readable.
void rename(const String &newName, TableOption)
Rename the table and all its subtables.
Definition: Table.h:1175
friend AipsIO & operator<<(AipsIO &, const Table &)
Write a table to AipsIO (for TypedKeywords<Table>).
TableExprNode key(const String &keywordName) const
Create a TableExprNode object for a column or for a keyword in the table keyword set.
void flush(Bool fsync=False, Bool recursive=False)
Flush the table, i.e.
Definition: Table.h:1133
BaseTable * baseTabPtr_p
Definition: Table.h:1071
Bool canRemoveColumn(const String &columnName) const
Test if columns can be removed.
void markForDelete()
Mark the table for delete.
Definition: Table.h:1196
static void relinquishAutoLocks(Bool all=False)
Unlock locked tables opened with the AutoLock option.
Bool isColumnStored(const String &columnName) const
Test if the given column is stored (otherwise it is virtual).
Definition: Table.h:1170
TableExprNode nodeRownr(rownr_t origin=0) const
Create a TableExprNode object for the rownumber function.
const StorageOption & storageOption() const
Get the storage option used for the table.
Definition: Table.h:1138
Table copyToMemoryTable(const String &name, Bool noRows=False) const
Make a copy of a table to a MemoryTable object.
Table(SetupNewTable &, TableType, const TableLock &lockOptions, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
static Bool canDeleteTable(const String &tableName, Bool checkSubTables=False)
Can the table be deleted? If true, function deleteTable can safely be called.
void removeColumn(const String &columnName)
Remove columns.
void showStructure(std::ostream &, Bool showDataMans=True, Bool showColumns=True, Bool showSubTables=False, Bool sortColumns=False, Bool cOrder=False) const
Show the structure of the table.
Definition: Table.h:1270
static Table openTable(const String &tableName, const TableLock &lockOptions, TableOption=Table::Old, const TSMOption &=TSMOption())
const TableRecord & keywordSet() const
Get readonly access to the table keyword set.
Definition: Table.h:1209
TableExprNode nodeRandom() const
Create a TableExprNode object for the rand function.
Table operator!() const
Take complement.
Table(const String &tableName, TableOption=Table::Old, const TSMOption &=TSMOption())
Create a table object for an existing table.
Table(MPI_Comm mpiComm, SetupNewTable &, TableLock::LockOption, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
static BaseTable * makeBaseTable(const String &name, const String &type, int tableOption, const TableLock &lockOptions, const TSMOption &tsmOpt, Bool addToCache, uInt locknr)
Construct a BaseTable object from the table file.
Table operator^(const Table &) const
Xor with another table.
void getTableKeyword(AipsIO &, Bool openWritable)
Read a table from AipsIO (for TableKeywords).
void removeRow(rownr_t rownr)
Remove the given row(s).
Definition: Table.h:1239
void showColumnInfo(ostream &os, const TableDesc &, uInt maxNameLength, const Array< String > &columnNames, Bool sort) const
Show the info of the given columns.
Table operator|(const Table &) const
Union with another table.
void throwIfNull() const
Throw an exception if the object is null, i.e.
friend AipsIO & operator>>(AipsIO &, Table &)
Read a table from AipsIO (for TypedKeywords<Table>).
Bool isMultiUsed(Bool checkSubTables=False) const
Is the table used (i.e.
Definition: Table.h:1140
Bool isWritable() const
Test if this table is opened as writable.
Definition: Table.h:1163
Table::EndianFormat endianFormat() const
Get the endian format in which the table is stored.
void resync()
Resynchronize the Table object with the table file.
Definition: Table.h:1135
Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed.
Definition: Table.h:1234
void reopenRW()
Try to reopen the table for read/write access.
Definition: Table.h:1131
TableDesc actualTableDesc() const
Table(MPI_Comm mpiComm, SetupNewTable &, const TableLock &lockOptions, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
TableType
Define the possible table types.
Definition: Table.h:185
@ Plain
plain table (stored on disk)
Definition: Table.h:187
const TableInfo & tableInfo() const
Get access to the TableInfo object.
Definition: Table.h:1214
void open(const String &name, const String &type, int tableOption, const TableLock &lockOptions, const TSMOption &tsmOpt)
Open an existing table.
Table sort(const Block< String > &columnNames, const Block< Int > &sortOrders, int=Sort::ParSort) const
Sort on multiple columns.
Table(BaseTable *, Bool countIt=True)
Construct a Table object from a BaseTable*.
void deepCopy(const String &newName, TableOption, Bool valueCopy=False, EndianFormat=AipsrcEndian, Bool noRows=False) const
virtual ~Table()
The destructor flushes (i.e.
BaseTable * lookCache(const String &name, int tableOption, const TableLock &tableInfo)
Look in the cache if the table is already open.
void addRow(rownr_t nrrow=1, Bool initialize=False)
Add one or more rows at the end of the table.
Definition: Table.h:1237
static Bool canDeleteTable(String &message, const String &tableName, Bool checkSubTables=False)
Table(const Table &)
Copy constructor (reference semantics).
Bool isRootTable() const
Test if this table is the root table (ie.
Definition: Table.h:1160
Table(MPI_Comm mpiComm, TableType, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
TableExprNode col(const String &columnName) const
Table(const Block< String > &tableNames, const Block< String > &subTables=Block< String >(), TableOption=Table::Old, const TSMOption &=TSMOption(), const String &subDirName=String())
Table sort(const Block< String > &columnNames, int=Sort::Ascending, int=Sort::ParSort) const
Sort on multiple columns.
Table()
Create a null Table object (i.e.
TableExprNode keyCol(const String &name, const Vector< String > &fieldNames) const
uInt lastModCounter_p
Definition: Table.h:1082
Table(const String &tableName, const TableLock &lockOptions, TableOption=Table::Old, const TSMOption &=TSMOption())
static Vector< String > nonWritableFiles(const String &tableName)
Find the non-writable files in a table.
Table operator-(const Table &) const
Subtract another table.
Table(SetupNewTable &, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
Make a table object for a new table, which can thereafter be used for reading and writing.
static Vector< String > getLockedTables(FileLocker::LockType=FileLocker::Read, int lockOption=-1)
Get the names of tables locked in this process.
Table project(const Block< String > &columnNames) const
Project the given columns (i.e.
RowNumbers rowNumbers(const Table &that, Bool tryFast=False) const
Get a vector of row numbers in that table of rows in this table.
void addColumn(const ColumnDesc &columnDesc, Bool addToParent=True)
Add a column to the table.
Definition: Table.h:1243
Block< String > getPartNames(Bool recursive=False) const
Get the names of the tables this table consists of.
BaseTable * baseTablePtr() const
Get the pointer to the underlying BaseTable.
Definition: Table.h:1205
void showKeywordSets(std::ostream &, Bool showTabKey, Bool showColKey, Int maxVal) const
Show the table and/or column keywords of this table.
Table(MPI_Comm mpiComm, SetupNewTable &, TableType, rownr_t nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian, const TSMOption &=TSMOption())
void showKeywords(std::ostream &, Bool showSubTables=False, Bool showTabKey=True, Bool showColKey=False, Int maxVal=25) const
Show the table and/or column keywords, possibly also of all subtables.
Record dataManagerInfo() const
Return all data managers used and the columns served by them.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
LatticeExprNode all(const LatticeExprNode &expr)
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46