Release Notes for snapshot 980827                - By Sai-Lai Lo
---------------------------------

The last snapshot was snapshot_980410. (ReleaseNote_980410 contains summary
of changes since omniORB_2.5.0.)

Summary of changes since snapshot_980410
----------------------------------------

1. IDL stubs must be regenerated with the new IDL compiler to be
   compatible with the runtime library.

   The current shared runtime library versions are:

   On various unices:

       libomniORB2.so ---> libomniORB2.so.6 --> libomniORB2.so.6.0

   On IBM AIX
       libomniORB26.a
       libomniLC2.a

   On Windows NT/95, the omniORB2 runtime DLLs for this version are:
                   --                   ---
       libomniORB260_rt.dll
       libomniORB260_rt.lib
       libomniLC22_rt.dll
       libomniLC22_rt.lib

   Make sure you update your IDE to pick up the right library.


2. Support of the DynAny interface.
     DynAny interface, except the DynFixed interface, is fully supported.
     At the moment, there are outstanding issues in the DynAny
     specifications that require revisions. The interpretation used in
     omniORB2 is described in the section 'Notes on the DynAny
     implementation' below.

3. omnithread library update 

  Updated omnithread library so that native threads can call any operations
  in the library and vice versa. Previously, native threads cannot call
  omni_thread::join and on nt cannot wait on omni_condition.
  The semantics of omni_thread::self() is clarified. If the caling thread
  is not the main thread and is not created using the omnithread library,
  omni_thread::self() returns 0.

4. Added new flag -t to omniidl2 to enable the generation
   of tie implementation template

	The example src/examples/echo/eg3_tieimpl.cc shows how the template
        can be used.

5. JavaIDL compatible bootstrapping

   It is now possible to use the same mechanism to tell the ORB the root
   context of the Naming Service. Previously, this is done via an IOR
   string in the configuration file omniORB.cfg or the win32 registry.

   Now, all omniORB2 servers, omniNames included, can responds to query
   to a special object with object key 'INIT' and the following interface
	 module CORBA {
               interface InitialReferences {
                  Object get(in ORB::ObjectId id);
                  ORB::ObjectIdList list();
               };
          };

   To tell an omniORB2 client to use this feature:

   1. Use the command line options:
          -ORBInitialHost <hostname (string)>
      and -ORBInitialPort <port (short 1-65535)>

      -ORBInitialPort is optionally. If not specified, port 900 will be
       used.

   2. Added the following into omniORB.cfg or win32 registry:

         ORBInitialHost <hostname (string)>
         ORBInitialPort <port (short 1-65535)>


   So a simpler way to set up omniNames is:

      1. Start omniNames the first time on host wobble:
             $ omniNames -start <port (e.g. 1234)>

      2. Add to omniORB.cfg the following lines:

           ORBInitialHost wobble
           ORBInitialPort 1234

      or

        Just invoke a client with -ORBInitialHost wobble -ORBInitialPort 1234

     3. To configure JavaIDL clients to use omniNames, use the JavaIDL
        command line options: -ORBInitialHost, -ORBInitialPort.

6. New runtime configuration variable:

     omniORB::maxTcpConnectionPerServer

   This variable controls the maximum number of tcp connections to open to
   a server. Previously this variable is hard-coded to 5.
   Changes this variable by assignment. Make sure that this is done before
   ORB_init because the variable is read only once in ORB_init.


7. Use of C++ namespace to represent IDL module is fully supported with
   MSVC++ 5.0 and DEC C++ v6.0 (Digital Unix 4.0D).
   See also ReleaseNote_980410 for more information on support for
   namespace.

8. Bugs fixed:
      The complete list of bugs fixed can be found in:
          http://www.orl.co.uk/omniORB/omniORBNews.html
      section omniORB_2.5.0 bugs and patches. 
   All the bugs listed have been fixed.


9. New platforms.
      Ports for SGI, Phar Lap ETS kernel, SCO OpenServer 5.

      Notice that these ports have not been exercised with omniORB2_testsuite
      to verify its correctness. Anyone with access to these platforms
      please run the tests and report any problems. See NOTES_TO_TESTERS
      for details.

