TableProxy.h

Classes

TableProxy -- High-level interface to tables (full description)

class TableProxy

Interface

Public Members

TableProxy (const Table& table) : table_p (table)

TableProxy (const String& tableName, const Record& lockOptions, int option)

TableProxy (const String& tableName, const Record& lockOptions, const String& endianFormat, const String& memType, int nrow, const Record& tableDesc, const Record& dmInfo)

TableProxy (const String& command, const std::vector<TableProxy>& tables)

TableProxy (const String& fileName, const String& headerName, const String& tableName, Bool autoHeader, const IPosition& autoShape, const String& separator, const String& commentMarker, Int firstLine, Int lastLine)

TableProxy (const TableProxy&)

~TableProxy()

TableProxy& operator= (const TableProxy&)

TableProxy selectRows (const Vector<Int>& rownrs, const String& outName)

void reopenRW()

void resync()

void flush (Bool recursive)

String endianFormat() const

void lock (Bool mode, Int nattempts)

void unlock()

Bool hasDataChanged()

Bool hasLock (Bool mode)

Record lockOptions()

Bool isMultiUsed (Bool checkSubTables)

void rename (const String& newTableName)

TableProxy copy (const String& newTableName, Bool toMemoryTable, Bool deepCopy, Bool valueCopy, const String& endianFormat, const Record& dminfo, Bool noRows)

void copyRows (TableProxy& out, Int startIn, Int startOut, Int nrow)

void deleteTable (Bool checkSubTables)

Record tableInfo()

void putTableInfo (const Record& value)

void addReadmeLine (const String& line)

Bool isReadable() const

Bool isWritable() const

void setMaximumCacheSize (const String& columnName, Int nbytes)

void addColumns (const Record& tableDesc, const Record& dminfo)

void renameColumn (const String& nameOld, const String& nameNew)

void removeColumns (const Vector<String>& columnNames)

void addRow (Int nrow)

void removeRow (const Vector<Int>& rownrs)

ValueHolder getColumn (const String& columnName, Int row, Int nrow, Int incr)

Record getVarColumn (const String& columnName, Int row, Int nrow, Int incr)

ValueHolder getColumnSlice (const String& columnName, const Vector<Int>& blc, const Vector<Int>& trc, const Vector<Int>& inc, Int row, Int nrow, Int incr)

void putColumn (const String& columnName, const ValueHolder&, Int row, Int nrow, Int incr)

void putVarColumn (const String& columnName, const Record& values, Int row, Int nrow, Int incr)

void putColumnSlice (const String& columnName, const ValueHolder&, const Vector<Int>& blc, const Vector<Int>& trc, const Vector<Int>& inc, Int row, Int nrow, Int incr)

Bool cellContentsDefined (const String& columnName, Int rownr)

ValueHolder getCell (const String& columnName, Int row)

ValueHolder getCellSlice (const String& columnName, Int row, const Vector<Int>& blc, const Vector<Int>& trc, const Vector<Int>& inc)

void putCell (const String& columnName, const Vector<Int>& rownrs, const ValueHolder&)

void putCellSlice (const String& columnName, Int row, const ValueHolder&, const Vector<Int>& blc, const Vector<Int>& trc, const Vector<Int>& inc)

Vector<String> getColumnShapeString (const String& columnName, Int rownr, Int nrow, Int incr, Bool cOrder = False)

ValueHolder getKeyword (const String& columnName, const String& keywordName, Int keywordIndex)

Record getKeywordSet (const String& columnName)

void putKeyword (const String& columnName, const String& keywordName, Int keywordIndex, Bool makeSubRecord, const ValueHolder&)

void putKeywordSet (const String& columnName, const Record& valueSet)

void removeKeyword (const String& columnName, const String& keywordName, Int keywordIndex)

Vector<String> getFieldNames (const String& columnName, const String& keywordName, Int keywordIndex)

String tableName()

Int ncolumns()

Int nrows()

Vector<Int> shape()

Vector<Int> rowNumbers (TableProxy& other)

