Software documentation: Campa

14-OCT-1996

Preface

This program is the Compact Array Monitor Point Archiver. It records the time and the monitor points that have changed, every integration cycle in a binary file. The format of the recorded file will be in 4 byte chunks. At each cycle, the time will be recorded as a 4 byte integer. 
 
              buffer
Following the time stamp, there are two 4 byte records containg the "backwards link" (BLINK) and "forwards link" FLINK) in that order. These indicate the record number of the next BLink or FLink record. BLink records always point to BLink records and likewise for FLink records. A BLink or FLink of 0 (zero) means that the end-of-file has been reached. In the case of the BLink, it indicates a true BOF (Begining of File), whereas the FLink indicates that although we are indicating EOF (End of File) further data may be present beyond this. However, the integrity of this data can not be guarenteed or verified and so it should be discarded (which is what will happen with interrupted records). At most, this will represent one cycle of data and so the loss is merely one of time resolution and is comparitively small. Additional code to enhance robustness would not prove incorrigable and would result in negligable gain in data for vast quantities of code (and maintenance). 
              ___________________________________
The data is streamed after the link records. It is encoded in 4 byte packets, each conatining an address comprising 2 bytes and then the 2 bytes of the data associated with that address. The address is of the form 
 
              +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
              | | | | | | | | | | | | | | | | | I MSB
              +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
               ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^
               | | | | | | | | | | | | | | | |
               | | | | | | | | | | | | +-+-+-+--- 4 bit antenna number
               | | | | | | | | | | | |
               +-+-+-+-+-+-+-+-+-+-+-+----------- 12 bit monitor point addr
The code for the CAMPA program is split into 3 files: 
 
              mpa_main.for     ! Main program
              mpa_file.for     ! Data file control routines
              mpa_pdef.for     ! Monitor point definition routines
The CAMPA program should only be run on the main control computer (NOEL::). This is becuase it is important to keep very up to date with monitor point records. Running this program on other machines may lead to missed to duplicated cycles possibly resulting in data loss.

Call sequence: 

      program mpa_main
      implicit none
      include 'ARRAY$INC:a_params.inc'
      include 'ARRAY$INC:a_data.inc'
      include 'ARRAY$INC:array.inc'
include 'CAOBS$INC:caobs_status.inc' Creation date: 26-May-1994

Author: Derek McKay

File: MPA_MAIN.FOR

Routine name: mpa_bflush

Function:

MPA_BFLUSH allows the buffer to be flushed during a write. The MPA_BFLUSH is a secondary entry point to the MPA_BWRITE routine. This routine is called just before closing a file.

Call sequence: 

      entry mpa_bflush(lun)
Creation date: 14-Oct-1996

Author: Mark Wieringa & Derek McKay

File: MPA_BIO.FOR

Routine name: mpa_bread

Function:

This routine allows CAMPR to do a buffered read of 512 byte record files from a monitor point archive file created with CAMPA. It is not a routine in itself, mearely an entry point into the MPA_BWRITE routine. See the MPA_WRITE routine for a description of call variables.

Call sequence: 

      entry mpa_bread(lun,rec,datum)
Creation date: 21-Oct-1994

Author: Mark Wieringa & Derek McKay

File: MPA_BIO.FOR

Routine name: mpa_bwrite

Function:

This routine allows CAMPA to write 512 byte buffered record files. The data is stored, until an MPA_BFLUSH is called, either internally, due to the 512 limit being reached or externally due to the file being about to be closed.

Call sequence: 

      logical function mpa_bwrite(lun,rec,datum)
      integer*4 lun,  ! Logical unit of file
     -          rec,  ! Logical record number
     -          datum ! 4 byte datum to be written
Creation date: 21-Oct-1994

Author: Mark Wieringa & Derek McKay

File: MPA_BIO.FOR

Routine name: mpa_copy_pntdef

Function:

