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