ObitData.h File Reference

ObitData virtual base class. More...

#include "Obit.h"
#include "ObitErr.h"
#include "ObitThread.h"
#include "ObitInfoList.h"
#include "ObitIO.h"
#include "ObitTableList.h"
#include "ObitHistory.h"
#include "ObitDef.h"
#include "ObitClassDef.h"

Go to the source code of this file.

Classes
struct	ObitData
	ObitData Class structure. More...
struct	ObitDataClassInfo
	ClassInfo Structure. More...
Defines
#define	ObitDataUnref(in)   ObitUnref (in)
	Macro to unreference (and possibly destroy) an ObitData returns a ObitData*.
#define	ObitDataRef(in)   ObitRef (in)
	Macro to reference (update reference count) an ObitData.
#define	ObitDataIsA(in)   ObitIsA (in, ObitDataGetClass())
	Macro to determine if an object is the member of this or a derived class.
#define	ObitDataSetFITS(in, disk, file, err)
	Convenience Macro to define ObitData I/O to a FITS file.
#define	ObitDataSetAIPS(in, disk, cno, user, err)
	Convenience Macro to define ObitData I/O to an AIPS file.
Typedefs
typedef ObitData *(*	newObitDataScratchFP )(ObitData *in, ObitErr *err)
typedef void(*	ObitDataFullInstantiateFP )(ObitData *in, gboolean exist, ObitErr *err)
typedef void(*	ObitDataRenameFP )(ObitData *in, ObitErr *err)
typedef ObitData *(*	ObitDataZapFP )(ObitData *in, ObitErr *err)
typedef ObitData *(*	ObitDataCopyFP )(ObitData *in, ObitData *out, ObitErr *err)
typedef void(*	ObitDataCloneFP )(ObitData *in, ObitData *out, ObitErr *err)
typedef gboolean(*	ObitDataSameFP )(ObitData *in1, ObitData *in2, ObitErr *err)
typedef void(*	ObitDataSetupIOFP )(ObitData *in, ObitErr *err)
typedef ObitIOCode(*	ObitDataOpenFP )(ObitData *in, ObitIOAccess access, ObitErr *err)
	Typedef for definition of class pointer structure.
typedef ObitIOCode(*	ObitDataCloseFP )(ObitData *in, ObitErr *err)
typedef ObitIOCode(*	ObitDataIOSetFP )(ObitData *in, ObitErr *err)
typedef ObitTable *(*	newObitDataTableFP )(ObitData *in, ObitIOAccess access, gchar *tabType, glong *tabver, ObitErr *err)
typedef ObitHistory *(*	newObitDataHistoryFP )(ObitData *in, ObitIOAccess access, ObitErr *err)
typedef ObitIOCode(*	ObitDataZapTableFP )(ObitData *in, gchar *tabType, glong tabVer, ObitErr *err)
typedef ObitIOCode(*	ObitDataCopyTablesFP )(ObitData *in, ObitData *out, gchar **exclude, gchar **include, ObitErr *err)
typedef ObitIOCode(*	ObitDataUpdateTablesFP )(ObitData *in, ObitErr *err)
typedef void(*	ObitDataCopyTableFP )(ObitData *in, ObitData *out, gchar *tabType, glong *inver, glong *outver, ObitErr *err)
typedef void(*	ObitDataWriteKeywordFP )(ObitData *in, gchar *name, ObitInfoType type, gint32 *dim, gconstpointer data, ObitErr *err)
typedef void(*	ObitDataReadKeywordFP )(ObitData *in, gchar *name, ObitInfoType *type, gint32 *dim, gpointer data, ObitErr *err)
Functions
void	ObitDataClassInit (void)
	Public: Class initializer.
ObitData *	newObitData (gchar *name)
	Public: Constructor.
ObitData *	newObitDataScratch (ObitData *in, ObitErr *err)
	Public: Copy Constructor for scratch file.
