Main Page | Class List | Directories | File List | Class Members | File Members
include

ObitHistory.h File Reference

ObitHistory class definition. More...

#include "Obit.h"
#include "ObitErr.h"
#include "ObitThread.h"
#include "ObitInfoList.h"
#include "ObitIOHistory.h"
#include "ObitDef.h"
#include "ObitClassDef.h"

Go to the source code of this file.

Classes

struct  ObitHistory
 ObitHistory Class structure. More...
struct  ObitHistoryClassInfo
 ClassInfo Structure For Table. More...

Defines

#define ObitHistoryUnref(in)   ObitUnref (in)
 Macro to unreference (and possibly destroy) an ObitHistory returns an ObitHistory*.
#define ObitHistoryRef(in)   ObitRef (in)
 Macro to reference (update reference count) an ObitHistory.
#define ObitHistoryIsA(in)   ObitIsA (in, ObitHistoryGetClass())
 Macro to determine if an object is the member of this or a derived class.
#define ObitHistorySetFITS(in, disk, file, err)
 Convenience Macro to define History I/O to a FITS file.
#define ObitHistorySetAIPS(in, disk, cno, user, err)
 Convenience Macro to define History I/O to an AIPS file.

Typedefs

typedef ObitHistory *(* ObitHistoryZapFP )(ObitHistory *in, ObitErr *err)
typedef ObitIOCode(* ObitHistoryOpenFP )(ObitHistory *in, ObitIOAccess access, ObitErr *err)
typedef ObitIOCode(* ObitHistoryCloseFP )(ObitHistory *in, ObitErr *err)

Functions

void ObitHistoryClassInit (void)
 Public: Class initializer.
ObitHistory * newObitHistory (gchar *name)
 Public: Default constructor.
gconstpointer ObitHistoryGetClass (void)
 Public: ClassInfo pointer.
ObitHistory * newObitHistoryValue (gchar *name, ObitInfoList *info, ObitErr *err)
 Public: Constructor from object infoList.
ObitHistory * ObitHistoryZap (ObitHistory *in, ObitErr *err)
 Public: Delete underlying structures.
ObitHistory * ObitHistoryCopy (ObitHistory *in, ObitHistory *out, ObitErr *err)
 Public: Deep copy.
ObitIOCode ObitHistoryCopyHeader (ObitHistory *in, ObitHistory *out, ObitErr *err)
 Public: Copy history from header (FITS).
ObitIOCode ObitHistoryCopy2Header (ObitHistory *in, ObitHistory *out, ObitErr *err)
 Public: Copy history to header (FITS).
ObitIOCode ObitHistoryHeader2Header (ObitHistory *in, ObitHistory *out, ObitErr *err)
 Public: Copy history from header (FITS) to header (FITS).
ObitIOCode ObitHistoryOpen (ObitHistory *in, ObitIOAccess access, ObitErr *err)
 Public: Create ObitIO structures and open file.
ObitIOCode ObitHistoryClose (ObitHistory *in, ObitErr *err)
 Public: Close file and become inactive.
ObitIOCode ObitHistoryReadRec (ObitHistory *in, glong recno, gchar hiCard[73], ObitErr *err)
 Public: Read specified Record.
ObitIOCode ObitHistoryWriteRec (ObitHistory *in, glong rowno, gchar hiCard[73], ObitErr *err)
 Public: Write specified Record.
ObitIOCode ObitHistoryTimeStamp (ObitHistory *in, gchar *label, ObitErr *err)
 Public: Add time stamp and label.
ObitIOCode ObitHistoryCopyInfoList (ObitHistory *out, gchar *pgmName, gchar *list[], ObitInfoList *info, ObitErr *err)
 Public: Copy a list of values from an InfoList to a History.
gint ObitHistoryNumRec (ObitHistory *in)
 Public: Tell number of history records.

Detailed Description

ObitHistory class definition.

This class is derived from the Obit class.

