# @(#) 1.4 src/buildcsd/README.CSD, som, som2.1 4/27/95 08:09:29 [4/27/95 19:04:23]
# 10H9767, 10H9769  (C) COPYRIGHT International Business Machines Corp. 1992,1995
# All Rights Reserved
# Licensed Materials - Property of IBM

Instructions for using the CSD211 update for SOMobjects 2.1
from the Developers Connection for LAN Systems CDROM
====================================================================

To use this update you must have already installed SOMobjects on your
system.  This update works for the Toolkit, Workstation, and Workgroup.
Two run the install, you may follow the instructions in this readme or
execute the script file in the directory for your platform.

YOU MUST ALSO ENSURE THAT THE "SOMBASE", "PATH", "LIBPATH", "SMINCLUDE",
ENVIRONMENT VARIABLES HAVE BEEN SET-UP ACCORDING TO THE SOMobjects 2.1
INSTALLATION INSTRUCTIONS.

DISK REQUIREMENTS:
=================
You must have 10MB of free disk space prior to installing this update.
Following the update there are some files that you can remove to reclaim
space.

Please ensure that you have AT LEAST 1MB free in the directory that
you are running this update AFTER you have downloaded and UNPACKED
the update program and file.

OS/2 Users:
==========

To install from the SERVICE script:
----------------------------------
Access the second disk for the Developers Connection for LAN Systems and
execute the REXX program, for example:
C:\> E:\SERVICE\SOMCS211\OS2\SERVICE.CMD

To install by hand:
------------------
Change to the drive in which SOM is installed (e.g. C:)
D:\> C:

Change directory to %SOMBASE% (assume %SOMBASE% = "C:\SOM"):
C:\> cd %SOMBASE%

Download the csd files "csd211.ex@" and "csd211.os@" to the %SOMBASE%
directory.  Before using the update you will need to unpack these files:
C:\SOM> unpack csd211.ex@
C:\SOM> unpack csd211.os@

You are now ready to run the update:
C:\SOM> csd211

NOTE:
=====
By default, the CSD will only overwrite files that are older than the ones
contained in the CSD data file.
If you want to force the overwrite, regardless of the dates then you
should type:
C:\SOM> csd211 -f

The update will do three main things:

1) Update any files that have changed since the last update.
2) Update the syslevel files.
3) Rebuild header files. (This will take most of the time.)

YOU MUST REBOOT THE SYSTEM TO HAVE THE UPDATE TAKE EFFECT!

Note: the update for this CSD does not update your CONFIG.SYS file like
earlier SOMobjects CSD's.

You may delete the following files after the update (these are automatically
deleted by the REXX install script):
   csd211.ex@
   csd211.os@
   csd211.exe
   csd211.os2

---------------------- The update is finished. -----------------------------

AIX Users:
==========

Login as "root".
(Ensure that LIBPATH, PATH, and SMINCLUDE are still set-up according to
the SOMobjects 2.1 installation instructions after you have logged in
as "root".)

To install from the SERVICE script:
----------------------------------
Access the second disk for the Developers Connection for LAN Systems and
execute the KSH program, for example:
/ #> /devconls/aix/service/somcs211/service.cmd

To install by hand:
------------------
Change directory to $SOMBASE (assume $SOMBASE = "/usr/lpp/som"):
/ #> cd $SOMBASE

FOR AIX 3.2.5
=============

Download the csd files "csd211.325.Z" and "csd211.aix.Z" to the $SOMBASE directory.
Before using the update you will need to uncompress these files:
/usr/lpp/som #> uncompress csd211.325.Z csd211.aix.Z
/usr/lpp/som #> chmod a+x csd211.325

You are now ready to run the update:
/usr/lpp/som #> csd211.325

**********************************************************************************

FOR AIX 4.1.1
=============

Download the csd files "csd211.411.Z" and "csd211.411.Z" to the $SOMBASE directory.
Before using the update you will need to uncompress these files:
/usr/lpp/som #> uncompress csd211.411.Z csd211.aix.Z
/usr/lpp/som #> chmod a+x csd211.411

You are now ready to run the update:
/usr/lpp/som #> csd211.411

*******************************************************************************

NOTE:
=====
By default, the CSD will only overwrite files that are older than the ones
contained in the CSD data file.
If you want to force the overwrite, regardless of the dates then you
should type:
/usr/lpp/som #> csd211.325 -f
or
/usr/lpp/som #> csd211.411 -f

The update will do three main things:

1) Update any files that have changed since the last update.
2) Set the fix level for installp (for somk only).
3) Rebuild header files. (This will take most of the time.)

---------------------- The update is finished. -----------------------------


Interface Repository File Notes:
================================

