README.txt, v.1.0, 2002-08-14, Per Cederberg <per@percederberg.net>
===================================================================


1. Introduction
---------------

  This is a GNU GPL licensed distribution of a Java MIB parser. This
  parser can be used to parse MIB files as well as simple ASN.1 files.
  It is not a stand-alone program, but rather a set of classes that
  can be used within your own programs.



2. Background
-------------

  The SNMP (Simple Network Management Protocol, RFC 1157) is used to
  remotely manage and monitor devices across a network. In order for
  both ends in this communication to be aware of the available
  parameters and agree on the semantics of each one of them, a MIB
  (Managable Information Base, RFC 1155) file is written. The MIB file
  contains the details of all the parameters available for reading
  and/or writing, as well as type information and free text
  descriptions.

  The MIB file format is an ASN.1 (ISO 8824) syntax, with some
  additional macros predefined. In general, a MIB file can contain any
  ASN.1 construct, but normally they only use simple data types such
  as strings, numbers, etc. The full ASN.1 syntax, however, allows
  definitions of macros that extends the syntax itself. This latter
  form of ASN.1 construct is not supported by this parser. A more
  detailed description of the syntax and limitations of ASN.1 and MIB
  files can be found in the following essay:

    http://www.percederberg.net/home/essays/master/master.html



3. License
----------

  The source code in this package is licensed under the GNU GPL
  license, as specified in the separate LICENSE.txt file. In short,
  this means that your source code must also be distributed under the
  GNU GPL if you wish to use the classes in this distribution. Usage
  is defined properly in the license, but includes copying source code
  from these files or compiling against the classes in this
  distribution.



4. Implementation Notes
----------------------- 

  The MIB parser in this distribution parses the files in a
  multi-stage process. The first stage is to actually parse the file
  in the ASN.1 parser and create a parse tree, i.e. a hierarchical
  structure in memory of all the contents in the file. Thereafter a
  first pass parse tree analysis is made that identifies all symbol
  names and checks for unsupported constructs. In the second and last
  pass of the parse tree, the symbol types are validated and object
  identifiers are created for all objects. Both of the two analysis
  passes operate on the same parse tree, without need to read the
  file twice from disk. These two passes roughly correspond to the
  semantical analysis in a normal compilation process.

  The ASN.1 parser is created by JavaCC from a AsnParser.jj file. All
  the source code generated by JavaCC is distributed in this package,
  so there is no need to download and install JavaCC if no changes are
  made to the grammar. Also, as a parse tree is created by the
  grammar, there is no need to modify the parser in order to change
  the semantics or processing stages. These stages instead operate
  cleanly on the parse tree. As the support for parse trees in JavaCC
  is far from being perfect, a manual approach to parse tree creation
  has been taken. This implies that some changes in the grammar file
  will also require changes in the parse tree classes.



5. Acknowledgements
-------------------

  This work was originally part of a MIB processing and automatic code
  generation tool (aka Plug-Out). It was developed as a part of my
  Master's thesis project at Ericsson Telecom in 1999 (documented in
  http://www.percederberg.net/home/essays/master/master.html).
  Ericsson has since been so kind as to allow me to relicense this
  code under the GNU GPL.
