==================================================================

   Read Me File for IBM* VisualAge* C++ for OS/2* Intel to OS/2 Warp
   (PowerPC* Edition) Cross Compiler on the Developer Connection for
   OS/2 CD-ROM Volume 9 Special Edition

   Note: VisualAge C++ was formerly called C Set ++*.

   (C) Copyright IBM Corp. 1995. All Rights Reserved.
   US Government Users Restricted Rights - Use, duplication or
   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

==================================================================

This file contains important information about the cross compiler
for OS/2 Intel to OS/2* Warp PowerPC Edition (PPC).  Please read
this file before you continue with the installation.

==================================================================

CONTENTS:
________

   * INTRODUCTION
   * PREREQUISITES

   * INSTALLATION
   * SUPPORT

   * FEATURES AND RESTRICTIONS
   * DOCUMENTATION

   * TRADEMARKS
   * YOUR FEEDBACK

INTRODUCTION:
____________

This driver contains:

    * C/C++ cross-compiler for OS/2 Intel to OS/2 Warp PPC and tools
    * Runtime libraries for C++
    * Documentation in .INF format

PREREQUISITES:
_____________

The prerequisites are:

- An OS/2 Intel system to run the compiler with:

    - Approximately 50 megabytes of free disk space

    - IBM Developer's Toolkit for OS/2 Warp (PowerPC Edition)
      - The Toolkit includes:
        - Debugger
        - C headers, and static and import libraries

- An OS/2 Power PC system with:

    - OS/2 Warp (PowerPC Edition)

    - Approximately 1 megabyte of free disk space

Note: Space estimates do not include space required by your program
      source files, objects, and executables.

To build applications, you need the following space on your Intel machine:

- 8 MB of RAM for C applications, 16 MB for C++
- 24 MB of swap space

CO-REQUISITES:
_____________

To link, you need the MetaWare** linker Version 3.54 or later, which is
part of the High C/C++** Compiler from MetaWare Incorporated.  You
install the linker from the Developer Connection for OS/2 CD.

INSTALLATION:
____________

IMPORTANT: If you install this code on a system that has a version of
           VisualAge C++ for OS/2 installed, see the section about
           co-existence.

A. Install the components on your Intel machine by doing these steps:

   1. Install the components from the Developer Connnection for OS/2 CD.

      The components are:

      - IBM Developer's Toolkit for OS/2 Warp (PowerPC Edition),
        which includes the remote debugger.

      - MetaWare Inc: MetaWare High C/C++ Cross Compiler, which contains
        the linker

      - IBM VisualAge C++ Cross Compiler for OS/2 Warp (PowerPC
        Edition)

    2. Reboot your machine

    3. Select the VisualAge C++ PPC Beta folder and then select the
       C/C++ Window to set the environment variables.

B. Copy the DLL files from Intel to PPC by doing the following steps.

1. On your Intel machine, copy the DLLs to a diskette.

  a. Format a diskette on an OS/2 system and create a directory called
     DLL on the diskette.

  b. Put the diskette into the drive of your Intel machine.

  c. Copy the files to the diskette.  %DRIVE% is the drive and path
     where you installed the files.

     For example, to copy all the C++ DLLs:

        copy %DRIVE%\VAPPC\PPC\DLL\CPPP* a:\

     For example, to copy the C++ Demangler DLL:

        copy %DRIVE%\VAPPC\PPC\DLL\DEMANGL.DLL A:\

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

   The following DLLs have been installed on your Intel machine.

   C++ Demangler: VAPPC\PPC\DLL\DEMANGL.DLL

   C++ DLLs:      VAPPC\PPC\DLL\CPPPS31.DLL
                  VAPPC\PPC\DLL\CPPPM31.DLL
                  VAPPC\PPC\DLL\CPPPN31.DLL

   The file names use the VisualAge C++ naming conventions:

   Characters  Value and Meaning
   ----------  -----------------
   1 to 3      CPP
   4           P for PPC
   5           S single thread, M multi thread, N subsystem
   6 to 7      31 for version number.  It will change in the future.

   - If you compile and link with a static runtime, for example using
     option /Gd-, you do not need the DLLs.

   - If you link dynamically, for example using option /Gd+, the DLLs you
     need depend on the other options you use.

   - The compiler defaults are /Gd- /Gm- /Re.

   Options                                         C++ DLLs Needed
   ----------------------------------------------  ---------------
   /Gm- (single-threaded) /Re (full runtime)       CPPPS31.DLL
   /Gm+ (multi-threaded)  /Re (full runtime)       CPPPM31.DLL
   /Gm- (single-threaded) /Rn (subsystem runtime)  CPPPN31.DLL

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

2. Copy the files from the diskette to your PPC machine.

   a. Remove the diskette and insert it into the drive on your PPC
      machine.

   b. On your PPC, run the following commands.  %DRIVE% is the drive and
      path where you installed the files.

         MKDIR %DRIVE%\VAPPC\PPC\DLL
         COPY A:\DLL %DRIVE%\VAPPC\PPC\DLL

   c. Edit C:\CONFIG.SYS on your PPC.

      Add C:\IBMCPP\DLL; to the end of the LIBPATH value.