Vector<String> columnNames()

Bool isScalarColumn (const String& columnName)

String columnDataType (const String& columnName)

String columnArrayType (const String& columnName)

Record getDataManagerInfo()

String getAsciiFormat() const

Record getCalcResult() const

Table& table()

const Table& table() const

static Record getKeyValues (const TableRecord& keySet)

static void putKeyValues (TableRecord& keySet, const Record& valueSet)

Private Members

static TableLock makeLockOptions (const Record& options)

static Table::EndianFormat makeEndianFormat (const String& endianFormat)

static Bool makeHC (const Record& gdesc, TableDesc& tabdesc, String& message)

Int checkRowColumn (Table& table, const String& colName, Int rownr, Int nrow, Int incr, const Char* caller)

ValueHolder getValueFromTable (const String& colName, Int rownr, Int nrow, Int incr, Bool isCell)

ValueHolder getValueSliceFromTable(const String& colName, const Slicer& slicer, Int rownr, Int nrow, Int incr, Bool isCell)

void putValueInTable (const String& colName, Int rownr, Int nrow, Int incr, Bool isCell, const ValueHolder&)

void putValueSliceInTable (const String& colName, const Slicer& slicer, Int rownr, Int nrow, Int incr, Bool isCell, const ValueHolder&)

void findKeyId (RecordFieldId& fieldid, const TableRecord*& keySet, const String& keyname, const String& column)

void findKeyId (RecordFieldId& fieldid, TableRecord*& keySet, const String& keyname, const String& column, Bool mustExist, Bool change, Bool makeSubRecord)

static ValueHolder getKeyValue (const TableRecord& keySet, const RecordFieldId& fieldId)

static void putKeyValue (TableRecord& keySet, const RecordFieldId& fieldId, const ValueHolder& value)

static Bool makeTableDesc (const Record& gdesc, TableDesc& tabdesc, String& message)

static Bool addArrayColumnDesc (TableDesc& tableDesc, const String& valueType, const String& columnName, const String& comment, const String& dataManagerType, const String& dataManagerGroup, int options, Int ndim, const Vector<Int>& shape, Bool cOrder, String& message)

static Record recordColumnDesc (const ColumnDesc&, Bool cOrder)

static Record recordHCDesc (const TableDesc& tableDesc)

void setDefaultForSlicer (Vector<Int>& vec) const

static void calcValues (Record& rec, const TableExprNode& expr)

void syncTable (Table& table)

static String getTypeStr (DataType)

static IPosition fillAxes (const IPosition&, Bool cOrder)

Description

Review Status

Reviewed By:

Paul Shannon

Date Reviewed:

1995/09/15

Programs:

Tests:

tgtable.g

Prerequisite

class Table
class GlishTableHolder
class GlishTableIteratorHolder
class GlishTableRowHolder
program gtable
script gtable.g

Etymology

TableProxy is a proxy for access to tables from any script.

Synopsis

TableProxy gives access to most of the functionality in the Table System. It is primarily meant to be used in classes that wrap access to it from scripting languages (like Glish and Python). However, it can also be used directly from other C++ code.

It has functions to open, create, read, write, and query tables. Accompying proxy classes give access to other functionality. They are:

TableIterProxy for iteration through a table using class TableIterator.
TableRowProxy for access to table rows using class TableRow.
TableIterProxy for faster indexed access to using classes ColumnsIndex and ColumnsIndexArray.

TableProxy does not have the TableRecord type in its interface, because such a type cannot be handled by e.g. Glish or Python. Instead it converts TableRecords to/from Records. If a TableRecord contains a field with a Table object, it is represented in the Record as a string with the value "Table: NAME" where NAME is the table name.

Motivation

TableProxy is the Tasking-independent high-level table interface. Different front-ends (e.g. GlishTableProxy) can be put on top of it.

Member Description

TableProxy()

Default constructor initializes to not open. This constructor is only needed for containers.

TableProxy (const Table& table) : table_p (table)

Create the object from an existing table (used by some methods).

