
        IBM SOMobjects Developer Toolkit - Version 3.0 - README
        -------------------------------------------------------
                         December 1996 Release
                         ---------------------

25H7912 (C) COPYRIGHT International Business Machines Corp. 1992,1996
All Rights Reserved
Licensed Materials - Property of IBM
US Government Users Restricted Rights - Use, duplication or disclosure
restricted by GSA ADP Schedule Contract with IBM Corp.


Welcome to SOMobjects Developer Toolkit - Version 3.0 December 1996 Release
===========================================================================

SOMobjects Developer Toolkit is now available for AIX, OS/2, and Windows NT.
The SOMobjects Developer Toolkit code, publications, and the latest version
of this README are available at:
  http://www.software.ibm.com/clubopendoc/som30tk.html

This file contains information that you need for installing SOMobjects
Developer Toolkit and additional information not included in the original
product documentation.

The following components and function which were provided in the
February 1996 Beta release of SOMobjects 3.0 are no longer supported:

      - IDL Editor and IR Browser
      - sommak utility
      - somdoc utility and ipf emitter
      - Direct-To-SOM Programming
      - Collection Classes
      - Event Management Framework
      - Event Service
      - Life Cycle Service
      - Persistent Object Service
      - Concurrency Control Service
      - Transaction Service
      - pregimpl Server Registration GUI
      - online documentation

This README file is divided into the following categories:

   - Before You Install
      - Hardware Requirements
      - Base Software Requirements
      - Networking Software Requirements
      - Supported Compilers
   - Installing SOMobjects Developer Toolkit
      - Installation on AIX
      - Installation on OS/2
      - Installation on Windows NT
      - ISO Latin-1 Code Page Conversion
   - Updated Component Information
      - General Component Information
      - SOM Kernel
      - SOM Emitters
      - Distributed SOM
      - Object Services
   - Trademarks
   - Your Satisfaction

Before You Install
==================

Hardware Requirements
---------------------
  - An IBM or non-IBM hardware platform supporting the required
    level of the operating system
  - Display, mouse, and keyboard
  - OS/2 and Windows NT
    - At least 16 MB of RAM
    - At least 30 MB of fixed disk space
  - AIX
    - At least 24 MB of RAM
    - At least 30 MB of fixed disk space

Base Software Requirements
--------------------------
The following levels of operating system products are supported:
  - OS/2 Warp Version 3
  - AIX Version 4.1.4 or 4.2 with fileset xlC.rte
  - Microsoft Windows NT 3.51

Networking Software Requirements
--------------------------------
When using Distributed SOM, networking software is required.  This
is true even when DSOM is used on a single workstation for
inter-process communication.

Distributed SOM requires one of the following network products:
  - IBM TCP/IP Version 3.0 for OS/2
  - IBM AnyNet/2 with NetBIOS or TCP/IP, Version 2.02 with
    corrective service for APAR IC12389
  - TCP/IP as provided in the AIX operating system
  - TCP/IP as provided in the Windows NT operating system

Security Service on OS/2 requires:
  - LAN Server Version 4.0 with fixpak PTF=IP08182

Supported Compilers
-------------------
The following compilers are supported:
  - IBM VisualAge C++ for OS/2, Version 3.0, FixPack CTC306
  - IBM VisualAge C++ for Windows, Version 3.5, FixPack WTC352
  - IBM CSet++ for AIX, Version 3.1.4

FixPacks for VisualAge C++ are available on the Web.  You can follow
links from the VisualAge C++ Home Page:

  http://www.software.ibm.com/ad/visualage_c++

Note: The target date for CSD2 for VisualAge C++ for Windows is 1/15/97.


Installing and Configuring the SOMobjects Developer Toolkit
===========================================================

  The following is a summary of SOM Installation and Configuration.
  See Chapter 2 of the Programmer's Guide, Volume 1: SOM and DSOM for
  complete configuration information.


Installation on AIX
-------------------

  If you already have a previous version of SOM installed, we strongly
  recommend that you install SOM 3.0 in a new directory rather than
  copying over the contents of the previous SOM directory.

  Installation instructions should be executed as root user.

1. Copy the SOMobjects Developer Toolkit for AIX tar file, som30aix.tar.Z,
   to the directory where you wish to install SOM 3.0.  If this is a first
   time install, make a directory called /usr/lpp/som and copy the tar file
   to this directory.  If you already have a previous version of SOM
   installed, make a directory called /usr/lpp/som30, and copy the
   som30aix.tar.Z to this directory. The following instructions will assume
   an install directory of /usr/lpp/som.

   Uncompress and then untar the file with the following commands:

      uncompress som30aix.tar.Z
      tar -xvf som30aix.tar

2. Execute one of the supplied shell scripts in the /usr/lpp/som/bin
   directory, somenv.sh or somenv.csh, to initialize basic SOM environment
   variables.  By default, these scripts assume SOM has been installed in
   /usr/lpp/som.  If you have installed SOM in another directory, edit the
   appropriate script and modify the value of SOMBASE to the directory where
   you installed SOM 3.0.

      cd /usr/lpp/som/bin
      . ./somenv.sh       (for Korn shell)
      source ./somenv.csh (for C Shell)

   You may want to incorporate these scripts into your .profile (Korn shell)
   or .login (C shell).

