ObitTable.h File Reference

ObitTable class definition. More...

#include "Obit.h"
#include "ObitErr.h"
#include "ObitThread.h"
#include "ObitInfoList.h"
#include "ObitIO.h"
#include "ObitTableDesc.h"
#include "ObitTableSel.h"
#include "ObitDef.h"
#include "ObitClassDef.h"

Go to the source code of this file.

Classes
struct	ObitTable
	ObitTable Class structure. More...
struct	ObitTableRow
	ObitTableRow Class structure. More...
struct	ObitTableClassInfo
	ClassInfo Structure For Table. More...
struct	ObitTableRowClassInfo
	ClassInfo Structure For TableRow. More...
Defines
#define	ObitTableUnref(in)   ObitUnref (in)
	Macro to unreference (and possibly destroy) an ObitTable returns an ObitTable*.
#define	ObitTableRef(in)   ObitRef (in)
	Macro to reference (update reference count) an ObitTable.
#define	ObitTableIsA(in)   ObitIsA (in, ObitTableGetClass())
	Macro to determine if an object is the member of this or a derived class.
#define	ObitTableRowUnref(in)   ObitUnref (in)
	Macro to unreference (and possibly destroy) an ObitTableRow returns an ObitTableRow*.
#define	ObitTableRowRef(in)   ObitRef (in)
	Macro to reference (update reference count) an ObitTableRow.
#define	ObitTableRowIsA(in)   ObitIsA (in, ObitTableRowGetClass())
	Macro to determine if an object is the member of this or a derived class.
#define	ObitTableSetFITS(in, disk, file, tab, ver, nrow, err)
	Convenience Macro to define Table I/O to a FITS file.
#define	ObitTableSetAIPS(in, disk, cno, tab, ver, user, nrow, err)
	Convenience Macro to define Table I/O to an AIPS file.
Typedefs
typedef ObitTableRow *(*	newObitTableRowFP )(ObitTable *in)
	Typedef for definition of class pointer structure.
typedef void(*	ObitTableFullInstantiateFP )(ObitTable *in, gboolean exist, ObitErr *err)
typedef void(*	ObitTableClearRowsFP )(ObitTable *in, ObitErr *err)
typedef ObitTable *(*	ObitTableZapFP )(ObitTable *in, ObitErr *err)
	Typedef for definition of class pointer structure.
typedef ObitTable *(*	ObitTableConvertFP )(ObitTable *in)
typedef ObitIOCode(*	ObitTableOpenFP )(ObitTable *in, ObitIOAccess access, ObitErr *err)
typedef ObitIOCode(*	ObitTableCloseFP )(ObitTable *in, ObitErr *err)
typedef ObitIOCode(*	ObitTableReadFP )(ObitTable *in, glong row, gfloat *data, ObitErr *err)
typedef ObitIOCode(*	ObitTableReadSelectFP )(ObitTable *in, glong row, gfloat *data, ObitErr *err)
typedef void(*	ObitTableSetRowFP )(ObitTable *in, ObitTableRow *row, ObitErr *err)
typedef ObitIOCode(*	ObitTableWriteFP )(ObitTable *in, glong row, gfloat *data, ObitErr *err)
typedef ObitIOCode(*	ObitTableReadRowFP )(ObitTable *in, glong rowno, ObitTableRow *row, ObitErr *err)
typedef ObitIOCode(*	ObitTableWriteRowFP )(ObitTable *in, glong rowno, ObitTableRow *row, ObitErr *err)
typedef gchar *(*	ObitTableGetTypeFP )(ObitTable *in, ObitErr *err)
typedef glong(*	ObitTableGetVersionFP )(ObitTable *in, ObitErr *err)
Functions
void	ObitTableRowClassInit (void)
	Public: Row Class initializer.
ObitTableRow *	newObitTableRow (ObitTable *table)
	Public: Constructor.
gconstpointer	ObitTableRowGetClass (void)
	Public: ClassInfo pointer.
void	ObitTableClassInit (void)
	Public: Class initializer.
ObitTable *	newObitTable (gchar *name)
	Public: Default constructor.