void	ObitDataFullInstantiate (ObitData *in, gboolean exist, ObitErr *err)
	Public: Fully instantiate.
gconstpointer	ObitDataGetClass (void)
	Public: ClassInfo pointer.
void	ObitDataRename (ObitData *in, ObitErr *err)
	Public: Rename underlying structures.
ObitData *	ObitDataZap (ObitData *in, ObitErr *err)
	Public: Delete underlying structures.
ObitData *	ObitDataCopy (ObitData *in, ObitData *out, ObitErr *err)
	Public: Copy (deep) constructor.
void	ObitDataClone (ObitData *in, ObitData *out, ObitErr *err)
	Public: Copy structure.
gboolean	ObitDataSame (ObitData *in1, ObitData *in2, ObitErr *err)
	Public: Do two ObitDatas have the same underlying structures?.
void	ObitDataSetupIO (ObitData *in, ObitErr *err)
	Public: Assign/Initialize IO member.
ObitIOCode	ObitDataOpen (ObitData *in, ObitIOAccess access, ObitErr *err)
	Public: Create ObitIO structures and open file.
ObitIOCode	ObitDataClose (ObitData *in, ObitErr *err)
	Public: Close file and become inactive.
ObitIOCode	ObitDataIOSet (ObitData *in, ObitErr *err)
	Public: Reset IO to start of file.
ObitTable *	newObitDataTable (ObitData *in, ObitIOAccess access, gchar *tabType, glong *tabver, ObitErr *err)
	Public: Return an associated Table.
ObitHistory *	newObitDataHistory (ObitData *in, ObitIOAccess access, ObitErr *err)
	Public: Return an associated History.
ObitIOCode	ObitDataZapTable (ObitData *in, gchar *tabType, glong tabVer, ObitErr *err)
	Public: Destroy an associated Table.
ObitIOCode	ObitDataCopyTables (ObitData *in, ObitData *out, gchar **exclude, gchar **include, ObitErr *err)
	Public: Copy associated Tables.
ObitIOCode	ObitDataUpdateTables (ObitData *in, ObitErr *err)
	Public: Update disk resident tables information.
void	ObitDataCopyTable (ObitData *in, ObitData *out, gchar *tabType, glong *inver, glong *outver, ObitErr *err)
	Public: Copy a given table from one ObitData to another.
void	ObitDataWriteKeyword (ObitData *in, gchar *name, ObitInfoType type, gint32 *dim, gconstpointer data, ObitErr *err)
	Public: Write header keyword.
void	ObitDataReadKeyword (ObitData *in, gchar *name, ObitInfoType *type, gint32 *dim, gpointer data, ObitErr *err)
	Public: Read header keyword.

---

Detailed Description

ObitData virtual base class.

This class is derived from the Obit class.

This class is the virtual base class for Obit data. The derived classes are data access objects which allow access to potentially, multiple data structures and present a uniform internal representation. There maybe (usually are) associated tables which either describe the data or contain calibration and/or editing information. These associated tables are listed in an ObitTableList member and the newObitDataTable function allows access to these tables. ObitData is a derived class from class Obit.

Generally ObitData objects will be of derived class but a generic ObitData will allow access to tables but not the main file data or descriptor.

Specifying desired data parameters

The desired data 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 ObitTypes.h.

files

This implementation uses cfitsio which allows using, in addition to regular FITS idata, gzip compressed files, pipes, shared memory and a number of other input forms. The convenience Macro ObitUVSetFITS simplifies specifying the desired data. Binary tables of the type created by AIPS program FITAB 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) Name of disk file.

AIPS files

The ObitAIPS class must be initialized before accessing AIPS files; this uses ObitAIPSClassInit. 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.

Creators and Destructors

