Software documentation: ATCA_Live

Preface

This "unofficial" program is the driver program for the "unofficial" "ATCA Live!" WWW page that is maintained on the Culgoora web site. It may only be maintained out-of-hours. What it does, is generate an HTML document once every 10 seconds which can be served by the local WWW server. The page is constructed using information from the on-line system. One feature in particular (the antenna images) are done by deriving a filename of the most suitable image bitmap which will best represent the current azimuth and elevation of the antennas. For antennas that are within the AZ/EL error spec's for the requested RA/Dec, all conforming antennas are given the same file name based on the average of their Az/Els. Antennas with a large AZ/EL error are plotted irrespective of other antennas. This system prevents unusual phenomena on image boundaries. The image selected is based on the closest to the given AZ/EL, it is the full solution, not an approximation. Finally, there are a few sources of auxiliary information that can be used to supplement the material that is naturally displayed on the "ATCA Live!" page. These are as follows:

 
                 [.MESSAGES]
                 [.PROJECTS]

The messages directory contains several important files:

 
                 COMMENTS.HTML
                 ABOUT.HTML
                 AWARDS.HTML
                 LINKS.HTML

The first of these (the COMMENTS.HTML file) contains what will appear at the bottom of the "ATCA Live!" page. It makes reference to the user feedback page and any other pages in the [.MESSAGES] directory that can be linked to. The ABOUT.HTML and AWARDS.HTML files are two that fall into that category. Any awards that the "ATCA Live!" page receives are placed in that file. The ABOUT.HTML file contains technical information about the page, and should be updated to refelct this. The LINKS.HTML file is a place where more recent, topical information, or just links to other "Live" pages can be included. The ATCA_LIVE project also calls for astronomers to contribute information about their own observing projects to be included in the page (see below). In addition, there are a miriad of files with the format:

 
                  YYMMDD.HTML