void	ObitTableFullInstantiate (ObitTable *in, gboolean exist, ObitErr *err)
	Public: Fully instantiate.
void	ObitTableClearRows (ObitTable *in, ObitErr *err)
	Public: Remove any previous entries - also forces instantiate.
gconstpointer	ObitTableGetClass (void)
	Public: ClassInfo pointer.
ObitTable *	ObitTableZap (ObitTable *in, ObitErr *err)
	Public: Delete underlying structures.
ObitTable *	ObitTableCopy (ObitTable *in, ObitTable *out, ObitErr *err)
	Public: Copy (deep) constructor.
ObitTable *	ObitTableClone (ObitTable *in, ObitTable *out)
	Public: Copy (shallow) constructor.
void	ObitTableConcat (ObitTable *in, ObitTable *out, ObitErr *err)
	Public: Concatenate two tables.
ObitTable *	ObitTableConvert (ObitTable *in)
	Public: Convert an ObitTable to a derived type.
ObitIOCode	ObitTableOpen (ObitTable *in, ObitIOAccess access, ObitErr *err)
	Public: Create ObitIO structures and open file.
ObitIOCode	ObitTableClose (ObitTable *in, ObitErr *err)
	Public: Close file and become inactive.
ObitIOCode	ObitTableRead (ObitTable *in, glong row, gfloat *data, ObitErr *err)
	Public: Read specified data.
ObitIOCode	ObitTableReadSelect (ObitTable *in, glong row, gfloat *data, ObitErr *err)
	Public: Read/select data.
void	ObitTableSetRow (ObitTable *in, ObitTableRow *row, ObitErr *err)
	Public: Attach Row to buffer.
ObitIOCode	ObitTableWrite (ObitTable *in, glong row, gfloat *data, ObitErr *err)
	Public: Write specified data.
ObitIOCode	ObitTableReadRow (ObitTable *in, glong rowno, ObitTableRow *row, ObitErr *err)
	Public: Read specified Row.
ObitIOCode	ObitTableWriteRow (ObitTable *in, glong rowno, ObitTableRow *row, ObitErr *err)
	Public: Write specified Row.
gchar *	ObitTableGetType (ObitTable *in, ObitErr *err)
	Public: Return table type.
glong	ObitTableGetVersion (ObitTable *in, ObitErr *err)
	Public: Return table version.

---

Detailed Description

ObitTable class definition.

This class contains tabular data and allows access. An ObitTable is the front end to a persistent disk resident structure. Both FITS (as Tables) and AIPS cataloged data are supported.

This class is derived from the Obit class. Related functions are in the ObitImageUtil module and table type specific classes and utility modules.

HistoryTable data storage

In memory tables are stored in a fashion similar to how they are stored on disk - in large blocks in memory rather than structures. Due to the word alignment requirements of some machines, they are stored by order of the decreasing element size: double, float long, int, short, char rather than the logical order. The details of the storage in the buffer are kept in the ObitTableDesc.

In addition to the normal tabular data, a table will have a "_status" column to indicate the status of each row. The status value is read from and written to (some modification) AIPS tables but are not written to externally generated FITS tables which don't have these colummns. It will be written to Obit generated tables which will have these columns. Status values:

• status = 0 => normal
• status = 1 => row has been modified (or created) and needs to be written.
• status = -1 => row has been marked invalid.

Specifying desired data transfer parameters

The desired data transfers are specified in the member ObitInfoList. There are separate sets of parameters used to specify the FITS or AIPS data files. In the following an ObitInfoList entry is defined by the name in double quotes, the data type code as an #ObitInfoType enum and the dimensions of the array (? => depends on application). To specify whether the underlying data files are FITS or AIPS

• "FileType" OBIT_int (1,1,1) OBIT_IO_FITS or OBIT_IO_AIPS which are values of an #ObitIOType enum defined in ObitIO.h.

The following apply to both types of files:

• "nRowPIO", OBIT_int, Max. Number of visibilities per "Read" or "Write" operation. Default = 1.

FITS files

