New Features as of version 1.00

  This is a major release with the addition of some major new features.
  Most, if not all, previous interfaces have been preserved.  

  A UsersGuide.txt has been added at the top-level.  It is still rough
  in some areas, but it should have enough information to help you
  get going.

  A Frequently Asked Questions (FAQ) text file has been added at the
  top-level.  There are sections for General, C++, Python, X-Midas, M2k and
  finally Proxies.  This should help learning the general use of 
  PicklingTools and its features.  There is also an html version (FAQ.html)
  for viewing from your web browser.

  Added the ability to "iterate" through Arrs.  Previously, the
  only way to iterate through an Arr was to loop through it. For example:
    // Arr& a; for (int ii=0; ii<a.length(); ii++) { cout << a[ii] << endl; }
  That still works, but now both the "It" and "Sit" support Arrs as well
  as Tabs.  So now you can:
    Val v = IsItAnArrOrTab();
    It ii(v);  
    while (ii()) {
	cout << ii.key() << " ";  // If Arr, keys are 0..a.length()-1
        cout << ii.value();       // If Arr, then a[ii] 
    }
  The "Sit" iterator can now iterate through the Arr as if the keys
  were sorted (but without changing the Arr in question).

  We have added the ability to "share" tables and arrays using the
  Proxy.  This is a new feature supported by OpenContainers 1.6.0.
  At a higher level, PicklingTools has introduced some shared
  memory (across processes) support.

  Highlights from OpenContainers 1.6.0
    * Create a reference counted table to share:  

        Val a = new Tab("{ }");
        Val b = a;
        a["INSERT"] = 18;          // Use just like Vals and Tabs
          // Both a and b have been changed!

    * Create a reference counted table, with locks, so threads 
      so that the table can be shared cleanly

        Val b = Locked(new Tab("{'a': 1}");
        Val c = b;                 // Proxies copied atomically

    * Allow mutual exclusive access to the table
      
        Val b = Locked(new Tab("{'a': 1}");
        {
          TransactionLock tl(b);  // Only one thread access this subtable

          Tab& t = b;
          t["INSERT"] = 17;
          t["AGAIN"] = 18;
        } // Locked until TransactionLock destructs

    * Ability to create tables in shared memory pools

        Val c = Shared(pool, Tab("{'d':17'}"));
        c["IN SHM"] = Tab("{ 'ALL IN SHM': 100 }"); // All in shared memory
    
    * Ability to create memory pools for allocation/deallocation

        StreamingPool* pool = 
          StreamingPool::CreateStreamingPool(new char[8192], 8192);

    * Many new examples demonstrating how to use Proxies and threads
      and perform synchronization.  There is an entire subdirectory
      in the C++ area called "Examples" which demonstrates many
      of the new features:  Proxy, Barrier Synchronization helper classes,
      Pipeline Synchronization helper classes, plus many examples.

    * All serialization protocols (OpenContainers, Python Pickling 0,
      Python Pickling 2 (also -2), and M2k binary serialization) all support
      serialization and deserialization of Proxys.   See the FAQ
      for more discussion on "serialization".
             

  With the ability to use Shared Memory in OpenContainers, Pickling
  Tools has added some tools to be able to use Shared Memory (where the
  shared memory can be used across processes).  Since this is a more
  system-level functionality, it has been added to PicklingTools proper
  rather than OpenContainers.  See the sharedmem_test for an
  example of how you might use this.

  Misc:  
   * All C++ Midastalker/Server/Listener/Yeller classes can use the
     OpenContainers serialization as yet another serialization
   * Updated midastalker_ex2 (Python and C++) to use Proxies in their
     example requests and other more complex features.
   * macro OC_USE_OC defined as version (eg., 1_6_0) to indicate 
     if we are using OC or not
   * Updated the OpalPythonDaemon to handle Links and Headers
     better if using M2k serialization
   * Added Eval function (simple wrapper for ValReader) for converting
     strings to Val easily:  Val v = Eval("1.0");
   * Added the length (and entries) field to Val:  If the underlying 
     data is a container (Tab, Arr, Array<POD>, string or Proxy to), then it
     returns the length, otherwise throws a runtime exception.
   * Fixed a bug with PicklingProtocol0 when requesting Numeric
   * Updated the M2k Pickler so that you have better control over the
     warnings coming out when serializing OpalHeaders, OpalLinks, etc.
     It does something reasonable, but users complained there were
     too many messages.  
   * Added Proxyize to Val so you can turn a plain-by-value Val into
     a Proxy in O(1) time without having to do a full copy.
   * The M2k area has been updated so that the OpalPythonDaemon supports
        -proxies (at least reading them, it doesn't create a true proxy,
                  just a copy)
        -OpenContainers serialization
   * Updated the append and appendStr for Tab so that they throw an
     exception in case you are going to overwrite a previous value
   * Added a little better support for Array<string> and Array<Tab>.
     TODO: Update all the protocols (from the Val side) so they have
     that support.  Next release?
   * Updated the error message in Python when trying ARRAYDISPOSITION_AS_ARRAY
     to indicate it's really Python 2.5 where it works (not 2.4)
   * In C++ area: The pretty.h and opalprint.h are redundant: deprecate the 
     pretty.h and pretty.cc files and have them include opalprint.h directly.
     We will remove them from a future baseline.
   * Even though PicklingTools 0.95 reported that we updated tab2opal to give
     better syntax errors, apparently that primitive didn't make it into the
     ptools option tree.  All fixed now.
   * Consistent support for M2Time, M2Duration, EventData, TimePackets, 
     and MultiVectors when coming from M2k across all serializations
   * C++ tests run on RedHat Enterprise 3,4 and 5 (3 was slightly problematic).
   * Added routines to convert from M2Time's int_u8 to a standard formatted
     string down to quarter nano-seconds.
   * Added "contains" to the top-level Val (so Tab and Arr and Array<POD>
     can access it easily)
   * Fixed bug to allow setting a tab from a sub-tab:  For example:
       Tab t = {'nest': {'here':1}} ; t = t["nest"]; 
     Also fixed for Arr and Val.
   * Added WriteValToFile and ReadValFromFile at the ValReader level
     to augment the already existing WriteTabToFile and ReadTabFromFile
   * Added conversion routines for explicitly trying to convert between Tabs
     and Arrs:  ConvertTabToArr and ConvertArrToTab
   * Added a fill method on Array<T> as a convenience to fill
     an Array<T> (including Arr) with the same Value:  usually used
     after a constructor to fill the array to capacity.
   * Made it so Protocol 2 always unserializes small ints (when
     it compresses them) as the larger int that "Python" likes.
     This is so 7000 becomes L:7000 instead of UI:7000.  This is 
     more backwards compatible with what Protocol 0 does anyway, and
     more in line with what Python would do.  Updated p2_test.cc to test.
   * Bug fix:  Numeric arrays (with P2WithNumeric serializarion) larger than 
     65536 would throw an exception.  Fixed.
   * Documentation fix: Made MidasTalker (C++/Python) show the numbers
     corresponding to the enumerations in the right order. 
   * Slightly better error message on OpalPythonDaemon if Client talks first.
   * Added pretty module for doing prettyPrint from Python like we would
     in M2k prettyPrint or OpenContainers prettyPrint
   * Made sure everything still works for OSF1 (aka Tru64): both X-Midas 
     C++ primitives and standalone C++.  Version tested with:
     [Compaq C++ V6.5-033 for Compaq Tru64 UNIX V5.1B (Rev. 2650)]
     TODO: Fix pool_test.cc 
   * Fixed long standing bug in ocvalreader so it could read large ints
   
  There has been considerable testing of this release for Backwards
  Compatibility as well as stability especially with respect to the
  OpalPythonDaemon and talking to it.

  --POSSIBLE BACKWARDS COMPATIBILITY ISSUES---

  If you depend on the implementation of Val, you may get bitten:
    Consider:

      Val v = GiveMeSomeVal();
      if (v.tag=='t') {
        Tab* tp = (Tab*)v.u.t;  // Only works if v is NOT a proxy.  
        ProcessTab(*tp);        //      If a Proxy, SEG FAULT
      }

    The above will work, but only if v is NOT a proxy.  You should use the 
    more "implementation agnostic" way to get the Table: ask for a Tab&
    (or Arr& or Array<T>&):

      Val v = GiveMeSomeVal();
      if (v.tag=='t') {
        Tab& tr = v;    // Works if v is a Proxy OR Tab
        ProcessTab(tr);
      }

    We have changed the "internal" string of a Val to ALWAYS be
    an OCString (to avoid execessive heap usage).  Again, if you depend 
    on the implementation (like in the example below) you will seg fault:

      string *sp = (string*)&v.u.a;  
      cerr << *sp << endl;  // SEG FAULT:  v.u.a is an OCString, 
                            // may or may not be the same as a string
    
    You should simply ask for a string directly out.

      string s = v;
      cerr << s << endl;  // Works fine

   Note that you can't ask for a string& out.