DataLink inputParam PARAM/@value

[Mark Taylor]

Markus

On Wed, 15 Nov 2017, Markus Demleitner wrote:

> On Tue, Nov 14, 2017 at 04:28:19PM +0000, Mark Taylor wrote:
> > I'm taking my first thorough look at DataLink with a view to writing
> > a client.  It mostly makes sense, but I have a question about the
> > use of the PARAM elements in the inputParams GROUP within a
> > service descriptor RESOURCE.
> > 
> > According to VOTable, PARAM elements must have a @value attribute.
> > But the @value doesn't seem to serve any purpose in an inputParams
> > GROUP, since the PARAM is just there to describe arguments that
> > are to be supplied, in some other way, to the described service.
> 
> Oh, it does -- and it's just a tiny wee bit cheesy.
> 
> 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.

On Wed, 15 Nov 2017, Markus Demleitner wrote:

> I've wondered for a bit whether the should be an update to the
> datalink document just trying to clarify the various aspects a bit.
> Should there?

I would therefore say yes, at least in a future version.
I would expect to see some text at the end of section 4.1 explaining
how PARAM/@value is to be interpreted for input params.
It would also be nice for the examples to include,
with explanations, at least one instance for PARAMs with each of:

  - non-blank @ref (and presumably required blank @value)
  - blank @ref with non-blank @value
  - blank @ref with blank @value

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/