"@(#)35     1.7  src/examples/Readme, examples.src, os2dce21.dss, 960602a.1  5/29/96  15:33:45"

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
COMPONENT_NAME:  examples.src

FUNCTIONS: Instructions for building the DCE examples from the HPFS toolkit

ORIGINS: 27

(C) COPYRIGHT International Business Machines Corp. 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.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


1.  CONTENTS OF THE DCE HPFS EXAMPLES

    : Source code and IDL for DCE sample applications
    : Makefiles [one per tested compiler] for each sample
    : Utility files used by the makefiles [dce_dirs, dce_dirs.wat]
    : OS/2 command files to build samples [all.cmd, one.cmd]
    : Instructions and setup scripts (readme files) for executing the samples

    : The following DCE sample applications are provided:

       1. acl manager        --->  opt\dcelocal\examples\acl_mgr
       2. bank               --->  opt\dcelocal\examples\bank
       3. context_app        --->  opt\dcelocal\examples\demo\context_app
       4. data_test_app      --->  opt\dcelocal\examples\demo\data_test_app
       5. sample             --->  opt\dcelocal\examples\demo\generic_app
       6. ems                --->  opt\dcelocal\examples\ems
       7. greet (4)          --->  opt\dcelocal\examples\pubs\greet
       8. binop              --->  opt\dcelocal\examples\pubs\binop
       9. dts sample         --->  opt\dcelocal\examples\pubs\dtssamp
      10. prime              --->  opt\dcelocal\examples\pubs\prime
      11. string-tree        --->  opt\dcelocal\examples\pubs\strtree
      12. password strength  --->  opt\dcelocal\examples\pwdstren
      13. hello_svc          --->  opt\dcelocal\examples\svc\hello_svc
      14. timop_svc          --->  opt\dcelocal\examples\svc\timop_svc
      15. timop              --->  opt\dcelocal\examples\timop
      16. type manager       --->  opt\dcelocal\examples\type_mgr
      17. xds/xom  [5]       --->  opt\dcelocal\examples\xdsxom


    * Note - in order to successfully build the examples, the following
      DCE Toolkit options are needed:
        : DCE header files and DCE import library
        : DCE application-building tools [IDL compiler, SAMS compiler, etc.]


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


2.  TESTED TOOLS -- VENDORS

    2.1 IBM OS/2 Socket/MultiProtocol Transport Services Programmer's toolkit [WR08200]

    2.2 IBM OS/2 tools
        : NMAKE [version 2.001.001]
        : RC [version 2.02.001]

    2.3 IBM WARP toolkit for OS/2 [XR03000]

    2.4 IBM CSet++ 2.01 tools
        : compiler [CT00012]
        : utilities [CT00003]
        : libraries [CT00010]
        : LINK386 [version 3.00.000]

    2.5 IBM Visual Age C++ 3.0 tools
        : compiler [CTC301]
        : class libraries [CTO302]
        : ILINK [version 01.02.03]

    2.6 Borland C++ for OS/2 2.0

    2.7 Watcom C/C++ 10.5 [A-level patch]
        Note: we do not support Watcom C/C++ 10.6


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


