ObitOTF.h File Reference

ObitOTF GBT On the fly data class definition. More...

#include "ObitData.h"
#include "ObitOTFDesc.h"
#include "ObitOTFSel.h"
#include "ObitOTFArrayGeom.h"
#include "ObitTableList.h"

Go to the source code of this file.

Classes
struct	ObitOTF
	ObitOTF Class structure. More...
struct	ObitOTFClassInfo
	ClassInfo Structure. More...
Defines
#define	ObitOTFUnref(in)   ObitUnref (in)
	Macro to unreference (and possibly destroy) an ObitOTF returns a ObitOTF*.
#define	ObitOTFRef(in)   ObitRef (in)
	Macro to reference (update reference count) an ObitOTF.
#define	ObitOTFIsA(in)   ObitIsA (in, ObitOTFGetClass())
	Macro to determine if an object is the member of this or a derived class.
#define	ObitOTFSetFITS(in, nsamp, disk, file, err)
	Convenience Macro to define OTF I/O to a FITS file.
Typedefs
typedef ObitOTF *(*	newObitOTFScratchFP )(ObitOTF *in, ObitErr *err)
	Typedef for definition of class pointer structure.
typedef void(*	ObitOTFFullInstantiateFP )(ObitOTF *in, gboolean exist, ObitErr *err)
typedef gboolean(*	ObitOTFSameFP )(ObitOTF *in1, ObitOTF *in2, ObitErr *err)
typedef ObitIOCode(*	ObitOTFIOSetFP )(ObitOTF *in, ObitErr *err)
typedef ObitTable *(*	newObitOTFTableFP )(ObitOTF *in, ObitIOAccess access, gchar *tabType, glong *tabver, ObitErr *err)
typedef ObitIOCode(*	ObitOTFZapTableFP )(ObitOTF *in, gchar *tabType, glong tabVer, ObitErr *err)
typedef ObitIOCode(*	ObitOTFCopyTablesFP )(ObitOTF *in, ObitOTF *out, gchar **exclude, gchar **include, ObitErr *err)
typedef ObitIOCode(*	ObitOTFUpdateTablesFP )(ObitOTF *in, ObitErr *err)
Functions
void	ObitOTFClassInit (void)
	Public: Class initializer.
ObitOTF *	newObitOTF (gchar *name)
	Public: Constructor.
ObitOTF *	newObitOTFScratch (ObitOTF *in, ObitErr *err)
	Public: Copy Constructor for scratch file.
void	ObitOTFFullInstantiate (ObitOTF *in, gboolean exist, ObitErr *err)
	Public: Fully instantiate.
gconstpointer	ObitOTFGetClass (void)
	Public: ClassInfo pointer.
void	ObitOTFRename (ObitOTF *in, ObitErr *err)
	Public: Rename underlying structures.
void	ObitIOOTFFITSRename (ObitIO *in, ObitInfoList *info, ObitErr *err)
	Public: Rename underlying structures.
ObitOTF *	ObitOTFZap (ObitOTF *in, ObitErr *err)
	Public: Delete underlying structures.
ObitOTF *	ObitOTFCopy (ObitOTF *in, ObitOTF *out, ObitErr *err)
	Public: Copy (deep) constructor.
ObitOTF *	ObitOTFAver (ObitOTF *in, ObitOTF *out, ObitErr *err)
	Public: Copy (deep) constructor averaging over frequency.
void	ObitOTFClone (ObitOTF *in, ObitOTF *out, ObitErr *err)
	Public: Copy structure only - no data copy.
gboolean	ObitOTFSame (ObitOTF *in1, ObitOTF *in2, ObitErr *err)
	Public: Do two OTFs have the same underlying structures?.
ObitIOCode	ObitOTFConcat (ObitOTF *in, ObitOTF *out, ObitErr *err)
	Public: Concatenate two OTF, (in at end of out).
ObitIOCode	ObitOTFOpen (ObitOTF *in, ObitIOAccess access, ObitErr *err)
	Public: Create ObitIO structures and open file.