3. The irindex command builds indexes for the Interface Repository
   files.  A one-time synchronization must be performed at install time.
   Issue the following command:

     irindex $SOMBASE/etc/som.ir

   There is no output from the irindex program if it is successful.

4. Configure DSOM

   Prior to configuring DSOM, make sure that if the SOMIR environment variable
   is set, that it is a valid setting.

   Configuring Install Hosts
   - Edit the /usr/lpp/som/etc/somenv.ini file.
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Save the revised somenv.ini file.
   - Run "som_cfg -i" to configure the Install host.
   - If you are going to continue by configuring some DSOM hosts on other
       machines, leave SOMDD running on the Install host.  Otherwise,
       stop somdd with a system "kill" command on the somdd process ID.

   Configuring DSOM Hosts
   - Copy the GLOBAL_OBJREF_FILE from the install host to the DSOM host.

       The default file name of the GLOBAL_OBJREF_FILE is somnm.ref.
       and is in the /usr/lpp/som/etc/dsom directory on the Install host.
       We suggest copying it to the /usr/lpp/som/etc directory on the
       DSOM host. Do not copy it to the /usr/lpp/som/etc/dsom directory,
       as the som_cfg program needs an empty /usr/lpp/som/etc/dsom directory.

   - Edit the /usr/lpp/som/etc/somenv.ini file.
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Change the GLOBAL_OBJREF_FILE value in the DSOM host's somenv.ini
       file to "$SOMBASE/etc/somnm.ref".
   - Make sure somdd is running on the Install Host.
   - Run "som_cfg -d" to configure the DSOM host.
   - Stop the DSOM host somdd with a system "kill" command on the somdd
       process ID.

   Configuring Simple DSOM clients (cannot run DSOM servers)
   - Edit the /usr/lpp/som/etc/somenv.ini file
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Copy the SOMNMOBJREF value from the install host's somenv.ini to
       the DSOM client's somenv.ini.
   - som_cfg does not need to be run for simple DSOM clients. You are done.

5. Build the SOM binding header files.
   To build the SOM binding files for C and C++, do the following:
   - For C header files such that object type variables do not need an '*',
     run somcorba.
   - For C header files such that object type variables do need an '*',
     run somstars.
   - For C++ header files, run somxh.

6. See Chapter 2 of the Programmer's Guide, Volume 1: SOM and DSOM for
   additional configuration information.


Installation on OS/2
--------------------

  If you already have a previous version of SOM installed, we strongly
  recommend that you install SOM 3.0 in a new directory rather than
  copying over the contents of the previous SOM directory. This is
  especially true if you have installed the SOM 3.0 OS/2 Beta.

1. Copy the zip file, som30os2.zip, or the Internet-sized OS/2 zip files,
   som30ox1.zip, som30ox2.zip and som30ox3.zip, to the directory where you
   wish to install SOM 3.0.  If this is a first-time install, make a new
   root directory called som, and copy the zip file(s) there.  If you have
   a prior version of SOM installed on your machine, create a new directory
   for SOM 3.0 and copy the SOMobjects Developer Toolkit for OS/2 zip file(s),
   to this directory.  The following instructions will assume an install
   directory of c:\som.

2. If you must install over a previous version of SOM, disable the Workplace
   Shell before unzipping the zip file(s).

   There are two ways to do this:

   A. Modifying config.sys to boot OS/2 in non-Workplace Shell mode.
      - Modify the config.sys LIBPATH statement so that the
        c:\som\lib directory where you are installing SOM 3.0
        appears first in the list of directories in each of these
        statements.  This will allow Workplace Shell to pick up the
        new SOM 3.0 dlls.
      - Make a temporary backup copy of this new config.sys. Call
        it config.som.
      - Again, edit config.sys and modify the PROTSHELL statement and the
        RUNWORKPLACE statements.

        Change the PROTSHELL statement to:
          PROTSHELL=c:\os2\cmd.exe

        Change the RUNWORKPLACE statement to:
          SET RUNWORKPLACE=c:\os2\cmd.exe

      - Reboot the system. OS/2 will boot up in non-WPS mode.
      - Change to the directory where you copied the zip file(s), and
        unzip the zip file(s) using your favorite unzip utility. You
        may use any unzip utility that you like, but make sure you restore
        the directory structure when unzipping.

        ex) pkunzip -d som30os2.zip

      - Copy the backup config.som back to config.sys.
      - Reboot the system. The OS/2 Workplace Shell will pick up the
        new SOM 3.0 DLLs.

   B. Interrupting the OS/2 boot sequence with Ctrl-Alt-F1.
      - Reboot the system.
      - When "OS/2" appears in the upper-left-hand corner of the screen,
        press ctrl-alt-F1 (all three keys at the same time). to bring up
        the "Recovery Choices" menu.  Enter "c" to open an OS/2 full screen
        window.
      - Change to the directory where you copied the zip file(s), and
        unzip the zip file(s) using your favorite unzip utility. You
        may use any unzip utility that you like, but make sure you restore
        the directory structure when unzipping.

        ex) pkunzip -d som30os2.zip

      - Edit config.sys and add %SOMBASE%\lib to the beginning of
        the LIBPATH variable.  This will allow Workplace Shell to pick
        up the new SOM dlls.

      - Press ctrl-alt-del to reboot your system. The OS/2 Workplace
        Shell will pick up the new SOM 3.0 DLLs.