This class contains a processing history in tabular form. An ObitHistory 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. The AIPS conventions for history records are give the program name followed by parameters in keyword=value form and to preceed any non parsable text by the FITS comment header comment delimiter '/'.

HistoryTable data storage

History tables are accessed as tables although the AIPS implementation is a pre-table version. History records are blocked into 70 character fixed strings althought AIPS internally uses 72.

Access to History

History records are stored in a system dependent fashion. AIPS history records are stored in an AIPS HI* file with 72 characters per record (Obit only uses 70). FOR FITS files, history records are normally kept in A History binary table but can be read or written to tyhe more traditional HISTORY keywords using ObitHistoryCopyHeader, or ObitHistoryCopy2Header for entire collections or ObitFileFITS functions ObitFileFITSReadHistory and ObitFileFITSWriteHistory for individual records. Access to the history component of an object (e.g. Image, UV data) can be obtained using the ObitInfoList containing the information defining the underlying file. This uses routine newObitHistoryValue. Then history lines can be read or written one at a time using ObitHistoryOpen, ObitHistoryReadRec, ObitHistoryWriteRec, ObitHistoryTimeStamp, ObitHistoryClose. The contents of entire history files may be copied using ObitHistoryCopy, or ObitHistoryCopyHeader to copy HISTORY records from a FITS header or ObitHistoryCopy2Header to copy a history file to a FITS header.

FITS files

The Obit FITS implementation uses a HISTORY table unlike the standard FITS practice of keeping histories in the main HDU header regular FITS images, gzip compressed files, pipes, shared memory and a number of other input forms. The convenience Macro ObitHistorySetFITS simplifies specifying the desired data.

AIPS files

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

Creators and Destructors

A copy of a pointer to an ObitHistory should always be made using the ObitHistoryRef function which updates the reference count in the object. Then whenever freeing an ObitHistory or changing a pointer, the function ObitHistoryUnref 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 ObitHistory or some external location. To Write an ObitHistory, create it, open it, and write. The object should be closed to ensure all data is flushed to disk. Deletion of an ObitHistory after its final unreferencing will automatically close it.

ObitHistoryRow

An ObitHistoryRow 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. ObitHistoryRow class definitions and functions are included in the files defining the associated ObitHistory. ObitHistoryRows are derived from basal class Obit.

Define Documentation

#define ObitHistoryIsA (  in   )     ObitIsA (in, ObitHistoryGetClass())
 

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

Macro to reference (update reference count) an ObitHistory.

returns an ObitHistory*. in = object to reference

#define ObitHistorySetAIPS (  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, "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 History I/O to an AIPS file.

Sets values on ObitInfoList on input object.

  • in = Obit Object with InfoList member to specify i/O for.
  • disk = AIPS disk number
  • cno = catalog slot number
  • user = User id number
  • err = ObitErr to receive error messages.

#define ObitHistorySetFITS (  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;                            \
       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);\
       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 History I/O to a FITS file.

Sets values on ObitInfoList on input object.

  • in = Obit Object with InfoList member to specify i/O for.
  • disk = FITS disk number
  • file = Specified FITS file name.
  • err = ObitErr to receive error messages.

#define ObitHistoryUnref (  in   )     ObitUnref (in)
 

Macro to unreference (and possibly destroy) an ObitHistory returns an ObitHistory*.

in = object to unreference

Typedef Documentation

typedef ObitIOCode(* ObitHistoryCloseFP)(ObitHistory *in, ObitErr *err)
 

typedef ObitIOCode(* ObitHistoryOpenFP)(ObitHistory *in, ObitIOAccess access, ObitErr *err)
 

typedef ObitHistory*(* ObitHistoryZapFP)(ObitHistory *in, ObitErr *err)
 

Function Documentation

ObitHistory* newObitHistory (  gchar *  name  ) 
 

Public: Default constructor.

Initializes class if needed on first call.

Parameters:
name An optional name for the object.
Returns:
the new object.