* Interface Repository Files (IR Files):
  This update includes two new IR Files in the "etc" directory:
  "somnew.ir" and "som211.ir".

  "somnew.ir" is a complete IR File replacement for the GA "som.ir"
  "som211.ir" contains just the idl files that have changed since GA.

  If you haven't changed the GA "som.ir" (this is the most likely case)
  then you can replace it with "somnew.ir":

    OS/2:
    C:\> cd %SOMBASE%/etc
    C:\%SOMBASE%\ETC> ren som.ir somir.ga
    C:\%SOMBASE%\ETC> ren somnew.ir som.ir

    AIX:
    cd $SOMBASE/etc
    $ mv som.ir somir.ga
    $ mv somnew.ir som.ir

    WIN:
    C:\> cd %SOMBASE%/etc
    C:\%SOMBASE%\ETC> ren som.ir somir.ga
    C:\%SOMBASE%\ETC> ren somnew.ir som.ir

  If you have changed the GA "som.ir" then you can pickup the changes
  by adding "som211.ir" into your SOMIR path, for example:

    OS/2:
    C> set SOMIR=%SOMBASE%\etc\som211.ir;%SOMBASE%\etc\som.ir;SOM.IR

    AIX:
    $  SOMIR="$SOMBASE/etc/som211.ir:$SOMBASE/etc/som.ir:./som.ir"; export SOMIR

    WIN:
    C> set SOMIR=%SOMBASE%\etc\som211.ir;%SOMBASE%\etc\som.ir;SOM.IR

  Or, if you have the all of the ".idl" files available and the SOM Compiler
  "sc", you can rebuild the IR file:

    OS/2:
    C> set SOMIR=%SOMBASE%\etc\som.ir
    C> cd %SOMBASE%\include
    C> sc -usir *.idl

    AIX:
    $  SOMIR="$SOMBASE/etc/som.ir"; export SOMIR
    $  cd $SOMBASE/include
    $  sc -usir *.idl

    WIN:
    C> set SOMIR=%SOMBASE%\etc\som.ir
    C> cd %SOMBASE%\include
    C> sc -usir *.idl

Fixes included in this Update CSD211
===========================================

CSD211 - New distribution utility

Feature number: 10419

Note:  The new distribution utility is provided as-is to assist
       people who install distributed applications.  It is NOT
       to be considered part of any SOMobjects product and will
       not be supported.


Implementation Repository Distribution
--------------------------------------

The Implementation Repository distribution utility has been written
to provide a means to distribute server and class information across
Implementation Repositories.  Since the selected information can be
distributed to other Implementation Repositories, the Implementation
Repository no longer needs to be shared.  With this utility,
information in the Implementation Repository can be grouped according
to selection identifiers.  A distribution file can be created using
the selection identifiers to decide which information is to be
included.  The distribution file can then be transported to other
hosts and the information can be applied to the other Implementation
Repositories.

The Implementation Repository distribution utility uses selection
identifiers to group the server and class information to be
distributed to other Implementation Repositories.  A selection
identifier is a string, with a maximum of 49 bytes, which is used to
group server information to be distributed. (Note:  on OS/2 and AIX,
selection identifiers are implemented as class associations in the
Implementation Repository.  The selection identifiers will be preceded
with a "*" to denote that the class is really a selection identifier.)

The Implementation Repository Distribution utility is a command line
utility with four options:  add selection identifier, remove selection
identifier, create distribution file, apply distribution file.


Add selection identifier

   To add a selection identifier to a server in the Implementation
   Repository, specify the "a" option, followed by the selection
   identifier and then the alias name of the server.  For example:

             dstf  "a" "Headquarters_1" "Headquarters"

   associates the selection identifier "Headquarters_1" with the
   server alias "Headquarters" in the Implementation Repository.


Remove selection identifier

   To remove a selection identifier from a server in the
   Implementation Repository, specify the "r" option, followed
   by the selection identifier and then the alias name of the
   server.  For example:

             dstf  "r" "Headquarters_1" "Headquarters"

   removes the association of selection identifier "Headquarters_1"
   with the server alias "Headquarters" in the Implementation
   Repository.


Create Distribution File

   To create an Implementation Repository distribution file to be
   distributed to other Implementation Repositories,  specify the
   "C" option, followed by the name of the file to be created and
   a list of selection identifier to be included in the file.
   For example:

             dstf  "C" "My_Company" "My_Company_Headquarters"
                   "My_Company_Branch1" "My_Company_Branch2"

   creates a distribution file "My_Company" containing the server and
   class information for all servers associated with the selection
   identifiers  "My_Company_Headquarters" "My_Company_Branch1"
   "My_Company_Branch2".

   A distribution file can also be created to contain all information
   in an Implementation Repository by specifying "*ALL" for the
   selection identifier.  For example:

             dstf "C" "All_Implrep" "*ALL"

   creates a distribution file "All_Implrep" that contains all the
   information in the Implementation Repository.