3. Execute the supplied command file, c:\som\bin\somenv.cmd, to initialize
   basic SOM environment variables.  You must first edit this command file
   and set SOMBASE to the directory where SOM is installed.

     cd som\bin
     (edit somenv.cmd and set SOMBASE to the directory where you
      installed SOM 3.0)
     somenv.cmd

   You may want to incorporate the commands in this command file into your
   config.sys file so that you do not have to execute this command file
   whenever you run SOM 3.0 applications.

4. The irindex command builds indexes for the Interface Repository
   files.  A one-time synchronization must be performed at install time.
   Issue the following command:

     irindex %sombase%\etc\som.ir

   There is no output from the irindex program if it is successful.

5. Configure DSOM

   Prior to configuring DSOM, make sure that if the SOMIR environment variable
   is set, that it is a valid setting.

   Configuring Install Hosts
   - Edit the c:\som\etc\somenv.ini file.
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Save the revised somenv.ini file.
   - Run "som_cfg -i" to configure the Install host.
   - If you are going to continue by configuring some DSOM hosts on other
       machines, leave SOMDD running on the Install host.  Otherwise, stop
       somdd by going to the SOMDD window and pressing ctrl-break.

   Configuring DSOM Hosts
   - Copy the GLOBAL_OBJREF_FILE from the install host to the DSOM host.

       The default file name of the GLOBAL_OBJREF_FILE is somnm.ref.
       and is in the c:\som\etc\dsom directory on the Install host.
       We suggest copying it to the c:\som\etc directory on the
       DSOM host. Do not copy it to the c:\som\etc\dsom directory,
       as the som_cfg program needs an empty c:\som\etc\dsom directory.

   - Edit the c:\som\etc\somenv.ini file.
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Change the GLOBAL_OBJREF_FILE value in the DSOM host's somenv.ini
       file to "c:\som\etc\somnm.ref".
   - Make sure somdd is running on the Install Host.
   - Run "som_cfg -d" to configure the DSOM host.
   - After running som_cfg, stop somdd by going to the SOMDD window
       and pressing ctrl-break.

   Configuring Simple DSOM clients (cannot run DSOM servers)
   - Edit the c:\som\etc\somenv.ini file.
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Copy the SOMNMOBJREF value from the install host's somenv.ini to
       the DSOM client's somenv.ini.
   - Som_cfg does not need to be run for simple DSOM clients. You are done.

6. Build the SOM binding header files.
   To build the SOM binding files for C and C++, do the following:
   - For C header files such that object type variables do not need an '*',
     run somcorba.
   - For C header files such that object type variables need an '*',
     run somstars.
   - For C++ header files, run somxh.

7. See Chapter 2 of the Programmer's Guide, Volume 1: SOM and DSOM for
   additional configuration information.


Installation on Windows NT
--------------------------

  If you already have a previous version of SOM installed, we strongly
  recommend that you install SOM 3.0 in a new directory rather than
  copying over the contents of the previous SOM directory.

1. Copy the zip file, som30nt.zip, or the Internet-sized NT zip files,
   som30nx1.zip, som30nx2.zip and som30nx3.zip, to the directory where you
   wish to install SOM 3.0.  If this is a first-time install, make a new
   root directory called som, and copy the zip file(s) there.  If you have
   a prior version of SOM installed on your machine, create a new directory
   for SOM 3.0 and copy the SOMobjects Developer Toolkit for NT zip file(s),
   to this directory.  Unzip the zip file(s) using your favorite unzip utility.
   You may use any unzip utility that you like, but make sure you restore the
   directory structure when unzipping.

   ex) pkunzip -d som30nt.zip

   The following instructions assume an install directory of c:\som.

   Note: SOM dynamically links with the C runtime.  The SOMobjects Developer
     Toolkit for NT ships somws35i.dll and somwm35i.dll, the single and
     multi-threaded C runtime libraries, to avoid requiring VisualAge C++.

2. Execute the supplied command file, c:\som\bin\somenv.cmd, to
   initialize basic SOM environment variables.  You must first edit
   the command file and set SOMBASE to the directory where SOM is
   installed.

     cd som\bin
     (edit somenv.cmd and set SOMBASE and save the file)
      somenv.cmd

   You may want to add these environment variable settings to the System or
   User Environment Variables in the System settings panel.

3. The irindex command builds indexes for the Interface Repository
   files.  A one-time synchronization must be performed at install time.
   Issue the following command:

     irindex %sombase%\etc\som.ir

   There is no output from the irindex program if it is successful.

