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) const;
547 
548  // Test if a table with the given name exists and is writable.
549  static Bool isWritable (const String& tableName, bool throwIf=False);
550 
551  // Find the non-writable files in a table.
552  static Vector<String> nonWritableFiles (const String& tableName);
553 
554  // Test if this table is the root table (ie. if it is not the subset
555  // of another table).
556  Bool isRootTable() const;
557 
558  // Test if this table is opened as writable.
559  Bool isWritable() const;
560 
561  // Test if the given column is writable.
562  // <group>
563  Bool isColumnWritable (const String& columnName) const;
564  Bool isColumnWritable (uInt columnIndex) const;
565  // </group>
566 
567  // Test if the given column is stored (otherwise it is virtual).
568  // <group>
569  Bool isColumnStored (const String& columnName) const;
570  Bool isColumnStored (uInt columnIndex) const;
571  // </group>
572 
573  // Get readonly access to the table keyword set.
574  // If UserLocking is used, it will automatically acquire
575  // and release a read lock if the table is not locked.
576  const TableRecord& keywordSet() const;
577 
578  // Get read/write access to the table keyword set.
579  // This requires that the table is locked (or it gets locked
580  // if using AutoLocking mode).
582 
583  // Get access to the TableInfo object.
584  // <group>
585  const TableInfo& tableInfo() const;
586  TableInfo& tableInfo();
587  // </group>
588 
589  // Write the TableInfo object.
590  // Usually this is not necessary, because it is done automatically
591  // when the table gets written (by table destructor or flush function).
592  // This function is only useful if the table info has to be written
593  // before the table gets written (e.g. when another process reads
594  // the table while it gets filled).
595  void flushTableInfo() const;
596 
597  // Get the table description.
598  // This can be used to get nr of columns, etc..
599  // <src>tableDesc()</src> gives the table description used when
600  // constructing the table, while <src>actualTableDesc()</src> gives the
601  // actual description, thus with the actual data managers used.
602  // <group>
603  const TableDesc& tableDesc() const;
604  TableDesc actualTableDesc() const;
605  // </group>
606 
607  // Return all data managers used and the columns served by them.
608  // The info is returned in a record. It contains a subrecord per
609  // data manager. Each subrecord contains the following fields:
610  // <dl>
611  // <dt> TYPE
612  // <dd> a string giving the type of the data manager.
613  // <dt> NAME
614  // <dd> a string giving the name of the data manager.
615  // <dt> COLUMNS
616  // <dd> a vector of strings giving the columns served by the data manager.
617  // </dl>
618  // Data managers may return some additional fields (e.g. BUCKETSIZE).
619  Record dataManagerInfo() const;
620 
621  // Get the table name.
622  const String& tableName() const;
623 
624  // Rename the table and all its subtables.
625  // The following options can be given:
626  // <dl>
627  // <dt> Table::Update
628  // <dd> A table with this name must already exists, which will be
629  // overwritten. When succesfully renamed, the table is unmarked
630  // for delete (if necessary).
631  // <dt> Table::New
632  // <dd> If a table with this name exists, it will be overwritten.
633  // When succesfully renamed, the table is unmarked
634  // for delete (if necessary).
635  // <dt> Table::NewNoReplace
636  // <dd> If a table with this name already exists, an exception
637  // is thrown. When succesfully renamed, the table
638  // is unmarked for delete (if necessary).
639  // <dt> Table::Scratch
640  // <dd> Same as Table::New, but followed by markForDelete().
641  // </dl>
642  // The scratchCallback function is called when needed.
643  void rename (const String& newName, TableOption);
644 
645  // Copy the table and all its subtables.
646  // Especially for RefTables <src>copy</src> and <src>deepCopy</src> behave
647  // differently. <src>copy</src> makes a bitwise copy of the table, thus
648  // the result is still a RefTable. On the other hand <src>deepCopy</src>
649  // makes a physical copy of all referenced table rows and columns, thus
650  // the result is a PlainTable.
651  // <br>For PlainTables <src>deepCopy</src> is the same as <src>copy</src>
652  // unless <src>valueCopy==True</src> is given. In that case the values
653  // are copied which takes longer, but reorganizes the data files to get
654  // rid of gaps in the data. Also if specific DataManager info is given
655  // or if no rows have to be copied, a deep copy is made.
656  // <br>The following options can be given:
657  // <dl>
658  // <dt> Table::New
659  // <dd> If a table with this name exists, it will be overwritten.
660  // <dt> Table::NewNoReplace
661  // <dd> If a table with this name already exists, an exception
662  // is thrown.
663  // <dt> Table::Scratch
664  // <dd> Same as Table::New, but followed by markForDelete().
665  // </dl>
666  // <group>
667  // The new table gets the given endian format. Note that the endian option
668  // is only used if a true deep copy of a table is made.
669  // <br>When making a deep copy, it is possible to specify the data managers
670  // using the <src>dataManagerInfo</src> argument.
671  // See <src>getDataManagerInfo</src> for more info about that record.
672  // <br>If <src>noRows=True</src> no rows are copied. Also no rows are
673  // copied in all subtables. It is useful if one wants to make a copy
674  // of only the Table structure.
675  void copy (const String& newName, TableOption, Bool noRows=False) const;
676  void deepCopy (const String& newName,
677  TableOption, Bool valueCopy=False,
679  Bool noRows=False) const;
680  void deepCopy (const String& newName, const Record& dataManagerInfo,
681  TableOption, Bool valueCopy=False,
683  Bool noRows=False) const;
684  // </group>
685 
686  // Make a copy of a table to a MemoryTable object.
687  // Use the given name for the memory table.
688  Table copyToMemoryTable (const String& name, Bool noRows=False) const;
689 
690  // Get the table type.
691  TableType tableType() const;
692 
693  // Get the table option.
694  int tableOption() const;
695 
696  // Mark the table for delete.
697  // This means that the underlying table gets deleted when it is
698  // actually destructed.
699  // The scratchCallback function is called when needed.
700  void markForDelete();
701 
702  // Unmark the table for delete.
703  // This means the underlying table does not get deleted when destructed.
704  // The scratchCallback function is called when needed.
705  void unmarkForDelete();
706 
707  // Test if the table is marked for delete.
708  Bool isMarkedForDelete() const;
709 
710  // Get the number of rows.
711  // It is unsynchronized meaning that it will not check if another
712  // process updated the table, thus possible increased the number of rows.
713  // If one wants to take that into account, he should acquire a
714  // read-lock (using the lock function) before using nrow().
715  uInt nrow() const;
716 
717  // Test if it is possible to add a row to this table.
718  // It is possible if all storage managers used for the table
719  // support it.
720  Bool canAddRow() const;
721 
722  // Add one or more rows at the end of the table.
723  // This will fail for tables not supporting addition of rows.
724  // Optionally the rows can be initialized with the default
725  // values as defined in the column descriptions.
726  void addRow (uInt nrrow = 1, Bool initialize = False);
727 
728  // Test if it is possible to remove a row from this table.
729  // It is possible if all storage managers used for the table
730  // support it.
731  Bool canRemoveRow() const;
732 
733  // Remove the given row(s).
734  // The latter form can be useful with the select and rowNumbers functions
735  // to remove some selected rows from the table.
736  // <br>It will fail for tables not supporting removal of rows.
737  // <note role=warning>
738  // The following code fragments do NOT have the same result:
739  // <srcblock>
740  // tab.removeRow (10); // remove row 10
741  // tab.removeRow (20); // remove row 20, which was 21
742  // Vector<uInt> vec(2);
743  // vec(0) = 10;
744  // vec(1) = 20;
745  // tab.removeRow (vec); // remove row 10 and 20
746  // </srcblock>
747  // because in the first fragment removing row 10 turns the former
748  // row 21 into row 20.
749  // </note>
750  // <group>
751  void removeRow (uInt rownr);
752  void removeRow (const Vector<uInt>& rownrs);
753  // </group>
754 
755  // Create a TableExprNode object for a column or for a keyword
756  // in the table keyword set.
757  // This can be used in selecting rows from a table using
758  // <src>operator()</src> described below.
759  // <br>The functions taking the fieldNames vector are meant for
760  // the cases where the keyword or column contains records.
761  // The fieldNames indicate which field to take from that record
762  // (which can be a record again, etc.).
763  // <group name=keycol>
764  TableExprNode key (const String& keywordName) const;
765  TableExprNode key (const Vector<String>& fieldNames) const;
766  TableExprNode col (const String& columnName) const;
767  TableExprNode col (const String& columnName,
768  const Vector<String>& fieldNames) const;
769  TableExprNode keyCol (const String& name,
770  const Vector<String>& fieldNames) const;
771  // </group>
772 
773  // Create a TableExprNode object for the rownumber function.
774  // 'origin' Indicates which rownumber is the first.
775  // C++ uses origin = 0 (default)
776  // Glish and TaQL both use origin = 1
777  TableExprNode nodeRownr (uInt origin=0) const;
778 
779  // Create a TableExprNode object for the rand function.
780  TableExprNode nodeRandom () const;
781 
782  // Select rows from a table using an select expression consisting
783  // of TableExprNode objects.
784  // Basic TableExprNode objects can be created with the functions
785  // <linkto file="Table.h#keycol">key</linkto> and especially
786  // <linkto file="Table.h#keycol">col</linkto>.
787  // Composite TableExprNode objects, representing an expression,
788  // can be created by applying operations (like == and +)
789  // to the basic ones. This is described in class
790  // <linkto class="TableExprNode:description">TableExprNode</linkto>.
791  // For example:
792  // <srcblock>
793  // Table result = tab(tab.col("columnName") > 10);
794  // </srcblock>
795  // All rows for which the expression is true, will be selected and
796  // "stored" in the result.
797  // You need to include ExprNode.h for this purpose.
798  // <br>The first <src>offset</src> matching rows will be skipped.
799  // <br>If <src>maxRow>0</src>, the selection process will stop
800  // when <src>maxRow</src> rows are selected.
801  // <br>The TableExprNode argument can be empty (null) meaning that only
802  // the <src>maxRow/offset</src> arguments are taken into account.
803  Table operator() (const TableExprNode&, uInt maxRow=0, uInt offset=0) const;
804 
805  // Select rows using a vector of row numbers.
806  // This can, for instance, be used to select the same rows as
807  // were selected in another table (using the rowNumbers function).
808  // <srcblock>
809  // Table result = thisTable (otherTable.rowNumbers());
810  // </srcblock>
811  Table operator() (const Vector<uInt>& rownrs) const;
812 
813  // Select rows using a mask block.
814  // The length of the block must match the number of rows in the table.
815  // If an element in the mask is True, the corresponding row will be
816  // selected.
817  Table operator() (const Block<Bool>& mask) const;
818 
819  // Project the given columns (i.e. select the columns).
820  Table project (const Block<String>& columnNames) const;
821 
822  //# Virtually concatenate all tables in this column.
823  //# The column cells must contain tables with the same description.
824 //#// Table concatenate (const String& columnName) const;
825 
826  // Do logical operations on a table.
827  // It can be used for row-selected or projected (i.e. column-selected)
828  // tables. The tables involved must come from the same root table or
829  // be the root table themselves.
830  // <group>
831  // Intersection with another table.
832  Table operator& (const Table&) const;
833  // Union with another table.
834  Table operator| (const Table&) const;
835  // Subtract another table.
836  Table operator- (const Table&) const;
837  // Xor with another table.
838  Table operator^ (const Table&) const;
839  // Take complement.
840  Table operator! () const;
841  // </group>
842 
843  // Sort a table on one or more columns of scalars.
844  // Per column a compare function can be provided. By default
845  // the standard compare function defined in Compare.h will be used.
846  // Default sort order is ascending.
847  // Default sorting algorithm is the parallel sort.
848  // <group>
849  // Sort on one column.
850  Table sort (const String& columnName,
851  int = Sort::Ascending,
852  int = Sort::ParSort) const;
853  // Sort on multiple columns. The principal column has to be the
854  // first element in the Block of column names.
855  Table sort (const Block<String>& columnNames,
856  int = Sort::Ascending,
857  int = Sort::ParSort) const;
858  // Sort on multiple columns. The principal column has to be the
859  // first element in the Block of column names.
860  // The order can be given per column.
861  Table sort (const Block<String>& columnNames,
862  const Block<Int>& sortOrders,
863  int = Sort::ParSort) const;
864  // Sort on multiple columns. The principal column has to be the
865  // first element in the Block of column names.
866  // The order can be given per column.
867  // Provide some special comparisons via CountedPtrs of compare objects.
868  // A null CountedPtr means using the standard compare object
869  // from class <linkto class="ObjCompare:description">ObjCompare</linkto>.
870  Table sort (const Block<String>& columnNames,
871  const Block<CountedPtr<BaseCompare> >& compareObjects,
872  const Block<Int>& sortOrders,
873  int = Sort::ParSort) const;
874  // </group>
875 
876  // Get a vector of row numbers in the root table of rows in this table.
877  // In case the table is a subset of the root table, this tells which
878  // rows of the root table are part of the subset.
879  // In case the table is the root table itself, the result is a vector
880  // containing the row numbers 0 .. #rows-1.
881  // <br>Note that in general it is better to use the next
882  // <src>rowNumbers(Table)</src> function.
883  Vector<uInt> rowNumbers() const;
884 
885  // Get a vector of row numbers in that table of rows in this table.
886  // In case the table is a subset of that table, this tells which
887  // rows of that table are part of the subset.
888  // In case the table is that table itself, the result is a vector
889  // containing the row numbers 0 .. #rows-1.
890  // <note role=caution>This function is in principle meant for cases
891  // where this table is a subset of that table. However, it can be used
892  // for any table. In that case the returned vector contains a very high
893  // number (max_uint) for rows in this table not part of that table.
894  // In that way they are invalid if used elsewhere.
895  // <br>In the general case creating the row number vector can be slowish,
896  // because it has to do two mappings. However, if this table is a subset
897  // of that table and if they are in the same order, the mapping can be done
898  // in a more efficient way. The argument <src>tryFast</src> can be used to
899  // tell the function to try a fast conversion first. If that cannot be done,
900  // it reverts to the slower way at the expense of an unsuccessful fast
901  // attempt.
902  // </note>
903  // <srcblock>
904  // Table tab("somename");
905  // Table subset = tab(some_select_expression);
906  // Vector<uInt> rownrs = subset.rowNumbers(tab);
907  // </srcblock>
908  // Note that one cannot be sure that table "somename" is the root
909  // (i.e. original) table. It may also be a subset of another table.
910  // In the latter case doing
911  // <br> <src> Vector<uInt> rownrs = subset.rowNumbers()</src>
912  // does not give the row numbers in <src>tab</src>, but in the root table
913  // (which is probably not what you want).
914  Vector<uInt> rowNumbers (const Table& that, Bool tryFast=False) const;
915 
916  // Add a column to the table.
917  // The data manager used for the column depend on the function used.
918  // Exceptions are thrown if the column already exist or if the
919  // table is not writable.
920  // <br>If this table is a reference table (result of selection) and if
921  // <src>addToParent=True</src> the column is also added to the parent
922  // table.
923  // <group>
924  // Use the first appropriate existing storage manager.
925  // If there is none, a data manager is created using the default
926  // data manager in the column description.
927  void addColumn (const ColumnDesc& columnDesc,
928  Bool addToParent = True);
929  // Use an existing data manager with the given name or type.
930  // If the flag byName is True, a name is given, otherwise a type.
931  // If a name is given, an exception is thrown if the data manager is
932  // unknown or does not allow addition of columns.
933  // If a type is given, a storage manager of the given type will be
934  // created if there is no such data manager allowing addition of rows.
935  void addColumn (const ColumnDesc& columnDesc,
936  const String& dataManager, Bool byName,
937  Bool addToParent = True);
938  // Use the given data manager (which is a new one).
939  void addColumn (const ColumnDesc& columnDesc,
940  const DataManager& dataManager,
941  Bool addToParent = True);
942  // </group>
943 
944  // Add a bunch of columns using the given new data manager.
945  // All columns and possible hypercolumn definitions in the given table
946  // description will be copied and added to the table.
947  // This can be used in case of specific data managers which need to
948  // be created with more than one column (e.g. the tiled hypercube
949  // storage managers).
950  // <br>The data manager can be given directly or by means of a record
951  // describing the data manager in the standard way with the fields
952  // TYPE, NAME, and SPEC. The record can contain those fields itself
953  // or it can contain a single subrecord with those fields.
954  // <br>If this table is a reference table (result of selection) and if
955  // <src>addToParent=True</src> the columns are also added to the parent
956  // table.
957  // <group>
958  void addColumn (const TableDesc& tableDesc,
959  const DataManager& dataManager,
960  Bool addToParent = True);
961  void addColumn (const TableDesc& tableDesc,
962  const Record& dataManagerInfo,
963  Bool addToParent = True);
964  // </group>
965 
966  // Test if columns can be removed.
967  // It can if the columns exist and if the data manager it is using
968  // supports removal of columns or if all columns from a data manager
969  // would be removed..
970  // <br>You can always remove columns from a reference table.
971  // <group>
972  Bool canRemoveColumn (const String& columnName) const;
973  Bool canRemoveColumn (const Vector<String>& columnNames) const;
974  // </group>
975 
976  // Remove columns.
977  // <br>When removing columns from a reference table, the columns
978  // are NOT removed from the underlying table.
979  // <group>
980  void removeColumn (const String& columnName);
981  void removeColumn (const Vector<String>& columnName);
982  // </group>
983 
984  // Test if a column can be renamed.
985  Bool canRenameColumn (const String& columnName) const;
986 
987  // Rename a column.
988  // An exception is thrown if the old name does not exist or
989  // if the name already exists.
990  // <note role=caution>
991  // Renaming a column should be done with care, because other
992  // columns may be referring this column. Also a hypercolumn definition
993  // might be using the old name.
994  // Finally if may also invalidate persistent selections of a table,
995  // because the reference table cannot find the column anymore.
996  // </note>
997  void renameColumn (const String& newName, const String& oldName);
998 
999  void renameHypercolumn (const String& newName, const String& oldName);
1000 
1001  // Write a table to AipsIO (for <src>TypedKeywords<Table></src>).
1002  // This will only write the table name.
1003  friend AipsIO& operator<< (AipsIO&, const Table&);
1004 
1005  // Read a table from AipsIO (for <src>TypedKeywords<Table></src>).
1006  // This will read the table name and open the table as writable
1007  // if the table file is writable, otherwise as readonly.
1008  friend AipsIO& operator>> (AipsIO&, Table&);
1009 
1010  // Read a table from AipsIO (for <src>TableKeywords</src>).
1011  // This will read the table name and open the table as writable
1012  // if the switch is set and if the table file is writable.
1013  // otherwise it is opened as readonly.
1014  void getTableKeyword (AipsIO&, Bool openWritable);
1015 
1016  // Write a table to ostream (for <src>TypedKeywords<Table></src>).
1017  // This only shows its name and number of columns and rows.
1018  friend ostream& operator<< (ostream&, const Table&);
1019 
1020  // Find the data manager with the given name or for the given column name.
1021  DataManager* findDataManager (const String& name,
1022  Bool byColumn=False) const;
1023 
1024 
1025 protected:
1026  BaseTable* baseTabPtr_p; //# ptr to table representation
1027  //# The isCounted_p flag is normally true.
1028  //# Only for internally used Table objects (i.e. in the DataManager)
1029  //# this flag is False, otherwise a mutual dependency would exist.
1030  //# The DataManager has a Table object, which gets deleted by the
1031  //# DataManager destructor. The DataManager gets deleted by the
1032  //# PlainTable destructor, which gets called when the last Table
1033  //# object gets destructed. That would never be the case if this
1034  //# internally used Table object was counted.
1036  //# Counter of last call to hasDataChanged.
1038  //# Pointer to the ScratchCallback function.
1040 
1041 
1042  // Construct a Table object from a BaseTable*.
1043  // By default the object gets counted.
1044  Table (BaseTable*, Bool countIt = True);
1045 
1046  // Open an existing table.
1047  void open (const String& name, const String& type, int tableOption,
1048  const TableLock& lockOptions, const TSMOption& tsmOpt);
1049 
1050 
1051 private:
1052  // Construct a BaseTable object from the table file.
1053  static BaseTable* makeBaseTable (const String& name, const String& type,
1054  int tableOption,
1055  const TableLock& lockOptions,
1056  const TSMOption& tsmOpt,
1057  Bool addToCache, uInt locknr);
1058 
1059 
1060  // Get the pointer to the underlying BaseTable.
1061  // This is needed for some friend classes.
1062  BaseTable* baseTablePtr() const;
1063 
1064  // Look in the cache if the table is already open.
1065  // If so, check if table option matches.
1066  // If needed reopen the table for read/write and merge the lock options.
1067  BaseTable* lookCache (const String& name, int tableOption,
1068  const TableLock& tableInfo);
1069 
1070  // Try if v1 is a subset of v2 and fill rows with its indices in v2.
1071  // Return False if not a proper subset.
1072  Bool fastRowNumbers (const Vector<uInt>& v1, const Vector<uInt>& v2,
1073  Vector<uInt>& rows) const;
1074 
1075  // Show the info of the given columns.
1076  // Sort the columns if needed.
1077  void showColumnInfo (ostream& os, const TableDesc&, uInt maxNameLength,
1078  const Array<String>& columnNames, Bool sort) const;
1079 };
1080 
1081 
1082 
1083 inline Bool Table::isSameRoot (const Table& other) const
1084  { return baseTabPtr_p->root() == other.baseTabPtr_p->root(); }
1085 
1086 inline void Table::reopenRW()
1087  { baseTabPtr_p->reopenRW(); }
1088 inline void Table::flush (Bool fsync, Bool recursive)
1089  { baseTabPtr_p->flush (fsync, recursive); }
1090 inline void Table::resync()
1091  { baseTabPtr_p->resync(); }
1092 
1094  { return baseTabPtr_p->storageOption(); }
1095 inline Bool Table::isMultiUsed(Bool checkSubTables) const
1096  { return baseTabPtr_p->isMultiUsed(checkSubTables); }
1097 inline const TableLock& Table::lockOptions() const
1098  { return baseTabPtr_p->lockOptions(); }
1099 inline Bool Table::lock (FileLocker::LockType type, uInt nattempts)
1100  { return baseTabPtr_p->lock (type, nattempts); }
1101 inline Bool Table::lock (Bool write, uInt nattempts)
1102 {
1104  nattempts);
1105 }
1106 inline void Table::unlock()
1107  { baseTabPtr_p->unlock(); }
1109  { return baseTabPtr_p->hasLock (type); }
1110 inline Bool Table::hasLock (Bool write) const
1111 {
1113 }
1114 
1115 inline Bool Table::isRootTable() const
1116  { return baseTabPtr_p == baseTabPtr_p->root(); }
1117 
1118 inline Bool Table::isWritable() const
1119  { return baseTabPtr_p->isWritable(); }
1120 inline Bool Table::isColumnWritable (const String& columnName) const
1121  { return baseTabPtr_p->isColumnWritable (columnName); }
1122 inline Bool Table::isColumnWritable (uInt columnIndex) const
1123  { return baseTabPtr_p->isColumnWritable (columnIndex); }
1124 
1125 inline Bool Table::isColumnStored (const String& columnName) const
1126  { return baseTabPtr_p->isColumnStored (columnName); }
1127 inline Bool Table::isColumnStored (uInt columnIndex) const
1128  { return baseTabPtr_p->isColumnStored (columnIndex); }
1129 
1130 inline void Table::rename (const String& newName, TableOption option)
1131  { baseTabPtr_p->rename (newName, option); }
1132 inline void Table::deepCopy (const String& newName,
1133  const Record& dataManagerInfo,
1134  TableOption option,
1135  Bool valueCopy,
1137  Bool noRows) const
1138  { baseTabPtr_p->deepCopy (newName, dataManagerInfo, option, valueCopy,
1139  endianFormat, noRows); }
1141  { baseTabPtr_p->markForDelete (True, ""); }
1143  { baseTabPtr_p->unmarkForDelete(True, ""); }
1145  { return baseTabPtr_p->isMarkedForDelete(); }
1146 
1147 inline uInt Table::nrow() const
1148  { return baseTabPtr_p->nrow(); }
1150  { return baseTabPtr_p; }
1151 inline const TableDesc& Table::tableDesc() const
1152  { return baseTabPtr_p->tableDesc(); }
1153 inline const TableRecord& Table::keywordSet() const
1154  { return baseTabPtr_p->keywordSet(); }
1155 
1156 inline TableInfo Table::tableInfo (const String& tableName)
1157  { return BaseTable::tableInfo (tableName); }
1158 inline const TableInfo& Table::tableInfo() const
1159  { return baseTabPtr_p->tableInfo(); }
1161  { return baseTabPtr_p->tableInfo(); }
1162 inline void Table::flushTableInfo() const
1164 
1165 inline const String& Table::tableName() const
1166  { return baseTabPtr_p->tableName(); }
1168  { return TableType(baseTabPtr_p->tableType()); }
1169 inline int Table::tableOption() const
1170  { return baseTabPtr_p->tableOption(); }
1171 
1172 inline Bool Table::canAddRow() const
1173  { return baseTabPtr_p->canAddRow(); }
1175  { return baseTabPtr_p->canRemoveRow(); }
1176 inline Bool Table::canRemoveColumn (const Vector<String>& columnNames) const
1177  { return baseTabPtr_p->canRemoveColumn (columnNames); }
1178 inline Bool Table::canRenameColumn (const String& columnName) const
1179  { return baseTabPtr_p->canRenameColumn (columnName); }
1180 
1181 inline void Table::addRow (uInt nrrow, Bool initialize)
1182  { baseTabPtr_p->addRow (nrrow, initialize); }
1183 inline void Table::removeRow (uInt rownr)
1184  { baseTabPtr_p->removeRow (rownr); }
1185 inline void Table::removeRow (const Vector<uInt>& rownrs)
1186  { baseTabPtr_p->removeRow (rownrs); }
1187 inline void Table::addColumn (const ColumnDesc& columnDesc, Bool addToParent)
1188  { baseTabPtr_p->addColumn (columnDesc, addToParent); }
1189 inline void Table::addColumn (const ColumnDesc& columnDesc,
1190  const String& dataManager, Bool byName,
1191  Bool addToParent)
1192  { baseTabPtr_p->addColumn (columnDesc, dataManager, byName, addToParent); }
1193 inline void Table::addColumn (const ColumnDesc& columnDesc,
1194  const DataManager& dataManager, Bool addToParent)
1195  { baseTabPtr_p->addColumn (columnDesc, dataManager, addToParent); }
1197  const DataManager& dataManager, Bool addToParent)
1198  { baseTabPtr_p->addColumn (tableDesc, dataManager, addToParent); }
1200  const Record& dataManagerInfo, Bool addToParent) { baseTabPtr_p->addColumns (tableDesc, dataManagerInfo, addToParent); }
1201 inline void Table::removeColumn (const Vector<String>& columnNames)
1202  { baseTabPtr_p->removeColumn (columnNames); }
1203 inline void Table::renameColumn (const String& newName, const String& oldName)
1204  { baseTabPtr_p->renameColumn (newName, oldName); }
1205 inline void Table::renameHypercolumn (const String& newName, const String& oldName)
1206  { baseTabPtr_p->renameHypercolumn (newName, oldName); }
1207 
1209  Bool byColumn) const
1210 {
1211  return baseTabPtr_p->findDataManager (name, byColumn);
1212 }
1213 
1214 inline void Table::showStructure (std::ostream& os,
1215  Bool showDataMans,
1216  Bool showColumns,
1217  Bool showSubTables,
1218  Bool sortColumns) const
1219  { baseTabPtr_p->showStructure (os, showDataMans, showColumns,
1220  showSubTables, sortColumns); }
1221 
1222 
1223 
1224 } //# NAMESPACE CASACORE - END
1225 
1226 #endif
virtual void renameHypercolumn(const String &newName, const String &oldName)=0
Rename a hypercolumn.
void markForDelete()
Mark the table for delete.
Definition: Table.h:1140
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:1181
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.
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:1083
void renameColumn(const String &newName, const String &oldName)
Rename a column.
Definition: Table.h:1203
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:259
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:1125
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:1026
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:1120
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:578
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
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:1169
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:1151
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:1108
Abstract base class for a node in a table column expression tree.
Definition: ExprNodeRep.h:150
static ScratchCallback * scratchCallback_p
Definition: Table.h:1039
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:1183
virtual void deepCopy(const String &newName, const Record &dataManagerInfo, int tableOption, Bool valueCopy, int endianFormat, Bool noRows) const
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:1174
Table operator^(const Table &) const
Xor with another table.
uInt lastModCounter_p
Definition: Table.h:1037
Table operator &(const Table &) const
Do logical operations on a table.
int tableOption() const
Get the table option.
Definition: BaseTable.h:240
virtual ~Table()
The destructor flushes (i.e.
void flushTableInfo() const
Write the TableInfo object.
Definition: Table.h:1162
void showStructure(std::ostream &, Bool showDataMans=True, Bool showColumns=True, Bool showSubTables=False, Bool sortColumns=False) const
Show the structure of the table.
Definition: Table.h:1214
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:1130
Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed.
Definition: Table.h:1178
BaseTable * baseTablePtr() const
Get the pointer to the underlying BaseTable.
Definition: Table.h:1149
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:1205
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:1035
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:255
TableType tableType() const
Get the table type.
Definition: Table.h:1167
const TableLock & lockOptions() const
Get the locking options.
Definition: Table.h:1097
void resync()
Resynchronize the Table object with the table file.
Definition: Table.h:1090
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:1118
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:1142
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:295
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:181
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
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:1099
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:1208
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:41
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:1095
void showStructure(std::ostream &, Bool showDataMan, Bool showColumns, Bool showSubTables, Bool sortColumns)
Show the table structure (implementation of Table::showStructure).
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:1144
Base class for the Data Manager Accessor classes.
uInt nrow() const
Get the number of rows.
Definition: Table.h:1147
Bool canAddRow() const
Test if it is possible to add a row to this table.
Definition: Table.h:1172
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:1093
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:1153
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.
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:1158
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:1115
virtual void addColumn(const ColumnDesc &columnDesc, Bool addToParent)
Add one or more columns to the table.
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:1165
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:1086
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:1187
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:40
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:284
void flush(Bool fsync=False, Bool recursive=False)
Flush the table, i.e.
Definition: Table.h:1088
unsigned int uInt
Definition: aipstype.h:48
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:1106
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.