These files are HTML snippets that will be inserted into the ATCA_LIVE.HTML file when their filename matches the current date (expressed in a similar format. These files should start with a single line to restart the paragraph. I.e.:

But may then carry any HTML code that the author wants. They can be primed in advance, so generally, once a term, all the reconfiguration announcements etc. will be put in. They can be used to announce any other special events, as the circumstance dictates. The other area that needs maintaining is the

 
                  [.PROJECTS]

directory. This contains files in the format:

 
                  PROJ_ID.HTML

Where PROJ_ID is the project ID that would be specified in the project (e.g. C999.HTML). These files can be generated automatically using the

 
                  IMPORT.FOR
                  IMPORT.EXE

programs. To do this, do a global search on the ATNF Projects Database Search. This can be found at the URL:

 
              http://www.atnf.csiro.au/Observe/Projects/search.html

You should select "C" in the project ID field (so as only to get ATCA projects. When you submit, the project search engine will start downloading the HTML file with all the projects that mathc your query. Be warned, this file will be huge! When it has downloaded, save it as:

 
                   projectdbsearch.html

Then run the IMPORT program. It will generate files for each project in the database. Too make it easier, it might be wise to

 
                   $ purge/log

It should be noted that the IMPORT program, when it generates its output files, will insert an HTML comment into each file it generates. This comment (which reads:

) is the first line in the file. It allows the users to detect files that are automatically generated, and those which are custom designed. Observers should be encouraged to contribute material for the PROJECTS files, thus making their own little contribution to public education with the ATCA. Most of the non-C projects (i.e. those that don't have a C### project ID) already come with descriptive files. Examples include

 
                 ALERT.HTML
                 BSLN.HTML
                 DQO.HTML
                 POINT.HTML

It is therefore important that during, say, reconfigurations, that the correlator files are regularly closed, so that the new files can be picked up by ATCA_LIVE and the correct information displayed. The other itme of note, is that the

 
                 C999.HTML

file assumes that the ATCA is in maintenance (as that is the "scratch" project ID.

 
              _______________

As for the code in the main routine, it basically goes into an infinite loop during which it builds the ATCA_LIVE.HTML file, closes it, waits about 10 seconds and then loops back to start again. Some of the more complicated functions for generating page data are in subroutines, and they are called from here.

Call sequence:

      program ATCA_Live
      implicit none
      include '($IODEF)'
      include '($SSDEF)'
      include 'caobs$inc:caobs_status.inc'
      include 'array$inc:a_params.inc'
      include 'array$inc:a_data.inc'

Creation date: 25-Jan-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_array_activity`

Function:

This routine reports the activity of the antennas. What sounds straightforward, however, is actually quite a complicated piece of logic, especially as there are some inconsistencies in the on-line software reporting. The results are written to the main output file.

Call sequence:

      subroutine live_array_activity(lun,seed,antfnc)
      implicit none
      include 'caobs$inc:caobs_status.inc'
      integer
     -  lun,        ! Logical Unit Number
     -  seed        ! Random number generator seed
      character*8
     -  antfnc(6)   ! Antenna function

Creation date: 24-Sep-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_blurb`

Function:

This routine gives a brief description of where the Australia Telescope Compact Array is located. It writes the information to the logical unit number of the main ATCA_LIVE file which is passed to it. It also takes the random number generator seed (alhtough it doesn't use it at this stage.

Call sequence:

      subroutine live_blurb(lun, seed)
      implicit none
      integer
     -  lun,     ! Logical Unit Number
     -  seed     ! Random number generator seed - for randomness' sake

Creation date: 23-Sep-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_current_project`

Function:

This subroutine checks the current project and looks to see if any information on that project is included in the [.PROJECTS] directory. If there is, then it copies that information into the ATCA_LIVE page. See the main preface to the ATCA_LIVE program for more information.

Call sequence:

      subroutine live_current_project(lun)
      implicit none
      integer
     -  lun          ! Logical Unit Number

Creation date: 14-Nov-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_daily_message`

Function:

This subroutine determines the date ID for today and converts it into a filename (namely YYMMDD.HTML). It then tries to add that file from the [.MESSAGES] directory to the page (file specified by LUN). See the preface of the ATCA_LIVE program for more information.

Call sequence:

      subroutine live_daily_message(lun)
      implicit none
      integer
     -  lun          ! Logical Unit Number

Creation date: 7-Dec-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_frequencies`

Function:

This routine gives a blurb about the frequencies and bandwidths that are being used by the Compact Array. The information is written to the file specified by the LUN.

Call sequence:

      subroutine live_frequencies(lun)
      implicit none
      include 'caobs$inc:caobs_status.inc'
      integer
     -  lun      ! Logical Unit Number

Creation date: 24-Sep1-995

Author: Derek McKay

File: atca_live.for

Routine name: `live_get_dist`

Function:

Determines the angular distance between two AZ/EL pairs. The function returns the angular distance in degrees, and arguments are also expected in degrees.

Call sequence:

      real function live_get_dist(az1,el1,az2,el2)
      implicit none
      real
     - az1,    ! Azimuth of first position
     - el1,    ! Elevation of first position
     - az2,    ! Azimuth of second position
     - el2     ! Elevation of second position

Creation date: 25-Jan-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_get_name`

Function:

This routine determines the appropriate filename for the antenna, having been provided with its azimuth and elevation. It is aware of the set of antenna images filenames and the position of the antenna to which each corresponds. The function returns the filename.

Call sequence:

      character*20 function live_get_name(az,el)
      implicit none
      real
     -  az,     ! Azimuth of the antenna
     -  el      ! Elevation of the antenna

Creation date: 26-Jan-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_get_project`

Function:

This routine returns the project ID based on the extension of the current RPFITS file. Originally it was in the CANDID subroutines. The filename is recovered from the global memory. All parts of the filename (excepting the file extension) are stripped off to leave just the extension, which is the project ID.

Call sequence:

      character*80 function live_get_project()
      implicit none
      include 'caobs$inc:caobs_status.inc'

Creation date: 8-Nov-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_location`

Function:

This routine gives a brief description of where the Australia Telescope Compact Array is located. Now obsolete.

Call sequence:

      subroutine live_location(lun, seed)
      implicit none
      integer
     -  lun,     ! Logical Unit Number
     -  seed     ! Random number generator seed - for randomness' sake

Creation date: 23-Sep-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_other_comments`

Function:

This subroutine adds the file COMMENTS.HTML, if it is available, to the page. See the preface to the ATCA_LIVE program for more information. The output is written to the file specified by the LUN.

Call sequence:

      subroutine live_other_comments(lun)
      implicit none
      integer
     -  lun          ! Logical Unit Number

Creation date: 31-May-1996

Author: Derek McKay

File: atca_live.for

Routine name: `live_other_links`

Function:

This subroutine adds the file LINKS.HTML, if it is available, to the page. See the preface to the ATCA_LIVE program for more information. The output is written to the file specified by the LUN.

Call sequence:

      subroutine live_other_links(lun)
      implicit none
      integer
     -  lun          ! Logical Unit Number

Creation date: 7-Dec-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_radio_source`

Function:

This routine gives a blurb about the current radio source that is being observed. It relies on the CALCODE as specified in the schedule file (we sort of make a bit of an assumption that the observers get this right). The output is written into the main file, as specified by the LUN.

Call sequence:

      subroutine live_radio_source(lun, seed)
      implicit none
      include 'caobs$inc:caobs_status.inc'
      integer
     -  lun,     ! Logical Unit Number
     -  seed     ! Random number generator seed

Creation date: 23-Sep-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_stations`

Function:

This routine puts some graphics in to display the positions of the ATCA antennas on the railway track. It determines the array from the station numbers that are recorded in the global memory. It checks to see if the current configuration matches any of the known, named configurations. The output is placed in the file specified by the LUN.

Call sequence:

      subroutine live_stations(lun)
      implicit none
      include 'caobs$inc:caobs_status.inc'
      integer
     -  lun        ! Logical Unit Number

Creation date: 28-Sep-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_table`

Function:

This routine creates a CAMON-style table of a variety of antenna parameters for inclusion in the HTML file. The output is written in fixed format to the file specified by the LUN.

Call sequence:

      subroutine live_table(lun,az,el,antfnc)
      implicit none
      include 'caobs$inc:caobs_status.inc'
      integer
     -  lun          ! Logical Unit Number
      real
     -  az(6),       ! Antenna azimuths
     -  el(6)        ! Antenna elevations
      character*8
     -  antfnc(6)    ! Antenna stati

Creation date: 28-Sep-1995

Author: Derek McKay

File: atca_live.for

Routine name: `live_today_crew`

Function:

This line prints a single line to the specified logical unit number, comprising of a general description of the date/time and a description of the dedicated souls to command this great telescope of ours.

Call sequence:

      subroutine live_today_crew(lun,seed)
      implicit none
      integer
     -  lun,     ! Logical Unit Number
     -  seed     ! Random number generator seed - for randomness' sake

Creation date: 23-Sep-1995

Author: Derek McKay (in a wave of patriotism)

File: atca_live.for

Routine name: `live_weather`

Function:

This routine gives a report of the current weather at the ATCA. It gives the cold data a chat feel. The output is written to the main LUN passed to it.

Call sequence:

      subroutine live_weather(lun, seed)
      implicit none
      include 'caobs$inc:caobs_status.inc'
      integer
     -  lun,     ! Logical Unit Number
     -  seed     ! Random number generator seed - for randomness' sake

Creation date: 23-Sep-1995

Author: Derek McKay

File: atca_live.for

Original: Derek McKay (11-Oct-1996)
Modified: Derek McKay (11-Oct-1996)

Software documentation: ATCA_Live

Preface

Routine name: live_array_activity

Routine name: live_blurb

Routine name: live_current_project

Routine name: live_daily_message

Routine name: live_frequencies

Routine name: live_get_dist

Routine name: live_get_name

Routine name: live_get_project

Routine name: live_location

Routine name: live_other_comments

Routine name: live_other_links

Routine name: live_radio_source

Routine name: live_stations

Routine name: live_table

Routine name: live_today_crew

Routine name: live_weather

Routine name: `live_array_activity`

Routine name: `live_blurb`

Routine name: `live_current_project`

Routine name: `live_daily_message`

Routine name: `live_frequencies`

Routine name: `live_get_dist`

Routine name: `live_get_name`

Routine name: `live_get_project`

Routine name: `live_location`

Routine name: `live_other_comments`

Routine name: `live_other_links`

Routine name: `live_radio_source`

Routine name: `live_stations`

Routine name: `live_table`

Routine name: `live_today_crew`

Routine name: `live_weather`