casa::Table Class Reference
[Tables]

#include <Table.h>

Inheritance diagram for casa::Table:

[legend]Collaboration diagram for casa::Table:

[legend]List of all members.

---

Detailed Description

Main interface class to a read/write table.

Intended use:

Part of API

Review Status

Reviewed By:

TPPR

Date Reviewed:

08.11.94

Test programs:

tTable

Prerequisite

• SetupNewTable
• TableDesc
• TableColumn
• ScalarColumn
• ArrayColum
• TableLock

Synopsis

Class Table can be used to create a new table or to access an existing table in read/write or readonly mode.

To access the data in a Table, objects have to be created to access the columns. These objects are TableColumn, ScalarColumn<T> and ArrayColumn<T>, which can be created via their constructors. Furthermore the Table has a TableRecord object for holding keywords which can be read or written using the appropriate functions.

To open an existing table, a simple Table constructor can be used. The possible construct options are:

• Old readonly table (default option)
• Update update existing table
• Delete delete table

Creating a new table requires more work, because columns have to be bound to storage managers or virtual column engines. Class SetupNewTable is needed for this purpose. The Tables module documentation explains in more detail how to create a table. When creating a table, it can be specified which endian format to use. By default it uses the format specified in the aipsrc variable table.endianformat which defaults to Table::LocalEndian (thus the endian format of the machine being used).

Other Table objects can be created from a Table using the select, project and sort functions. In that way a subset of the table can be created and it can be read/written in the same way as a normal Table. However, writing has the effect that the underlying table gets written.

Example

    // Open a table to be updated.
    Table myTable ("theTable", Table::Update);
    // Write the column containing the scalar RA.
    ScalarColumn<double> raColumn(myTable, "RA");
    uInt nrrow = myTable.nrow();
    for (uInt i=0; i<nrrow; i++) {
       raColumn.put (i, i+10);    // Put value i+10 into row i
    }

Motivation

Table is the envelope for the underlying counted referenced classes derived from BaseTable. In this way no pointers have to be used to get polymorphism.

To Do

• add, remove, rename columns.
• virtual concatenation of tables (if still necessary).
• maybe an isAttached function.

Definition at line 137 of file Table.h.