ObitIOCode	ObitOTFClose (ObitOTF *in, ObitErr *err)
	Public: Close file and become inactive.
ObitIOCode	ObitOTFIOSet (ObitOTF *in, ObitErr *err)
	Public: Reset IO to start of file.
ObitIOCode	ObitOTFRead (ObitOTF *in, gfloat *data, ObitErr *err)
	Public: Read specified data.
ObitIOCode	ObitOTFReadSelect (ObitOTF *in, gfloat *data, ObitErr *err)
	Public: Read select, edit, calibrate specified data.
ObitIOCode	ObitOTFWrite (ObitOTF *in, gfloat *data, ObitErr *err)
	Public: Write specified data.
ObitTable *	newObitOTFTable (ObitOTF *in, ObitIOAccess access, gchar *tabType, glong *tabver, ObitErr *err)
	Public: Return an associated Table.
ObitIOCode	ObitOTFZapTable (ObitOTF *in, gchar *tabType, glong tabVer, ObitErr *err)
	Public: Destroy an associated Table.
ObitIOCode	ObitOTFCopyTables (ObitOTF *in, ObitOTF *out, gchar **exclude, gchar **include, ObitErr *err)
	Public: Copy associated Tables.
ObitIOCode	ObitOTFUpdateTables (ObitOTF *in, ObitErr *err)
	Public: Update disk resident tables information.
void	ObitOTFWriteKeyword (ObitOTF *in, gchar *name, ObitInfoType type, gint32 *dim, gconstpointer data, ObitErr *err)
	Public: Write header keyword.
void	ObitOTFReadKeyword (ObitOTF *in, gchar *name, ObitInfoType *type, gint32 *dim, gpointer data, ObitErr *err)
	Public: Read header keyword.
glong	ObitOTFNumRecScan (ObitOTF *inOTF)
	Public: How many records in current scan?

---

Detailed Description

ObitOTF GBT On the fly data class definition.

This class contains single dish data and allows access. An ObitOTF is the front end to a persistent disk resident structure. 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 newObitOTFTable function allows access to these tables. ObitOTF is a derived class from class ObitData. Only FITS data are supported.

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. Data is read and written as arrays of floats. 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). Only FITS format data are supported.

The following apply to all types of files:

• "nVisPIO", 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 idata, gzip compressed files, pipes, shared memory and a number of other input forms. The convenience Macro ObitOTFSetFITS 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.

Creators and Destructors

An ObitOTF can be created using newObitOTF which allows specifying a name for the object. This name is used to label messages. The copy constructors ObitOTFClone and ObitOTFCopy make shallow and deep copies of an extant ObitOTF. If the output ObitOTF has previously been specified, including its disk resident information, then ObitOTFCopy 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 ObitOTF should always be made using the ObitOTFRef function which updates the reference count in the object. Then whenever freeing an ObitOTF or changing a pointer, the function ObitOTFUnref will decrement the reference count and destroy the object when the reference count hits 0. There is no explicit destructor.

I/O

Visibility data is available after an input object is "Opened" and "Read". "Read Select" also allows specifying the data to be read as well as optional calibration and editing to be applied as the data is read. I/O optionally uses a buffer attached to the ObitOTF or some external location. To Write an ObitOTF, create it, open it, and write. The object should be closed to ensure all data is flushed to disk. Deletion of an ObitOTF after its final unreferencing will automatically close it.

---

Define Documentation

#define ObitOTFIsA (  in   )     ObitIsA (in, ObitOTFGetClass())

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

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

#define ObitOTFSetFITS (  in, nsamp, 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; \ in->info->work[1] = nsamp; in->info->work[2]= disk; \ ObitInfoListPut (in->info, "FileType", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[0], err);\ ObitInfoListPut (in->info, "nRecPIO", OBIT_int, \ in->info->dim, (gpointer)&in->info->work[1], err);\ ObitInfoListPut (in->info, "IOBy", OBIT_int, in->info->dim, \ (gpointer)&in->info->work[1], 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 OTF I/O to a FITS file. Sets values on ObitInfoList on input object. in = ObitOTF to specify i/O for. nsamp = Max. Number of visibilities per read. disk = FITS disk number file = Specified FITS file name. err = ObitErr to receive error messages.