4. Configure DSOM

   Prior to configuring DSOM, make sure that if the SOMIR environment variable
   is set, that it is a valid setting.

   Configuring Install Hosts
   - Edit the c:\som\etc\somenv.ini file.
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Save the revised somenv.ini file.
   - Run "som_cfg -i" to configure the Install host.
   - If you are going to continue by configuring some DSOM hosts on other
       machines, leave SOMDD running on the Install host.  Otherwise, stop
       somdd by going to the SOMDD window and pressing ctrl-break.

   Configuring DSOM Hosts
   - Copy the GLOBAL_OBJREF_FILE from the install host to the DSOM host.

       The default file name of the GLOBAL_OBJREF_FILE is somnm.ref.
       and is in the c:\som\etc\dsom directory on the Install host.
       We suggest copying it to the c:\som\etc directory on the
       DSOM host. Do not copy it to the c:\som\etc\dsom directory,
       as the som_cfg program needs an empty c:\som\etc\dsom directory.

   - Edit the c:\som\etc\somenv.ini file.
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Change the GLOBAL_OBJREF_FILE value in the DSOM host's somenv.ini
       file to "somnm.ref".
   - Make sure somdd is running on the Install Host.
   - Run "som_cfg -d" to configure the DSOM host.
   - After running som_cfg, stop somdd by going to the SOMDD window
       and pressing ctrl-break.

   Configuring Simple DSOM clients (cannot run DSOM servers)
   - Edit the c:\som\etc\somenv.ini file.
     Change all occurences of "thehostname" to the machine's TCP/IP hostname.
     If you intend to run DSOM across machines, change "SOMDPROTOCOLS=SOMD_IPC"
       to "SOMDPROTOCOLS=SOMD_TCPIP".
     Copy the SOMNMOBJREF value from the install host's somenv.ini to
       the DSOM client's somenv.ini.
   - som_cfg does not need to be run for simple DSOM clients. You are done.

5. Build the SOM binding header files.
   To build the SOM binding files for C and C++, do the following:
   - For C header files such that object type variables do not need an '*',
     run somcorba.
   - For C header files such that object type variables need an '*',
     run somstars.
   - For C++ header files, run somxh.

6. See Chapter 2 of the Programmer's Guide, Volume 1: SOM and DSOM for
   additional configuration information.


ISO Latin-1 Code Page Conversion
--------------------------------

DSOM 3.0 supports a configuration file setting, SOMDISOLATIN1, in the [somd]
stanza of somenv.ini, which, if set to 1, instructs DSOM to convert to the
ISO Latin-1 codeset (ISO8859-1 or IBM-819) character data in messages sent
between processes.  This support is provided for two reasons:
   (1) to allow interoperability between ASCII-based systems (AIX, OS/2, NT)
       and EBCDIC-based systems (MVS).
   (2) to comply with the CORBA 2.0 IIOP interoperability specification.
       (Note, however, that most non-IBM ORBs do not yet perform translation
       for character data in messages, therefore setting SOMDISOLATIN1 may
       actually hinder interoperability between DSOM 3.0 and other vendors'
       ORBs.)

Applications requiring interoperability with SOMobjects on MVS should set
SOMDISOLATIN1=1 in the [somd] stanza of the SOMobjects configuration file.
Most other users will probably want to leave it unset, to enhance performance
and to allow interoperability between SOMobjects 3.0 and non-IBM ORBs.

Note that on OS/2 and Windows NT, ISO Latin-1 code set conversion of
character data, using the SOMDISOLATIN1 setting, is only supported for
systems/applications using the IBM-850 or IBM-437 code sets (which is the
case for most English systems).

OS/2 and Windows NT users who wish to enable ISO Latin-1 code set conversion
who don't have the VisualAge C++ compiler installed: it is necessary to
download file localeo2.zip (for OS/2) or localent.zip (for Windows NT) from
the SOMobjects Developer Toolkit Web page.  Unzip the file and update the
LOCPATH environment variable in your operating system environment to
include the directory created by unzipping it.

Updated Component Information
=============================

General Component Information
-----------------------------

The following items affect either the product as a whole or multiple
components.

1. Applications written with SOMobjects 2.x may need to increase the
   application stack size when migrating to SOMobjects 3.0.

2. Applications written for Windows NT should use the Gd+ compile option.
   Gd is a compiler option which specifies whether to dynamically or
   statically link with the VAC++ runtime functions.  Gd+ indicates
   dynamic linking.

3. When using the def emitter on Windows NT, update the output .nid file
   to export "_SOMInitModule@12".  This is required when using module
   names within IDL files. 

4. Scripts or processes checking the return code from an application running
   on Windows NT may not receive an accurate value.  Although main may
   return 0 indicating success, another value may be received by the caller.

5. som_cfg creates error log entries that can be ignored if som_cfg
   completes successfully.  You can expect log entries with the following
   error codes:

   Error code is 30109 [SOMDERROR_SOMDDNotRunning].
   som_cfg starts the DSOM daemon if it is not running.  When querying
   for the status of the daemon, this error may be raised.

   Error code is 30046 [SOMDERROR_EntryNotFound].
   som_cfg registers the Naming Service and Security Service in the
   Implementation Repository.  When querying whether entries for these
   servers already exist, this error may be raised.

   Error code is 30088 [SOMDERROR_NamingNotActive].
   When registering with the Implementation Repository, DSOM will
   attempt to store the information in the Naming Service.  If the
   Naming Server is not running, this error will be raised.

6. DSOM and the Object Services do not provide code page conversion.
   Therefore, if a client and server are operating under different
   code pages, operations performed against character data will have
   unpredictable results.

7. On AIX, an application must call SOMD_Init before invoking a method
   migrated from SOMDObject to SOMObject.  This requirement applies to
   the following methods: create_request, create_request_args, duplicate,
   get_implementation, get_interface, is_nil, is_proxy, and release.