This implementation uses cfitsio which allows using, in addition to regular FITS images, gzip compressed files, pipes, shared memory and a number of other input forms. The convenience Macro ObitTableSetFITS simplifies specifying the desired data. Binary tables are used for storing visibility data in FITS. For accessing FITS files the following entries in the ObitInfoList are used:

• "Disk" OBIT_int (1,1,1) FITS "disk" number.
• "FileName" OBIT_string (?,1,1) FITS file name.
• "TabName" OBIT_string (?,1,1) Table name (e.g. "AIPS CC").
• "Ver" OBIT_int (1,1,1) Table version number

AIPS files

The ObitAIPS class must be initialized before accessing AIPS files; this uses ObitAIPSClassInit. The convenience Macro ObitTableSetAIPS simplifies specifying the desired data. For accessing AIPS files the following entries in the ObitInfoList are used:

• "Disk" OBIT_int (1,1,1) AIPS "disk" number.
• "User" OBIT_int (1,1,1) user number.
• "CNO" OBIT_int (1,1,1) AIPS catalog slot number.
• "TableType" OBIT_string (2,1,1) AIPS Table type
• "Ver" OBIT_int (1,1,1) AIPS table version number.

Creators and Destructors

An ObitTable can be created using newObitTable which allos specifying a name for the object. This name is used to label messages. The copy constructors ObitTableClone and ObitTableCopy make shallow and deep copies of an extant ObitTable. If the output ObitTable has previously been specified, including its disk resident information, then ObitTableCopy will copy the disk resident as well as the memory resident information.

A copy of a pointer to an ObitTable should always be made using the ObitTableRef function which updates the reference count in the object. Then whenever freeing an ObitTable or changing a pointer, the function ObitTableUnref will decrement the reference count and destroy the object when the reference count hits 0.

I/O

Visibility data is available after an input object is "Opened" and "Read". I/O optionally uses a buffer attached to the ObitTable or some external location. To Write an ObitTable, create it, open it, and write. The object should be closed to ensure all data is flushed to disk. Deletion of an ObitTable after its final unreferencing will automatically close it.

ObitTableRow

An ObitTableRow is used to pass the data for a single table row. It is most useful in derived classes where it includes entries by symbolic names. ObitTableRow class definitions and functions are included in the files defining the associated ObitTable. ObitTableRows are derived from basal class Obit.

---

Define Documentation

#define ObitTableIsA (  in   )     ObitIsA (in, ObitTableGetClass())

Macro to determine if an object is the member of this or a derived class. Returns TRUE if a member, else FALSE in = object to reference

#define ObitTableRef (  in   )     ObitRef (in)

Macro to reference (update reference count) an ObitTable. returns an ObitTable*. in = object to reference

#define ObitTableRowIsA (  in   )     ObitIsA (in, ObitTableRowGetClass())

Macro to determine if an object is the member of this or a derived class. Returns TRUE if a member, else FALSE in = object to reference

#define ObitTableRowRef (  in   )     ObitRef (in)

Macro to reference (update reference count) an ObitTableRow. returns an ObitTableRow*. in = object to reference

#define ObitTableRowUnref (  in   )     ObitUnref (in)

Macro to unreference (and possibly destroy) an ObitTableRow returns an ObitTableRow*. in = object to unreference

#define ObitTableSetAIPS (  in, disk, cno, tab, ver, user, nrow, err   )

Value: G_STMT_START{ \ in->info->dim[0]=1; in->info->dim[1]=1; in->info->dim[2]=1; \ in->info->dim[3]=1; in->info->dim[4]=1; \ in->info->work[0] = OBIT_IO_AIPS; \ in->info->work[1]= ver; in->info->work[2]= nrow; \ ObitInfoListPut (in->info, "FileType", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[0], err);\ in->info->dim[0] = 1; \ ObitInfoListPut (in->info, "Disk", OBIT_int, \ in->info->dim, (gpointer)&disk, err); \ ObitInfoListPut (in->info, "Ver", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[1], err); \ ObitInfoListPut (in->info, "CNO", OBIT_int, \ in->info->dim, (gpointer)&cno, err); \ ObitInfoListPut (in->info, "User", OBIT_int, \ in->info->dim, (gpointer)&user, err); \ ObitInfoListPut (in->info, "nRowPIO", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[2], err); \ in->info->dim[0] = 2; \ ObitInfoListPut (in->info, "TableType", OBIT_string, \ in->info->dim, (gpointer)&tab, err); \ }G_STMT_END Convenience Macro to define Table I/O to an AIPS file. Sets values on ObitInfoList on input object. in = ObitTable to specify i/O for. disk = AIPS disk number cno = catalog slot number tab = table type (e.g. 'CC') ver = table version number user = User id number nrow = Maximum number of Rows per read/write. err = ObitErr to receive error messages.

