rfc1023.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

                   exactly one node in the dictionary tree).

   Opcodes         These objects tell the query interpreter to do
                   something.  They are described in detail later in
                   this report.  Opcodes are represented as an
                   application-specific type whose value determines
                   the operation.  These values are defined in
                   RFC-1024.

   Data            These are the same objects that are used to
                   represent information returned from an entity.
                   It is occasionally be necessary to send data as



Trewitt & Partridge                                             [Page 6]

RFC 1023                     HEMS Language                  October 1987


                   part of a request.  For example, when requesting
                   information about the interface with IP address
                   "10.0.0.51", the address would be sent in the
                   same format in the request as it would be seen
                   in a reply.

   Data, Tags, and Templates are usually in either the context-specific
   class, except for items in the root dictionary and a few special
   cases, which are in the application-specific class.

QUERY LANGUAGE

   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.

   In the current version of the query language:

         - There are no subroutines.

         - There are no control structures defined in the language.

         - There are no arithmetic or conditional operators.

   These features could be added to the language if needed.

   This language is designed with the goal of being expressive enough to
   write useful queries with, but to guarantee simplicity, both of query
   execution and language implementation.

   The central element of the language is the stack.  It may contain
   templates, (and therefore tags), data, or dictionaries (and therefore
   arrays) from the entity being monitored.  Initially, 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 things from the stack and may generate ASN.1 objects
   and send them to the output stream.  Note that portions of the
   response may be generated while the query is still being received.

   The following opcodes are defined in the language.  This is a



Trewitt & Partridge                                             [Page 7]

RFC 1023                     HEMS Language                  October 1987


   provisional list -- changes may need to be made to deal with
   additional needs.

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

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

   Here are the operators defined in the query language:

   GET         dict template    GET    dict
               Emit an ASN.1 object with the same "shape" as the given
               template.  Any items in the template that are not in
               <dictionary> (or its components) are represented as
               objects with a length of zero.  This handles requests for
               data that isn't available, either because it isn't
               defined or because it doesn't apply in this situation.

   or          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.

   BEGIN       dict1 tag    BEGIN     dict1 dict
               Pushes the value for dict{ tag } on the stack, which
               should be another dictionary.  At the same time, produce
               the beginning octets of an ASN.1 object corresponding to
               that dictionary.  It is up to the implementation to
               choose between using the "indefinite length"
               representation or going back and filling the length in
               later.

   END         dict    END    --
               Pop the dictionary off of the stack and terminate the
               currently open ASN.1 object.  Must be paired with a
               BEGIN.

Getting Items Based on Their Values

   One problem that has not been dealt with was alluded to earlier:
   When dealing with array data, how do you specify one or more entries
   based upon some value in the array entries?  Consider the situation
   where there are several interfaces.  The data might be organized as:



Trewitt & Partridge                                             [Page 8]

RFC 1023                     HEMS Language                  October 1987


          interfaces {
                  interface { type, ip-addr, in-pkts, out-pkts, ...}
                  interface { type, ip-addr, in-pkts, out-pkts, ...}
                                  :
                                  :
                  }

   If you only want information about one interface (perhaps because
   there is an enormous amount of data about each), then you have to
   have some way to name it.  One possibility is to just number the
   interfaces and refer to the desired interface as:
          interfaces(3)
   for the third one.

   But this is probably not sufficient since interface numbers may
   change over time, perhaps from one reboot to the next.  This method
   is not sufficient at all for arrays with many elements, such as
   processes, routing tables, etc.  Large, changing arrays are probably
   the more common case, in fact.

   Because of the lack of utility of indexing in this context, there is
   no general mechanism in the language for indexing.

   A better scheme is to select objects based upon some value contained
   in them, such as the IP address or process name.  The GET-MATCH
   operator provides this functionality in a fairly general way.

   GET-MATCH   array value template    GET-MATCH    array
               <array> should be a array (dictionary containing only
               one type of item).  The first tag in <value> and
               <template> must match this type.  For each entry in
               <array>, match the <value> against the contents of
               the entry.  If there is a match, emit the entry based
               upon <template>, just as in a GET operation.

   If there are several leaf items in the value to be matched against,
   as in:
          route-entry{ interface(1), cost(3) }
   all of them must match an array entry for it to be emitted.

   Here is an example of how this operator would be used to obtain the
   input and output packet counts for the interface with ip-address
   10.0.0.51.








Trewitt & Partridge                                             [Page 9]