8. SOMobjects 3.0 does not support Direct-To-SOM.  The following notes
   are provided to assist users who created DTS C++ code using support
   provided by earlier releases, and who now want to migrate this DTS C++
   code to C or native mode C++ code that uses the C or native mode C++
   bindings provided by the SOMobjects 3.0 product.

   DTS C++ allows definition and use of either native mode or SOM classes,
   but the following discussion focuses on DTS C++ code that implements or
   uses SOM classes.

   There are a few different usage scenarios for DTS C++:

   1) To implement SOM classes:
      a) start with IDL, use the hh emitter to produce a DTS C++ header,
         include this header into a DTS C++ implementation file that you
         write.
      b) start with DTS C++. Optionally, use the DTS C++ compiler to produce
         IDL for other users.

   2) To use SOM classes:
      a) if the SOM classes are described using IDL, use the hh emitter to
         produce a DTS C++ header, include this header into your DTS C++
         source file.
      b) if the SOM classes are described using a DTS C++ header, include
         this header into your DTS C++ source file.

   The migration issues related to each of the above scenarios are
   somewhat different:

   1a) Generate new usage bindings, implementation bindings, and
       implementation template from the IDL that was originally used as input
       to the hh emitter.  In general, for each member function definition in
       your DTS C++ implementation source, your implementation template file
       will contain a global function stub.  You'll need to move the code
       from your member function definitions to the function stubs in the
       template file.  Expect to make lots of changes in the source code.
       You'll have to rewrite any use of stack-allocated objects to use heap
       allocation.  And, of course, access to instance variables is done
       differently in the native mode bindings (via somThis).

   1b) The IDL provided by the DTS C++ compiler will likely require
       modifications.  After you have made any necessary modifications,
       proceed as in case 1a.

   2a) DTS C++ code that uses SOM objects (as opposed to implementing them)
       should generally port fairly easily to native mode C++ usage bindings.
       The big exception is stack-allocated objects.

   2b) Again, as in case 2a, it will be necessary to produce IDL from which
       usage bindings can be generated.

SOM Kernel
----------

1. The somthrd.h file is no longer available.

   Replace each of the following functions:

   Old Function            Replacement Function on OS/2
   ----------------------------------------------------
   SOMStartThread()        _beginthread()
   SOMEndThread()          _endthread()
   SOMKillThread()         DOSKillThread()
   SOMYieldThread()        DOSSleep(0)
   SOMGetThreadHandle()    DOSGetInfoBlocks()

   Similar functions are also available on AIX and Window NT.  For more
   information, see the programming guide for your operating system.

   The following typedefs are no longer supported.

   somTD_SOMStartThread
   somTD_SOMEndThread
   somTD_SOMYieldThread
   somTD_SOMKillThread()
   somTD_SOMGetThreadHandle

2. The SOMObject methods somDispatchV, somDispatchL, somDispatchA, and
   somDispatchD have been replaced by the single SOMObject method
   somDispatch.

3. The generated class name for a derived metaclasses is now of the form
   SOMM_<class>_Derived.  In 2.x, the class name was of the form
   M_<class>_Derived.

SOM Emitters
------------

1. Usage bindings now support IDL files that contain only global
   definitions. As before, global definitions must be bracketed within
   somemittypes on/off pragmas to emit the corresponding bindings.

2. When a typedef within one IDL file refers to a type defined in some
   other IDL file, the emitted usage bindings for the first IDL file will
   automatically #include usage bindings corresponding to the other IDL just
   prior to the typedef mapping. This side-effect of typedefs allows you to
   use typedefs to assure that headers upon which usage bindings for your IDL
   depend will be #included into the usage bindings for your IDL, while
   avoiding the use of passthru statements.

   There is no similar support for types that simply appear in method
   signatures.  If you define a method that uses a type defined in some
   other IDL file, and usage bindings for that other file will not be included
   for some other reason, you should add a typedef to your interface
   that mentions a type defined in the other IDL file.

3. The fix for mapping interface typedefs into usage bindings that was
   originally provided in CSD212 (via the sc command line modifier -mitdfix)
   is now the default behavior. As a result of this fix, the IDL typedef

        typedef I myType; // where I is an interface

   results in usage bindings that include the following typedef:

        typedef I myType;

   Thus, in all cases, the name myType must  be treated (by
   bindings and program code) in the same way that the name "I" would be
   treated. Because of the way that previous bindings mapped interface
   typedefs (by adding an explicit star to the typedef in some cases), two
   kinds of source changes may be required when recompiling code that uses
   non-CORBA C bindings:

  a. The prototypes for methods that receive myType arguments must be
     changed. Compile-time errors when compiling class implementations would
     signal this, and the simplest response is to use the incremental
     template emitter to modify the method procedure prototypes.
     It should not be necessary to make these changes in your method
     implementations by hand. The template emitter will make the necessary
     changes in the signatures of your method procedures.

  b. Code that uses local variables of type myType may have to be modified
     by hand, by adding a star (when using the non-CORBA somstars C bindings).

   In this release, the older mapping for typedefs may be generated
   by using the sc command line modifier -mitdlegacy but their continued
   use is not recommended.

