DataLink inputParam PARAM/@value

[Mark Taylor]

On Fri, 17 Nov 2017, Markus Demleitner wrote:

> Hi Mark,
> 
> On Wed, Nov 15, 2017 at 11:15:26PM +0000, Mark Taylor wrote:
> > On Wed, 15 Nov 2017, Markus Demleitner wrote:
> > > Essentially, PARAMs that can or must be filled (there's no way for a
> > > machine client to distinguish between the two cases yet; I am hoping
> > > for a VO-DML-based annotation there) have value=""; the rationale is
> > > that PARAM/@value is, in effect, TABLEDATA-encoded[1] and in TABLEDATA,
> > > an empty string is always NULL since VOTable 1.3.
> > > 
> > > If, on the other hand, @value is non-empty, then this value should be
> > > included in the query literally (or after parsing and
> > > TABLEDATA-serialisation, which should end up with an equivalent
> > > result).
> > 
> > Thanks.  This response makes perfect sense.  However, unless I'm
> > missing something (possible - is there a bit of text you can point at?)
> > it's not spelled out or even really suggested in the DataLink text.
> > 
> > I don't think I'm the only one to fail to divine this intent;
> > Carlos Rodrigo responded (in a message which may show up on-list
> > at some point) that he thought that non-blank @value represented
> > a default.
> > 
> > Also, some of the examples look a bit weird to me in the light of your
> > interpretation.  For instance, section 4.3 has this:
> > 
> >    <PARAM name="COLLECTION" datatype="char" arraysize="*" value="ALL">
> >      <VALUES>
> >        <OPTION value="ALL" />
> >        <OPTION value="FOO" />
> >        <OPTION value="BAR" />
> >      </VALUES>
> >    </PARAM>
> > 
> > I don't understand the point of specifying all the options if the
> > client is required to pass COLLECTION=ALL when invoking the service.
> > Given your explanation, I would not in general expect a PARAM
> > with a non-blank @value to have a VALUES child.
> 
> Right -- I eat my words, and this certainly goes to show that we need
> to be more explicit.  As to wording (place TBD) I would propose:
> 
>   [something on @value="" meaning "pass something in"]  If a PARAM
>   within the inputParams GROUP has a non-empty value attribute, a
>   value must be passed to the corresponding service parameter.  While
>   a client may optionally allow user interaction to change that
>   parameter value, its default must be the value of the PARAM's
>   value attribute.
> 
> That sounds almost like a parody.  Hm.  Improvements welcome, but
> apart from surface form, I think that's sensible behaviour, and at
> least the one I had in mind way back when.

I think that needs at least some changes.  The sentence:

    "If a PARAM within the inputParams GROUP has a non-empty
     value attribute, a value must be passed to the corresponding
     service parameter."

doesn't look very helpful - surely the intention of *any* of the
input params is that a value must, or at least is normally expected,
to be passed to the corresponding service parameter.

In some library code I'm sketching out now that works out how to
invoke Service Descriptor-defined services, I'm currently assigning
input parameters into three different groups, according to how
their values are acquired at service invocation time:

   - ROW parameters:
         value is acquired from a cell of the result table;
         a table row object must be supplied to obtain the value

   - FIXED parameters:
        value is provided by the parameter definition
        and fixed for all invocations

   - USER parameters:
        the value must be supplied for each invocation by the user

I'm doing the grouping like this:

   if ( @ref not null )
      -> ROW parameter
   else if ( @value not null )
      -> FIXED parameter
   else
      -> USER parameter

This arrangement doesn't prevent the application code from filling
these parameters differently, e.g. giving the users the option to
change ROW or FIXED parameter values at invocation time; so the
ROW and FIXED values can be viewed as defaults.  I'm currently
not taking any further hints from the PARAM specifications about
how suitable-for-modification the ROW/FIXED [default] values are,
though if a VALUES element is present it can be used to assist
a user who wants to supply their own value.

Incidentally, this means that you can't specify a FIXED parameter
for which the [default] value is null or the empty string.

If the DataLink authors and user community agree that this is the
correct interpretation, or at least the one we want to go with,
then I'd suggest some clarification text following the outline
above (I can draft something on request).  If not ... what
should I be doing?

> One thing I'd consider given my implementation experience is whether
> to disallow changing the parameter value absent a VALUES child of the
> PARAM.  I think without VALUES it's hard to present an actually
> usable UI in the first place

Not necessarily, some counter-examples might be:

   <PARAM name="give-me-all-columns" datatype="boolean" value="false"/>

   <PARAM name="MAXREC" datatype="int" value="100"/>

   <PARAM name="FOO" datatype="char" arraysize="*" value="">
     <DESCRIPTION>
        If you have specified BAR="baz", this parameter's value should
        be the name of your first pet.  Otherwise, use the number you
        first thought of.
     </DESCRIPTION>
   </PARAM>

In the first two of those you could construct a meaningful VALUES
element in an obvious way.  In the third, you couldn't.

It would be possible to take presence of a VALUES child (even an
empty one) as some kind of flag that the user should be
invited to supply a non-default value for what I'm calling a FIXED
(or even ROW) parameter, which I think is what Carlos suggested.
But really if that's the intended meaning, it has to be spelt out
in standards or at least usage note text somewhere, it's (IMHO)
not obvious enough to be implied.

Mark

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-9288776  http://www.star.bris.ac.uk/~mbt/