#define ObitOTFUnref (  in   )     ObitUnref (in)

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

---

Typedef Documentation

typedef ObitOTF*(* newObitOTFScratchFP)(ObitOTF *in, ObitErr *err)

Typedef for definition of class pointer structure.

typedef ObitTable*(* newObitOTFTableFP)(ObitOTF *in, ObitIOAccess access, gchar *tabType, glong *tabver, ObitErr *err)

typedef ObitIOCode(* ObitOTFCopyTablesFP)(ObitOTF *in, ObitOTF *out, gchar **exclude, gchar **include, ObitErr *err)

typedef void(* ObitOTFFullInstantiateFP)(ObitOTF *in, gboolean exist, ObitErr *err)

typedef ObitIOCode(* ObitOTFIOSetFP)(ObitOTF *in, ObitErr *err)

typedef gboolean(* ObitOTFSameFP)(ObitOTF *in1, ObitOTF *in2, ObitErr *err)

typedef ObitIOCode(* ObitOTFUpdateTablesFP)(ObitOTF *in, ObitErr *err)

typedef ObitIOCode(* ObitOTFZapTableFP)(ObitOTF *in, gchar *tabType, glong tabVer, ObitErr *err)

---

Function Documentation

ObitOTF* newObitOTF (  gchar *  name  )

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

ObitOTF* newObitOTFScratch (  ObitOTF *  in, ObitErr *  err )

Public: Copy Constructor for scratch file. A scratch OTF is more or less the same as a normal OTF 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. Parameters: in  The object to copy err  Error stack, returns if not empty. Returns: pointer to the new object.

ObitTable* newObitOTFTable (  ObitOTF *  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. "ArrayGeom"). 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 ObitIOOTFFITSRename (  ObitIO *  in, ObitInfoList *  info, ObitErr *  err )

Public: Rename underlying structures. New name information is given on the info member: "newFileName" OBIT_string (?,1,1) New Name of disk file. Parameters: in  Pointer to object to be renamed info  Associated ObitInfoList err  ObitErr for reporting errors.

ObitOTF* ObitOTFAver (  ObitOTF *  in, ObitOTF *  out, ObitErr *  err )

Public: Copy (deep) constructor averaging over frequency. 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. The file etc. info should have been stored in the ObitInfoList: "doCalSelect" OBIT_boolean scalar if TRUE, calibrate/select/edit input data. "DOCALIB" OBIT_int (1,1,1) >0 -> calibrate, "GAINUSE" OBIT_int (1,1,1) SN/CL table version number, 0-> use highest 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 ObitOTFClassInit (  void   )

Public: Class initializer.

void ObitOTFClone (  ObitOTF *  in, ObitOTF *  out, ObitErr *  err )

Public: Copy structure only - no data copy. Parent class members are included but any derived class info is ignored. Parameters: in  The object to copy out  The output object, must be previously created and associated files specified. err  Error stack, returns if not empty.