TableProxy (const String& tableName, const Record& lockOptions, int option)

Open the table with a given name.

TableProxy (const String& tableName, const Record& lockOptions, const String& endianFormat, const String& memType, int nrow, const Record& tableDesc, const Record& dmInfo)

Create a table with given name and description, etc..

TableProxy (const String& command, const std::vector<TableProxy>& tables)

Creeate a table object from a table command (as defined in TableGram).
If a CALC command was given, the resulting values are stored in the a record and a null TableProxy object is returned. The result can be obtained using getCalcResult. If the command string contains no GIVING part, the resulting table is temporary and its name is blank.

TableProxy (const String& fileName, const String& headerName, const String& tableName, Bool autoHeader, const IPosition& autoShape, const String& separator, const String& commentMarker, Int firstLine, Int lastLine)

Create a table from an Ascii file. It fills a string containing the names and types of the columns (in the form COL1=R, COL2=D, ...). The string can be obtained using getAsciiFormat.

TableProxy (const TableProxy&)

Copy constructor.

~TableProxy()

Close the table.

TableProxy& operator= (const TableProxy&)

Assignment.

TableProxy selectRows (const Vector<Int>& rownrs, const String& outName)

Select the given rows from the table and create a new (reference) table. If outName is not empty, the new table is made persistent with that name.

void reopenRW()

Reopen the table for read/write.

void resync()

Resync the table.

void flush (Bool recursive)

Flush the table and optionally all its subtables.

String endianFormat() const

Get the endian format of the table. It fills the result with value "big" or "little".

void lock (Bool mode, Int nattempts)

Acquire a (read or write) lock on the table.

void unlock()

Release a lock on the table.

Bool hasDataChanged()

Determine if data in the table has changed.

Bool hasLock (Bool mode)

Determine if the process has a read or write lock on the table.

Record lockOptions()

Get the lock options of the table. It fills the record with the fields option, interval and maxwait.

Bool isMultiUsed (Bool checkSubTables)

Determine if the table (and optionally its subtables) are in use in another process.

void rename (const String& newTableName)

Rename the table

TableProxy copy (const String& newTableName, Bool toMemoryTable, Bool deepCopy, Bool valueCopy, const String& endianFormat, const Record& dminfo, Bool noRows)

Copy the table (possibly a deep copy). If noRows=True, an empty table is created.

void copyRows (TableProxy& out, Int startIn, Int startOut, Int nrow)

Copy rows from one table to another. If startOut<0, it is set to the end of the output table.

void deleteTable (Bool checkSubTables)

Close and delete the table.

Record tableInfo()

Get the table info of the table.

void putTableInfo (const Record& value)

Put the table info of the table.

void addReadmeLine (const String& line)

Add a line to the TableInfo readme.

Bool isReadable() const

Test if a table is readable.

Bool isWritable() const

Test if a table is writable.

void setMaximumCacheSize (const String& columnName, Int nbytes)

Set the maximum cache size for the given column in the table with the given id.

void addColumns (const Record& tableDesc, const Record& dminfo)

Add one or more columns to the table.

void renameColumn (const String& nameOld, const String& nameNew)

Rename a column in the table.

void removeColumns (const Vector<String>& columnNames)

Remove one or more columns from the table.

void addRow (Int nrow)

Add rows to the table.

void removeRow (const Vector<Int>& rownrs)

Remove rows from the table.

ValueHolder getColumn (const String& columnName, Int row, Int nrow, Int incr)
Record getVarColumn (const String& columnName, Int row, Int nrow, Int incr)

Get some or all values from a column in the table. row is the starting row number (0-relative). nrow=-1 means until the end of the table. incr is the step in row number.

ValueHolder getColumnSlice (const String& columnName, const Vector<Int>& blc, const Vector<Int>& trc, const Vector<Int>& inc, Int row, Int nrow, Int incr)

Get some or all value slices from a column in the table. If the inc vector is empty, it defaults to all 1.