RFC 1023                     HEMS Language                  October 1987


          interfaces BEGIN                    -- get dictionary
          interface{ ip-addr(10.0.0.51) }     -- value to match
          interface{ in-pkts out-pkts }       -- data template to get
          GET-MATCH
          END                                 -- finished with dict

   The exact meaning of a "match" is dependent upon the characteristics
   of the entities being compared.  In almost all cases, it is a
   comparison for exact equality.  However, it is quite reasonable to
   define values that allow matches to do interesting things.  For
   example, one might define three different flavors of "ip-addr":  one
   that has only the IP net number, one with the IP net+subnet, and the
   whole IP address.  Another possibility is to allow for wildcards in
   IP addresses (e.g., if the "host" part of an IP address was all ones,
   then that would match against any IP address with the same net
   number).

   So, for all data items defined, the behavior of the match operation
   must be defined if it is not simple equality.

   Implementations don't have to provide the ability to use all items in
   an object to match against.  It is expected that some data structures
   that provide for efficient lookup for one item may be very
   inefficient for matching against others.  (For instance, routing
   tables are designed for lookup with IP addresses.  It may be very
   difficult to search the routing table, matching against costs.)

   NOTE:  It would be desirable to provide a general-purpose filtering
   capability, rather than just "equality" as provided by GET-MATCH.
   However, because of the potential complexity of such a facility, lack
   of a widely-accepted representation for filter expressions, and time
   pressure, we are not defining this mechanism now.

   However, if a generalized filtering mechanism is devised, the GET-
   MATCH operator will disappear.

Data Attributes

   Although ASN.1 data is self-describing as far as the structure goes,
   it gives no information about what the data means (e.g., By looking
   at the raw data, it is possible to tell that an item is of type
   [context 5] and 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?).

   Most of the time, this information will come from RFC-1024, which
   defines all of the ASN.1 tags and their precise meaning.  When
   extensions have been made, it may not be possible to get



Trewitt & Partridge                                            [Page 10]

RFC 1023                     HEMS Language                  October 1987


   documentation on the extensions.  (See the section about extensions,
   page 15.)

   The query language provides a set of operators parallel to the GET
   and GET-MATCH operators that return a set of attributes describing
   the data.  This information should be sufficient to let a human
   understand the meaning of the data and to let a sophisticated
   application treat the data appropriately.  The information is
   sufficient to let an application format the information on a display
   and decide whether or not 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
   it.  Extensive descriptions of standard data are optional, since they
   are defined in RFC-1024.  Complete descriptions of extensions must be
   available, even if they are documented in a user's manual.  Network
   firefighters may not have the manual handy when the network is
   broken.

   The format of the attributes is not as simple as the format of the
   data itself.  It isn't possible to use the data's tag, since that
   would just look exactly like the data itself.  The format is:

          Attributes ::= [APPLICATION 2] IMPLICIT SEQUENCE {
                  tagASN1       [0] IMPLICIT INTEGER,
                  valueFormat   [1] IMPLICIT INTEGER,
                  longDesc      [2] IMPLICIT IA5String OPTIONAL,
                  shortDesc     [3] IMPLICIT IA5String OPTIONAL,
                  unitsDesc     [4] IMPLICIT IA5String OPTIONAL,
                  precision     [5] IMPLICIT INTEGER OPTIONAL,
                  properties    [6] IMPLICIT BITSTRING OPTIONAL,
          }

   For example, the attributes for
       system{ name, clock-msec }
   might be:
       system{
               Attributes{
                       tagASN1(name), valueFormat(IA5String),
                       longDesc("The name of the host"),
                       shortDesc("hostname")
               },
               Attributes{
                       tagASN1(clock-msec), valueFormat(Integer),
                       longDesc("milliseconds since boot"),
                       shortDesc("uptime"), unitsDesc("ms")
                       precision(4294967296),
                       properties(1)



Trewitt & Partridge                                            [Page 11]

RFC 1023                     HEMS Language                  October 1987


               }
   Note that in this example <name> and <clock-msec> are integer values
   for the ASN.1 tags for the two data items.  A complete definition of
   the contents of the Attributes type is in RFC-1024.

   Note that there will be exactly as many Attributes items in the
   result as there are objects in the template.  Attributes objects for
   items which do not exist in the entity will have a valueFormat of
   NULL and none of the optional elements will appear.

   GET-ATTRIBUTES
               dict template    GET-ATTRIBUTES    dict
               Emit ASN.1 Attributes objects that for the objects named
               in <template>.  Any items in the template that are not
               in <dictionary> (or its components), elicit an
               Attributes object with no.