4. The following enhancements to initializers have been made:

  a. New control argument types have been declared in somobj.idl. These have
     the same structure as the original types, but are passed as "in"
     parameters to initializer methods instead of "inout" parameters.  This
     change does not affect the C and C++ bindings, but is important to
     Smalltalk bindings.  The names of the new control types differ from those
     used previously because they start with "som3" instead of "som".  Thus,
     for example, there is a new type named som3InitCtrl.

     The old names are still supported (they are defined in somapi.h, along
     with the new ones). So, there is no reason to modify existing C or C++
     code to use the new type names, but you may want to modify the IDL for
     your classes if you want Smalltalk code to be able to invoke initializers
     on their instances. To do this, add a "3" to the initial "som" in the
     control argument type for your initializers, and change "inout" to "in"
     for this argument.  All the methods in SOMObject that take control
     arguments, and output from the template emitter use the new type names.
     When you define new classes in IDL, their initializers should use the
     new type names.

  b. Initializers can now be overridden. That is, a class can define a local
     initialization method by overriding an inherited initializer. You need
     to specify the init modifier along with the override.  For example, if
     foo is an inherited initializer method, the following could be used in
     the implementation section to override it:

        foo: override, init;

     This results in an initializer template in your emitted implementation
     template file, and usage bindings for your class will include a
     constructor that invokes foo.

  c. When the implementation template for overrides of SOMObject's object
     copy and object assignment methods is emitted, the ancestor calls that
     are provided correspond to the method that is overridden.  For example,
     if you override somDefaultConstVCopyInit, then ancestor calls to
     somDefaultConstVCopyInit will be emitted in the implementation template
     file.

     But, when the macros that support ancestor calls to SOM's object copy
     and object assignment methods are emitted in implementation bindings,
     macros are provided only for those methods that are actually available
     in the ancestor.  A comment in the implementation bindings indicates
     when one of these methods is not available in an ancestor.

     The concept of copy and assignment method availability is new to
     SOMobjects 3.0.  It works as follows: a copy or assignment method is
     available in a class if:

     - It is defined by the class (by overriding the method)
     - The method is "below" a stronger method that is defined
     - The method is somDefaultCopyInit or somDefaultAssign.

     Here are the strength orderings for SOMObject's copy methods. A similar
     diagram describes the corresponding assignment methods.

                  somDefaultConstVCopyInit
                           / \
                          /   \
                         /     \
                        /       \
      somDefaultConstCopyInit   somDefaultVCopyInit
                        \       /
                         \     /
                          \   /
                           \ /
                     somDefaultCopyInit

     For example, if a class X defines somDefaultConstInit, ancestor
     initializer macros in a subclass will be provided (only) for
     somDefaultConstInit and somDefaultInit.  So, if you subclass this class
     to create Y and override somDefaultVCopyInit (for example), you will
     have the following unresolved symbol when you try to link your class
     implementation:

             Y_Init_X_somDefaultConstVCopyInit

     This tells you that somDefaultConstVCopyInit is not available in X.
     You would then look at X's IDL (or at your implementation bindings) to
     see what object copy methods are available in X, and use those instead.
     As mentioned above, somDefaultCopyInit will always be available.

6. A new chk emitter checks that the IDL input to the SOM compiler
   is semantically meaningful, to guarantee that output from all other
   emitters will be useful. This emitter does not create an output file.

   Normally, the chk emitter is run automatically before other emitters (you
   can see this by using the -v switch when using the sc command to invoke an
   emitter explicitly). But, you can also invoke the chk emitter explicitly as
   with any other emitter (by using -schk on the sc command line), or you can
   omit its execution by using -mnochk on the sc command line.

   Many of the checks performed by the chk emitter are obvious. One of the
   new checks is that all interfaces other than SOMObject must specify
   a parent which guarantees useful .xh bindings. This is a new requirement.

   The chk emitter generates warnings for any unsupported modifiers.

   * Modifiers related to attributes can sometimes cause spurious warnings,
     for example:

        my_attribute: nodata;

     This may raise two warnings: Once for "nodata" and once for
     "my_attribute" under certain conditions.

     The warning looks like this:

     "<file-name>", line <line-no>: warning: Unknown modifier "my_attribute"
     in interface/method "<interface-name>". It may be misspelled.


7. The PDL program now supports more sophisticated processing of IDL files.
   In previous versions of the toolkit, PDL could remove only sections of IDL
   text bracketed via #ifdef and #endif directives.  PDL is now also capable
   of removing sections delimited via #if and #ifndef directives, and
   partially evaluating conditional expressions.  See the Programmer's Guide
   Volume I for details.

8. The following Emitter Framework typedefs/functions have been renamed:
      old                          new
     ---------------------------------------------------
     EmitFn                        EmitFnSL
     somterror                     somterrorSL
     somtfatal                     somtfatalSL
     somtfclose                    somtfcloseSL
     somtinternal                  somtinternalSL
     somtmsg                       somtmsgSL
     somtopenEmitFile              somtopenEmitFileSL
     somtresetEmitSignals          somtresetEmitSignalsSL
     somtunsetEmitSignals          somtunsetEmitSignalsSL
     somtwarn                      somtwarnSL

   Under SOM2.1, the above functions/typedefs did not make use of SOMLINK.
   This worked on AIX, but is not particularly portable on OS/2 and NT.
   For backward compatibility, the old functions/typedefs are still available.
   However, use the new functions for portability.

9. When a SOMFOREIGN type is referenced in an IDL method declaration, the
   emitters generate incorrect bindings for the method in the following
   situation:

   1. the SOMFOREIGN type is declared in the same interface as the method
      that references it
   2. the SOMFOREIGN type has the "struct" storage class as indicated by
      the "struct" IDL modifier
   3. the "struct" modifier for the SOMFOREIGN type is specified using a
      SOM IDL modifier statement (in the implementation section) rather
      than using the modifier #pragma.

   The workaround is to use the modifier #pragma instead of the modifier
   statement, for SOMFOREIGN types that need to be referenced in method
   declarations prior to the implementation statement.