3.  TOOLSETS

    3.1 Required tools
        : IBM OS/2 Socket/MultiProtocol Transport Services Programmer's toolkit
        : IBM OS/2 resource compiler [RC]
        : C/C++ compiler and Make utility
        : a programmer's toolkit for WARP

    3.2 Tested compiler/toolkit combinations
        : IBM CSet++ 2.01 + IBM WARP toolkit
        : IBM Visual Age 3.00 + IBM WARP toolkit [included]
        : Borland C++ 2.0 [w/ programmer's toolkit for OS/2]
        : Watcom C++ 10.5 [w/ programmer's toolkit for OS/2]


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


4.  REQUIRED END-USER CONFIGURATION

    4.1 ALL.CMD -and- ONE.CMD
        ALL is a script to compile all of the DCE examples. ONE is used to build
        an individual example. Please define the following variables:

        4.1.1 Define the root directory where the DCE examples were installed.  The
              default directory is c:\opt\dcelocal\examples. ALL and ONE are installed
              files are located in the STEM directory.
              : set STEM=c:\opt\dcelocal\examples


        4.1.2 Configure the partitions where the development tools are installed.  By
              default all tools are assumed to be installed on 'c'.  Values assigned
              to these environmental variables are passed to the MAKE utility and are
              expanded as the macros  $(T), $(X) and $(Y) in DCE_DIRS.*.
              : set COMPILER=c
              : set DCE=c
              : set TCPIP=c
              : set TOOLKIT=c

        4.1.3 Remove the block of '@rem ' phrases to select the installed compiler if it
              is not 'visualage30'[IBM Visual Age 3.00] and '@rem ' the Visual Age lines.
              : @rem set CNAM=visualage30
              : @rem set INCLUDE=%STEM%;%INCLUDE%
              : @rem set INC=
              : @rem set MK=nmake
              : @rem set DF=
              : @rem set MAKE-EXT=vc3
              : @
              : set CNAM=cset20_201
              : set INCLUDE=%STEM%;%INCLUDE%
              : set INC=
              : set MK=nmake
              : set DF=
              : set MAKE-EXT=os2


    4.2 DCE_DIRS -or- DCE_DIRS.WAT
        These files contain macros that are used in the makefiles supplied with the
        DCE examples.  They are installed in the directory named in 'set STEM='.
        DCE_DIRS contains information for the IBM C++ and Borland C++ compilers,
        while DCE_DIRS.WAT is included by the Watcom C++ makefiles.

        4.2.1 Modify the path macros pointing to the compiler and toolkit installation
              directories.  In this example IBM Visual Age C++ was installed in the
              in the default directory \IBMCPP.  Be careful to avoid conflicts with
              the IBM CSet++ 2.01 compiler if it is installed on the same machine.
              Use of the WARP toolkit included with Visual Age is assumed.
              : #Compiler dependencies
              : !if ("$(C) " == "visualage30")
              : IBMC_inc    = $(Y):\ibmcpp\include;$(Y):\ibmcpp\include\sys
              : IBMC_lib    = $(Y):\ibmcpp\lib
              : toolkit_h   = $(Y):\ibmcpp\include\os2
              : toolkit_lib = $(Y):\ibmcpp\lib
              : !endif

        4.2.2 Modify the path macros pointing to the MPTN [or TCPIP] toolkit.
              : MPTN_inc    = $(T):\mptn\include
              : MPTN_lib    = $(T):\mptn\lib

        4.2.3 Modify the default name(s) to match the EMS server(s) in the target cell.
              Modify the PFLAGS macro if more than 1 EMS server is available.
              : # EMS example DNS-style server host names
              : host1   = "\"/.:/hosts/machine1.domain.org\""
              : host2   = "\"/.:/hosts/machine2.domain.org\""

              : #EMS example -- uncomment one of the following selections
              : #PFLAGS = -D_TWOHOSTS      # two hosts running emsd with one consumer
              : PFLAGS  =                  # one host  running emsd with one consumer


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


5.  COMMAND FILE USAGE

    5.1 General

        all [option]  -OR-  one <example> [option]

            where [option] is
                clean    = delete objects, stubs and IDL/SAMS compiler output
                rmtarget = delete executables and maps
                clobber  = delete objects, stubs, etc. and executables

            and <example> = subdirectory containing the sample application

    5.2 Examples
        : 'all' [build all of the example applications]
        : 'all clobber' [delete all compiler-generated output and executables]
        : 'one xdsxom rmtarget' [delete executables and maps in the XDSXOM example]
        : 'one bank\pm clean' [delete only the compiler output in the BANK example]


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


6.  NOTES

    6.1 Restrictions
        : The DCE examples must be installed on an HPFS partition.
        : DCE_DIRS.* must be located in the directory named as 'set STEM='.

        6.1.1 Watcom C/C++ 10.5
              : Some examples compiled with Watcom 10.5 are NOT aligned on a 4-byte
                boundary if /ot compile option is removed.
              : Release 10.5 of the C/C++ compilers restricts the maximum depth for
                include file nesting as a function of the maximum file handles allowed
                in the parent process.  The default value of 20 may not be large enough
                for your applications to be compiled from the OS/2 command line.
                To work-around this file handle problem with the compiler, you may
                need to increase your session's file handles. The api DosSetRelMaxFh
                call can be used to increase your session's file handles.
              : When building the type_mgr examples:
                The file TYPES.H in the MPTN and TCPIP programmer's toolkits includes
                both ERRNO.H and NERRNO.H.  This results in a fatal redefinition error
                when used with the Watcom OS/2 programmer's toolkit.  The following
                patch should be made to TYPES.H between the #includes.
                      #include <errno.h>
                      #ifdef ENAMETOOLONG      <------
                      #undef ENAMETOOLONG      <------
                      #endif                   <------
                      #ifdef ENOTEMPTY         <------
                      #undef ENOTEMPTY         <------
                      #endif                   <------
                      #include <nerrno.h>



        6.1.2 Watcom C/C++ 10.6
              : We do not support Release 10.6 of Watcom C++ [WPP386]


        6.1.3 Borland C++ 2.0
              : The Borland compiler does not expand the # operator in macros in the
                same manner as the IBM and Watcom C++ compilers.  There is considerable
                conditional compilation required to support the Borland compiler in the
                DCE xds*.h header files used by the XDSXOM example.


    6.2 Tips
        : Output from build operations can be saved by redirecting the output
          to a separate list file [ex. all > junk.list].
        : Since the Watcom MAKE utility only supports the building of "real" targets
          the error messages genreated by specifying the pseudo-targets 'clean',
          'clobber' and 'rmtarget' can be safely ignored.

    6.3 Adding support for additional compilers
        : Add the required compiler support block to the ALL and ONE command files.
              : set CNAM="compiler name string"
              : set INCLUDE=%STEM%;%INCLUDE%
              : set INC=
              : set MK="MAKE utility name"
              : set DF="MAKE define option if not -D"
              : set MAKE-EXT="makefile extension"

        : Add the required compiler/support block to DCE_DIRS
              : !if ("$(C) " == "compiler name string")
              : IBMC_inc    = $(Y):\path\include;$(Y):\path\include\sys
              : IBMC_lib    = $(Y):\path\lib
              : toolkit_h   = $(Y):\path\os2-include-dir
              : toolkit_lib = $(Y):\path\os2-lib-dir
                      etc.  ...
              : !endif

        : Create additional makefiles having the MAKE-EXT extension.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

7.  COMPILER & LINKER OPTIONS

    7.1 Common Flags
        : DSSFLAGS     = /DINTEL80x86 /DIBMOS2
        : IDLFLAGS     = -v -keep c_source -no_cpp
        : NO_EPV_IDL   = -no_mepv $(IDLFLAGS)
        : EPV_IDL      = $(IDLFLAGS)


    7.2 Compile options
                            CSet ++       Visual Age         Watcom          Borland
                         -------------   -------------   --------------   -------------
: IDL preprocessor       no_cpp          no_cpp          no_cpp (req'd)   no_cpp (req'd)
: Debug                  Ti+             Ti+             d2  hw           v
: Warnings               W3              W3              w3               w
: C-lang. extensions     Se              Se              ze               A-
: Floating point         Gf-             Gf-             fpi              ff
: Multi-thread           Gm+             Gm+             bm               sm
: DLL run-time init                                      bd
: Structure packing      Sp4             Sp4             zp4              a4
: Enum size (32-bit)     Su4             Su4             ei               b
: Default signed char    J+              J+              j                K+
: Optimization(off/time) O-              O-              ot               Od
: 386|stack|C-calls      G3  Ms          G3  Ms          3s  mf  sg       pc  r+
: No // comments         Ss-             Ss-
: Compile w/o link       C+              C+                               c
: Produce EXE            Ge              Ge
: Quiet operation        Q+              Q+              zq
: Disable C++ exceptions                                 xd


    7.3 Linker options
: Debug                  DE  L           DE  L           DEBUG WATCOM     v
: Create map file        MAP             MAP             MAP              m  s
: VIO executable file    PM:VIO          PM:VIO          SYSTEM os2v2     Toe  ap
: PM executable file     PM:PM           PM:PM           SYSTEM os2v2_pm  Toe  aa
: Dynamic link library   PM:VIO          PM:VIO          SYSTEM os2v2 dll Toe  ap
: Case sensitivity       NOI             NOI             CASEEXACT        (default)
: Default lib search     NOD             DEF                              n
: Extended library       NOE             NOE
: Exepack {Code, Data}   EXEPACK         EXEPACK:2
: Base of 1st segment    BASE:0x10000    BASE:0x10000    OFFSET=0x10000   B:0x10000
: Alignment {page}       A:512           A:512           ALIGNMENT=9      A:9
: Data segments          DATA MULTIPLE   DATA MULTIPLE   MANYAUTODATA     DATA MULTIPLE
: DLL run-time data                                      INITINSTANCE
: Heap size              HEAPSIZE        HEAPSIZE        HEAPSIZE         HEAPSIZE
: Stack size             STACKSIZE       STACK           STACK            STACKSIZE
: Quiet operation        NOL             NOL


    7.4 Libraries
:                        os2386          os2386          os2386           os2
:                        dceos2          dceos2          dceos2           dceos2
:                        dde4mbs           --              --             c2mt