There should only be instances of derived classes ( which do not include "Data" in the class name). An object derived from ObitData can be created using newObit? which allows specifying a name for the object. This name is used to label messages. The copy constructors Obit?Clone and Obit?Copy make shallow and deep copies of an extant Obit?. If the output ObitU? has previously been specified, including its disk resident information, then Obit?Copy will copy the disk resident as well as the memory resident information. Also, any associated tables will be copied.

A copy of a pointer to an ObitData should always be made using the Obit?Ref function which updates the reference count in the object. Then whenever freeing an ObitUV or changing a pointer, the function Obit?Unref will decrement the reference count and destroy the object when the reference count hits 0. There is no explicit destructor.

---

Define Documentation

#define ObitDataIsA (  in   )     ObitIsA (in, ObitDataGetClass())

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 ObitDataRef (  in   )     ObitRef (in)

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

#define ObitDataSetAIPS (  in, disk, cno, user, 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; \ 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, "DISK", OBIT_int, \ in->info->dim, (gpointer)&disk, 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); \ }G_STMT_END Convenience Macro to define ObitData I/O to an AIPS file. Sets values on ObitInfoList on input object. in = ObitData to specify i/O for. disk = AIPS disk number cno = catalog slot number user = User id number err = ObitErr to receive error messages.

#define ObitDataSetFITS (  in, disk, file, 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; \ 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)&in->info->work[2], 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 ObitData I/O to a FITS file. Sets values on ObitInfoList on input object. in = ObitData to specify i/O for. disk = FITS disk number file = Specified FITS file name. err = ObitErr to receive error messages.

#define ObitDataUnref (  in   )     ObitUnref (in)

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

---

Typedef Documentation

typedef ObitHistory*(* newObitDataHistoryFP)(ObitData *in, ObitIOAccess access, ObitErr *err)

typedef ObitData*(* newObitDataScratchFP)(ObitData *in, ObitErr *err)

typedef ObitTable*(* newObitDataTableFP)(ObitData *in, ObitIOAccess access, gchar *tabType, glong *tabver, ObitErr *err)

typedef void(* ObitDataCloneFP)(ObitData *in, ObitData *out, ObitErr *err)

typedef ObitIOCode(* ObitDataCloseFP)(ObitData *in, ObitErr *err)

typedef ObitData*(* ObitDataCopyFP)(ObitData *in, ObitData *out, ObitErr *err)

typedef void(* ObitDataCopyTableFP)(ObitData *in, ObitData *out, gchar *tabType, glong *inver, glong *outver, ObitErr *err)

typedef ObitIOCode(* ObitDataCopyTablesFP)(ObitData *in, ObitData *out, gchar **exclude, gchar **include, ObitErr *err)

typedef void(* ObitDataFullInstantiateFP)(ObitData *in, gboolean exist, ObitErr *err)

typedef ObitIOCode(* ObitDataIOSetFP)(ObitData *in, ObitErr *err)

typedef ObitIOCode(* ObitDataOpenFP)(ObitData *in, ObitIOAccess access, ObitErr *err)

Typedef for definition of class pointer structure.

typedef void(* ObitDataReadKeywordFP)(ObitData *in, gchar *name, ObitInfoType *type, gint32 *dim, gpointer data, ObitErr *err)

typedef void(* ObitDataRenameFP)(ObitData *in, ObitErr *err)

typedef gboolean(* ObitDataSameFP)(ObitData *in1, ObitData *in2, ObitErr *err)

typedef void(* ObitDataSetupIOFP)(ObitData *in, ObitErr *err)

typedef ObitIOCode(* ObitDataUpdateTablesFP)(ObitData *in, ObitErr *err)

typedef void(* ObitDataWriteKeywordFP)(ObitData *in, gchar *name, ObitInfoType type, gint32 *dim, gconstpointer data, ObitErr *err)

typedef ObitData*(* ObitDataZapFP)(ObitData *in, ObitErr *err)

typedef ObitIOCode(* ObitDataZapTableFP)(ObitData *in, gchar *tabType, glong tabVer, ObitErr *err)

