rfc1076.txt

RFC 的详细文档！

   returned objects must be fully qualified.  For example, the name of
   the entity must always be returned encapsulated inside an ASN.1
   object for "System".  If it were not, there would be no way to tell
   if the object that was returned was "name" inside the "System"
   dictionary or "address" inside the "interfaces" dictionary (assuming
   in this case that "name" and "address" were assigned the same integer
   as their ASN.1 tags).

   Having fully-qualified data simplifies decoding of the data at the
   receiving end and allows the tags to be locally chosen.  Definitions
   for tags within routing tables won't conflict with definitions for
   tags within interfaces.  Therefore, the people doing the name
   assignments are less constrained.  In addition, most of the
   identifiers will be fairly small integers, which is an advantage
   because ASN.1 can fit tag numbers up to 30 in a one-octet tag field.
   Larger numbers require a second octet.

   If data is requested that doesn't exist, either because the tag is
   not defined, or because an implementation doesn't provide that data
   (such as when the data is optional), the response will contain an
   ASN.1 object that is empty.  The tag will be the same as in the
   query, and the object will have a length of zero.

   The same response is given if the requested data does exist, but the
   invoker of the query does not have authorization to access it.  See
   section 10 for more discussion of authorization mechanisms.



Trewitt & Partridge                                            [Page 11]

RFC 1076          HEMS Monitoring and Control Language     November 1988


   This allows completely generic queries to be composed without regard
   to whether the data is defined or implemented at all of the entities
   that will receive the query.  All of the available data will be
   returned, without generating errors that might otherwise terminate
   the processing of the query.

8. QUERY LANGUAGE

   The query language is designed to be expressive enough to write
   useful queries with, yet simple enough to be easy to implement.  The
   query processor should be as simple and fast as possible, in order to
   avoid placing a burden on the monitored entity, which may be a
   critical node such as a gateway.

   Although queries are formed in a flexible way using what we term a
   "language", this is not a programming language.  There are operations
   that operate on data, but most other features of programming
   languages are not present.  In particular:

         - Programs are not stored in the query processor.

         - The only form of temporary storage is a stack, of limited
           depth.

         - There are no subroutines.

         - There are no explicit control structures defined in the
           language.

   The central element of the language is the stack.  It may contain
   templates, (and therefore paths), values, and filters taken from the
   query.  In addition, it can contain dictionaries (and therefore
   arrays) from the data tree.  At the beginning of a query, it contains
   one item, the root dictionary.

   The overall operation consists of reading ASN.1 objects from the
   input stream.  All objects that aren't opcodes are pushed onto the
   stack as soon as they are read.  Each opcode is executed immediately
   and may remove items from the stack, may generate ASN.1 objects and
   send them to the output stream, and may leave items on the stack.
   Because each input object is dealt with immediately, portions of the
   response may be generated while the query is still being received.

   In the descriptions below, operator names are in capital letters,
   preceded by the arguments used from the stack and followed by results
   left on the stack.  For example:





Trewitt & Partridge                                            [Page 12]

RFC 1076          HEMS Monitoring and Control Language     November 1988


   OP                             a b   OP   a t
             means that the OP operator takes <a> and <b> off of the
             stack and leaves <t> on the stack.  Most of the operators
             in the query language leave the first operand (<a> in this
             example) on the stack for future use.

   If both <a> and <b> were received as part of the query (as opposed to
   being calculated by previous operations), then this part of the query
   would have consisted of the sequence:
       <a>
       <b>
       OP
   So, like other stack-based languages, the arguments and operators
   must be presented in postfix order, with an operator following its
   operands.

   Here is a summary of all of the operators defined in the query
   language.  Most of the operators can take several different sets of
   operands and behave differently based upon the operand types.
   Details and examples are given later.

   BEGIN                   dict1 path   BEGIN   dict1 dict
                    array path filter   BEGIN   array dict
             Move down in the data tree, establishing a context for
             future operations.

   END                           dict   END   --
             Undo the most recent BEGIN.

   GET                           dict   GET   dict
                        dict template   GET   dict
                array template filter   GET   array
             Retrieve data from the data tree.

   GET-ATTRIBUTES
                                 dict   GET-ATTRIBUTES   dict
                        dict template   GET-ATTRIBUTES   dict
                array template filter   GET-ATTRIBUTES   array
             Retrieve attribute information about data in the data tree.

   GET-RANGE   dict path start length   GET-RANGE   dict
             Retrieve a subrange of an OctetString.  Used for reading
             memory.

   SET                     dict value   SET   dict
                   array value filter   SET   array
             Change values in the data tree, possibly performing control
             functions.



Trewitt & Partridge                                            [Page 13]