#define ObitTableSetFITS (  in, disk, file, tab, ver, nrow, err   )

Value: G_STMT_START{ \ in->info->dim[0]=1; in->info->dim[1]=1; in->info->dim[2]=1; \ in->info->dim[3]=1; in->info->dim[4]=1; \ in->info->work[0] = OBIT_IO_FITS; \ in->info->work[1] = ver; in->info->work[2]= nrow; \ in->info->work[2] = disk; \ in->info->dim[0] = 1; \ ObitInfoListPut (in->info, "Disk", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[2], err); \ ObitInfoListPut (in->info, "FileType", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[0], err);\ ObitInfoListPut (in->info, "Ver", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[1], err); \ ObitInfoListPut (in->info, "nRowPIO", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[2], err); \ in->info->dim[0] = strlen(tab); \ ObitInfoListPut (in->info, "TabName", OBIT_string, \ in->info->dim, (gpointer)tab, err); \ in->info->dim[0] = strlen(file); \ ObitInfoListPut (in->info, "FileName", OBIT_string, \ in->info->dim, (gpointer)file, err); \ }G_STMT_END Convenience Macro to define Table I/O to a FITS file. Sets values on ObitInfoList on input object. in = ObitTable to specify i/O for. disk = FITS disk number file = Specified FITS file name. tab = table type (e.g. 'AIPS CC') ver = table version number nrow = Maximum number of Rows per read/write. err = ObitErr to receive error messages.

#define ObitTableUnref (  in   )     ObitUnref (in)

Macro to unreference (and possibly destroy) an ObitTable returns an ObitTable*. in = object to unreference

---

Typedef Documentation

typedef ObitTableRow*(* newObitTableRowFP)(ObitTable *in)

Typedef for definition of class pointer structure.

typedef void(* ObitTableClearRowsFP)(ObitTable *in, ObitErr *err)

typedef ObitIOCode(* ObitTableCloseFP)(ObitTable *in, ObitErr *err)

typedef ObitTable*(* ObitTableConvertFP)(ObitTable *in)

typedef void(* ObitTableFullInstantiateFP)(ObitTable *in, gboolean exist, ObitErr *err)

typedef gchar*(* ObitTableGetTypeFP)(ObitTable *in, ObitErr *err)

typedef glong(* ObitTableGetVersionFP)(ObitTable *in, ObitErr *err)

typedef ObitIOCode(* ObitTableOpenFP)(ObitTable *in, ObitIOAccess access, ObitErr *err)

typedef ObitIOCode(* ObitTableReadFP)(ObitTable *in, glong row, gfloat *data, ObitErr *err)

typedef ObitIOCode(* ObitTableReadRowFP)(ObitTable *in, glong rowno, ObitTableRow *row, ObitErr *err)

typedef ObitIOCode(* ObitTableReadSelectFP)(ObitTable *in, glong row, gfloat *data, ObitErr *err)

typedef void(* ObitTableSetRowFP)(ObitTable *in, ObitTableRow *row, ObitErr *err)

typedef ObitIOCode(* ObitTableWriteFP)(ObitTable *in, glong row, gfloat *data, ObitErr *err)

typedef ObitIOCode(* ObitTableWriteRowFP)(ObitTable *in, glong rowno, ObitTableRow *row, ObitErr *err)

typedef ObitTable*(* ObitTableZapFP)(ObitTable *in, ObitErr *err)

Typedef for definition of class pointer structure.

---

Function Documentation

