--------------------------------------------------------------------------------
--
-- COPYRIGHT:
--   IBM WorkFrame - Project Smarts
--   (C) Copyright International Business Machines Corporation 1996
--   Licensed Material - Program-Property of IBM - All Rights Reserved.
--   US Government Users Restricted Rights - Use, duplication, or disclosure
--   restricted by GSA ADP Schedule Contract with IBM Corp.
--
--------------------------------------------------------------------------------


Project Smarts - Direct-to-SOM (DTS) application README
_______________________________________________________


TARGET(S):
_________

<if ($BUILD_DLL_AND_EXE$)>
The layout of this project is as shown below:

  +-----------------------------------------------------+
  |          Direct-to-SOM Application                  |
  |   (Builds an executable client program that         |
  |      uses objects in the DTS DLL project.)          |
  |                                                     |
  |                                                     |
  |         +----------------------------------+        |
  |         |         DTS DLL Project          |        |
  |         |  (Builds the DLL that contains   |        |
  |         |        your DTS classes.)        |        |
  |         +----------------------------------+        |
  |                                                     |
  +-----------------------------------------------------+
</if>

This project builds:

[1] A $DLL_NAME$.dll dynamic link library.
<if ($BUILD_DLL_AND_EXE$)>
[2] A main $EXE_NAME$.EXE executable program.
</if>


ABOUT THIS APPLICATION:
_______________________


DTS Project Smarts has constructed a skeletal framework for $DLL_NAME$.dll,
a DLL consisting of DTS C++ classes based on the information you
provided to DTS Project Smarts.  $DLL_NAME$.dll encorporates the DTS
C++ classes specified on the "DTS Classes" page of DTS Project Smarts.

For each DTS class included in the DLL, a corresponding '.hh' class definition
file and '.cpp' implementation file has been generated.  These files are
named after the class they contain but in certain instances the file names
may be shortened.  For example, if the class name is greater than 8
characters and the 'use long files names' options on page "DTS Classes" of
DTS Project Smarts has not been selected, or if the file resides on a FAT
file system.


CUSTOMIZING YOUR DLL:
____________________


In order for $DLL_NAME$.dll to be of any use, you will need to flesh out
the body of each DTS C++ class and file.  To do this, follow the three
easy steps listed below:


[1]  Edit the '.hh' file corresponding to a DTS C++ class and fill in the
     class definition by adding any types, data members, member functions
     and SOM pragmas you require.  You may also add C++ code outside the
     class such as global types, data or functions.

[2]  For the same class, edit the associated '.cpp' file and add any
     definitions required to complete the class, such as definitions for
     member functions or static member data.

[3]  Repeat the above steps [1]-[2] for each DTS C++ class included in
     $DLL_NAME$.dll.


An initialization function for the class library must be provided to support
dynamic loading of the library by the SOM Class Manager.  The name of this
function is SOMInitModule and it is located in file SOMINIT.CPP.  By default
function SOMinitModule creates a single instance of each DTS C++ class'
class object.  You may edit this file and customize the initialization
function as desired.


*NOTE*
______

   o If you are not sure of any C++ coding restrictions imposed on a DTS
     C++ class, please refer to VisualAge for C++'s User's Guide.

   o If you require any information on the SOM Toolkit or SOM API calls
     refer to the SOM Toolkit Users Guide and/or SOM Toolkit Programmers
     Reference Manual.


LOCATION, LOCATION, LOCATION:
____________________________


If you opted to create just a DTS C++ DLL, then all the '.hh' and '.cpp'
skeleton files, along with SOMINIT.CPP reside in the same sub-directory
as this README.  Within WorkFrame, you may edit these files by
double-clicking on their names.

If you opted to create a DLL and EXE file, then the '.hh' and '.cpp'
skeleton files for the DLL, along with SOMINIT.CPP reside in a child
sub-directory, named DTSDLL, of the directory in which this README resides.
To edit these files, open up the sub-project for $DLL_NAME$.dll by
double-clicking on $DLL_NAME$.iwp.  Then, within WorkFrame, double-click
on each file you wish to edit.


BUILDING YOUR DLL:
_________________


Once customization of each class and the initialization function is complete,
build $DLL_NAME$.dll by selecting "Build Normal" in the "Project" menu
located at the top left of $DLL_NAME$.dll's project window.

If you decide to enhance your DLL by adding files not created by DTS Project
Smarts to your DLL, you may need to use the MakeMake or other options within
WorkFrame to build your project. In this case, please refer to WorkFrame's
Users Guide in order to build your project correctly.


<if ($BUILD_DLL_AND_EXE$)>
CUSTOMIZING .EXE FILE:
_____________________

DTS Project Smarts has also created a skeleton $EXE_NAME$.cpp for you.
The file resides in the same directory as this README, and currently
includes each DTS C++ class you specified on page "DTS Classes" and provides
a hollow function 'main'.  Edit $EXE_NAME$.cpp and customize it to
instantiate and exploit the DTS C++ classes you have just designed.

To build both $EXE_NAME$.exe and $DLL_NAME$.dll, select "Build Normal"
in the "Project" pull-down menu located at the top left of $EXE_NAME$.exe's
project window.

</if>

<if ($DSOM$)>
Distributed-SOM (DSOM):
______________________


The class(es) included in $DLL_NAME$.dll are DSOM enabled.

There are two noteable differences between a SOM and DSOM enabled
DTS C++ project generated by Project Smarts.

[1] Pragma SOMIDLPass is added at the bottom of every class definition
    file.  Pragma SOMIDLPass provides the necessary information for DSOM
    servers to locate each class's DLL when when they consult the Interface
    Repository.

[2] DSOMREG.MAK is created to register your DTS C++ class's IDL interfaces
    into the Interface Repository "$SOM_IR_FILE$", and to register
    "$SOM_SERVER$"s implemenatation and it's associated classes with the
    Implementation Repository.



BUILDING A DSOM PROJECT:
________________________


Build your DSOM project in the same manner as you would a regular DTS C++
project by following the steps listed in each prior section.  Once your
DLL and/or EXE builds cleanly you may then register your classes and
DSOM server.  This last step is completed by running "DSOM registration"
from the project menu, or IDSOMREG from the command line.



*NOTE*
______


You must ensure your environment is set up correctly to build and run a
DSOM project.  Refer to the SOM Toolkit Users Guide if you are not sure
what environment settings are required.
</if>
