Software documentation: vis
Preface
Complete program for the display of visibility data, as aquired by the CAGET data logging process. It augments the old M. Kesteven CAVIS. This function consitutes the main loop and interrupt detect. The interrupt system uses the Screen Management Run-Time Libraries, In the event of an interrupt, the command parser is called, else, every 5 seconds, the current graph is updated. The entire program implements PGPLOT routines for graphics capability, and the initialisation of these are also done here. Thanks go to Mark Wieringa and Dave McConnell for help with some of the code.Call sequence:
program vis
implicit none
include 'vis$inc:command_ast.inc' !Declarations for async. input
include 'vis$inc:vis_cmd.inc' ! Declarations for command variables
include 'vis$inc:vis_int.inc' ! Declarations for interrupt variables
include 'vis$inc:vis_plt.inc' ! Plot include file (for warning message)
include 'vis$inc:vis_std.inc' ! Standard include file (devices etc.)
include 'caget$inc:caget.inc' ! CAGET standard declarations
character*80 plot_dev ! String returned by PGplot (for testing)
logical
- replace, ! Do we want to clear an old graph?
- timer ! Interrupt loop flag
integer
- n_calls, ! Number of calls made to map_mem()
- seconds, ! Number of seconds in interrupt cycle
- pbcols, ! Number of columns in the SMG$ paste board
- str_len, ! Generic string length variable
- status, ! Generic function "return status" variable
- i ! Generic loop variable
external command_ast
data seconds /5/ ! Time between checks for data updates
Creation date:
13-Jul-1993
Author: Derek McKay
File: VIS.FOR
Routine name: [bs]
Function:
[tbs]
Call sequence:
subroutine vis_www_help
implicit none
include 'vis$inc:vis_int.inc' ! Handle SMG$ calls etc.
include 'vis$inc:command_ast.inc'
Creation date:
[tbs]
Author: [tbs]
File: VIS_HELP.FOR
Routine name: bells_whistles
Function:
Adds some nice effects to the output display, most of which aren't particulary well documented - especially the symbols. Maybe the symbols could be taken out one day?
Call sequence:
subroutine bells_whistles
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_plt.inc'
Creation date:
16-Jun-1993
Author: Derek McKay
File: PLOTGRAPH.FOR
Routine name: cavis_err.inc
Function:
Error handling variables.
Call sequence:
character error*72 ! Error message
logical valid ! Is the command valid or not
common /error/ error,valid
Creation date:
28-Jul-1994
Author: Derek Mckay
File: VIS_ERR.INC
Routine name: cavis_int.inc
Function:
Cavis_int.inc contains the interrupt variable declarations.
Call sequence:
integer pbid, ! SMG pasteboard id number
- kbid, ! SMG virtual keyboard id number
- dispid, ! SMG display id
- pbrows, ! #rows on pasteboard
- cyc_id, ! Interrupt cycle id number
- cycle_ef, ! Interrupt cycle event flag
- interrupt_ef, ! Interrupt event flag
- efn_wait_any ! Function (event flag wait)
logical cycle, ! No interrupt, continue
- cycle_flag, ! Logical for the cycle event flags
- interrupt_flag ! Logical for interrupts
common /smg/ kbid,dispid,pbrows
Creation date:
15-Apr-1993
Author: Derek McKay
File: VIS_INT.INC
Routine name: cavis_std.inc
Function:
Standard include file. Contains the user command and the device names.
Call sequence:
character
- cmd*80, ! User input command
- hard_dev*80, ! Hardcopy standard device
- soft_dev*80 ! Software screen display device
common /standard/ cmd,hard_dev,soft_dev
Creation date:
12-May-1993
Author: Derek Mckay
File: VIS_STD.INC
Routine name: clean_cmd
Function:
Remove leading colons (usually for residues, but you never know). Remove leading spaces. Works on any string varible, not "command" specific.
Call sequence:
subroutine clean_cmd(command)
implicit none
character*(*) command ! Command to be cleaned
Creation date:
6-Apr-1993
Author: Derek McKay
File: VIS_COMMAND.FOR
Routine name: cmd_array
Function:
This allows one to specify exactly which antennas constitute a valid array. This will prevent the ONSOURCE command from causing no data to be plotted, because at least one antenna is not on source. It will also prevent the users from selecting baselines involving that antenna, while the "EXPERT" function is disabled.
Call sequence:
subroutine cmd_array()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
include 'vis$inc:vis_int.inc'
Creation date:
23-Jun-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_caget
Function:
To show the user the current status of the CAGET system. Basically set as a diagnostic for the developer/trouble- shooter.
Call sequence:
subroutine cmd_caget()
implicit none
include 'vis$inc:vis_int.inc'
include 'caget$inc:caget.inc'
Creation date:
6-Jul-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_cycles
Function:
Accept a number of cycles for the history of the VIS display
Call sequence:
subroutine cmd_cycles(cmd_line)
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
character*72 cmd_line ! The command that invoked this call
Creation date:
-0-Jun-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_history
Function:
Accept a time for the history of the VIS display. The second argument in the cmd_line variable is the history offset. This is set to 0, if it is not specified.
Call sequence:
subroutine cmd_history(cmd_line)
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
character*72 cmd_line ! The command that invoked this call
Creation date:
21-Sep-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_monitor
Function:
To extract and load a new monitor point as specified on the commands line. It returns .true. if the current graph would be affected by the requested monitor point. VIS will handle up to three monitor points. It will monitor them over every antenna, but it has no history. When a monitor point is set up to be monitored, all data from that point on, will begin to accumulate in the history (5000 cycles at present 17-Nov-1993). As mentioned above, VIS can only monitor 3 at a time. They are quantities "1","2" and "3", just like amplitude is "A". The monitor points are allocated to these quantities. So, if the user wants to examine the monitor point for the 70K stage temperatures in the L/S (20/13cm) receiver, he would allocate to a VIS quantity (1,2 or 3) the monitor point "LS70K". Data collection would commence from the time of definition. If it was viewed one hour later, there would be one hours history to view. To specify it, the user would use "1-t" or the appropriate number, if not "1". Of course, this means the user can plot other things with it. e.g. "1ap-t", "1a-b" or even "123-t" or "1-2". The monitor point data will continue to roll in until the 5000 (or whatever) cycles are filled, after which it will write over the oldest data.
Call sequence:
logical function cmd_monitor(cmd_line,axis_code)
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
include 'vis$inc:vis_mon.inc'
include 'vis$inc:vis_plt.inc'
character*80 cmd_line ! The standard command line from the user
character*4 axis_code ! The code that specifies what quantities are
! currently being displayed.
Creation date:
16-Nov-1993
Author: Derek McKay
File: MONITOR.FOR
Routine name: cmd_psc
Function:
This routine displays the Phase Stability Correlation (PSC) for a given reference antenna and IF (e.g. 6A, 3D etc.). It handles the unusual setup by discarding any command residue, establishing its own command sequence and forcing the interpreter to handle that, instead of any alternative commands thta the user may have appended.
Call sequence:
subroutine cmd_psc()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
include 'vis$inc:vis_plt.inc'
include 'vis$inc:vis_int.inc'
Creation date:
-1-Apr-1994
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_recall
Function:
This routine reads all the selectable parameters from a file. These must have been previously saved with a SAVE command (which calls cmd_save). It accepts its search target as the argument. If the argument is LIST, it will display everything it has got so far.
Call sequence:
subroutine cmd_recall()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_int.inc'
include 'vis$inc:vis_err.inc'
Creation date:
9-Jul-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_ref
Function:
This routine will indicate every trace to be plotted in terms of of an offset from the requested reference baseline. If a suitable selection is made then it is set as the reference baseline, otherwise the referencing is disabled.
Call sequence:
subroutine cmd_ref()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_int.inc'
include 'vis$inc:vis_err.inc'
Creation date:
6-Jul-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_save
Function:
This routine writes all the selectable parameters to a file. These may later be recovered by the "RECALL" command which calls cmd_recall. The argument will be the name given to the setup. An argument of RESET will clear the file of all setups.
Call sequence:
subroutine cmd_save()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
Creation date:
5-Jul-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_scale
Function:
This command allows the user to force manual scaling onto a quantity. If the argument to the command is nothing then all manual scaling is turned off. If it is a single quantity, and nothing else, then that particular quantity is auto scaled, if a quantity letter and two values are specified, then manual scaling is implemented for that quantity.
Call sequence:
subroutine cmd_scale()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
include 'vis$inc:vis_plt.inc'
include 'vis$inc:vis_int.inc'
Creation date:
5-Jul-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_scan
Function:
Basically, this function is similar to the CMD_SOURCE routine, but it allows one to check for a specific scan type instead of a source name. It is useful for picking out calibrators, etc.
Call sequence:
subroutine cmd_scan()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
Creation date:
-1-Apr-1994
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_source
Function:
If a non-space source name is specified, then turn source filtering on and set the argument as the source name.
Call sequence:
subroutine cmd_source()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
Creation date:
-5-Jun-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_src_list
Function:
Provides a list of the sources that can be seen by the CAGET file.
Call sequence:
subroutine cmd_src_list
implicit none
Creation date:
11-Aug-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_status
Function:
To show the user the current settings and selections that have been deployed on the VIS program.
Call sequence:
subroutine cmd_status()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_int.inc'
include 'vis$inc:vis_ver.inc'
include 'vis$inc:vis_plt.inc'
include 'caget$inc:caget.inc'
Creation date:
28-Jul-1994
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_time
Function:
Determine from the user, what time reference frame he would like to use. Options will generally be AEST, UT, EDST. Some times will have pointers and will default to a similar time; e.g. UTC,GMT -> UT, etc. Notice that we convert the length of the history offset if we are going from solar to sidereal time of vice versa.
Call sequence:
subroutine cmd_time()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
include 'constants'
Creation date:
-1-Nov-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: cmd_zoom
Function:
This routine will use the mouse/cursor selection of the user to rescale the graph of the users choice.
Call sequence:
subroutine cmd_zoom()
implicit none
include 'vis$inc:vis_plt.inc' ! For plot/data information
include 'vis$inc:vis_err.inc' ! Allow error handling
include 'vis$inc:vis_cmd.inc' ! Access to command lines etc.
Creation date:
3-Dec-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: colourmap
Function:
Defines the colours used in the VIS program. The selection is designed to maximise colour sparation, as well as intensity separation.
Call sequence:
subroutine colourmap
implicit none
Creation date:
12-May-1993
Author: Derek Mckay
File: SETUP.FOR
Routine name: command_ast
Function:
The COMMAND_AST function is responsible for the collection of command input. It works asynchronously from the main program. It collects characters till return is hit and returns a command- string stripped of leading and trailing whitespace and converted to uppercase (a single space may be returned). Only when return is hit does it set the interrupt flag to signal the main program that there are commands to be processed It also provides a 20 line command recall buffer and can store more than one command if required.
Call sequence:
subroutine command_ast
implicit none
include 'vis$inc:command_ast.inc'
include '($smgdef)'
Creation date:
24-Jun-1993 - latest version 7-Oct-93 MHW
Author: Mark Wieringa & Derek McKay
File: COMMAND_AST.FOR
Routine name: command_ast.inc
Function:
command_ast.inc contains the asynchronous input variable declarations.
Call sequence:
integer
- cmd_dispid, ! SMG display id for input
- cmd_disprows, ! #rows on input display
- cmd_ef, ! Interrupt event flag to set on completed input
- cmd_kbid, ! SMG virtual keyboard id number
- MAXN_CMD, ! Constant, max. number of commands in cmd_arr
- MAXN_RECALL, ! Size of command recall buffer
- MAXCMD_LEN, ! Max length of command
- n_cmd ! Actual #commands in cmd_arr
parameter (MAXN_CMD=1,MAXN_RECALL=20,MAXCMD_LEN=60)
character*60
- cmd_arr(MAXN_CMD)! array with commands to be processed
common /command_ast/ cmd_dispid,cmd_disprows,cmd_ef,cmd_kbid,
- n_cmd,cmd_arr
Creation date:
7-Oct-1993
Author: Mark Wieringa
File: COMMAND_AST.INC
Routine name: cross_hair
Function:
Given the (x,y) coordinate, and the number of the graph (1-3) this routine plots a full graph cross hair in the currently selected colour. The graph ID number merely refers to which graph on the VIS screen. As you may know, VIS can plot multiple graphs simultaneously. These are numbered from 1 to 3 (at present) and the graph ID number is merely the index to this. Note that the reference to graph ID 4 is the common horizontal axis.
Call sequence:
subroutine cross_hair(x,y,graph)
implicit none
include 'vis$inc:vis_plt.inc'
real
- x, ! The x-corrdinate of the cross-hair centre
- y ! The y-coordinate of the cross-hair centre
integer
- graph ! The graph ID number (1,2 or 3)
Creation date:
6-Dec-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: extract_cmd
Function:
When the user enters a string of text at a program prompt, the program delimits it by a carriage return. In addition to this, we would like the ability to stack multiple commands on one line. Using the delimiting character "", this routine pulls off all characters in front of the first "" and puts it into teh variable "command". The remaining characters (after the first "") are put in the "residue" variable. That way, the command interpreter can keep extracting and executing commands until the residue is empty.
Call sequence:
subroutine extract_cmd(command,residue)
implicit none
character*(*) command, ! Command to be extracted
- residue ! What occurs after the first ";"
integer colon, ! Index of first colon in string
- len ! Length of returned string from str$trim
Creation date:
6-Apr-1993
Author: Derek McKay
File: VIS_COMMAND.FOR
Routine name: get_coord
Function:
This routine will examine the graphical output display and determine what the coordinates are for the selected point. It is only valid for some device types.
Call sequence:
subroutine get_coord()
implicit none
include 'vis$inc:vis_plt.inc' ! ONly needed for graph colours
include 'vis$inc:vis_err.inc' ! Allow error handling
include 'vis$inc:vis_cmd.inc' ! Access to command lines etc.
Creation date:
2-Nov-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: get_time
Function:
Determines the time of the requested cycle in seconds. Will do a solar-sidereal conversion if neccessary and apply the timezone/logitude correction that was supplied
Call sequence:
real*8 function get_time(utc,offset,sidereal)
implicit none
real*8
- utc, ! Universal Coordinated Time (in TJD format)
- offset ! The correction to be applied for timezone/longitude
logical
- sidereal ! The time requested is a sidereal one (GMST,LST,etc.)
Creation date:
11-Nov-1993
Author: Derek McKay
File: LOADDATA.FOR
Routine name: getbsln
Function:
Given two antennas, "a" and "b", this routine calculates the appropiate CAGET reference (i.e. bsln subscript in the "vis"/"del"/etc. arrays. It may in future be replaced by an outright lookup table, but it is not particularly important for speed.
Call sequence:
integer function getbsln(a,b)
implicit none
integer a,b,c,d,x(5)
data x/0,5,9,12,14/
Creation date:
12-May-1993
Author: Derek McKay
File: SELECT.FOR
Routine name: graphcount
Function:
In the character string, AXIS, there are four postions. The character in the 4th indicates the X-axis, and the characters in positions 1 to 3 indicate the Y-axes. So that the plotting function knows how many sets of axes there are needed to cover all the valid Y-axes, this routine counts the number of non- white space characters in positions 1 to 3 inclusive and returns the value.
Call sequence:
integer function graphcount(axis)
implicit none
character*4 axis ! The data types for the axes
Creation date:
18-Jun-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: install_mp
Function:
This subroutine will take a monitor point index and monitor point VIS ID, and set up the appropriate graph labels etc. See also the comment for the routine: cmd_monitor.
Call sequence:
subroutine install_mp(mp_qty,mp_index)
implicit none
include 'vis$inc:vis_plt.inc'
include 'array$inc:a_params.inc'
include 'array$inc:a_data.inc'
character*1
- mp_qty ! This is the VIS mp number that is being defined
integer
- mp_index ! The pnt_def monitor point index
Creation date:
16-Nov-1993
Author: Derek McKay
File: MONITOR.FOR
Routine name: interpret_cmd
Function:
When a command interrupt is received, this routine analyses the contents and determines what action to take. If neccessary error messages will be displayed. It is somewhat unfortunate that the number of commands has blown out of control - there are millions of the little blighters... and the wretched thing is that half of them aren't even VIS commands (aarrrgggghhhh!)
Call sequence:
subroutine interpret_cmd()
implicit none
include 'vis$inc:vis_cmd.inc' ! Be responsive to command passing
include 'vis$inc:vis_err.inc' ! Be resposive to error handling
include 'vis$inc:vis_plt.inc' ! Know about what are valid quantities
include 'vis$inc:vis_int.inc' ! Handle screen printing, SMG$ calls etc.
Creation date:
31-Jul-1996
Author: Derek McKay
File: INTERPRET.FOR
Routine name: lo_av
Function:
A simple function that merely returns the LO round trip phase average out of OBSCOM. It has been written seperately to avoid a confilct in the CAOBS$INC:CAOBS_STATUS.INC and CAGET$INC:CAGET.INC include files (duplicity of the /getvis/ structure.
Call sequence:
real function lo_av(antenna)
implicit none
include 'caobs$inc:caobs_status.inc'
integer antenna ! Antenna number
Creation date:
3-Dec-1993
Author: Derek McKay
File: MONITOR.FOR
Routine name: load_array
Function:
This routine takes a specified quantity ID letter and loads an array with this data suitable for plotting by PGplot. It also returns the lower and upper limits of the data for limit analysis and autoscaling. At present, only a limited number of quantities are supported, and accurate baseline representation is not guarenteed. Graph is asked for so that the function knows which part of the data array to load it into. Multiple, large scale "if" structures are used to speed the access. In the future, source detection may be implemented.
Call sequence:
subroutine load_array(req_cyc)
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_mon.inc'
include 'vis$inc:vis_plt.inc'
include 'vis$inc:vis_tri.inc'
include 'caget$inc:caget.inc'
include 'obs$1:[array.code.ref]constant.inc'
integer req_cyc ! Requested number of cycles (-1 = max)
Creation date:
3-Jun-1993
Author: Derek McKay
File: LOADDATA.FOR
Routine name: load_mp
Function:
Load Monitor Points. This routine will take the current values of the requested monitor points and the RTP's (round trip phases) and insert them into an array that mimics the organisation of the CAGET structure. See also the comment for the routine cmd_monitor.
Call sequence:
subroutine load_mp()
implicit none
include 'vis$inc:vis_plt.inc'
include 'vis$inc:vis_mon.inc'
include 'caget$inc:caget.inc'
include 'array$inc:a_params.inc'
include 'array$inc:a_data.inc'
Creation date:
12-Nov-1993
Author: Derek McKay
File: MONITOR.FOR
Routine name: map_mem
Function:
A simple call for the map_file operation. This routine calls MAP_FILE for a limited set of often used applications: namely mapping an area of memory onto a file starting at the start of the file. Note that the area of memory to be mapped (argument START) should be page aligned. This can be achieved by placing it in a named common block and including the option "psect_attr=name,page" in the link statement.
Cluster variable changed from 32 to 256 (DJM:10-Jun-1993)
Call sequence:
subroutine map_mem(start,end,fname,init,chan)
implicit none
byte start, ! starting location to me mapped
- end ! last byte to be mapped
character*(*) fname ! name of file on which to map the memory
logical init ! if .TRUE., the file will be opened
integer chan ! If init=.true., chan is returned to be
! used on subsequent calls.
Creation date:
5-MAR-1993
Author: D McConnell
File: CAGETMAP.FOR
Routine name: num_ants
Function:
Users specify the antennas that consitute a valid Array using the "ARRAY" command. This information is stored as a bit-indexed integer ( decimal 3 = binary 00000110 = CA03,CA04,CA05,CA06 OK). This routine counts the number of selected antennas, and returns the result of this count.
Call sequence:
integer function num_ants(array)
implicit none
integer array ! Bit indexed user antenna selection
Creation date:
25-Nov-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: numbsln
Function:
VIS is currently set up that 15 baselines may be specified. The currently selected ones are generally stored in a 3x15 integer array. For each of the 15 baselines there is a baseline number (1-21), a polarisation number (1-4) and a frequency number (1-2). Regardless of the 2nd and 3rd values, a value of 0 in the bseline variable indicates a NULL selection. This function simply counts the number of non-NULL selections and returns this number as the number of valid baselines selected. Note that the array "bsln" is from 0 to 16; this is to allow for the 0th trace (which is the reference - and not plotted).
Call sequence:
integer function numbsln(bsln)
implicit none
integer bsln(1:3,0:15)
Creation date:
19-May-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: onoff
Function:
Returns an "ON" if the passed value is true, otherwise is returns "OFF".
Call sequence:
character*3 function onoff(value)
implicit none
logical value
Creation date:
-7-Jun-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: plotdata
Function:
Plot the data onto a viewport.
Call sequence:
subroutine plotdata(plot,num_traces,cyc,ant_qty)
implicit none
integer plot, ! Which plot are we doing
- num_traces, ! How many traces are we plotting
- cyc ! the number of cycles to put on the screen
logical ant_qty ! Is this an antenna based quantity? (T=yes,F=no)
include 'vis$inc:vis_plt.inc'
include 'vis$inc:vis_cmd.inc'
Creation date:
15-Jun-1993
Author: Derek McKay
File: PLOTGRAPH.FOR
Routine name: plotdump
Function:
Creates a postscript file of the current VIS display.
Call sequence:
subroutine plotdump(command)
implicit none
include 'vis$inc:vis_err.inc' ! Allow error message display
include 'vis$inc:vis_std.inc' ! Provides us with device names etc.
include 'vis$inc:vis_plt.inc' ! Allows access to the label colours
character*80 command ! The user command that activated this subroutine
Creation date:
10-May-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: plotgraph
Function:
Clear the screen and plots a new graph from scratch. I refer to a "data signal". When the data is read, a certain condition will cause it to stop acquiring data and plot what it has. Things like off-source, source change, etc. are valid resons and I refer to these condition events as data signals. The data signal is indicate in the variable "signal"
Call sequence:
subroutine plotgraph(replace)
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_plt.inc'
include 'caget$inc:caget.inc'
logical replace ! Do we want to replace an old graph
Creation date:
21-Sep-1993
Author: Derek McKay
File: PLOTGRAPH.FOR
Routine name: plotuv
Function:
Clear the screen and plots a new UV grey-scale graph from scratch.
Call sequence:
subroutine plotuv(replace,req_qty)
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_err.inc'
include 'vis$inc:vis_plt.inc'
include 'caget$inc:caget.inc'
logical replace ! Do we want to replace an old graph
character*1 req_qty ! Requested quantity
Creation date:
11-AUG-1993
Author: Derek McKay
File: PLOTUV.FOR
Routine name: qty_index
Function:
This routine will take the specified character and return the array subscript for the appropriate quantity. This allows functions to gain access to the units and names of quantities that are being plotted as well as the limits etc. This function merely converts the user's letter choice into that array index by finding the index within the reserved quantitt letter array (QTYS). The value returned by the index value is what is desired.
Call sequence:
integer function qty_index(qty_letter)
implicit none
include 'vis$inc:vis_plt.inc'
character*1 qty_letter ! The data types for the axes
Creation date:
20-Sep-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: select_bsln
Function:
Interpret the arguments of a "select" command to assign a Baseline, Polarization and Frequency number of each of the 15 traces that are currently supported. It roughly follows the Mike Kesteven CAVIS system.
Call sequence:
subroutine select_bsln
implicit none
include 'vis$inc:vis_cmd.inc' ! Be responsive to commands
include 'vis$inc:vis_err.inc' ! Be responsive to error handling
Creation date:
12-May-1993
Routine name: select_cross
Function:
Checks of a leading "-" (to see if we want it on or off) and then applies this to the selection map.
Call sequence:
subroutine select_cross (sub_line, map)
implicit none
include 'vis$inc:vis_err.inc' ! Be responsive to error handling
character*(*) sub_line
Creation date:
6-Jul-1993
Author: Derek McKay
File: SELECT.FOR
Routine name: set_cursor
Function:
Set the cursor to allow for the position of the prompt. The passed argument indicates the requested column.
Call sequence:
subroutine set_cursor(column)
implicit none
integer column
Creation date:
11-Oct-1993
Author: Derek McKay
File: VIS_UTIL.FOR
Routine name: set_vport
Function:
Create a PGPLOT viewport. Because of the enormity of the labels in a time style quantity (e.g. Right Ascension, Hour Angle, Time etc.), I have constricted the graph slightly in the horizontal to fit *most* device driver outputs, even though the XWINDOW could be filled out a bit more...
Call sequence:
subroutine set_vport(graph,maxgraphs)
implicit none
include 'vis$inc:vis_plt.inc'
include 'vis$inc:vis_cmd.inc'
integer
- graph, ! The number of the current graph that we want to
! establish
- maxgraphs ! The total number of graphs that are being displayed
Creation date:
2-Nov-1993
Author: Derek McKay
File: PLOTGRAPH.FOR
Routine name: set_window
Function:
Create a PGPLOT window.
Call sequence:
subroutine set_window(graph)
implicit none
integer
- graph ! The number of the current graph that we want to
! establish
include 'vis$inc:vis_plt.inc'
include 'vis$inc:vis_cmd.inc'
Creation date:
2-Nov-1993
Author: Derek McKay
File: PLOTGRAPH.FOR
Routine name: setup
Function:
Perform all the neccessary functions at startup time. It is also used as a means of resetting the display from a particulary convoluted user setup. It is called at program startup and when the "default" command is issued.
Call sequence:
subroutine setup
implicit none
include 'vis$inc:vis_cmd.inc/list'
include 'vis$inc:vis_std.inc/list'
include 'vis$inc:vis_err.inc/list'
include 'vis$inc:vis_mon.inc/list'
include 'vis$inc:vis_plt.inc/list'
include 'vis$inc:vis_ver.inc/list'
include 'caget$inc:caget.inc/list'
Creation date:
29-Nov-1993
Author: Derek McKay
File: SETUP.FOR
Routine name: sort_bsln_order
Function:
This routine takes the "bsln" array (which defines what baselines each trace displays) and sorts it by the length of the baseline. The sort algorithm is adapted from a straight insertion method outlined on page 321 of Numerical Recipes (in FORTRAN) 2nd ed.
Call sequence:
subroutine sort_bsln_order
implicit none
include 'vis$inc:vis_cmd.inc'
Creation date:
7-Jul-1993
Author: Derek McKay
File: SELECT.FOR
Routine name: start_cycle
Function:
Determines which cycle is appropriate as a starting location for reading in the requested data.
Call sequence:
integer function start_cycle(offset)
implicit none
include 'caget$inc:caget.inc'
real*8 offset ! Offset in days from the most recent data
Creation date:
16-Jun-1993
Author: Derek McKay
File: LOADDATA.FOR
Routine name: timeoffset
Function:
Determines the number of seconds to be added to the Modified Julian Date (in seconds) to get the requested time standard.
Call sequence:
real*8 function timeoffset(timestd)
implicit none
include 'obs$1:[array.code.ref]constant.inc'
character*4 timestd ! The time standard that has been requested
Creation date:
16-Jun-1993
Author: Derek McKay
File: LOADDATA.FOR
Routine name: toggle
Function:
Turn on/off a specified logical. The arguments ON and OFF are recognised, otherwise the command will just toggle the current value to the alternative. The variable "cmd_line" is set up. For one a direct call with arguments will be more cpu efficient than including the entire include file "vis_cmd.inc" Also, it make this routine available for other non-command line operations. The function returns the XOR of the passed and returned value of the specified logical; i.e. it will return .true. if the value changes.
Call sequence:
logical function toggle(cmd_item,cmd_line,verbose,message)
implicit none
logical
- cmd_item, ! The logical that is to be turned on/off
- verbose ! If TRUE, display verbose command report
! message
character*72
- cmd_line ! The command that invoked this call
character*(*)
- message ! The message to be displayed if VERBOSE
! command reporting has been turned on
Creation date:
7-Jul-1993
Author: Derek McKay
File: COMMANDS.FOR
Routine name: trace_census
Function:
This routine determines how many traces should be loaded, based on the qunatity that has been given. If the quantity is an antenna based one, then we set the number of traces to the number of antennas, and analyze the array mask (antennas selected, when needed. This saves the implementation of even more arrays and variables, which, in a program like this, are hard to keep track of anyway. Notice that the number of baselines is passed into this routine, rather than calculated from it. This is to reduce the need for passing all the "bsln" array in/out to allow the calculation. This program is getting rather large, and this is a way to help reduce overheads. A further modification that may be made to this subroutine, is that of "array based" quantities. These are things that are the same for every baseline/antenna, and so the number of traces would be one only. I don't think that any additional graphics modifications need to be made in this case.
Call sequence:
subroutine trace_census(qty,num_bslns,num_traces,ant_qty)
implicit none
character*1 qty ! The VIS quantity that is being "`census'ed"
integer
- num_bslns, ! The number of baselines selected
- num_traces ! The number of traces to be used by the calling
! routine
logical ant_qty ! Set to .true. if the quantity is antenna based
Creation date:
26-Nov-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: update_graph()
Function:
This routine would only be called if it was believed that new data has been recorded by CAGET. If there has it determines whether we have crossed our time limit (gone of the right hand edge of the screen for a time graph) and if so, will order a new graph. Otherwise, it will just add the extra points. It replaces the old routine "data_check".
Call sequence:
subroutine update_graph()
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_plt.inc'
include 'caget$inc:caget.inc'
Creation date:
12-Nov-1993
Author: Derek McKay
File: PLOTGRAPH.FOR
Routine name: value_to_string
Function:
Converts a given value (for a given axis) into a meaningful string; returning this, and its length.
Call sequence:
subroutine value_to_string(value,qty,str,len)
implicit none
real value ! The raw "world-coordinate" value of the quantity
character
- qty*1, ! The quantity that is being converted
- str*(*) ! The returned string
integer len ! The length of the returned string
Creation date:
1-Nov-1993
Author: Derek McKay
File: GRAPHUTIL.FOR
Routine name: vis_bsln_name
Function:
Given a traces baseline, polarization and frequency indicies, this routine provides a 4 character "baseline" name. For example "34CC" or "25Q2". Note that the second set of polarisations provides the stokes parameters. The naming conventions used in vis are that the 2 linear polarisations are A and B for the first frequency and C and D for the second frequency. In this way the four IF's (in the true sense of the word) are mapped onto A, B, C and D. For the stokes parameters, the standard nomenclature (I, Q, U and V) are used with the frequency (1 or 2) appended. (OK, so it's a glorified lookup table. So sue me!)
Call sequence:
character*4 function vis_bsln_name(bsln,poln,freq,stokes_conv)
implicit none
integer bsln, ! Baseline (1-21)
- poln, ! Polaraisation
- freq ! Frequency (1-2)
logical stokes_conv ! Are we converting to stokes parameters?
character*2 num(21), ! Antenna numbers
- chr(16) ! Polarisations (linear + stokes)
This routine relies on teh following lookup tables...
data num /'11','22','33','44','55','66','12','13','14','15','16',
- '23','24','25','26','34','35','36','45','46','56'/
data chr /'AA','AB','BA','BB','CC','CD','DC','DD',
- 'I1','Q1','U1','V1','I2','Q2','U2','V2'/
Creation date:
12-May-1993
Author: Derek McKay
File: SELECT.FOR
Routine name: vis_cmd.inc
Function:
vis_cmd.inc contains all the variables that are used by the VIS programs as commands and command flags. It also contains user selection information.
Call sequence:
character
- scanflag*1, ! Display only 'C' or 'B' or all (' ')
- axis*4, ! Code for the axes of a plot
- command*72, ! VIS command
- residue*72, ! Remainder of a VIS command line
- source_name*9, ! Name of object for the source filter
- timecode*4 ! Specifies what time is used: AEST,UT,etc.
integer
- array, ! The mask of what consititues a valid array
- bsln(1:3,0:15), ! It is set up for 15 traces (0=ref bsln if
! needed - indicated by the logical refbsln)
! Antenna reference # (1-21)
! Polarisation reference # (1-4)
! Frequency reference (1-2)
- max_cyc, ! The max. number of cycles we allocate to load
- n_cyc, ! The number of cycles that are displayed
- rel_antenna ! The number of the antenna that data may be
! referenced to (for antenna based quantities -
! added as an experiment).
logical
- bells, ! Do we want the glorified bells & whistles
- bslnsort, ! Sort traces by baseline length? (T=yes,F=no)
- concat_cyc, ! Do we want to concatenate cycles (T=yes,F=no)
- expert, ! If FALSE, then VIS tries to make intelligent
! guesses to help the user (e.g. bsln suppression)
- filter, ! Do we want to filter out bad data (T=yes,F=no)
- freq_adjusted, ! Do we divide the Astronomical phase by f(GHz)?
- grid_on, ! Do we plot a grid? (T=yes,F=no)
- labels, ! Label all the graphs (boxes, numbers, source,
! frequency, etc.)
- lines, ! Plot a line regardless!!
- lock, ! Whether or not we want to fix the l-h edge
- loop, ! Main loop flag
- man_scale, ! Is any manual scaling in place?
- new_plot, ! New plot (true) or suspended/update (false)
- on_source, ! Is the array on source?
- ph_track, ! Do we want primitive phase tracking
- polcal, ! Do we want polarization calibration
- refbsln, ! Has a reference baseline been selected
- sidereal, ! True if the selected time code is sidereal
- source_filter, ! Are we only interested in a single source?
- squared, ! Are the axes of the same aspect ratio?
- stokes_conv, ! Do we want to convert visibilities to Stokes?
- suspend, ! Do we want updates with time (T=yes,F=no)
- vec_av, ! Do we want primitive vector averaging
- verbose ! Do we want verbose messages on every command
real*8
- hist_offset, ! The offset in the history
- history ! How far back do you want to look?
complex*8
- leakage(6,2,2) ! Leakage terms for pol. calibration
common /command/
- axis,command,residue,timecode,source_name,scanflag, ! Character
- array,bsln,max_cyc,n_cyc,rel_antenna, ! Integer
- bells,bslnsort,concat_cyc,expert,filter,freq_adjusted, ! Logical
- grid_on,labels,lock,loop,
- lines,man_scale, on_source,new_plot,ph_track,polcal,refbsln,
- sidereal,source_filter,squared,stokes_conv,suspend,
- vec_av,verbose,
- hist_offset,history, ! Real*8
- leakage !complex*8
Creation date:
11-Nov-1993
Author: Derek McKay
File: VIS_CMD.INC
Routine name: vis_extract_linear_b
Function:
Looks for 2 antenna numbers and 1 polarisation. Wild card assumed if absent. This routine does the physical interpretation of each of the arguments specified to the select command. This rountine handles the standard format; the "X" option is covered by the select_cross routine.
Call sequence:
subroutine vis_extract_linear_bsln (sub_line, map)
implicit none
include 'vis$inc:vis_err.inc' ! Be responsive to error handling
character*(*) sub_line
Creation date:
12-May-1993
Author: Derek McKay
File: SELECT.FOR
Routine name: vis_extract_stokes_b
Function:
Looks for 2 antenna numbers,1 polarisation and 1 frequency (which is specified immediately after the polarisation). Wild card assumed if absent. This routine does the physical interpretation of each of the arguments specified to the select command. This rountine handles the standard format for stokes parameters.
Call sequence:
subroutine vis_extract_stokes_bsln (sub_line, map)
implicit none
include 'vis$inc:vis_err.inc' ! Be responsive to error handling
character*(*) sub_line
Creation date:
28-Jul-1994
Author: Derek McKay
File: SELECT.FOR
Routine name: vis_get_click
Function:
This routine is a straigh forward user input routine that highlights a given VIS window (out of the total number of VIS windows) and then waits for mouse/cursor input. When this occurs, the routine returns the X and Y values and the ASCII code of the key that was pressed or the button cicked.
Call sequence:
integer function vis_get_click(graph,max_graphs,x,y,c)
implicit none
include 'vis$inc:vis_plt.inc' ! Only needed for graph colours
integer
- graph, ! The graph to select from
- max_graphs ! The total number of graphs on the screen
real
- x,y ! The X,Y coordinates of the clicked location
character*1
- c ! The ID of the button/key that was pressed
Creation date:
2-May-1994
Author: Derek McKay
File: VIS_POINT.FOR
Routine name: vis_get_cycle
Function:
This is a real ^@$%# of a routine. Basically we have to identify the cycle of the CAGET record, which closest fits the time of the mouse/cursor click (i.e. the X-axis cursor value). Thank goodness for the ol' RAMDISK, eh? The routine returns the number of this CAGET cycle.
Call sequence:
integer function vis_get_cycle(req_time)
implicit none
include 'vis$inc:vis_cmd.inc'
include 'vis$inc:vis_mon.inc'
include 'vis$inc:vis_plt.inc'
include 'caget$inc:caget.inc'
real*8
- req_time ! The requested time that the user has asked for a
! "cycle match" for.
Creation date:
2-May-1994
Author: Derek McKay
File: VIS_POINT.FOR
Routine name: vis_help
Function:
This program provides help for the VIS program. It uses the custom "write_line" function, to make it compatible with the SMG$ calls that are used by the main program. Thus it would be suitable for use with other programs that make use of the SMG$ features. It takes a parameter, that specifies the sub-area of the help structure; therefore, users can get help on a specific command straight off, without having to wade through the structure. The library that the program references is just a standard text file (.HLP) that is formatted so that when compiled with the LIBRARIAN (use LIBRARY/HELP/CREATE VIS.HLB VIS.HLP) the suitable help library is generated. Information on how to structure this text file is currently (9-Nov-1993) located in the VMS Programming Manual VOL2B LBR (V5) or The Open VMS Utility Routines Manual LBR (V6). The former contains some concrete examples. The later has some code examples on which this was based.
Creation date: 8-Apr-1994
Author: Derek McKay
File: VIS_HELP.FOR
Routine name: vis_mon.inc
Function:
Monitor point and round trip phase support
Call sequence:
integer
- m_cycles(0:3), ! The number of cycles that have been collected on each
! monitor point
- m_pnt(1:3), ! Monitor point indices
- m_start(0:3) ! CAGET index of the first (oldest) datum; indices
! represent the LO round trip phases (0), and 3 monitor
! points (1-3)
real*4
- m_data(0:4999,1:6,0:3) ! Monitor point data structure
! 5000 cycles
! 6 antennas
! 4 quantities, LO rnd.trip.phase + 3 Mon.Pts
common /monitor/ m_cycles,m_pnt,m_start,m_data
Creation date:
25-Nov-1993
Author: Derek McKay
File: VIS_MON.INC
Routine name: vis_plt.inc
Function:
An include file for data to be plotted. It contains limit information as well as some of the parameters for graph default colours etc.
Call sequence:
integer
- cvsize, ! How much of cvdata was filled
- MAX_QTY, ! How many quantities are avail. to plot
- LAB_COLOUR, ! Colour for labels and borders
- lockcycle, ! Cycle at which data acquisition halts
- plotcycle, ! Last CAGET cycle plotted
- updatecycle, ! Latest CAGET cycle available
- WARN_COLOUR ! Colour for warning messages
parameter (LAB_COLOUR=5,MAX_QTY=24,WARN_COLOUR=4)
logical cvflag(1:5000) ! To plot, or not to plot...
real*4
- cvdata(1:5000,1:15,1:4), ! Generic data structure
! 5000 cycles
! 15 traces (baselines)
! 4 axes, (x, y1, y2 & y3)
- amax(1:4),amin(1:4), ! Auto-scale limits for the 4 axes
- gmax(1:4),gmin(1:4), ! Used limits for the 4 axes
- qty_max(1:MAX_QTY), ! Quantity limits -
- qty_min(1:MAX_QTY) ! (if max&min=0 then auto scale)
real*8
- plottime, ! Time when last cycle plotted
- locktime, ! Time of the earliest cycle on screen
- updatetime ! Time of latest cycle available
character*20
- qty_left(MAX_QTY), ! Left hand side label. This will be the quantity
! name for non-time/angle entities; otherwise it
! will be a blank string (to avoid fouling the
! numeric labelling.
- qty_right(MAX_QTY) ! Similar, bu for the right hand side. This will
! typically be units, but for time/angle qtys. it
! will be the actual name. cf qty_left().
! NB: units should include the parentheses.
character*(*) QTYS ! String of quantity 1st letters (+SPACE)
parameter (QTYS='TNZEXHYRI0123UVWBKFDCPGA ') ! One TRAILING space is
* parameter (QTYS='ABCDEFGHIKNPRTUVWXYZ0123 ') ! One TRAILING space is
! required
NB: The values in QTYS and the arrays qty_left and qty_right must
all be sequentially identical with respect to their referenced
quantities. Order is critical to their succesful operation. The
order is chosen in terms of priority. In a graph, time is expected
to be plotted on the bottom axis at all times. To get around this,
the EXPERT mode must be enabled.
data qty_left /
- ' ', ! Time
- 'Cycles',
- ' ', ! Azimuth
- ' ', ! Elevation
- ' ', ! RA
- ' ', ! HA
- ' ', ! Dec
- 'Real',
- 'Imaginary',
- '1-Way LO Phase',
- 'Monitor Point',
- 'Monitor Point',
- 'Monitor Point',
- 'U',
- 'V',
- 'W',
- 'Baseline',
- 'Paralactic angle',
- 'Frequency',
- 'Delay',
- 'Closure phase',
- 'Phase',
- 'Power (Amp.\u2\d)',
- 'Amplitude'/
data qty_right /
- 'Time', ! Time
- '(CAGET index)', ! Cycles
- 'Azimuth', ! Azimuth
- 'Elevation', ! Elevation
- 'Right Ascension', ! RA
- 'Hour Angle', ! HA
- 'Declination', ! Dec
- '(Pseudo-Jy)', ! Real
- '(Pseudo-Jy)', ! Imaginary
- '(degrees/GHz)', ! 1-way LO phase
- ' ', ! Monitor point 1
- ' ', ! Monitor point 2
- ' ', ! Monitor point 3
- '(kilowavelengths)', ! U
- '(kilowavelengths)', ! V
- '(kilowavelengths)', ! W
- '(kilowavelengths)', ! Baseline
- '(degrees)', ! Paralactic angle
- '(MHz)', ! Frequency
- '(ns)', ! Delay
- ' ', ! Closure phase
- '(degrees)', ! Phase
- '(Pseudo-Jy\u2\d)', ! Power
- '(Pseudo-Jy)'/ ! Amplitude
common /dataplot/ cvsize,cvdata,cvflag,amax,amin,gmax,gmin,
- plottime,plotcycle,updatetime,updatecycle,
- qty_left,qty_right,qty_max,qty_min,lockcycle,
- locktime
Creation date:
12-Nov-1993
Author: Derek McKay
File: VIS_PLT.INC
Routine name: vis_rough_point
Function:
This illegal routine asks the user for a nubmer of inputs using the mouse/cursor. These are then interpretted to provide a set of azimuthal offsets which are ADDED to the pointing parameter "ea" in the PPARAMS.DAT file.
Call sequence:
Creation date: 11-May-1995
Author: Anonymous ;-)
File: VIS_POINT.FOR
Routine name: vis_select_closure
Function:
This routine is the interpretter on the closure command. It allows the user to input a number of closure quantites for plotting. The quantities are then stored in an array that is defined in the included file VIS_TRI (Vis triplets). These are used by the load_array routine to determine the parameters to use in the construction of the final values. It is also used by the plot)graph and associated routines for plotting the values on the graph as they do not match the standard baseline selection. Closure with no arguments however will return to the input screen all the currently selected values.
Call sequence:
subroutine vis_select_closure()
Creation date:
12-Jan-1995
Author: Derek McKay
File: VIS_CLOSURE.FOR
Routine name: vis_ver.inc
Function:
Automatically generated include file to indicate the version and creation date of the program VIS.
Call sequence:
character*(*) VER_STR,VER_CRE
integer VER_MAJ,VER_MIN
parameter (VER_MAJ= 8 )
parameter (VER_MIN= 0 )
parameter (VER_STR='v8.0')
parameter (VER_CRE='VIS v8.0 3-OCT-1996 13:08:00.58')
Creation date:
3-OCT-1996
Author: OBS$1:[VIS.WORK]BUILD_VIS.COM
File: VIS_VER.INC
Routine name: write_help_line
Function:
Write a line of text to the screen taking care to scroll properly. It also will return a status.
Call sequence:
integer function write_help_line(text)
implicit none
character*(*) text
Creation date:
8-Apr-1994
Author: Derek McKay
File: VIS_HELP.FOR
Routine name: write_line
Function:
Write a line of text to the screen taking care to scroll properly. It also will return a status.
Call sequence:
integer function write_line(text)
implicit none
character*(*) text
Creation date:
9-Nov-1993
Author: Mark Wieringa & Derek McKay
File: VIS_UTIL.FOR
Routine name: zero_bsln
Function:
The program can (currently) handle 15 traces. Each trace has associated with it, 3 parameters; the addresses of the baseline, polarization and frequency (1 or 2). These reference the location in the CAGET structures. The baseline index has a valid range of 1 to 21. If it is zero, then that particular trace is regarded as disabled, and is not plotted. As an initialization process, all traces are disabled (have their baseline references set to zero). This routine does that. It does not zero the reference baseline (trace 0).
Call sequence:
subroutine zero_bsln(bsln)
implicit none
integer bsln(1:3,0:15)
Creation date:
12-May-1993
Author: Derek McKay
File: SELECT.FOR
Routine name: zero_map
Function:
When sorting out which baselines/polarizations/frequencies are valid, a logical 21x4x2 "map" is established. If an element is true, then the bsln/poln/freq reference is used. Obviously, the map must be initially set to zero, and that is what this routine does.
Call sequence:
subroutine zero_map (map)
implicit none
logical map(1:21,1:4,1:2)
Creation date:
12-May-1993
Author: Derek McKay
File: SELECT.FOR
Include file: vis_tri
Function:
Contains the general declaration of variables for triplet (closure) quantities.
Creation date: 12-Jan-1994
Author: Derek McKay
File: VIS_TRI.INC
Original: Derek McKay (11-Oct-1996)
Modified: Derek McKay (11-Oct-1996)