ObitTable* newObitTable (  gchar *  name  )

Public: Default constructor. Initializes class if needed on first call. Parameters: name  An optional name for the object. Returns: the new object.

ObitTableRow* newObitTableRow (  ObitTable *  table  )

Public: Constructor. Initializes Row class if needed on first call. Parameters: name  An optional name for the object. Returns: the new object.

void ObitTableClassInit (  void   )

Public: Class initializer.

void ObitTableClearRows (  ObitTable *  in, ObitErr *  err )

Public: Remove any previous entries - also forces instantiate. Parameters: in  Pointer to object err  ObitErr for reporting errors. Returns: error code, OBIT_IO_OK=> OK

ObitTable* ObitTableClone (  ObitTable *  in, ObitTable *  out )

Public: Copy (shallow) constructor. The result will have pointers to the more complex members. Parent class members are included but any derived class info is ignored. Parameters: in  The object to copy out  An existing object pointer for output or NULL if none exists. Returns: pointer to the new object.

ObitIOCode ObitTableClose (  ObitTable *  in, ObitErr *  err )

Public: Close file and become inactive. Parameters: in  Pointer to object to be closed. err  ObitErr for reporting errors. Returns: error code, OBIT_IO_OK=> OK

void ObitTableConcat (  ObitTable *  in, ObitTable *  out, ObitErr *  err )

Public: Concatenate two tables. Parameters: in  The object to copy out  An existing object pointer for output or NULL if none exists. err  Error stack, returns if not empty. Returns: pointer to the new object.

ObitTable* ObitTableConvert (  ObitTable *  in  )

Public: Convert an ObitTable to a derived type. Parameters: in  Pointer to object to be converted still exists after call. err  ObitErr for reporting errors. Returns: converted table

ObitTable* ObitTableCopy (  ObitTable *  in, ObitTable *  out, ObitErr *  err )

Public: Copy (deep) constructor. Copies are made of complex members including disk files; these will be copied applying whatever selection is associated with the input. Objects should be closed on input and will be closed on output. In order for the disk file structures to be copied, the output file must be sufficiently defined that it can be written. The copy will be attempted but no errors will be logged until both input and output have been successfully opened. ObitInfoList and ObitThread members are only copied if the output object didn't previously exist. Parent class members are included but any derived class info is ignored. Parameters: in  The object to copy out  An existing object pointer for output or NULL if none exists. err  Error stack, returns if not empty. Returns: pointer to the new object.

void ObitTableFullInstantiate (  ObitTable *  in, gboolean  exist, ObitErr *  err )

Public: Fully instantiate. If object has previously been opened, as demonstrated by the existance of its myIO member, this operation is a no-op. Virtual - calls actual class member Parameters: in  Pointer to object exist  TRUE if object should previously exist, else FALSE err  ObitErr for reporting errors. Returns: error code, OBIT_IO_OK=> OK

gconstpointer ObitTableGetClass (  void   )

Public: ClassInfo pointer. Returns: pointer to the class structure.

gchar* ObitTableGetType (  ObitTable *  in, ObitErr *  err )

Public: Return table type. "AIPS AN") Parameters: in  Pointer to object to be read. err  ObitErr for reporting errors. Returns: pointer to string

glong ObitTableGetVersion (  ObitTable *  in, ObitErr *  err )

Public: Return table version. Parameters: in  Pointer to object to be read. err  ObitErr for reporting errors. Returns: version number

ObitIOCode ObitTableOpen (  ObitTable *  in, ObitIOAccess  access, ObitErr *  err )

Public: Create ObitIO structures and open file. The image descriptor is read if OBIT_IO_ReadOnly or OBIT_IO_ReadWrite and written to disk if opened OBIT_IO_WriteOnly. After the file has been opened the member, buffer is initialized for reading/storing the table unless member bufferSize is <0. If the requested version ("Ver" in InfoList) is 0 then the highest numbered table of the same type is opened on Read or Read/Write, or a new table is created on on Write. The file etc. info should have been stored in the ObitInfoList: "FileType" OBIT_int scalar = OBIT_IO_FITS or OBIT_IO_AIPS for file type (see class documentation for details). "nRowPIO" OBIT_int scalar = Maximum number of table rows per transfer, this is the target size for Reads (may be fewer) and is used to create buffers. Parameters: in  Pointer to object to be opened. access  access (OBIT_IO_ReadOnly,OBIT_IO_ReadWrite, or OBIT_IO_WriteOnly). If OBIT_IO_WriteOnly any existing data in the output file will be lost. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK=> OK