ObitHistory* newObitHistoryValue (  gchar *  name,
ObitInfoList *  info,
ObitErr *  err
) 
 

Public: Constructor from object infoList.

Parameters:
name An optional name for the object.
info Parent object list defining the underlying file e.g. FileType, disk, name for FITS, disk, user, cno for AIPS.
err Error stack, returns if not empty.
Returns:
the new object.

void ObitHistoryClassInit (  void   ) 
 

Public: Class initializer.

ObitIOCode ObitHistoryClose (  ObitHistory *  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

ObitHistory* ObitHistoryCopy (  ObitHistory *  in,
ObitHistory *  out,
ObitErr *  err
) 
 

Public: Deep copy.

Both objects should be filly defined.

Parameters:
in The object to copy, if underlying structures don't exist, it merely returns without writing the out History.
out An existing object pointer for output
err Error stack, returns if not empty.
Returns:
pointer to the new object.

ObitIOCode ObitHistoryCopy2Header (  ObitHistory *  in,
ObitHistory *  out,
ObitErr *  err
) 
 

Public: Copy history to header (FITS).

Both objects should be filly defined.

Parameters:
in The object to copy
out Output object for HISTORY header entries.
err Error stack, returns if not empty.
Returns:
pointer to the new object.

ObitIOCode ObitHistoryCopyHeader (  ObitHistory *  in,
ObitHistory *  out,
ObitErr *  err
) 
 

Public: Copy history from header (FITS).

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.

ObitIOCode ObitHistoryCopyInfoList (  ObitHistory *  out,
gchar *  pgmName,
gchar *  list[],
ObitInfoList *  info,
ObitErr *  err
) 
 

Public: Copy a list of values from an InfoList to a History.

Parameters:
out Output object for HISTORY header entries.
list NULL terminated list of entries in info
info ObitInfoList with values to copy
err Error stack, returns if not empty.
Returns:
pointer to the new object.

gconstpointer ObitHistoryGetClass (  void   ) 
 

Public: ClassInfo pointer.

Returns:
pointer to the class structure.

ObitIOCode ObitHistoryHeader2Header (  ObitHistory *  in,
ObitHistory *  out,
ObitErr *  err
) 
 

Public: Copy history from header (FITS) to header (FITS).

Both objects should be filly defined.

Parameters:
in The object to copy
out Output object for HISTORY header entries.
err Error stack, returns if not empty.
Returns:
pointer to the new object.

gint ObitHistoryNumRec (  ObitHistory *  in  ) 
 

Public: Tell number of history records.

Parameters:
in Pointer to open object to be tested
Returns:
number of records, <0 => problem

ObitIOCode ObitHistoryOpen (  ObitHistory *  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).
    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 ObitHistoryReadRec (  ObitHistory *  in,
glong  recno,
gchar  hiCard[73],
ObitErr *  err
) 
 

Public: Read specified Record.

Parameters:
in Pointer to object to be read.
recno Record number to read, -1 = next;
hiCard Char array to accept line
err ObitErr for reporting errors.
Returns:
return code, OBIT_IO_OK => OK

ObitIOCode ObitHistoryTimeStamp (  ObitHistory *  in,
gchar *  label,
ObitErr *  err
) 
 

Public: Add time stamp and label.

Parameters:
in Pointer to object to be written.
label Label string for record
err ObitErr for reporting errors.
Returns:
return code, OBIT_IO_OK => OK

ObitIOCode ObitHistoryWriteRec (  ObitHistory *  in,
glong  recno,
gchar  hiCard[73],
ObitErr *  err
) 
 

Public: Write specified Record.

Parameters:
in Pointer to object to be written.
rowno Record number to write, -1 = next;
err ObitErr for reporting errors.
Returns:
return code, OBIT_IO_OK => OK

ObitHistory* ObitHistoryZap (  ObitHistory *  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

Generated on Fri Aug 31 22:13:06 2007 for Obit by  doxygen 1.3.9.1