---

Function Documentation

ObitData* newObitData (  gchar *  name  )

Public: Constructor. A generic ObitData object allows access to tables byt not the main data Initializes class if needed on first call. Parameters: name  An optional name for the object. Returns: the new object.

ObitHistory* newObitDataHistory (  ObitData *  in, ObitIOAccess  access, ObitErr *  err )

Public: Return an associated History. If such an object exists, a reference to it is returned, else a new object is created and if access=OBIT_IO_WriteOnly entered in the ObitTableList if appropriate (AIPS) Parameters: in  Pointer to object with associated tables. This MUST have been opened before this call. access  access (OBIT_IO_ReadOnly,OBIT_IO_ReadWrite, or OBIT_IO_WriteOnly). err  ObitErr for reporting errors. Returns: pointer to created ObitTable, NULL on failure.

ObitData* newObitDataScratch (  ObitData *  in, ObitErr *  err )

Public: Copy Constructor for scratch file. A scratch Data is more or less the same as a normal Data except that it is automatically deleted on the final unreference. The output will have the underlying files of the same type as in already allocated. Virtual - calls actual class member; not supported for Generic ObitData Parameters: in  The object to copy err  Error stack, returns if not empty. Returns: pointer to the new object.

ObitTable* newObitDataTable (  ObitData *  in, ObitIOAccess  access, gchar *  tabType, glong *  tabVer, ObitErr *  err )

Public: Return an associated Table. If such an object exists, a reference to it is returned, else a new object is created and entered in the ObitTableList. Parameters: in  Pointer to object with associated tables. This MUST have been opened before this call. access  access (OBIT_IO_ReadOnly,OBIT_IO_ReadWrite, or OBIT_IO_WriteOnly). This is used to determine defaulted version number and a different value may be used for the actual Open. tabType  The table type (e.g. "AIPS CC"). tabVer  Desired version number, may be zero in which case the highest extant version is returned for read and the highest+1 for write. err  ObitErr for reporting errors. Returns: pointer to created ObitTable, NULL on failure.

void ObitDataClassInit (  void   )

Public: Class initializer.

void ObitDataClone (  ObitData *  in, ObitData *  out, ObitErr *  err )

Public: Copy structure. Virtual - calls actual class member; not supported for Generic ObitData 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.

ObitIOCode ObitDataClose (  ObitData *  in, ObitErr *  err )

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