ObitIOCode ObitTableRead (  ObitTable *  in, glong  rowno, gfloat *  data, ObitErr *  err )

Public: Read specified data. The ObitTableDesc maintains the current location in the table. The number read will be mySel->nRowPIO (until the end of the selected range of rows in which case it will be smaller). The first row number after a read is myDesc->firstRow and the number of row is myDesc->numRowBuff. If there are existing rows in the buffer marked as modified ("_status" column value =1) the buffer is rewritten to disk before the new buffer is read. Parameters: in  Pointer to object to be read. rowno  Row number to start reading, -1 = next; data  pointer to buffer to write results. if NULL, use the buffer member of in. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK => OK

ObitIOCode ObitTableReadRow (  ObitTable *  in, glong  rowno, ObitTableRow *  row, ObitErr *  err )

Public: Read specified Row. The ObitTableDesc maintains the current location in the table. If there are existing rows in the buffer marked as modified ("_status" column value =1) the buffer is rewritten to disk before the new buffer is read. Parameters: in  Pointer to object to be read. rowno  Row number to start reading, -1 = next; row  pointer to Table row Structure to accept data. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK => OK

ObitIOCode ObitTableReadSelect (  ObitTable *  in, glong  rowno, gfloat *  data, ObitErr *  err )

Public: Read/select data. The number read will be mySel->nRowPIO (until the end of the selected range of visibilities in which case it will be smaller). The first visibility number after a read is myDesc->firstRow and the number of visibilities is myDesc->numRowBuff. If there are existing rows in the buffer marked as modified ("_status" column value =1) the buffer is rewritten to disk before the new buffer is read. Parameters: in  Pointer to object to be read. rowno  Row number to start reading, -1 = next; data  pointer to buffer to write results. if NULL, use the buffer member of in. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK => OK

void ObitTableRowClassInit (  void   )

Public: Row Class initializer.

gconstpointer ObitTableRowGetClass (  void   )

Public: ClassInfo pointer. Returns: pointer to the Row class structure.

void ObitTableSetRow (  ObitTable *  in, ObitTableRow *  row, ObitErr *  err )

Public: Attach Row to buffer. This is only useful prior to filling a row structure in preparation . for a WriteRow operation. Array members of the Row structure are . pointers to independently allocated memory, this routine allows using . the table IO buffer instead of allocating yet more memory.. This routine need only be called once to initialize a Row structure for write.. Parameters: in  Table with buffer to be written row  Table Row structure to attach err  ObitErr for reporting errors.

ObitIOCode ObitTableWrite (  ObitTable *  in, glong  rowno, gfloat *  data, ObitErr *  err )

Public: Write specified data. The data in the buffer will be written starting at visibility myDesc->firstRow and the number written will be myDesc->numRowBuff which should not exceed mySel->nRowPIO if the internal buffer is used. myDesc->firstRow will be maintained and need not be changed for sequential writing. Parameters: in  Pointer to object to be written. rowno  Row number (1-rel) to start reading, -1 = next; data  pointer to buffer containing input data. if NULL, use the buffer member of in. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK=> OK

ObitIOCode ObitTableWriteRow (  ObitTable *  in, glong  rowno, ObitTableRow *  row, ObitErr *  err )

Public: Write specified Row. Parameters: in  Pointer to object to be read. rowno  Row number to start reading, -1 = next; row  pointer to Table row Structure to accept data. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK => OK

ObitTable* ObitTableZap (  ObitTable *  in, ObitErr *  err )

Public: Delete underlying structures. Parameters: in  Pointer to object to be zapped. err  ObitErr for reporting errors. Returns: pointer for input object, NULL if deletion successful

---