Programming with the xtract library

The process of compilation and execution of the xtract macro described above is done via a stand-alone library. This section describes the Application Programming Interface (API) of this library.

The C/C++ interface of this library is defined in fmt.h, which must be included in the code and linked to libjump.a, in addition to all other GMRT Off-line libraries (liboff.a, libregex.a, libkum.a).

Interpretation and compilation of the format string

The xtract macros are interpreted via the following function call:

      int interpret(char *fmtString, struct fftmac *fm,
                    Parameters *Params, SymbType *Inst)

The first argument is the macro as a NULL terminated string. Second argument is the sanjay/Offline/gstruct">fftmac (Bhatnagar1997a) structure which holds the various mappings for the LTA database (e.g., sampler to the MAC mapping, etc.). This structure must be filled using services provided by the sanjay/Offline/ltaobj">GMRT Offline Library (getFFTMac method). The third argument is a pointer to the structure of the type Parameters. This structure holds the various parameters which the library uses while executing the macro. Various fields of this structure are described in Section B.4.3. The value of some of the fields of this structure are defined by the user, while others are to be extracted from the LTA database. The fourth argument is a pointer to a structure of type SymbType. This is the table of elements mentioned earlier and must be initialized to NULL before being passed to this routine. A return value of less than EOF ($-1$), indicates a syntax error in the macro.

Compilation of the macro string is done via a call to:

      int Compile(SymbType *Inst,struct fftmac *fm,
                  struct AntCoord *Tab, Parameters *Params)

The first argument is the symbol table returned by a call to interpret. It now points to the head of a linked list of nodes of type SymbType. The last node of this list is NULL. The second argument is the fftmac structure. The third argument is the table of antenna co-ordinates. This can be retrieved from the LTA database via the services provided by the sanjay/Offline/ltaobj">GMRT Offline Library (getFFTMac method). The fourth argument is a pointer to the Parameters structure. A return value of less than EOF($-1$) indicates error in compilation of the macro. On successful compilation, it returns the size of the compiled symbol table in units of the size of the structure SymbType.

Execution of the compiled macro

If the interpretation and compilation of the macro was successful, the compiled macro can be executed via calls to a user-supplied function of signature

int Exec(FILE *fd, SymbType *Inst, float *Buf, int ProgSize) fd refers to the output file already opened for writing. Inst is the symbol table returned by interpret. In case the output data is not to be written to any file, the user can write versions of this routine which will fill the data in the buffer Buf. ProgSize is the value returned by Compile.

The data field of the Parameters structure (see section B.4.3) must be made to point to the buffer in which the LTA-data buffers are read. To generate a regular stream of output, corresponding to each input data record, this function must be called every time a new LTA-data record is read.

Few types of Exec functions are provided in the library. These include:

• Execute

  It writes the output data to the fd file descriptor. It does not use the Buf pointer.

• ExecuteDef

  This writes the output data to the buffer pointed by Buf. The size of the this buffer must be big enough to hold one floating point number per node of the symbol table (return value of Compile). This does not use the file descriptor.

• ExecuteQDP

  This supplies output data to the QDP program via a pipe opened via the libpipe.a library. This uses the Buf pointer but does not use fd.

To generate any other functionality, the programmers need to write their versions of this function. The recommended route for writing a new function is to modify Execute or ExecuteDef functions.

The Parameters structure

The Parameters structure is of the following type:

            typedef struct StructParamType{
               int Norm;
               int *BList, *SList, *AList, *CList;
               int  NBase,  NScans, NAnt,   NChan;
               int dBNBase, dBNChan, dBNAnt;
               int dBStartChan;
               int TimeOff, ParOff,DataOff;

               float Lambda;
               float sd,cd, TUnits;
               char *data;
            } Parameters;

Various fields and their use is as follows:

• int Norm

  This must be set to 1 if the visibility data is to be normalized by the geometric mean of the self correlations. Otherwise this must be set to 0.

• int *BList, *SList, *AList, *CList

  These are pointers to the user selected list of the baseline, scan, antenna and channel numbers respectively. The list of channel numbers must be 0-relative and not the absolute channel index of the data base (which could start with number between 0 to maximum number of channels).

  Typically, the user selects the baselines and antennas via the baseline/antenna names. These are supplied as strings by the user. Two functions, MkBaselines and MkAntNo, are provided to convert these stings to a list of bit fields in which the bits corresponding to the selected baselines are set to 1. Another routine toIntList, is provided to convert the bit fields to list of integers representing the selected baselines. These functions are available in the library liboff.a and are described in Appendix A of sanjay/Offline/ltaobj">GMRT Offline Library.

• int NBase, NScans, NAnt, NChan

  These are the lengths of BList, SList, AList and CList.

• int dBNBase, dBNChan, dBNAnt

  These are the number of the baselines, channels and antenna in the data base.

• int dBStartChan

  This is the number of the first frequency channel in the data base.

• int TimeOff, ParOff, DataOff

  These are the offsets within the LTA-data buffer to locate the time stamp, the auxiliary parameters, and the visibility data itself. These offsets can be extracted from the global header of the database.

• float sd,cd

  These are the values of $\sin(\delta)$ and $\cos(\delta)$ where $\delta$ is the declination of the pointing center of the telescope. These are used for the calculation of the ($u,v,w$) co-ordinates during execution.

• float TUnits

  This is the multiplication factor used to convert the time stamp in the data to seconds of time. This is also extracted from the global header.

• float Lambda

  This the wavelength of the observing frequency in meters.

• char *data

  This is the pointer to the beginning of the LTA-data buffer.