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