[Css-csts] Comments on CSTS Framework R-0.19

Thu Jul 23 17:21:12 EDT 2009

CSTSWG colleagues ---

In looking again at the CSTS Framework (R-0.19) while working on the
next draft of the Monitored Data CSTS White Book, I've stumbled across a
few more issues, typos, etc. Here they are:

A. "Purpose" of operations is really behavior

The "Purpose" sections (3.X.1) for operation definitions really contain
the specifications of the behavior of those operations. This was really
made apparent to me when I looked at the Behavior section for the
Information Query procedure (4.4.1.3), which states "This procedure
shall adopt the behavior of the GET operation (see 3.12)." Of course,
there is nothing labeled "Behavior" for any of the operations, but under
"Purpose" there are "the user shall..." and "the provider shall ..."
statements. 

I propose that the "Purpose" sections of the operations specifications
be renamed "Behavior". This would more-accurately reflect the normative
nature of the paragraphs contained in them, and in the case of the
Information Query procedure would make it obvious what "behavior" of the
GET operation is being referred to.

B. Comment on the TRANSFER-DATA operation

Section 3.9.2.4.2 states: "[A] Pprocedure using this operation shall
refine (i.e. specify) the format and the semantic of the data field by
extension of the operation or by defining the data field as an octert
string." 

Isn't refining by extension a contradiction in terms? Isn't it correct
to simply say "...shall refine (i.e. specify) the format and the
semantic of the data field or by defining the data field ..."?

C. Comments on the GET operation

1. The NOTE under 3.12.1.2 states "The list of parameters to be
retrieved may be a list explicitly named in the invocation or a default
list agreed by the procedures using this operation." I don't think that
"agreed by the procedures using this operation" is correct. Are we
trying to talk about the list being agreed by the user and provider, or
that the list is defined by the procedure (as stated in 3.12.1.3)? 

2. The wording of 3.12.1.3 is inaccurate, ambiguous, and/or confusing in
several places: e.g., "the request is left empty", "the request contains
the one or more parameters". Suggest rephrasing this paragraph as:

3.12.1.3" Upon invocation of the GET operation, the Service Provider
shall return the values of the requested parameters. If the list of
parameters in the invocation:

a)        Is null, the values of all parameters contained in the default
list shall be returned;

b)       Contains one or more individual parameters, the values of those
named parameters shall be returned;

c)        Contains the name of a list of parameters, the values of all
parameters contained in that named list shall be returned."

3. Section 3.12.1.4 states Procedures using this operation shall define
(a) the list of parameters; (b) the parameters contained in that list".
Is "the list of parameters" in (a) the list of individual parameters
(and if so, how is that different from (b)) or is it a named list of
parameters (and if so, why is there only one named list)?

4. Two typos in section 3.12.1.4:

- in bullet (c), "lits" should be "list", and

- in bullet (d), "thye" should be "the".

5. Section 3.12.2.3.2 is a requirement to transmit data (in the return),
even though it is under the definition of the list-of-parameters
parameter (a parameter of the invocation). Also, the requirement does
not mention the condition that the result must be positive, leading a
possible interpretation that if the value of the list-of-parameters
parameter is 'null', the default list values is to be returned even if
the result is negative. 

Section 3.12.2.3.1 states that the list-of-parameters parameter may
contain a name of a list of parameters, but sections 3.12.2.3, 3.12.2.4,
and annex B collectively do not address how this value translates into
what is to appear in the qualified-parameters parameter. 

Section 3.12.2.4.1 is phrased in terms of how the qualified-parameters
parameter is to be formatted if the result is positive, but the more
important dependency on the result is whether the parameter appears in
the return at all.

May I suggest the following restructuring of 3.12.2.3 and 3.12.2.4:

1. Delete 3.12.2.3.2.

2. Under 3.12.2.4, replace 3.12.2.4.1 with the following set of
paragraphs:

3.12.2.4.1    If the result is 'positive result' (i.e. positive GET
return), the qualified-parameters parameter shall be present in the
return.

3.12.2.4.2    If the result is 'negative result' (i.e. negative GET
return), the qualified-parameters parameter shall not be present in the
return.