RFC 1076          HEMS Monitoring and Control Language     November 1988


   CREATE                 array value   CREATE   dict
             Create new table entries.

   DELETE                array filter   DELETE   array
             Delete table entries.

   These operators are defined so that it is impossible to generate an
   invalid query response.  Since a response is supposed to be a
   snapshot of a portion (or portions) of the data tree, it is important
   that only data that is actually in the tree be put in the response.
   Two features of the language help guarantee this:

      - Data is put in the response directly from the tree (by
        GET-*).  Data does not go from the tree to the stack and
        then into the response.

      - Dictionaries on the stack are all derived from the initial,
        root dictionary.  The operations that manipulate
        dictionaries (BEGIN and END) also update the response with
        the new location in the tree.

8.1 Moving Around in the Data Tree

   The initial point of reference in the data tree is the root.  That
   is, operators name data starting at the root of the tree.  It is
   useful to be able to move to some other dictionary in the tree and
   then name data from that point.  The BEGIN operator moves down in the
   tree and END undoes the last unmatched BEGIN.

   BEGIN is used for two purposes:

      - By moving to a dictionary closer to the data of interest,
        the name of the data can be shorter than if the full name
        (from the root) were given.

      - It is used to establish a context for filtered operations
        to operate in.  Filters are discussed in section 8.6.

   BEGIN                   dict1 path   BEGIN    dict1 dict
             Follow <path> down the dictionary starting from <dict1>.
             Push the final dictionary named by <path> onto the stack.
             <path> must name a dictionary (not a leaf node).  At the
             same time, produce the beginning octets of an ASN.1 object
             corresponding to the new dictionary.  It is up to the
             implementation to choose between using the "indefinite
             length" representation or the "definite length" form and
             going back and filling the length in later.




Trewitt & Partridge                                            [Page 14]

RFC 1076          HEMS Monitoring and Control Language     November 1988


   END                           dict   END   --
             Pop <dict> off of the stack and terminate the open ASN.1
             object(s) started by the matching BEGIN.  Must be paired
             with a BEGIN.  If an END operation pops the root dictionary
             off of the stack, the query is terminated.

   <path> must point to a regular dictionary.  If any part of it refers
   to a non-existent node, if it points to a leaf node, or if it refers
   to a node inside an array-type dictionary, then it is in error, and
   the query is terminated immediately.

   An additional form of BEGIN, which takes a filter argument, is
   described later.

8.2 Retrieving Data

   The basic model that all of the data retrieval operations follow is
   that they take a template and fill in the leaf nodes of the template
   with the appropriate data values.

   GET                  dict template   GET   dict
             Emit an ASN.1 object with the same "shape" as the given
             template, except with values filled in for each node.  The
             first ASN.1 tag of <template> should refer to an object in
             <dict>.  If a dictionary tag is supplied anywhere in
             <template>, the entire dictionary contents are emitted to
             the response.  Any items in the template that are not in
             <dictionary> (or its components) are represented as objects
             with a length of zero.

                                 dict   GET   dict
             If there is no template, get all of the items in the
             dictionary.  This is equivalent to providing a template
             that lists all of the items in the dictionary.

   An additional form of GET, which takes a filter argument, is
   described later.

   Here is an example of using the BEGIN operator to move down the data
   tree to the TCP dictionary and then using the GET operator to
   retrieve 5 data values from the TCP Stats dictionary:

       IPTransport{ TCP } BEGIN
       Stats{ octetsIn, octetsOut, inputPkts, outputPkts, badtag } GET
       END






Trewitt & Partridge                                            [Page 15]

RFC 1076          HEMS Monitoring and Control Language     November 1988


   This might return:

       IPTransport{ TCP
           Stats{ octetsIn(13255), octetsOut(82323),
                  inputPkts(9213), outputPkts(12425), badtag() }
       }

   "badtag" is a tag value that is undefined.  No value is returned for
   it, indicating that there is no data value associated with it.

8.3 Data Attributes

   Although ASN.1 "self-describes" the structure and syntax of the data,
   it gives no information about what the data means.  For example, by
   looking at the raw data, it is possible to tell that an item is of
   type [context 5] and is 4 octets long.  That does not tell how to
   interpret the data (is this an integer, an IP address, or a 4-
   character string?) or what the data means (IP address of what?).
   Even if the data were "tagged", in ASN.1 parlance, that would only
   give the base type (e.g., IP-address or counter) and not the meaning.

   Most of the time, this information will come from RFC-1024, which
   defines the ASN.1 tags and their precise meaning.  When extensions
   have been made, it may not be possible to get documentation on the
   extensions.  (Extensions are discussed in section 9.)

   The GET-ATTRIBUTES operator is similar to the GET operator, but
   returns a set of attributes describing the data rather than the data
   itself.  This information is intended to be sufficient to let a human
   understand the meaning of the data and to let a sophisticated
   application treat the data appropriately.  Such an application could
   use the attribute information to format the data on a display and
   decide whether it is appropriate to subtract one sample from another.

   Some of the attributes are textual descriptions to help a human
   understand the nature of the data and provide meaningful labels for