Public Types
enum	TableOption
enum	TableType
enum	EndianFormat
typedef 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.e.
Public Member Functions
	Table ()
	Create a null Table object (i.e.
	Table (TableType, EndianFormat=Table::AipsrcEndian)
	Make a new empty table (plain (scratch) or memory type).
	Table (const Table &)
	Copy constructor (reference semantics).
	~Table ()
	The destructor flushes (i.e.
Table &	operator= (const Table &)
	Assignment (reference semantics).
Bool	isSameRoot (const Table &other) const
	Is the root table of this table the same as that of the other one?
void	closeSubTables () const
	Close all open subtables.
void	reopenRW ()
	Try to reopen the table for read/write access.
Table::EndianFormat	endianFormat () const
	Get the endian format in which the table is stored.
Bool	isMultiUsed (Bool checkSubTables=False) const
	Is the table used (i.e.
const TableLock &	lockOptions () const
	Get the locking options.
void	unlock ()
	Unlock the table.
Bool	hasDataChanged ()
	Determine if column or keyword table data have changed (or is being changed) since the last time this function was called.
void	flush (Bool fsync=False, Bool recursive=False)
	Flush the table, i.e.
void	resync ()
	Resynchronize the Table object with the table file.
Bool	isNull () const
	Test if the object is null, i.e.
void	throwIfNull () const
	Throw an exception if the object is null, i.e.
Bool	isRootTable () const
	Test if this table is the root table (ie.
Bool	isWritable () const
	Test if this table is opened as writable.
const TableRecord &	keywordSet () const
	Get readonly access to the table keyword set.
TableRecord &	rwKeywordSet ()
	Get read/write access to the table keyword set.
void	flushTableInfo () const
	Write the TableInfo object.
Record	dataManagerInfo () const
	Return all data managers used and the columns served by them.
const String &	tableName () const
	Get the table name.
void	rename (const String &newName, TableOption)
	Rename the table and all its subtables.
Table	copyToMemoryTable (const String &name, Bool noRows=False) const
	Make a copy of a table to a MemoryTable object.
TableType	tableType () const
	Get the table type.
int	tableOption () const
	Get the table option.
void	markForDelete ()
	Mark the table for delete.
void	unmarkForDelete ()
	Unmark the table for delete.
Bool	isMarkedForDelete () const
	Test if the table is marked for delete.
uInt	nrow () const
	Get the number of rows.
Bool	canAddRow () const
	Test if it is possible to add a row to this table.
void	addRow (uInt nrrow=1, Bool initialize=False)
	Add one or more rows at the end of the table.
Bool	canRemoveRow () const
	Test if it is possible to remove a row from this table.
TableExprNode	nodeRownr (uInt origin=0) const
	Create a TableExprNode object for the rownumber function.
TableExprNode	nodeRandom () const
	Create a TableExprNode object for the rand function.
Table	operator() (const TableExprNode &, uInt maxRow=0) const
	Select rows from a table using an select expression consisting of TableExprNode objects.
Table	operator() (const Vector< uInt > &rownrs) const
	Select rows using a vector of row numbers.
Table	operator() (const Block< Bool > &mask) const
	Select rows using a mask block.
Table	project (const Block< String > &columnNames) const
	Project the given columns (i.e.
Vector< uInt >	rowNumbers () const
	Get a vector of row numbers in the root table of rows in this table.
Vector< uInt >	rowNumbers (const Table &that) const
	Get a vector of row numbers in that table of rows in this table.
Bool	canRenameColumn (const String &columnName) const
	Test if a column can be renamed.
void	renameColumn (const String &newName, const String &oldName)
	Rename a column.
void	getTableKeyword (AipsIO &, Bool openWritable)
	Read a table from AipsIO (for TableKeywords).
	Table (const String &tableName, TableOption=Table::Old)
	Create a table object for an existing writable table.
	Table (const String &tableName, const TableLock &lockOptions, TableOption=Table::Old)
	Table (const String &tableName, const String &tableDescName, TableOption=Table::Old)
	Table (const String &tableName, const String &tableDescName, const TableLock &lockOptions, TableOption=Table::Old)
	Table (SetupNewTable &, uInt nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian)
	Make a table object for a new table, which can thereafter be used for reading and writing.
	Table (SetupNewTable &, TableType, uInt nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian)
	Table (SetupNewTable &, TableType, const TableLock &lockOptions, uInt nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian)
	Table (SetupNewTable &, TableLock::LockOption, uInt nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian)
	Table (SetupNewTable &, const TableLock &lockOptions, uInt nrrow=0, Bool initialize=False, EndianFormat=Table::AipsrcEndian)
Bool	hasLock (FileLocker::LockType=FileLocker::Write) const
	Has this process the read or write lock, thus can the table be read or written safely?
Bool	hasLock (Bool write) const
Bool	lock (FileLocker::LockType=FileLocker::Write, uInt nattempts=0)
	Try to lock the table for read or write access (default is write).
Bool	lock (Bool write, uInt nattempts=0)
Bool	isColumnWritable (const String &columnName) const
	Test if the given column is writable.
Bool	isColumnWritable (uInt columnIndex) const
Bool	isColumnStored (const String &columnName) const
	Test if the given column is stored (otherwise it is virtual).
Bool	isColumnStored (uInt columnIndex) const
const TableInfo &	tableInfo () const
	Get access to the TableInfo object.
TableInfo &	tableInfo ()
const TableDesc &	tableDesc () const
	Get the table description.
TableDesc	actualTableDesc () const
void	copy (const String &newName, TableOption, Bool noRows=False) const
	Copy the table and all its subtables.
void	deepCopy (const String &newName, TableOption, Bool valueCopy=False, EndianFormat=AipsrcEndian, Bool noRows=False) const
void	deepCopy (const String &newName, const Record &dataManagerInfo, TableOption, Bool valueCopy=False, EndianFormat=AipsrcEndian, Bool noRows=False) const
void	removeRow (uInt rownr)
	Remove the given row(s).
void	removeRow (const Vector< uInt > &rownrs)
TableExprNode	key (const String &keywordName) const
	Create a TableExprNode object for a column or for a keyword in the table keyword set.
TableExprNode	key (const Vector< String > &fieldNames) const
TableExprNode	col (const String &columnName) const
TableExprNode	col (const String &columnName, const Vector< String > &fieldNames) const
TableExprNode	keyCol (const String &name, const Vector< String > &fieldNames) const
Table	operator & (const Table &) const
	Do logical operations on a table.
Table	operator| (const Table &) const
	Union with another table.
Table	operator- (const Table &) const
	Subtract another table.
Table	operator^ (const Table &) const
	Xor with another table.
Table	operator! () const
	Take complement.
Table	sort (const String &columnName, int=Sort::Ascending, int=Sort::HeapSort) const
	Sort a table on one or more columns of scalars.
Table	sort (const Block< String > &columnNames, int=Sort::Ascending, int=Sort::HeapSort) const
	Sort on multiple columns.
Table	sort (const Block< String > &columnNames, const Block< Int > &sortOrders, int=Sort::HeapSort) const
	Sort on multiple columns.
Table	sort (const Block< String > &columnNames, const PtrBlock< ObjCompareFunc * > &compareFunctionPointers, const Block< Int > &sortOrders, int=Sort::HeapSort) const
	Sort on multiple columns.
void	addColumn (const ColumnDesc &columnDesc)
	Add a column to the table.
void	addColumn (const ColumnDesc &columnDesc, const String &dataManager, Bool byName)
	Use an existing data manager with the given name or type.
void	addColumn (const ColumnDesc &columnDesc, const DataManager &dataManager)
	Use the given data manager (which is a new one).
void	addColumn (const TableDesc &tableDesc, const DataManager &dataManager)
	Add a bunch of columns using the given new data manager.
void	addColumn (const TableDesc &tableDesc, const Record &dataManagerInfo)
Bool	canRemoveColumn (const String &columnName) const
	Test if columns can be removed.
Bool	canRemoveColumn (const Vector< String > &columnNames) const
void	removeColumn (const String &columnName)
	Remove columns.
void	removeColumn (const Vector< String > &columnName)
Static Public Member Functions
static ScratchCallback *	setScratchCallback (ScratchCallback *)
	Set the pointer to the ScratchCallback function.
static void	deleteTable (const String &tableName, Bool checkSubTables=False)
	Delete the table.
static Bool	isOpened (const String &tableName)
	Is the table used (i.e.
static uInt	nAutoLocks ()
	Determine the number of locked tables opened with the AutoLock option (Locked table means locked for read and/or write).
static void	relinquishAutoLocks (Bool all=False)
	Unlock locked tables opened with the AutoLock option.
static Bool	isNativeDataType (DataType dtype)
	Test if the given data type is native to the table system.
static String	fileName (const String &tableName)
	Make the table file name.
static Bool	isReadable (const String &tableName)
	Test if a table with the given name exists and is readable.
static uInt	getLayout (TableDesc &desc, const String &tableName)
	Return the layout of a table (i.e.
static TableInfo	tableInfo (const String &tableName)
	Get the table info of the table with the given name.
static Bool	isWritable (const String &tableName)
	Test if a table with the given name exists and is writable.
static Vector< String >	nonWritableFiles (const String &tableName)
	Find the non-writable files in a table.
static Bool	canDeleteTable (const String &tableName, Bool checkSubTables=False)
	Can the table be deleted? If true, function deleteTable can safely be called.
static Bool	canDeleteTable (String &message, const String &tableName, Bool checkSubTables=False)
Protected Member Functions
	Table (BaseTable *, Bool countIt=True)
	Construct a Table object from a BaseTable*.
void	open (const String &name, const String &type, int tableOption, const TableLock &lockOptions)
	Open an existing table.
Protected Attributes
BaseTable *	baseTabPtr_p
Bool	isCounted_p
uInt	lastModCounter_p
Static Protected Attributes
static ScratchCallback *	scratchCallback_p
Private Member Functions
BaseTable *	baseTablePtr () const
	Get the pointer to the underlying BaseTable.
BaseTable *	lookCache (const String &name, int tableOption, const TableLock &tableInfo)
	Look in the cache if the table is already open.
DataManager *	findDataManager (const String &datamanagerName) const
	Find the data manager with the given name.
Static Private Member Functions
static BaseTable *	makeBaseTable (const String &name, const String &type, int tableOption, const TableLock &lockOptions, Bool addToCache, uInt locknr)
	Construct a BaseTable object from the table file.
Friends
class	ROTableColumn
class	BaseTable
class	PlainTable
class	MemoryTable
class	RefTable
class	TableIterator
class	RODataManAccessor
class	TableExprNode
class	TableExprNodeRep
AipsIO &	operator<< (AipsIO &, const Table &)
	Write a table to AipsIO (for TypedKeywords<Table>).
AipsIO &	operator>> (AipsIO &, Table &)
	Read a table from AipsIO (for TypedKeywords<Table>).
ostream &	operator<< (ostream &, const Table &)
	Write a table to ostream (for TypedKeywords<Table>).

---

Member Typedef Documentation

typedef void casa::Table::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.e.

created, closed, renamed, (un)markForDelete).
- isScratch=True indicates that a scratch table is created (oldName is empty) or renamed (oldName is not empty).
- isScratch=False indicates that a scratch table with name name is not scratch anymore (because it is closed or because its state is set to non-scratch).

Definition at line 192 of file Table.h.

---

Member Enumeration Documentation

enum casa::Table::TableOption

Definition at line 150 of file Table.h.

enum casa::Table::TableType

Definition at line 165 of file Table.h.

enum casa::Table::EndianFormat

Definition at line 172 of file Table.h.

---

Constructor & Destructor Documentation

casa::Table::Table

(

)

Create a null Table object (i.e.

no table is attached yet). The sole purpose of this constructor is to allow construction of an array of Table objects. The assignment operator can be used to make a null object reference a column. Note that sort functions, etc. will cause a segmentation fault when operating on a null object. It was felt it was too expensive to test on null over and over again. The user should use the isNull or throwIfNull function in case of doubt.

casa::Table::Table	(	const String &	tableName,
		TableOption	= Table::Old
	)			[explicit]

Create a table object for an existing writable table.

The only options allowed are Old, Update, and Delete. When the name of a table description is given, it is checked if the table has that description. Locking options can be given (see class TableLock . When the table with this name was already opened in this process, the existing and new locking options are merged using TableLock::merge. The default locking mechanism is DefaultLocking. When the table is not open yet, it comes to AutoLocking with an inspection interval of 5 seconds. Otherwise DefaultLocking keeps the locking options of the already open table.

casa::Table::Table	(	const String &	tableName,
		const TableLock &	lockOptions,
		TableOption	= Table::Old
	)

casa::Table::Table	(	const String &	tableName,
		const String &	tableDescName,
		TableOption	= Table::Old
	)

casa::Table::Table	(	const String &	tableName,
		const String &	tableDescName,
		const TableLock &	lockOptions,
		TableOption	= Table::Old
	)

casa::Table::Table	(	TableType	,
		EndianFormat	= Table::AipsrcEndian
	)			[explicit]

Make a new empty table (plain (scratch) or memory type).

Columns should be added to make it a real one. Note that the endian format is only relevant for plain tables.

casa::Table::Table	(	SetupNewTable &	,
		uInt	nrrow = 0,
		Bool	initialize = False,
		EndianFormat	= Table::AipsrcEndian
	)			[explicit]

Make a table object for a new table, which can thereafter be used for reading and writing.

If there are unbound columns, default storage managers an/ord virtual column engines will be created and bound to those columns. Create the table with the given nr of rows. If a storage manager is used which does not allow addition of rows, the number of rows in the table must already be given here. Optionally the rows can be initialized with the default values as defined in the column descriptions. Locking options can be given (see class TableLock . The default locking mechanism is AutoLocking with a default inspection interval of 5 seconds.
The data will be stored in the given endian format.

casa::Table::Table	(	SetupNewTable &	,
		TableType	,
		uInt	nrrow = 0,
		Bool	initialize = False,
		EndianFormat	= Table::AipsrcEndian
	)

casa::Table::Table	(	SetupNewTable &	,
		TableType	,
		const TableLock &	lockOptions,
		uInt	nrrow = 0,
		Bool	initialize = False,
		EndianFormat	= Table::AipsrcEndian
	)

casa::Table::Table	(	SetupNewTable &	,
		TableLock::LockOption	,
		uInt	nrrow = 0,
		Bool	initialize = False,
		EndianFormat	= Table::AipsrcEndian
	)

casa::Table::Table	(	SetupNewTable &	,
		const TableLock &	lockOptions,
		uInt	nrrow = 0,
		Bool	initialize = False,
		EndianFormat	= Table::AipsrcEndian
	)

casa::Table::Table

(

const Table &

)

Copy constructor (reference semantics).

casa::Table::~Table

(

)

The destructor flushes (i.e.

writes) the table if it is opened for output and not marked for delete. It will flush if the destructor is called due to an exception, because the Table object may not be correct. Of course, in that case the flush function could be called explicitly.

casa::Table::Table	(	BaseTable *	,
		Bool	countIt = True
	)			[protected]

Construct a Table object from a BaseTable*.

By default the object gets counted.

---

Member Function Documentation

static ScratchCallback* casa::Table::setScratchCallback

(

ScratchCallback *

)

[static]

Set the pointer to the ScratchCallback function.

It returns the current value of the pointer. This function is called when changing the state of a table (i.e. create, close, rename, (un)markForDelete).

Table& casa::Table::operator=

(

const Table &

)

Assignment (reference semantics).

Bool casa::Table::isSameRoot

(

const Table &

other

)

const [inline]

Is the root table of this table the same as that of the other one?

Definition at line 933 of file Table.h.

References baseTabPtr_p, and casa::BaseTable::root().

static Bool casa::Table::canDeleteTable	(	const String &	tableName,
		Bool	checkSubTables = False
	)			[static]

Can the table be deleted? If true, function deleteTable can safely be called.

If not, message contains the reason why (e.g. 'table is not writable'). It checks if the table is writable, is not open in this process and is not open in another process.
If checkSubTables is set, it also checks if a subtable is not open in another process.

static Bool casa::Table::canDeleteTable	(	String &	message,
		const String &	tableName,
		Bool	checkSubTables = False
	)			[static]

static void casa::Table::deleteTable	(	const String &	tableName,
		Bool	checkSubTables = False
	)			[static]

Delete the table.

An exception is thrown if the table cannot be deleted because its is not writable or because it is still open in this or another process.
If checkSubTables is set, it is also checked if a subtable is used in another process.

void casa::Table::closeSubTables

(

)

const

Close all open subtables.

void casa::Table::reopenRW

(

)

[inline]

Try to reopen the table for read/write access.

An exception is thrown if the table is not writable. Nothing is done if the table is already open for read/write.

Definition at line 936 of file Table.h.

References baseTabPtr_p, and casa::BaseTable::reopenRW().

Table::EndianFormat casa::Table::endianFormat

(

)

const

Get the endian format in which the table is stored.

static Bool casa::Table::isOpened

(

const String &

tableName

)

[static]

Is the table used (i.e.

open) in this process.

Bool casa::Table::isMultiUsed

(

Bool

checkSubTables = False

)

const [inline]

Is the table used (i.e.

open) in another process. If checkSubTables is set, it is also checked if a subtable is used in another process.

Definition at line 943 of file Table.h.

References baseTabPtr_p, and casa::BaseTable::isMultiUsed().

const TableLock & casa::Table::lockOptions

(

)

const [inline]

Get the locking options.

Definition at line 945 of file Table.h.

References baseTabPtr_p, and casa::BaseTable::lockOptions().

Bool casa::Table::hasLock

(

FileLocker::LockType

= FileLocker::Write

)

const [inline]

Has this process the read or write lock, thus can the table be read or written safely?

Definition at line 956 of file Table.h.

References baseTabPtr_p, and casa::BaseTable::hasLock().

Referenced by casa::TableLocker::hasLock().

Bool casa::Table::hasLock

(

Bool

write

)

const [inline]

Definition at line 958 of file Table.h.

References baseTabPtr_p, casa::BaseTable::hasLock(), casa::FileLocker::Read, and casa::FileLocker::Write.

Bool casa::Table::lock	(	FileLocker::LockType	= FileLocker::Write,
		uInt	nattempts = 0
	)			[inline]

Try to lock the table for read or write access (default is write).

The number of attempts (default = forever) can be specified when acquiring the lock does not succeed immediately. When nattempts>1, the system waits 1 second between each attempt, so nattempts is more or less equal to a wait period in seconds. The return value is false when acquiring the lock failed. When PermanentLocking is in effect, a lock is already present, so nothing will be done.

Definition at line 947 of file Table.h.

References baseTabPtr_p, and casa::BaseTable::lock().

Referenced by casa::VisSet::lock().

Bool casa::Table::lock	(	Bool	write,
		uInt	nattempts = 0
	)			[inline]

Definition at line 949 of file Table.h.

References baseTabPtr_p, casa::BaseTable::lock(), casa::FileLocker::Read, and casa::FileLocker::Write.

void casa::Table::unlock

(

)

[inline]

Unlock the table.

This will also synchronize the table data, thus force the data to be written to disk. When PermanentLocking is in effect, nothing will be done.

Definition at line 954 of file Table.h.

References baseTabPtr_p, and casa::BaseTable::unlock().

Referenced by casa::VisSet::unlock().

static uInt casa::Table::nAutoLocks

(

)

[static]

Determine the number of locked tables opened with the AutoLock option (Locked table means locked for read and/or write).

static void casa::Table::relinquishAutoLocks

(

Bool

all = False

)

[static]

Unlock locked tables opened with the AutoLock option.

If all=True all such tables will be unlocked. If all=False only tables requested by another process will be unlocked.

Bool casa::Table::hasDataChanged

(

)

Determine if column or keyword table data have changed (or is being changed) since the last time this function was called.

void casa::Table::flush

(

Bool

fsync =