Date: Mon, 21 Apr 2008 16:50:02 -0600 (MDT)
From: Steven T. Myers <smyers@aoc.nrao.edu>
To: aips2-naug@aoc.nrao.edu
Subject: globals/locals proposal

I propose that the following minor changes be made.  This will cause minimal
(in)compatibility issues, and will be easy to document. It will, probably,
not make all users happy.

1. Regardless of the casaglobals=T/F choice, tasks will not change
   the current values of the global parameters (ie. set at python
   level with <param>=<value>).  This means that if you call a
   function with parameters as arguments, these will not reset
   any of the global parameter values, e.g.

   > vis = 'orion.ms'
   > listobs(vis='taurus.ms')
   > print vis
      orion.ms

   The exception to this is that output parameters will be set by the
   task as before.  They are modified upon successful completion of
   the task.

2. If casaglobals=True (the default) then invoking the task
   either with go or with the function call will use the
   current global parameter values for any parameter not
   explicitly given as an argument.  This is what happens
   now, with the exception that the global values for those
   set as a call argument will not be changed (see 1 above)
   as they are currently.

3. If casaglobals=False, then the current global parameters
   will NOT be used on execution, either via go or function
   call.  Any parameters not given as an argument will be
   defaulted to the task default, as if default(<taskname>)
   had been done (e.g. in casaglobal=T mode).  Note that
   the global parameters still exist and retain any values,
   so they can be used explicitly, e.g.

   > casaglobals = F
   > vis = 'orion.ms'
   > listobs(vis=vis)

   As per (1) the globals will not be reset to defaults when the
   task is run (unlike the current behavior).

4. Regardless of the casaglobals=T/F choice, the <taskname>.last
   or any file made with saveinputs will have the current format,
   with the globals set explicitly and the full function call
   given as a comment at the end.  This means that if casaglobals=F
   and you do

   > tget <taskname>
   > go

   It will NOT use the tget values.  This is the price for using
   casaglobals=F.  But you will have the .last values for the globals
   so you can do what is shown as an example in (3) above to use them.

5. Note that an interesting twist might be to allow the setting of
   casaglobals in the task invocation: 

   > task( var1=value1, var2=value2, casaglobals=F) 

   which would not reset the global value of casaglobals but use it
   and thus default the non-specified paramters.  I would therefore
   add casaglobals to the list of all task parameters (like async is
   more or less). My guess is that this is too cumbersome for many
   users`, but it would be one way to get this behavior consistent
   with the rest of my proposal.  It does clutter the parameters list,
   and now casaglobals can be (re)set unexpectedly by a tget.

There are no changes to the way defaults work, there are NO "sticky locals"
where it remembers underneath any previously set values.  The only way to
get previous used values on a task-specific basis is through
saveinputs/tget. Users must manage inputs in their scripts, and if
casaglobals=F then tget does not behave as might be expected (see 4 above).

At this time I do not want to embark on some sort of internal parameter
managing system (e.g. where it keeps the last run values for each task in a
dictionary which may or may not be used depending on mode). I think this
mode will cause more problems than it will actually solve.  If the ALMA and
EVLA sub-system scientists require it, we can scope out this option.

Implementation:

Inside a task, the following will happen:

i) An internal copy of the task parameters is initialized:

   If casaglobals=T, the internal set of parmeters are initialized to the
   current global values (currently in myf[]).

   If casaglobals=F, the internal set of parameters are initialized to the
   task defaults.

ii) Any parameters specified explicitly on the command line call are set to
   specified values.

iii) Task parameters are checked.  If any are invalid, these are reported
   and execution is halted.

iv) Task is executed.

v) If task completion is successful, then the <taskname>.last file is
   written, as it is now.

I think this will be a simple modification of the current tasking.  I think
it captures all the options on the wiki
https://wikio.nrao.edu/bin/view/Software/CasaVariableScope
except for 'Persistent Local (a.k.a. "sticky parameters")', which as is
noted
there can be handled through tget in casaglobals=T mode.

Note that because the global values of parameters will then ONLY be
changeable via explict Python <param>=<value> settings, and the
casaglobals=T/F choice only controls what the task uses as a default
underneath (current/default), scripts should be straighforward to write in a
robust way.

I do NOT propose to have a vigorous round of comments on this.  Feel free to
express opinions to this list but do not expect them to have effect. The
exceptions are the two project sub-system scientists (Crystal and Gustaaf)
who will give their OK (or not) to this proposal, and Lindsey as the ALMA
pipeline lead, who might find this proposal untenable and should let
me know asap if so.  Lorant as the EVLA pipeline guru should also comment
to Gustaaf if he has any issues with this also (but I am assuming since it
has AIPS-like behavior it will be OK).

  -Steve