Subject: use cases appendix

From: Jamal Hadi Salim <[email-masked]>
Date: Wed, 12 Oct 2005 12:52:51 -0400

Ok, attached is the appendix to match section 6.1.
I need a pair of eyes or more to scan it for obvious errors.

cheers,
jamal

---

From: Jamal Hadi Salim <[email-masked]>
Date: Wed, 12 Oct 2005 12:59:46 -0400

Sorry, I posted the wrong text - that text also needs fixing (i forgot
about it);i dont have time today. Heres the correct text. 

cheers,
jamal

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 12 Oct 2005 13:27:09 -0400

These look good.
The cases described here reminded me of a case that we have not discussed, 
but which this syntax can represent.
Suppose that a structure has an optional element b.  And suppose that an 
instance has that element set.
How does the CE cause that optional element to no longer occur?
One way I can think of is to say that if a sparse data component has a 
length of zero (in a SET) then that is a request to remove that 
element.  This has the drawback that there is no way to allow a zero length 
but present element in a SET request (i.e. to distinguish between a string 
that is to be undefined and a string that is to be set to length 0.)
Another choices is to use the delete operation (which is currently defined 
for array elements.

We should specify how it is handled.

Yours,
Joel

---

From: Jamal Hadi Salim <[email-masked]>
Date: Wed, 12 Oct 2005 14:02:16 -0400

> Another choices is to use the delete operation (which is currently defined 

The delete sounds simpler in my view. i.e instead of having an
exception. On getting a deleted optionally appearing data, we should
return a RESULT TLV with something along the lines of NOEXIST.
Does that sound reasonable?

Reminds me:
Do we really think we have properly/sufficiently defined the result
codes?

> We should specify how it is handled.

Agreed. Suggestions on where to add such text?

cheers,
jamal

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 12 Oct 2005 14:34:53 -0400

In terms of where to add the text, if we go with the delete choice, then 
this section should include a note that SETting a variable length item to a 
0 length value is not the same as deleteing it.  And the section where the 
DELETE type code is defined should indicate that it can be used to delete 
an array element or an optional structure element.   The syntax already 
allows for it, we should just call it out as permitted.

Yours,
Joel

---

From: Jamal Hadi Salim <[email-masked]>
Date: Wed, 12 Oct 2005 15:30:55 -0400

> In terms of where to add the text, if we go with the delete choice, then 

Shall i assume this is what we are going with or do you feel strongly
the other way?

> allows for it, we should just call it out as permitted.

I will add this text based on your response to above.

cheers,
jamal

---

From: Jamal Hadi Salim <[email-masked]>
Date: Wed, 12 Oct 2005 15:40:13 -0400

On Wed, 2005-12-10 at 14:34 -0400, Joel M. Halpern wrote:
> SETting a variable length item to a 
> 0 length value is not the same as deleteing it.  

Should we return an error code? What would it be?

cheers,
jamal

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 12 Oct 2005 16:59:03 -0400

No need for an error code.  it is a valid thing.  Setting an array to have 
no entries.  Setting a string to be the 0 length string.  Setting a 
variable length bit string to have no bits.
And all of those are different from removing the attribute.

Now, some variable length items may have minimum lengths.  Then such a set 
attempt should return an "invalid value" error.

Yours,
Joel

---

From: Jamal Hadi Salim <[email-masked]>
Date: Wed, 12 Oct 2005 18:17:03 -0400

Ok, attached the diff incorporating all your other comments.
Thanks for your efforts Joel.

cheers,
jamal

> >Should we return an error code? What would it be?
--- sec-6.1.txt	2005-10-11 22:48:45.000000000 -0400
+++ sec-6.1-new.txt	2005-10-12 18:10:57.000000000 -0400
@@ -1,3 +1,4 @@
+
 6.  Protocol Construction
 
 6.1.  Protocol Grammar
@@ -90,9 +91,10 @@
 
    o  PATH-DATA-TLV identifies the exact element targeted and may have
       zero or more paths associated with it.  The last PATH-DATA-TLV in
-      the case of nesting of paths via the DATA construct is terminated
-      by encoded data or response in the form of either FULLDATA-TLV or
-      SPARSEDATA-TLV or RESULT-TLV.
+      the case of nesting of paths via the DATA construct in the case of
+      SET requests and GET response is terminated by encoded data or
+      response in the form of either FULLDATA-TLV or SPARSEDATA-TLV or
+      RESULT-TLV.
 
    o  PATH provides the path to the data being referenced.
 
@@ -207,13 +208,13 @@
       transported.  This data will be as was described in the LFB
       definition.
 
-      *   As an example a 16 bit value within a TLV will have an extra
-          16 bit pad; however two 16 bits values in another TLV
-          structure will be shipped together with no padding etc.
-
    o  Variable sized data within a FULLDATA TLV will be encapsulated
       inside another FULLDATA TLV inside the V of the outer TLV.  For
-      example of this see Appendix E example 13.
+      example of such a setup refer to Appendix E and Appendix D.
+
+   o  In the case of FULLDATA TLVs:
+
+

@@ -222,14 +223,12 @@
 Internet-Draft                   ForCES                      August 2005

-   o  In the case of PACKEDDATA TLVs:
-
    o  When a table is refered to in the PATH (ids) of a PATH-DATA-TLV,
-      then the PACKEDDATA's "V" will contain that table's row content
+      then the FULLDATA's "V" will contain that table's row content
       prefixed by its 32 bit index/subscript.  OTOH, when PATH flags are
       00, the PATH may contain an index pointing to a row in table; in
-      such a case, the PACKEDDATA's "V" will only contain the content
-      with the index in order to avoid ambiguity.
+      such a case, the FULLDATA's "V" will only contain the content with
+      the index in order to avoid ambiguity.
 
 6.1.1.1.2.  Path Flags
 
@@ -296,7 +297,7 @@
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

-   Figure 11
+   Figure 11: PL PDU layout
 
    Type:
        The type of the TLV is "LFBselect"
@@ -325,7 +326,7 @@
    of the TLV.  Definitions for individual Types of operation TLVs are
    in corresponding message description sections followed.
 
-
+   SET and GET Requests do not have result information (they are

@@ -334,29 +335,6 @@
 Internet-Draft                   ForCES                      August 2005

-6.1.1.1.7.  Result TLV
-
-   A RESULT TLV contains a integer (probably 4 bytes, but we only need 1
-   byte) value.
-
-   The defined values are
-
-   0 = success
-
-   1 = no such object
-
-   2 = permission denied
-
-   3 = invalid value (the dataraw could not validly be stored in the
-   field)
-
-   4 = invalid array creation (when the subscript in an array create is
-   not allowed)
-
-   255 = unspecified error (for when the FE can not decide what went
-   wrong)
-
-   SET and GET Requests do not have result information (they are
    requests).  SET and GET Responses have result information.  SET and
    GET Responses use SET-RESPONSE and GET-RESPONSE operation TLVs.
 
@@ -365,11 +343,12 @@
    elements that fail, instead of the FULLDATA TLV there will be a
    RESULT TLV.
 
-   For a SET response, each FULLDATA TLV in the original request will be
-   replace with a RESULT TLV in the response.  If the request was for
-   Ack-fail, then only those items which failed will appear in the
-   response.  If the request was for ack-all, then all elements of the
-   request will appear in the response with RESULT TLVs.
+   For a SET response, each FULLDATA or or SPARSEDATA TLV in the
+   original request will be replaced with a RESULT TLV in the response.
+   If the request was for Ack-fail, then only those items which failed
+   will appear in the response.  If the request was for ack-all, then
+   all elements of the request will appear in the response with RESULT
+   TLVs.
 
    Note that if a SET request with a structure in a FULLDATA is issued,
    and some field in the structure is invalid, the FE will not attempt
@@ -381,7 +360,29 @@
    another field to an invalid value, the FE can return whatever error
    it likes.
 
+   A SET operation on a variable length element with a length of 0 for
+   the item is not the same as deleteing it.  If the CE wishes to delete
+   then the DEL operation should be used whether the the path refers to
+   an array element or an optional structure element.
 
+6.1.1.1.7.  Result TLV
+
+   A RESULT TLV contains a integer (probably 4 bytes, but we only need 1
+   byte) value.
+
+   The defined values are
+
+   0 = success
+
+   1 = no such object
+
+   2 = permission denied
+
+   3 = invalid value (the dataraw could not validly be stored in the
+   field)
+
+   4 = invalid array creation (when the subscript in an array create is
+   not allowed)

@@ -390,6 +391,9 @@
 Internet-Draft                   ForCES                      August 2005

+   255 = unspecified error (for when the FE can not decide what went
+   wrong)
+
 6.1.1.1.8.  DATA TLV
 
    A FULLDATA TLV has "T"= FULLDATA, and a 16bit Length followed by the
@@ -398,8 +402,8 @@
    the case of the SPARSEDATA each element in the Value part of the TLV
    will be further encapsulated in an ILV.  Rules:
 
-   1.  Both ILVs and TLVs MUST 32 bit aligned.  If need be they SHOULD
-       be padded to achieve the alignement.
+   1.  Both ILVs and TLVs MUST 32 bit aligned.  If need be they MUST be
+       padded to achieve the alignement.
 
    2.  FULLDATA TLV may be used at a particular path only if every
        element at that path level is present.  This requirement holds
@@ -548,7 +549,7 @@

-   Figure 12: PL PDU layout
+   Figure 12: PL PDU logical layout

@@ -647,4 +648,3 @@

    Figure 13: Sample operation layout
-