3. Reboot the PPC so that the CONFIG.SYS changes take effect.

Co-existence with the VisualAge C++ Compiler
--------------------------------------------

It is possible to have both the VisualAge C++ compiler for OS/2 Intel
and the PPC compiler running at the same time, but they cannot
both be started from the same OS/2 session.  This is because the
same names are used for environment variables (INCLUDE, LIB,
and ICC), and for programs.

By running the SETENVS.CMD script, you can switch from the
Intel compiler to the PPC compiler.  To go back to the Intel
compiler, you need to undo all the environment variable changes.
You should start a new OS/2 session if you want to return to
compiling for the Intel processor.

You need to do the following steps on your Intel machine:

1. Edit CONFIG.SYS

   a. Delete the changes made by the installation of the Developer's
      Toolkit.  Toolkit path names are added to the beginning of the
      environment variables listed below.

      - BEGINLIBPATH

      - PATH
      - LIB
      - INCLUDE

      - SMINCLUDE
      - SOMRUNTIME
      - SOMBASE

      Here is an example of the INCLUDE environment variable.  To keep
      the example simple, it shows only the value previously added
      by the VisualAge C++ compiler for OS/2 Intel and the value added
      by the Toolkit.

      C:\PPCTLKT is the default drive and path where the Developer's
      Toolkit is installed.

         set INCLUDE=C:\PPCTLKT\TOOLKIT\H;C:\IBMCPP\TOOLKIT\H

      Delete the added value, which is C:\PPCTLKT\TOOLKIT\H;

      The resulting environment variable is:

         set INCLUDE=C:\IBMCPP\TOOLKIT\H

   b. Add a line at the bottom of the CONFIG.SYS file to define the
      environment variable PPCSDKTOP to the drive and path where you
      installed the Toolkit.

      For example:

         set PPCSDKTOP=M:\BETA

2. Reboot your system.

3. Select the VisualAge C++ PPC Beta folder and then select the
   C/C++ Window to set the environment variables.

   Alternatively, you can run the SETENVS.CND script from any OS/2
   session.  By default, the script is in the VAPPC\BIN path.

SUPPORT:
_______

Limited technical support is provided on a best-effort
basis by the Visual Age C++ Service and Support team through:

- Talklink or IBMLink   CPPCBETA CFORUM
  or EMEA DAP:

- Compuserve:           CSET++ Power Beta in the PSPBETA area

- Internet:             cppcbeta@vnet.ibm.com

If you have comments or suggestions, please send them to us.

FEATURES AND RESTRICTIONS:
_________________________


This section contains:

- C RUNTIME LIBRARY
  - Functions now shipped in operating system or Toolkit
  - XPG4 Now Provides Support for POSIX Locales
  - Restrictions

- COMPILER
  - Features
  - Restrictions

C RUNTIME LIBRARY
=================

Functions Now Shipped With the Operating System or Toolkit
----------------------------------------------------------

The library functions and documentation that were previously shipped
with the VisualAge C++ Cross compiler are now shipped as part of the
operating system or the Toolkit.

XPG4 Now Provides Support for POSIX Locales
-------------------------------------------

XPG4 functions replace the POSIX functions.  The following collating
functions for POSIX support do not have equivalent XPG4 functions and
they do not exist.

  - cclass
  - collequiv
  - collorder
  - collrange
  - colltostr
  - getmccoll
  - getwmccoll
  - ismccollel
  - maxcoll
  - strtocoll

Restrictions
------------

   The least significant digits of a long double value do not
   print correctly, for example in a printf statement.

COMPILER
========

FEATURES
--------

This section identifies the objects, libraries, and options
that are used to link in the Version 3 C runtime libraries.

We recommend that you use icc and the default libraries to link, and
then you can ignore this section.  If you do not use icc and the
default libraries to link, read this section.