Apply Distribution File

   To apply an Implementation Repository distribution file to the
   Implementation Repositories, specify the "A" option, followed by
   the name of the file to be applied, the apply option, and a list
   of selection identifiers to be applied.  There are 2 options that
   can be used when applying a distribution file:
      "10" Merge - Add any new server information in the distribution
                   file to the implementation repository.  Update any
                   existing server with the information in the
                   distribution file.
      "20" Replace - Remove any entries in the Implementation
                   Repository that are associated with the specified
                   selection identifier.  Add the entries from the
                   distribution file to the Implementation Repository.

   For example:
             dstf  "A" "My_Company" "10" "My_Company_Headquarters"
                   "My_Company_Branch1" "My_Company_Branch2"

   applies the distribution file "My_Company" for all servers
   associated with the selection identifiers  "My_Company_Headquarters"
   "My_Company_Branch1" "My_Company_Branch2".  Any existing servers in
   the Implementation Repository associated with the specified
   selection identifiers will be updated using the information in the
   distribution file.  If a server associated with a selection
   identifier does not exist in the distribution file, its information
   in the Implementation Repository will not be changed.


             dstf  "A" "My_Company" "20" "My_Company_Headquarters"
                   "My_Company_Branch1" "My_Company_Branch2"

   applies the distribution file "My_Company" for all servers
   associated with the selection identifiers  "My_Company_Headquarters"
   "My_Company_Branch1" "My_Company_Branch2".  Any existing servers in
   the Implementation Repository associated with the specified
   selection identifiers will be deleted and replaced with the entries
   from the distribution file.


Restriction(s)

   The distribution tool currently has the limitation that
   a distribution file cannot be applied to a nonexistent
   Implementation Repository.  (There must be valid files
   in the directory specified by SOMDDIR before attempting
   to apply a distribution file.)

----------------------------------------------------------------------

CSD211 - New DSOM functions

(Defect 9772)

Two new DSOM functions have been added:

        SOMD_YesORBfree is a companion to SOMD_NoORBfree.
        It signifies that the application, which had previously
        called SOMD_NoORBfree, now wishes to free ORB-allocated
        memory using ORBfree rather than SOMFree.

        SOMD_QueryORBfree allows an application to determine
        whether SOMD_NoORBfree or SOMD_YesORBfree has been
        called (whether an application should be freeing ORB-allocated
        memory using ORBfree or SOMFree).  It returns TRUE if ORBfree
        should be used and FALSE if SOMFree should be used.

Notes regarding SOMD_NoORBfree/SOMD_YesORBfree and SOMD_QueryORBfree:

1.  SOMD_NoORBfree and SOMD_YesORBfree affect global process state,
hence these functions must be used carefully by threaded applications
to avoid conflict.

2.  Applications must be written to insure that the same mode of
memory management is in effect when memory is allocated as when it
is freed; otherwise, memory leaks will result.  For example, if an
application calls SOMD_NoORBfree, makes a remote method call resulting
in some memory being allocated, calls SOMD_YesORBfree, then (because
SOMD_QueryORBfree now returns TRUE), calls ORBfree on that memory, the
memory will not be freed.  Similarly, if an application calls
SOMD_YesORBfree, makes a remote call, calls SOMD_NoORBfree, then
(becuase SOMD_QueryORBfree now returns FALSE), uses SOMFree to free
the data structure, then although the data structure itself is freed,
the memory that DSOM uses to maintain information about the memory
(e.g., its TypeCode) will not be freed.

----------------------------------------------------------------------

CSD211 - Features

Features
--------

 7359 - It's not a fatal error to delete an unregistered server
        via regimpl - an error message will be produced only when
        SOMDDEBUG is set
 8011 - Allow servers to be designated nonstoppable - via a new
        "-n {on|off}" option to regimpl.  When a server is registered
        as nonstoppable, neither the "dsom stop" command nor the
        somdShutdownServer method can be used to terminate the server.

----------------------------------------------------------------------

CSD211 - Defects