This routine is invoked if it is believed that a new version of AT$ACC:PNDEF.DAT exists. What it will do, is create a local file with an appropriate name (in the form PDEF.MPA####) which conatins one line only. This line is the date of the current PDEF array (as stored in the LAST record). The actual monitor point definitions file is then appended to this newly created file and as such will consitute the local copy of the monitor point database definitions. Note that this routine is passed a version number (as is currently believed by the system). The file it tries to create is labelled acording to its new version number; we increment it here.

Call sequence: 

      subroutine mpa_copy_pntdef(version)
      implicit none
      include 'ARRAY$INC:a_params.inc'   ! To access the date stamp
      include 'ARRAY$INC:a_data.inc'     ! To access the date stamp
      integer version      ! The version number
Creation date: 25-May-1994

Author: Derek McKay

File: MPA_PDEF.FOR

Routine name: mpa_file_name

Function:

This code determines an appropriate filename for the monitor point data file based upon the current UT date (as extracted from the TJD (Truncated Julian Date) and the current version number of PDEF. Both these values are supplied by the calling routine. The file name (which is the returned value) is coded as follows: 

 
                 YYMMDD.MPAVVVV
where "YY" is the last 2 digits of the UT year, "MM" is the UT month and "DD" is the UT day. "MPA" is fixed and is an acronym for "Monitor Point Archive" - uniquely associating this data with the CAMPA program that produces it. "VVVV" is the PDEF version number as explained elsewhere. An example name is given: 
 
                 880126.MPA0001
which would have been taken on the Australian Bicentenary (after 10am AEST) with a PDEF version of 1. Note also that the file name is prepended by 
 
                 CAMPA$DATA:
which will be a logical that points to the valid CAMPA data area.

Call sequence: 

      character*25 function mpa_file_name(tjd,pdef_version)
      implicit none
      real*8 tjd              ! Truncated Julian Date
      integer*4 pdef_version  ! The version number of the monitor point
                              ! definitions
Creation date: 26-Apr-1994

Author: Derek McKay

File: MPA_FILE.FOR

Routine name: mpa_file_new

Function:

Here a new file is opened with the appropriate file name and logical unit number (lun). This file is for the storing of raw monitor point data. It will not contain any header information like PDEF etc..

Call sequence: 

      subroutine mpa_file_new(lun, filename)
      implicit none
      integer lun             ! Logical unit number of file to be opened
      character*25 filename   ! The name of the data file
Creation date: 20-Apr-1994

Author: Derek McKay

File: MPA_FILE.FOR

Routine name: mpa_file_old

Function:

Having established that there is an old file suitable for appending to, we must open it, ascertain the last valid position of data within the file and return the record number pointing to this location and a link_record number pointing to the last valid BLink record in the file. Position determination is done by skipping from FLink record to FLink record and should be moderately fast. An "apparently" redundant buffer variable is used to ensure that any errors on the read are not interpretted as a new record number and are incorrectly passed to the calling routine. The routine should even be able to cope with data files that contain no valid record information. One should remember that this file is for the storing of raw monitor point data. It will not contain any header information like PDEF etc.. Such information is stored in a different file and is accessed by other MPA_* routines.

Call sequence: 

      subroutine mpa_file_old(lun, filename, rec, link_rec)
      implicit none
      character*25 filename   ! The name of the data file
      integer
     -  lun,            ! Logical unit number of file to be opened
     -  rec,            ! Last valid record number -1
     -  link_rec        ! Record number of the last BLink record
Creation date: 26-May-1994

Author: Derek McKay

File: MPA_FILE.FOR

Routine name: mpa_file_open

Function:

This routine will examine whether or not it needs to open a new file. If there is no currently open file, it will attempt to find a file to append to first. It will return the Logical Unit Number (lun) of the opened file and the record number (rec) of the first valid record - 1 (this, of course, will be zero for a new file).

Call sequence: 

      subroutine mpa_file_open(filename,lun,rec,link_rec)
      implicit none
      character*25
     -  filename   ! The VMS file spec. of the data file
      integer*4
     -  lun,       ! Logical Unit Number (of data file)
     -  rec,       ! First valid record number - 1
     -  link_rec   ! The record number of the previous BLink record
Creation date: 20-Apr-1994

Author: Derek McKay

File: MPA_FILE.FOR

Routine name: mpa_file_terminate

Function:

This routine will neatly terminate a file that has been marked for closing. It does this by adding one more dummy record to the data, specifying a dummy time, and a correct BLink and zero FLink. It also gets the previous monitor point record series to point to this FLink record. The routine mpa_file_old will detect this, and discard the dummy monitor point record series, but retain the last (valid) series. As this will not occur on an error or program interruption, the integrity of the data is not compromised.

Call sequence: 

      subroutine mpa_file_terminate(lun, link_rec, rec)
      implicit none
      integer
     -  lun,       ! Logical Unit Number of file to be terminated
     -  rec,       ! Last valid record number
     -  link_rec   ! Record number of the last valid BLink record
Creation date: 1-Jun-1994

Author: Derek McKay

File: MPA_FILE.FOR

Routine name: mpa_pdef_ident

Function:

This routine determines the PDEF identifier from the specified PDEF version file. The identifier is merely the VMS format date, which is stored in the first line of the file (as a comment)

Call sequence: 

      character*40 function mpa_pdef_ident(version)
      implicit none
      include 'ARRAY$INC:a_params.inc'   ! Needed by a_data
      include 'ARRAY$INC:a_data.inc'     ! Just so we can use the
                                         ! "format"
      integer version    ! The version number of PDEF file to be
                         ! examined.
Creation date: 6-May-1994

Author: Derek McKay

File: MPA_PDEF.FOR

Routine name: mpa_pdef_version

Function:

This routine examines all the available PDEF.MPA#### files and determines which one has the highest, and therefore most recent, version number (####) embedded in its filename. This is then returned as the version number of the most recent PDEF archive file.

Call sequence: 

      integer function mpa_pdef_version()
      implicit none
      include '($RMSDEF)'    ! Required for the FIND_FILE... routines
Creation date: 29-Apr-1994

Author: Derek McKay

File: MPA_PDEF.FOR

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