Distributed SOM (DSOM)
----------------------

Important differences between DSOM 2.1 and DSOM 3.0
---------------------------------------------------

Configuration (regimpl and the Implementation Repository)
---------------------------------------------------------
DSOM runtime settings must now come from the [somd] stanza in the
configuration file, and from environment variables.  (The configuration
file name is specified by the SOMENV environment variable.)  SOMIR, HOSTNAME,
and USER are still supported as environment variables.  If these environment
variables are unset, the configuration file is consulted.  Compile-time
environment variables (those used by the SOM Compiler and Emitters) are also
not affected.

Registering servers (using regimpl) requires that somdd is running
and that the Naming Service has been configured using the som_cfg tool
because DSOM now uses the Naming Service to store server-class
associations.  There are other significant changes to the Implementation
Repository; see the Programmer's Guide Volume 1 for more information.

DSOM doesn't support outstanding object references when a server
machine is upgraded from one version of DSOM to another.  This implies
that "object reference table" files are rendered obsolete during the
upgrade.

Error Handling
--------------
DSOM 3.0 almost never terminates the process in which it is run
because of a DSOM exception.  This allows applications to control when
they terminate and how they cleanup.  It also means that applications
are responsible for error checking after every DSOM call.  Applications
should avoid, however, checking for specific DSOM minor codes, because
these are subject to change.

User exceptions raised by remote method invocations cannot be marshaled
unless the method declares the exception in a "raises" expression in
IDL.  Otherwise, DSOM returns a system exception to the client
(with minor code SOMDERROR_UndeclaredException).  System exceptions can
be raised by any method and are not declared in an IDL "raises" expression.

Sockets Classes
---------------
User-defined Sockets classes are no longer supported.  Configuration has
been simplified by eliminating the SOMSOCKETS environment variable.  One
exception is that SOMSOCKETS is used by migimpl3, a tool to convert 2.1
Implementation Repositories to 3.0 format.  SOMSOCKETS is used by migimpl3
to determine what value of SOMDPROTOCOLS to assume for the converted entries.

Parameter Memory Management
---------------------------
In DSOM 2.x, the default parameter-memory management policy was not
uniformly "caller owns".  (The "memory_management=corba" IDL modifier had
to be used to request this behavior.)  Applications that are recompiled
using DSOM 3.0 will have a new default policy, which is "caller
owned".  If this new default is not appropriate for the application,
then the application's IDL should be modified to contain explicit
modifiers (for example, object_owns_result, object_owns_parameters,
dual_owned_result, dual_owned_parameters, and suppress_inout_free).
See the Programmer's Guide Volume I for more information.  The new
memory-management policy does not affect an application until its .ih/.xih
files are regenerated using the SOMObjects 3.0 SOM Compiler.

For some data types, the storage inside an inout parameter will be
unconditionally freed in the "in" direction, and reallocated in the
"out" direction (in the client's address space), when using the default
parameter-memory management policy.  Specifically, an inout object
reference, the _value and _type fields of an inout any, an inout
TypeCode, and inout SOMFOREIGNS have this property.  Thus, this storage
must be allocated with SOMMalloc, and may not be static or automatic
storage.

For inout strings, sequences, and pointers, the "in" storage may be freed
and reallocated by DSOM if it changes in the "out" direction.  Specifically:
    - if an unbounded string comes back longer than the original, or
      set to NULL, the original will be freed by DSOM,
    - if an unbounded sequence's _buffer comes back longer than the
      original's _maximum, the original is freed and reallocated by DSOM,
    - if a pointer comes back NULL, then the original value is freed by DSOM.
Thus, even though it is legal for inouts of these types to point to static
storage, it is risky, because it relies on the out value not invalidating
the original storage.

When an application object changes an inout parameter (for example, giving
a string a longer value) in a way that causes storage to be "orphaned", the
object is responsible for freeing the orphaned storage (for example, the
old string), unless the method parameter has the IDL modifier
"suppress_inout_free".

The argument to ORBfree in DSOM 3.0 is the topmost argument pointer
used to return a result or out parameter.  (In DSOM 2.x, the argument
to ORBfree was the topmost "freeable" pointers within the parameter.)
This allows an application to free all ORB-allocated memory in a return
result or out parameter with a single call, rather than multiple
calls.   As in DSOM 2.x, ORBfree frees only the memory within the
parameter that the ORB allocated on behalf of the client (and not any
memory within the parameter that the application allocated).  ORBfree
is not applicable to inout parameters or exceptions parameters.

In DSOM 3.0, it is an error for an application object (within a server) to
dereference an out parameter of type pointer.  Like all other out
parameters, the initial value must be set by the application object, and
the object should not assume that the initial value of an out parameter is
valid data.

Object Reference Table
----------------------
Support for the Object Reference Table, including the SOMOA methods
create_constant and change_id, is now deprecated.  create_constant is
now equivalent to create except for servers whose ImplementationDef object
specifies an Object Reference Table file name.  If a file name is specified,
the 2.x semantics of create apply.  Object Reference Table data will be
stored in the directory designed by SOMDDIR (as opposed to the Object
Reference Table file name specified in the ImplementationDef).  The same
files can be used by multiple servers.  Servers that need persistent storage
of object-reference data, such as that previously provided by the Object
Reference Table, should implement this functionality in an application-
pecific subclass of SOMDServer or use the SOMOS::Server class.

New Method Semantics
--------------------
DSOM applications, once recompiled, will receive the new default
behavior for invoking somFree on a proxy object. The new behavior is
that both the remote object and the proxy are freed.  (The 2.x default
was that only the remote object was freed.)  Applications that want to
continue to use the 2.x default behavior for somFree must set the
somd21somFree attribute of the SOMD_ObjectMgr global object to FALSE
after calling SOMD_Init.  This attribute, however, is deprecated and may
not be supported in future releases.

DSOM applications, once recompiled, will receive the new default
behavior for the ORB::string_to_object method. The new behavior is that
if the string object reference refers to an object local to a server,
the local SOMObject will be returned, rather than a SOMDObject.  (The
2.x behavior was to return a SOMDObject, which is not local/remote
transparent.)  Applications that want to continue to use the 2.x default
behavior for string_to_object must set the stringToObject30 attribute
of the SOMD_ORBObject global object to FALSE after calling SOMD_Init.  This
attribute, however, is deprecated and may not be supported in future
releases.

Known restrictions in DSOM
--------------------------

1. For machines that are used together as a DSOM workgroup (where
   the DSOM client is run on one machine and the DSOM server is run on
   another machine), both machines must be running the same version of
   SOMobjects (either 2.x or 3.0 GA).  A machine running SOMobjects 2.x
   will not communicate via DSOM with a machine running SOMobjects 3.0.

2. SOMObject methods get_implementation and get_interface are not supported
   when executed between DSOM and another ORB.

3. User-defined proxy classes and user-defined proxy base classes
   developed using SOMobjects 2.x are incompatible with SOMobjects 3.0.
   Such proxy classes must be reimplemented using a new programming model;
   see the Programmer's Guide Volume I for more information.

4. When classes are registered in the Naming Service (for example via
   regimpl), to be retrieved by client applications using the DSOM Factory
   Service, the Naming Server running on the install host must be able to
   load those classes.  This means that the DLLs for those classes must be
   loadable by the install host's Naming Server (either the real DLL or a
   "stub" DLL), and if the class name is not the same as the DLL name, the
   install host Naming Server's SOMIR setting must reference an Interface
   Repository file that contains the classes' "dllname" modifiers.