C Runtime Files
---------------

 DESCRIPTION   STATIC   DLL       IMPORT     ---- STARTUP OBJECTS ------
               LIBS     LIBS      LIBS       EXE     DLL with  DLL with
                                                     STATIC    DYNAMIC
                                                     LINK      LINK
 -----------   -------- --------  --------   ------- --------- ---------

 Single-thread LIBC.A   LIBC.DLL  LIBCI.LIB  LIBC.O  LIBCL.O   LIBCLI.O
 Multi-thread  LIBCM.A  LIBCM.DLL LIBCMI.LIB LIBCM.O LIBCML.O  LIBCMLI.O
 Subsystem     LIBCS.A  LIBCS.DLL LIBCSI.LIB LIBCS.O LIBCSL.O  LIBCSLI.O


 Other Objects
 -------------
 CRT1_LE.O  - Needed for creating user DLLs.  Provided by the
              Developer's Toolkit.

 System libraries
 ----------------
  - LIBOS2.LIB

 Using SOM
 ---------
  - If you use SOM routines, you need to link in the LIBSOMTK.A library.
    Using VisualAge C++ for OS/2 you did not have to link in the SOM
    library yourself.

 SAMPLE FILES
 ------------

 Here are some sample files:

 Linker Definition File
 ----------------------
 NAME "test" WINDOWCOMPAT
 CODE MOVEABLE
 DATA MOVEABLE MULTIPLE
 HEAPSIZE 32000
 STACKSIZE 16384

 Linker Response Files
 ---------------------

 The following are samples of response files for different types
 of linking.

 Dynamic Link to Runtime - File called TEST.LNK
 ----------------------------------------------
  -dy -Bsymbolic -Brogotplt -Bpic -zdefs -Bdynamic
  -i TEST.DEF
  PPCTLKT\PPC\LIB\LIBC.O
  TEST.O
  PPCTLKT\PPC\LIB\LIBCI.LIB
  PPCTLKT\PPC\LIB\LIBOS2.LIB
  -o TEST.EXE

 Static Link to Runtime - File called TEST.LNK
 ----------------------------------------------
  -dy -Bsymbolic -Brogotplt -Bpic -zdefs -Bstatic
  -i TEST.DEF
  PPCTLKT\PPC\LIB\LIBC.O
  TEST.O
  PPCTLKT\PPC\LIB\LIBC.LIB
  PPCTLKT\PPC\LIB\LIBOS2.LIB
  -o TEST.EXE

 Static Link of User DLL to Runtime - File called TEST.LNK
 ---------------------------------------------------------
  -dy -Bsymbolic -Brogotplt -Bpic -zdefs -Bstatic
  -i TESTDLL.DEF
  PPCTLKT\PPC\LIB\LIBCL.O
  TEST.O
  PPCTLKT\PPC\LIB\LIBC.LIB
  PPCTLKT\PPC\LIB\LIBOS2.LIB
  -o TESTDLL.DLL

  Example of TESTDLL.DEF
  ----------------------
  LIBRARY TESTDLL INITINSTANCE TERMINSTANCE
  PROTMODE
  DATA MULTIPLE NONSHARED READWRITE LOADONCALL
  CODE LOADONCALL
  EXPORTS
     testfunction

 Example
 -------

 LDPPC.EXE @TEST.LNK

 where LDPPC.EXE is the name of the MetaWare linker.

COMPILER RESTRICTIONS
---------------------

1. Compile With OPT May Be Unsafe

   Programs compiled using /O or /O+ may not run correctly because
   of a defect in OS/2 Warp for PPC.  Non-volatile condition registers
   may be corrupted by file I/O calls.

   Most programs can avoid this problem by using the option
   "-qxflag=nbool" when compiling.  This disables most attempts
   to use the non-volatile condition registers.

2. #pragma Directives and Keywords

  - The following #pragma directives are accepted, but they have no
    effect because of linker limitations:

    import, export, entry, library

  - The following pragmas and keywords are ignored:

    - __loadds (C only, it was never accepted with C++)

    - seg16

    - stack16

    - The 16-bit and Pascal linkage keywords

      _Far16 _Cdecl
      _Far16 _Fastcall
      _Far16 _Pascal
      _Far32 _Pascal (C only, it was never accepted with C++)
      _Pascal (same as _Far32 _Pascal)
      _Far16 (same as _Far16 _Cdecl)

    - pragma linkage - with the following keywords:
      _Far16 _Cdecl
      _Far16 _Fastcall
      _Far16 _Pascal
      _Far32 _Pascal
      _Pascal
      _Far16

3. Using DSOM

  - Workgroup DSOM is not supported.

  - DTS with DSOM is not working at this time.

DOCUMENTATION:
_____________

  The documents provided are:

    CPPPLNF.INF     C/C++ Language Reference

    CPPPPRG.INF     Programming Guide (C/C++ programming techniques)

    CPPPUG.INF      User's Guide (compiler options)

  The .INF files are installed in \VAPPC\HELP.

  You can view these .INF files online using the view command.
  For example, to view the .INF file for the User's Guide, enter
  the following command:

    VIEW CPPPUG.INF

  The C runtime library functions are documented in the file called
  XPG4REF.INF in the BOOK directory of the Toolkit.  Select the icon
  called OS/2 Warp (PowerPC Edition) C Library Reference.

  For information about linking your program, refer to the MetaWare
  Programmer's Guide for details.

TRADEMARKS AND SERVICE MARKS
____________________________

The following items are trademarks of the IBM Corporation.

    C Set ++
    IBM
    OS/2
    PowerPC
    VisualAge

Other terms used in this Read Me, which may be denoted by a double
asterisk(**), are trademarks or service marks of others.

    High C/C++ is a trademark of MetaWare Incorporated.
    MetaWare is a registered trademark of MetaWare Incorporated.

YOUR FEEDBACK
_____________

We appreciate your comments and suggestions.  Please send them to us
using the channels listed in the Support section.