------------------------------------------------------------------------------
Notes on the DynAny implementation
-----------------------------------

  Clarification on the DynAny interface
  -------------------------------------

  DynAny current_component();

  Returns the DynAny object associates with the current logical pointer
  into the DynAny buffer.

  [clarification end]
  If the current logical pointer is invalid, return CORBA::DynAny::_nil().
  [clarification begin]

  Clarification on the DynStruct interface
  ----------------------------------------

  char* current_member_name();

  Returns the name of the member currently being accessed.

  [clarification end]
  The current logical pointer points to the member.
  If the current logical pointer is invalid, return 0.
  [clarification begin]

  TCKind current_member_kind();

  Returns the TCKind associated with the current member being accessed.

  [clarification end]
  The current logical pointer points to the member.
  If the current logical pointer is invalid, return tk_null.
  [clarification begin]


  NameValuePairSeq* get_members();

  Obtain a sequence of name/value pairs describing the name and the value
  of each member in the struct.

  [clarification end]
  If the struct has not bee completely initialised, raise a 
  CORBA::SystemException. 
  [clarification begin]



  Clarification on the DynUnion interface
  ---------------------------------------
  The DynUnion interface as defined in CORBA 2.2 is lacking in detail on the
  behaviour of the member functions. As a result a number of intepretations
  could be applied. A number of these issues are currently opened with the ORB 
  revision task force. Until the issues are resolved, the following 
  interpretation is used in this implementation:

  DynUnion objects are associated with unions.

  interface DynUnion: DynAny {
     attribute boolean set_as_default;
     DynAny discriminator();
     TCKind discriminator_kind();
     DynAny member();
     attribute FieldName member_name;
     TCKind member_kind();
  };

  The DynUnion interface allows for the insertion/extraction of an OMG
  IDL union type into/from a DynUnion object.

  The TCKind associated with the discriminator is returned by 
  discriminator_kind().

  TCKind discriminator_kind();

  The discriminator operation returns a DynAny object reference that must
  be narrowed to the type of the discriminator in order to insert/get
  the discriminator value:

  DynAny discriminator();

  [clarification begin]
  Insert a value into the discriminator select the member. 

  If the discriminator has already been initialised by a previous insert
  operation, the new insert may cause a different member to be selected. In
  this case the previous member would be overridden.

  Overriding an already initialised discriminator, to say the least,
  is confusing. Developers are STRONG DISCOURAGED from writing code that
  relies on this behaviour. It is possible that a future CORBA revision may
  disallow this completely.
  [clarification end] 

  The member operation retuns a DynAny object reference that is used in order
  to insert/get the member of the union:

  DynAny member();

  The TCKind associated with the member of the union is returned by
  member_kind.

  TCKind member_kind();

  [clarification begin]
  If the discriminator of the DynUnion has not been initialised, either through
  the DynAny returned by discriminator() or through the value copied from
  the argument when the DynUnion was constructed, member() returns a
  nil DynAny (CORBA::DynAny::_nil()). member_kind() returns tk_null.
  
  Suppose a member() call returns a DynAny_ptr A. Then a different 
  discriminant value is inserted  causing a different member to be selected. 
  In this case, inserting a value through A would not affect the value of
  the DynUnion. A effectively is detached from the union. If A already contains
  a valid value, this value would be returned by A and would not be the
  current value of the union.

  Again, developers are STRONG DISCOURAGED from writing code that relies
  on this behaviour.
  [clarification end]

  The member_name attribute allows for the inspection/assignment of the
  name of the union member without checking the value of the discriminator.

  [clarification begin]
  Setting the name of the union member automatically causes the value of
  the discriminator to changed to the corresponding value reflecting the
  selection. 

  If the discriminant has already been initialised to a different value-member
  selection, the description above applies.
  
  [clarification end]

  The set_as_default attribute determines whether the discriminator
  associated with the union has been assigned a valid default value.

  [clarification begin]

  If the union does have an explicit default branch, writing a TRUE value
  to the attribute select that member. Writing a FALSE value is quietly
  ignored because the exact meaning of this operation is unclear.

  If the union does not have an explicit default branch but not all permissible
  values of the union discriminant are listed, writing a TRUE value to
  the attribute select the implicit default. In this case, the value of the
  union is composed only of the discriminant value. Writing a FALSE value
  is ignored.

  If all the permissible values of the union discriminant are listed,
  set_as_default always returns FALSE and writing a value to the attribute
  is quietly ignored.


  [clarification end]

  Recommendation to developers on the use of DynUnion
  ---------------------------------------------------
  When writing into a DynUnion, uses the following steps:
  1. Create a DynUnion using CORBA::ORB::create_dyn_union.
  2. Set the member_name attribute to select the member.
  3. Use member() to obtain the DynAny of the member.
  4. Insert value into the member DynAny.

  Never change the discriminator once it has been initialised.  



  Clarification on the DynSequence interface
  ------------------------------------------

  AnySeq* get_elements();

  Return the elements of the sequence.

  [clarification end]
  If any of the elements in the sequence has not be initialised, raise a
  CORBA::SystemException.
  [clarification begin]


  Clarification on the DynArray interface
  ------------------------------------------

  AnySeq* get_elements();

  Return the elements of the array.

  [clarification end]
  If any of the elements in the array has not be initialised, raise a
  CORBA::SystemException.
  [clarification begin]