ObitData* ObitDataCopy (  ObitData *  in, ObitData *  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. If the contents of the data are copied, all associated tables are copied first. 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. Virtual - calls actual class member; not supported for Generic ObitData 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 ObitDataCopyTable (  ObitData *  in, ObitData *  out, gchar *  tabType, glong *  inver, glong *  outver, ObitErr *  err )

Public: Copy a given table from one ObitData to another. Any previous data in the output table will be lost. Parameters: in  The ObitData with tables to copy. out  An ObitData to copy the tables to, old ones replaced. tabType  Table type, e.g. "AIPS CC" inver  Input table version number, 0=>highest, actual returned outver  Output table version number, 0=>new, actual returned err  ObitErr for reporting errors.

ObitIOCode ObitDataCopyTables (  ObitData *  in, ObitData *  out, gchar **  exclude, gchar **  include, ObitErr *  err )

Public: Copy associated Tables. Parameters: in  The ObitData with tables to copy. out  An ObitData to copy the tables to, old ones replaced. exclude  a NULL termimated list of table types NOT to copy. If NULL, use include include  a NULL termimated list of table types to copy. ignored if exclude nonNULL. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK=> OK

void ObitDataFullInstantiate (  ObitData *  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; not supported for Generic ObitData 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 ObitDataGetClass (  void   )

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

ObitIOCode ObitDataIOSet (  ObitData *  in, ObitErr *  err )

Public: Reset IO to start of file. Parameters: in  Pointer to object to be rewound. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK=> OK

ObitIOCode ObitDataOpen (  ObitData *  in, ObitIOAccess  access, ObitErr *  err )

Public: Create ObitIO structures and open file. Virtual - calls actual class member Reads table list if in generic ObitData Object Parameters: in  Pointer to object to be opened. access  access (OBIT_IO_ReadOnly,OBIT_IO_ReadWrite, OBIT_IO_ReadCal 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

void ObitDataReadKeyword (  ObitData *  in, gchar *  name, ObitInfoType *  type, gint32 *  dim, gpointer  data, ObitErr *  err )

Public: Read header keyword. Parameters: in  object to update, must be fully instantiated name  [out] The label (keyword) of the information. Max 8 char type  [out] Data type of data element (enum defined in ObitInfoList class). dim  [out] Dimensionality of datum. Only scalars and strings up to 8 char are supported Note: for strings, the first element is the length in char. data  [out] Pointer to the data. err  ObitErr for reporting errors.

void ObitDataRename (  ObitData *  in, ObitErr *  err )

Public: Rename underlying structures. New name information depends on the underlying file type and is given on the info member. Not supported for Generic ObitData For FITS files: "newFileName" OBIT_string (?,1,1) New Name of disk file. For AIPS: "newName" OBIT_string (12,1,1) New AIPS Name Blank = don't change "newClass" OBIT_string (6,1,1) New AIPS Class Blank = don't changeO "newSeq" OBIT_int (1,1,1) New AIPS Sequence 0 => unique value Parameters: in  Pointer to object to be zapped. err  ObitErr for reporting errors.

gboolean ObitDataSame (  ObitData *  in1, ObitData *  in2, ObitErr *  err )

Public: Do two ObitDatas have the same underlying structures?. This test is done using values entered into the ObitInfoList in case the object has not yet been opened. Not supported for Generic ObitData Parameters: in1  First object to compare in2  Second object to compare err  ObitErr for reporting errors. Returns: TRUE if to objects have the same underlying structures else FALSE

void ObitDataSetupIO (  ObitData *  in, ObitErr *  err )

Public: Assign/Initialize IO member. This is the principle place where the underlying file type is known. Virtual - calls actual class member; not supported for Generic ObitData Parameters: in  object to attach myIO err  ObitErr for reporting errors.

ObitIOCode ObitDataUpdateTables (  ObitData *  in, ObitErr *  err )

Public: Update disk resident tables information. Parameters: in  Pointer to object to be updated. err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK=> OK

void ObitDataWriteKeyword (  ObitData *  in, gchar *  name, ObitInfoType  type, gint32 *  dim, gconstpointer  data, ObitErr *  err )

Public: Write header keyword. Parameters: in  object to update, must be open during call with Write access name  The label (keyword) of the information. Max 8 char type  Data type of data element (enum defined in ObitInfoList class). dim  Dimensionality of datum. Only scalars and strings up to 8 char are allowed Note: for strings, the first element is the length in char. data  Pointer to the data. err  ObitErr for reporting errors.

ObitData* ObitDataZap (  ObitData *  in, ObitErr *  err )

Public: Delete underlying structures. Virtual - calls actual class member; not supported for Generic ObitData Parameters: in  Pointer to object to be zapped. err  ObitErr for reporting errors. Returns: pointer for input object, NULL if deletion successful

ObitIOCode ObitDataZapTable (  ObitData *  in, gchar *  tabType, glong  tabVer, ObitErr *  err )

Public: Destroy an associated Table. The table is removed from the ObitTableList but it is not updated. A call to ObitDataUpdateTables to update disk structures. Parameters: in  Pointer to object with associated tables. tabType  The table type (e.g. "AIPS CC"). tabVer  Desired version number, may be zero in which case the highest extant version is returned for read and the highest+1 for write. -1 => all versions of tabType err  ObitErr for reporting errors. Returns: return code, OBIT_IO_OK=> OK

---