ObitIOCode ObitOTFClose (  ObitOTF *  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

ObitIOCode ObitOTFConcat (  ObitOTF *  in, ObitOTF *  out, ObitErr *  err )

Public: Concatenate two OTF, (in at end of out). Parameters: in  The object to copy out  An existing object pointer for output err  Error stack, returns if not empty. Returns: pointer to the new object.

ObitOTF* ObitOTFCopy (  ObitOTF *  in, ObitOTF *  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. The file etc. info should have been stored in the ObitInfoList: "doCalSelect" OBIT_boolean scalar if TRUE, calibrate/select/edit input data. "DOCALIB" OBIT_int (1,1,1) >0 -> calibrate, "GAINUSE" OBIT_int (1,1,1) SN/CL table version number, 0-> use highest 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.

ObitIOCode ObitOTFCopyTables (  ObitOTF *  in, ObitOTF *  out, gchar **  exclude, gchar **  include, ObitErr *  err )

Public: Copy associated Tables. Parameters: in  The ObitOTF with tables to copy. out  An ObitOTF 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 ObitOTFFullInstantiate (  ObitOTF *  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 ObitOTFGetClass (  void   )

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

ObitIOCode ObitOTFIOSet (  ObitOTF *  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

glong ObitOTFNumRecScan (  ObitOTF *  inOTF  )

Public: How many records in current scan? Only returns valid results after reading has begun. If there is no selection in effect then the size of the file is returned. Parameters: in  object to query, should be open and reads started

ObitIOCode ObitOTFOpen (  ObitOTF *  in, ObitIOAccess  access, ObitErr *  err )

Public: Create ObitIO structures and open file. The image descriptor is read if OBIT_IO_ReadOnly, OBIT_IO_ReadCal or OBIT_IO_ReadWrite and written to disk if opened OBIT_IO_WriteOnly. If access is OBIT_IO_ReadCal then the calibration/selection/editing needed is initialized. See the ObitOTFSel class for a description of the selection and calibration parameters. After the file has been opened the member, buffer is initialized for reading/storing the data unless member bufferSize is <0. The file etc. info should have been stored in the ObitInfoList: "FileType" OBIT_int scalar = OBIT_IO_FITS for file type. "nRecPIO" OBIT_int scalar = Maximum number of visibilities per transfer, this is the target size for Reads (may be fewer) and is used to create buffers. "Compress" Obit_bool scalar = TRUE indicates output is to be in compressed format. (access=OBIT_IO_WriteOnly only). 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

ObitIOCode ObitOTFRead (  ObitOTF *  in, gfloat *  data, ObitErr *  err )

Public: Read specified data. The ObitOTFDesc maintains the current location in the file. The number read will be mySel->nRecPIO (until the end of the selected range of records in which case it will be smaller). The first visibility number after a read is myDesc->firstRec and the number of visibilities is myDesc->numRecBuff. Parameters: in  Pointer to object to be read. 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 ObitOTFReadKeyword (  ObitOTF *  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.

ObitIOCode ObitOTFReadSelect (  ObitOTF *  in, gfloat *  data, ObitErr *  err )

Public: Read select, edit, calibrate specified data. The number read will be mySel->nRecPIO (until the end of the selected range of record in which case it will be smaller). The first record number after a read is myDesc->firstRec and the number of records is myDesc->numRecBuff. Parameters: in  Pointer to object to be read. 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 ObitOTFRename (  ObitOTF *  in, ObitErr *  err )

Public: Rename underlying structures. For FITS files: "newFileName" OBIT_string (?,1,1) New Name of disk file. Parameters: in  Pointer to object to be renamed. err  ObitErr for reporting errors.

gboolean ObitOTFSame (  ObitOTF *  in1, ObitOTF *  in2, ObitErr *  err )

Public: Do two OTFs have the same underlying structures?. This test is done using values entered into the #ObitInfoList in case the object has not yet been opened. 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

ObitIOCode ObitOTFUpdateTables (  ObitOTF *  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

ObitIOCode ObitOTFWrite (  ObitOTF *  in, gfloat *  data, ObitErr *  err )

Public: Write specified data. The data in the buffer will be written starting at record myDesc->firstRec and the number written will be myDesc->numRecBuff which should not exceed mySel->nRecPIO if the internal buffer is used. myDesc->firstRec will be maintained and need not be changed for sequential writing. Parameters: in  Pointer to object to be written. 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

void ObitOTFWriteKeyword (  ObitOTF *  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.

ObitOTF* ObitOTFZap (  ObitOTF *  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

ObitIOCode ObitOTFZapTable (  ObitOTF *  in, gchar *  tabType, glong  tabVer, ObitErr *  err )

Public: Destroy an associated Table. The table is removed from the ObitTableList 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

---