Software documentation: Candid

14-OCT-1996

Preface

This program is designed to monitor the operation of the Australia Telescope Compact Array and record how much time is spent actually observing. Hopefully it will automate the process of compiling downtime statistics. 
            _____________________
The basic operation of the program is to record for each CAGET cycle (which it actually gets from the OBSCOM history, not CAGET), what the timestamp was, the project associated with the scan, the number of tracking antennas, the integration time and whether the source was marked as a calibrator. These data are accumulated into the file AT$LOG:CANDID.DAT. 
            _____________________
At the end of each AEST day, these data are processed and a summary of time expenditure is generated for each project that operated during that day. This information is datestamped with the day in question and appended to the end of a log file called AT$LOG:CANDID.LOG. Later, a postprocessor will be able to read that extended log and generate ATCA downtime and utilisation reports . 
            _____________________
The name CANDID means, of course, "unbiased; not censorious; frank", and it is hoped that this program will, at last, give us a better representation of the downtime at the ATCA. Until now, we have relied on the sketchy reports of the observers; often underestimated or ignored. For those who want to make it an acronym, try: Compact Array Non-Downtime Intelligent Detector (feel free to come up with something better). 
            _____________________
Some "trigger" code has been left in, but commented out. This allows the programmer to test the processing functionality without having to wait for an AEST day cahnge.

Call sequence: 

      program candid
      implicit none
      include 'array$inc:array_gs.inc'
      include 'caobs$inc:caobs_status.inc'
Creation date: 7-Nov-1995

Author: Derek McKay

File: CANDID.FOR

Routine name: decode_mask

Function:

Converts the mask into the number of antennas tracking and a calcode. Normally the calcode is blank, but may be set to "C" if the cycle was marked as a calibrator field. The working copy of the antenna mask is called "mask", the original is left in its pristine state as "ref_mask".

Call sequence: 

      subroutine decode_mask(ref_mask,calcode,num_ants)
      implicit none
      integer
     -  ref_mask,  ! Input. Encoded cycle mask
     -  num_ants   ! Returned. Number of tracking antennas
      character*(*)
     -  calcode    ! "C" if a calibrator
Creation date: 8-Nov-1995

Author: Derek McKay

File: CANDID.FOR

Routine name: get_project

Function:

This routine returns the project ID based on the extension of the current RPFITS file.

Call sequence: 

      character*80 function get_project()
      implicit none
      include 'caobs$inc:caobs_status.inc'
Creation date: 8-Nov-1995

Author: Derek McKay

File: CANDID.FOR

Routine name: get_time_stamp()

Function:

This routine derives a time stamp for data to go inot the log files. Basically, it ends up as a number in the range 0000 - FFFF (hexadecimal) that corresponds to the range 0 - 86399 (seconds), i.e. one day. The resolution is about 1.3 seconds, which is fine considering that integration cycles are typically of 10 or 15 seconds each.

Call sequence: 

      integer function get_time_stamp()
      implicit none
Creation date: 8-Nov-1995

Author: Derek McKay

File: CANDID.FOR

Routine name: open_file

Function:

This routine opens a new file for the cycle utililisation log. If one already exists for that day, the routine opens it for appending.

Call sequence: 

      character*80 function open_file(new)
      implicit none
      logical new      ! TRUE if we should be opening a new file
Creation date: 8-Nov-1995

Author: Derek McKay

File: CANDID.FOR

Routine name: process_file

Function:

Processor for analysing UTIL datafiles

Call sequence: 

      logical function process_file(datestamp)
      implicit none
      character*(*) datestamp
Creation date: 8-Nov-1995

Author: Derek McKay

File: CANDID.FOR

Automatically generated by DOC using the layout file utl$doc:for_html.dat. Last updated 14-OCT-1996.