5. There are known problems restarting the Workplace Shell DSOM server
   thread.  After running an application and terminating the server thread,
   a system reboot is necessary before the server can be restarted.

   As a result, when running the Sample DSOM Client shown in the Workplace
   Shell Programming Guide (or any DSOM WPS client program that starts/stops
   the daemon and server programmatically if they are not already running),
   it is advisable to start the daemon and server using the "wpdsinit /s"
   command before running the client.  This prevents the client from
   terminating the server, allowing the client to be rerun any number of
   times without rebooting.  It also insures that the daemon will be ready
   before the client attempts to make the first remote request.

6. On AIX, if a DSOM process terminates without calling SOMD_Uninit, the
   resources often remain allocated.  The cleanipc script can be used to
   free IPC resources for a particular user.  Due to potential side effects,
   cleanipc does not free resources when run as root.  Consider using a
   privileged user id other than root to run the DSOM daemon and application
   servers.  Another disadvantage to running the DSOM daemon as root is
   that servers started by the daemon will also execute as root; this adds
   a potential security exposure to the system.

7. If your application runs for an extended period of time, it is
   recommended that you set SOMDNUMTHREADS in the [somd] stanza of
   somenv.ini.  SOMDNUMTHREADS specifies the maximum number of request
   threads created per server.


Object Services
---------------

1. When deriving classes from somOS::ServiceBase and overriding the method
   init_for_object_reactivation, do not perform any actions within the
   implementation of init_for_object_reactivation that will result in a
   remote method invocation on another server.  When a server is performing
   init_for_object_reactivation, it cannot perform any remote communication;
   if any is attempted, the server will hang.

2. The Security Service should be used with servers that use somOS::Server
   (such as somossvr.exe); when used with other servers (such as somdsvr.exe),
   errors may occur when the server is terminating.

3. When using the Security Service, if the server's entry in the
   Implementation Repository initially indicates that the server is secure,
   then is changed to indicate that the server is not secure, the server will
   continue to behave as a secure server.  The workaround is to unregister
   the server from the Implementation Repository and re-register the server
   as a non-secure server (so that the server will have a new UUID).

4. The Externalization Service is not thread safe.

Trademarks
==========

AIX is a trademark of International Business Machines Corporation.
IBM is a trademark of International Business Machines Corporation.
OS/2 is a trademark of International Business Machines Corporation.
SOM is a trademark of International Business Machines Corporation.
SOMobjects is a trademark of International Business Machines Corporation.
VisualAge C++ is a trademark of International Business Machines Corporation.
C Set++ is a trademark of International Business Machines Corporation.
Windows is a trademark of Microsoft Corporation.
Windows NT is a trademark of Microsoft Corporation.

Your Satisfaction
=================

Your satisfaction is important to us.  If you encounter a problem you
believe to be a defect in the SOMobjects Developer Toolkit code or
documentation, please submit a report to the technical support team.  The
problem submission form is located at:
  http://www.austin.ibm.com/somservice/supform.html


SOMobjects, Making Reuse a Reality