void putColumn (const String& columnName, const ValueHolder&, Int row, Int nrow, Int incr)
void putVarColumn (const String& columnName, const Record& values, Int row, Int nrow, Int incr)

Put some or all values into a column in the table. row is the starting row number (0-relative). nrow=-1 means until the end of the table. incr is the step in row number.

void putColumnSlice (const String& columnName, const ValueHolder&, const Vector<Int>& blc, const Vector<Int>& trc, const Vector<Int>& inc, Int row, Int nrow, Int incr)

Put some or all value slices into a column in the table.

Bool cellContentsDefined (const String& columnName, Int rownr)

Tests if the contents of a cell are defined. Only a column with variable shaped arrays can have an empty cell.

ValueHolder getCell (const String& columnName, Int row)

Get a value from a column in the table.

ValueHolder getCellSlice (const String& columnName, Int row, const Vector<Int>& blc, const Vector<Int>& trc, const Vector<Int>& inc)

Get a value slice from a column in the table. If the inc vector is empty, it defaults to all 1.

void putCell (const String& columnName, const Vector<Int>& rownrs, const ValueHolder&)

Put a value into a column in the table.

void putCellSlice (const String& columnName, Int row, const ValueHolder&, const Vector<Int>& blc, const Vector<Int>& trc, const Vector<Int>& inc)

Put a value slice into a column in the table. If the inc vector is empty, it defaults to all 1.

Vector<String> getColumnShapeString (const String& columnName, Int rownr, Int nrow, Int incr, Bool cOrder = False)

Get the shape of one or more cells in a column as a vector of Strings containing the shapes as [a,b,c]. If the shape is fixed, a single String is returned.

ValueHolder getKeyword (const String& columnName, const String& keywordName, Int keywordIndex)

Get a table or column keyword value in the table. If the columnName is empty, a given keyword is a table keyword. The keyword can be given as a name or a 0-based index.

Record getKeywordSet (const String& columnName)

Get the table or column keyword values in the table. If the columnName is empty, the table keyword values are returned.

void putKeyword (const String& columnName, const String& keywordName, Int keywordIndex, Bool makeSubRecord, const ValueHolder&)

Define a table or column keyword in the table. If the column name is empty, a table keyword is defined. The keyword can be given as a name or a 0-based number. The value should be a record containing the value of the keyword. The value can be any type (including a record).

void putKeywordSet (const String& columnName, const Record& valueSet)

Define multiple table or column keywords in the table. If the column name is empty, a table keywords are defined. The value should be a record containing the values of the keywords. The values can be any type (including a record). The field names are the keyword names.

void removeKeyword (const String& columnName, const String& keywordName, Int keywordIndex)

Remove a table or column keyword from the table. If the column name is empty, a table keyword is removed.

Vector<String> getFieldNames (const String& columnName, const String& keywordName, Int keywordIndex)

Get the names of all field in a record in the table. If the column name is empty, the table keywords are used. If the keyword name is empty, the names of all keywords are returned. Otherwise the names of all fields in the keyword value are returned. In that case the value has to be a record.

String tableName()

Get table name.

Int ncolumns()

Get #columns of the table.

Int nrows()

Get #rows of the table.

Vector<Int> shape()