Defects
-------
 3256      The COM emitter adds invalid comments to the .c file
 3406      The .xh compiler generates annoying messages
 3561      Incorrect marshalling of TypeCodes in DSOM
 6369      Fixes for problems in 2.1 Collection Classes
            1. somf_TDictionary_somfKeyAtM and
               somf_TDictionary_somfKeyAtMF get a "Segmentation fault
               (core dumped)" if the value being passed is not in
               the dictionary.
            2. somf_TCollection_somfMember will delete objects
               from the collection.
            3. If somf_TDeque_somfTDequeInitD is called on a non-empty
               TDeque, the objects from the second TDeque are added to
               it.
            4. somf_TPrimitiveLinkedList_somfRemove will core dump if
               user tries to remove an object that does not exist in
               the linked list.
            5. somf_TSet_somfXorSS does not set the count correctly
               under certain conditions.
            6. somf_TSortedSequence_somfOccurrencesOf will core dump
               if it is called on a TSortedSequence object that is
               empty.
 6466      problem with size of unions calculated in tcSize
 6989      If somf_TSequence_somfCreateIterator is not overridden,
           incorrect message will be displayed.
 7206      Comment such as "// /_Fachtyp_/" causes exception when using
           sc.
 7223      Error message is not generated by the C and C++ emitters if
           noself modifier is used for methods.
 7290      The // comment at begin of IDL file causes incorrect error
           message when running 'sc'.
 7334      If the staticdata modifier is used for an attribute or
           instance variable the instance data access macro is defined
           incorrectly in the .ih.
 7436      The pdl emitter still assumes that there is only a single
           interface or module) per idl file, and emits duplicate
           information into the pdl file.
 7447      TypeCode_size & TypeCode_alignment not computed correctly on
           AIX for structs containing doubles
 7516      If the somfTPriorityQueue class is used, _somfInsert will
           insert objects into the wrong order.
 7779      emitih: BeginInitializer generated incorrectly
 7879      SOM generated macro name '_value' conflicts with the '_value'
           field of the CORBA standard type 'any'.
 7921      DSOM does not marshall 'any' parameter with TypeCode tk_null
           or tk_void
 8046      sc -r option
 8060      SOM Compiler problem - duplicate sequence type nodes.
 8068      SOMD peer example for Windows has unneeded DSOMEventCallBack
           and TimerEventCallBack
 8076      The file produced by newemit (gen_emit.efc) does not handle
           opening the emitfile correctly.
 8161      If the source file is not in current directory, no PDL file
           is emitted by the PDL Emitter and "The file cannot be found."
           message is generated.
 8187      Deadlock after invoking oneway method from a DSOM server
 8218      DSOM does not correctly marshall an out struct containing a
           NULL string
 8219      Error in SOM compiler help message
 8237      Ability to specify multithreaded server using pregimpl
           (OS/2 only)
 8339      In C++ binding, the .xh and .xih files are generated
           differently between using "=" and ":". A coredump will
           be generated if metaclass : ... is used.
 8362      Error in the CTOI.CMD file when converting .CSC files to
           .IDL files.
 8396      Only the comment at the end of a union will be handled by
           the emitter and the emitter framework. Comments within
           the union are ignored.
 8420      If object pointers are in the struct, only the first object
           pointer is handled correctly by the .h compiler.
 8503      Allow a DSOM client to continue communicating with a server
           after the server goes down and comes back up
 8556      -d option on sc
 8615      SOM produces unfriendly error message "YOU LOSE BIGTIME"
           when an iterator is used before calling somfFirst
 8702      DSOM PERSIST_STORE error (AIX)
 9218      regimpl problem writing to read-only file (regimpl terminates
           with no error message unless SOMDDEBUG is set)
 9306      Name clash between som and cset (identifier "version" in
           somdtype.idl)
 9463      Using delete operator with proxies
 9571      If an overloaded initializer is declared with no additional
           parameters, any initializers declared after it will not be
           properly emitted in the .xh file.
 9694      A class object is implicitely created each time the dll
           is loaded and never freed.
 9740      On OS/2 there is no way to have all classes traced as
           described in the documentation (2.1 Users Guide, pg 10-9).
 9772      How to know when SOMD_NoORBfree has been called.  (A new
           function, SOMD_QueryORBfree, has been added.)
 9863      Having a large set of -I include paths generates an error
           message even if emptyfile.idl is empty.
 9876      When sommBeforeMethod returns FALSE, the primary method is
           still invoked
----------------------------------------------------------------------

CSD211 - Duplicate or not reproducible defects


The following defects are either duplicates of fixed defects
or are not reproducible under the new level:

Defects
-------
 2657      memory leaks found when using contents method
 3387      _System calling convention.
 5457      Possible Persistence Framework bugs
 6015      Persistence Framework woe
 6425      unknown SOMFree calls
 7510      scopes, bugs and docs
 7570      Name clashes
 8500      InterfaceRepository, CSet++ HeapView Debugger and memory leak
 8654      Variable syntax error in somenv.csh
 8805      GPF on server when server started after an abnormal stop
 8870      Before/After hook used with DSOM
 8922      passthru behavior
 9158      Change default for .xh emitter to be "-mnocfront" instead
           of "-mcfront"
 9864      somDestruct called more often than needed

----------------------------------------------------------------------