3.12.2.4.3    If the value of the list-of-parameters parameter is
'null', the parameters identified by the list-of-parameters used to
select the parameters returned in qualified-parameters shall be the
parameters in the default list of parameters. 

3.12.2.4.4    If the value of the list-of-parameters parameter is a list
of individual parameter names, the parameters identified by the
list-of-parameters used to select the parameters returned in
qualified-parameters shall be those individual parameters.

3.12.2.4.5    If the value of the list-of-parameters parameter is the
name of a list of parameters, the parameters identified by the
list-of-parameters used to select the parameters returned in
qualified-parameters shall be the parameters in the named list of
parameters.

3.12.2.4.6    The format and content of the list-of-parameters parameter
is specified in annex B2.1.

C. Mutually-incomplete cross-referencing of GET operation and
Information Query operation

Under the specification of the GET operation, section 3.12.1.4 states
"Procedures using this operation shall define ... the list of
parameters; [etc.]". However, the Information Query procedure, which
uses the GET operation, does not define these entities. Rather, it
simply refers back to the GET operation for the definition of its
behavior. The Behavior section of the Information Query operation
section should probably be changed to say something like: "This
procedure shall adopt the behavior of the GET operation as defined in
3.12, with the following exception: the parameter, lists of parameters,
the default list of parameters, and the maximum number of parameters
shall be defined by the service that incorporates this procedure."  

D. qualified-parameter vs. qualified-parameters

The GET operation names the parameter qualified-parameters, but in Annex
B and the TRANSFER-DATA operation for Cyclic Report (4.7.3.2) it is
still called qualified-parameter. They should all be changed to
qualified-parameters.

E. Comments on the Information Query procedure

There is nothing that explicitly identifies the Information Query
procedure as a stateless procedure. Only the lack of a Procedure State
Table section gives any indication. I suggest that identity as a
stateless procedure be included somewhere in the description. It could
be as simple as changing the Purpose to read "The Information Query
procedure is a stateless procedure that enables ...".

F. Comments on the Cyclic Report procedure

1. The Behavior section uses phrases like "if no name or list of names
is specified" and "if the subscription is left empty". Is it clear that
these refer to the list-of-parameters parameter having a 'null' value,
or should the terminology used in the Behavior section be more precise?

2. Section 4.7.2.3.3 states "The Service Provider shall deliver the
name, the value, the type and the qualifier of the parameters (See 0)
using the Qualified-Parameter parameter" and section 4.7.3.2 states "The
TRANSFER-DATA shall be refined as required in 3.9 to carry the selected
parameters (names, type, value and qualifier) using the
Qualified-Parameter parameter (see annex B)." This operation doesn't use
a qualified-parameters parameter, it formats the data parameter as a
qualified-parameters parameter (see comments under D, above). It might
be more clear if we said that the data parameter is refined by
formatting it as a parameter of type Qualified-Parameters (this seems to
be where you were going with the initial upper case letters), and have
Annex B define the Qualified-Parameters type (see G, below). Section
4.7.3.2 could be rephrased as "The data parameter of the TRANSFER-DATA
operation shall be refined as required in 3.9 to be of type
Qualified-Parameter (see annex B) to carry the selected parameters
(names, type, value and qualifier)."

Note that in the GET operation would also the cast the
qualified-parameters parameter to be of type Qualified-Parameters.

G. Comments on Annex B

This annex is focuses more on the Qualified-Parameter type, not "List of
Parameters" I suggest changing it to "Qualified Parameters".

The Introduction could be changed to "This annex defines the
requirements for the Qualified-Parameter parameter type. Parameters of
this type are used by the GET operation (see 3.12) and the Cyclic Report
procedure (see 4.7)." 

B2.1 could read "A parameter of type Qualified-Parameter shall contain
for each parameter identified by the corresponding list-of-parameters
the following information:"

H. Miscellaneous typos

In table 3-1, "Result' and "Diagnostic" should be lower case.

Best regards,

John

John Pietras

GST, Inc. 

7855 Walker Drive, Suite 200

Greenbelt, MD 20770

240-542-1155

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mailman.ccsds.org/pipermail/css-csts/attachments/20090723/cabb7265/attachment-0001.html