Get the shape (#columns, #rows) of the table.

Vector<Int> rowNumbers (TableProxy& other)

Get the row numbers of the table.

Vector<String> columnNames()

Get all column names in the table.

Bool isScalarColumn (const String& columnName)

Return in result if the column contains scalars.

String columnDataType (const String& columnName)

Return the data type of the column as: Bool, UChar, Short, UShort, Int, UInt, Float, Double, Complex, DComplex, String, Table, or unknown.

String columnArrayType (const String& columnName)

Return the type of array in the column as: Direct Undefined FixedShape Direct,Undefined Direct,FixedShape Undefined,FixedShape Direct,Undefined,FixedShape or Error -- unexpected column type

Record getDataManagerInfo()

Get the data manager info of the table with the given id.

String getAsciiFormat() const

Get ascii format string.

Record getCalcResult() const

Get result of possible CALC statement.

Table& table()
const Table& table() const

Return the table object.

static Record getKeyValues (const TableRecord& keySet)
static void putKeyValues (TableRecord& keySet, const Record& valueSet)

Get or put the values of all keywords. Thus convert from TableRecord to/from Record. Keywords containing a table are converted to a string containing the table name preceeded by 'Table: '.

static TableLock makeLockOptions (const Record& options)

Get the lock options from the fields in the record. If the record or lockoption is invalid, an exception is thrown.

static Table::EndianFormat makeEndianFormat (const String& endianFormat)

Turn the string into the endian format option. An exception is thrown if the string is invalid.

static Bool makeHC (const Record& gdesc, TableDesc& tabdesc, String& message)

Make hypercolumn definitions for the given hypercolumns.

Int checkRowColumn (Table& table, const String& colName, Int rownr, Int nrow, Int incr, const Char* caller)

Check if the column name and row numbers are valid. Return the recalculated nrow so that it does not exceed #rows.

ValueHolder getValueFromTable (const String& colName, Int rownr, Int nrow, Int incr, Bool isCell)

Get values from the column. Nrow<0 means till the end of the column.

ValueHolder getValueSliceFromTable(const String& colName, const Slicer& slicer, Int rownr, Int nrow, Int incr, Bool isCell)

Get value slices from the column. Nrow<0 means till the end of the column.

void putValueInTable (const String& colName, Int rownr, Int nrow, Int incr, Bool isCell, const ValueHolder&)

Put values into the column. Nrow<0 means till the end of the column.

void putValueSliceInTable (const String& colName, const Slicer& slicer, Int rownr, Int nrow, Int incr, Bool isCell, const ValueHolder&)

Put value slices into the column. Nrow<0 means till the end of the column.

void findKeyId (RecordFieldId& fieldid, const TableRecord& keySet, const String& keyname, const String& column)
void findKeyId (RecordFieldId& fieldid, TableRecord& keySet, const String& keyname, const String& column, Bool mustExist, Bool change, Bool makeSubRecord)

Split the keyname into its separate parts (separator is .). Check if each part exists and is a subrecord (except last part). When putting, subrecords are created if undefined and if makeSubRecord is set. On return it fills in the fieldid with the latest keyword part. KeySet is set to the last subrecord.

static ValueHolder getKeyValue (const TableRecord& keySet, const RecordFieldId& fieldId)

Get the value of a keyword.

static void putKeyValue (TableRecord& keySet, const RecordFieldId& fieldId, const ValueHolder& value)

Put the value of a keyword.

static Bool makeTableDesc (const Record& gdesc, TableDesc& tabdesc, String& message)

Make a real table description from a table description in a record. An exception is thrown if the record table description is invalid. A record table description is a Record object as returned by getDesc.

static Bool addArrayColumnDesc (TableDesc& tableDesc, const String& valueType, const String& columnName, const String& comment, const String& dataManagerType, const String& dataManagerGroup, int options, Int ndim, const Vector<Int>& shape, Bool cOrder, String& message)

Add an array column description to the table description. It is used by the function makeDesc.

static Record recordColumnDesc (const ColumnDesc&, Bool cOrder)

Make a record containing the column description.

static Record recordHCDesc (const TableDesc& tableDesc)

Make a record containing the description of all hypercolumns.

void setDefaultForSlicer (Vector<Int>& vec) const

Replace the user-given default value by the default value used by Slicer (i.e. by Slicer::MimicSource). Note that the user is 1-relative, while this is 0-relative, so the user default value of -1 is here -2.

static void calcValues (Record& rec, const TableExprNode& expr)

Calculate the values of a CALC expression and store them in field 'values' in rec.

void syncTable (Table& table)

Synchronize table if readlocking is in effect. In this way the number of rows is up-to-date.

static String getTypeStr (DataType)

Get the type string as used externally (in e.g. glish).

static IPosition fillAxes (const IPosition&, Bool cOrder)

Optionally reverse the axes.