________________________________________________________________

IBM DEVELOPER'S TOOLKIT FOR OS/2 WARP, VERSION 3 README FILE
________________________________________________________________

Welcome to the IBM* Developer's Toolkit for OS/2* Warp, Version 3 (Toolkit).
In addition to this README file, the book--"Using Your Toolkit"--is included
to help you:

   -  See what is new and what has changed in the Toolkit
   -  Become familiar with the Toolkit
   -  Access information about the Toolkit more easily and quickly

This READ.ME file is a supplement to that book and provides information
about Toolkit installation.  Use a non-proportional font to view this file.
This README file contains:

   1. Introduction to the Toolkit
   2. Installing the Toolkit
   3. Updates to CONFIG.SYS
   4. Known limitations and restrictions


INTRODUCTION TO THE TOOLKIT
________________________________________________________________

The Toolkit is a collection of sample application programs, programming tools,
library files, header files, and online documents that help you develop
applications for OS/2.  The Toolkit can be installed from CD-ROM or from
diskettes created from diskette images on the CD-ROM.


INSTALLING THE TOOLKIT
________________________________________________________________

This section provides a step-by-step procedure for installing the Toolkit.


System Requirements
________________________________________________________________

You can install the Toolkit for OS/2 Warp, Version 3 on any of the 
following systems:

   -  OS/2 2.1
   -  OS/2 2.11
   -  OS/2 Warp, Version 3
   -  OS/2 Warp with WIN-OS/2, Version 3
   -  OS/2 Warp Connect
   -  OS/2 Warp Connect with WIN-OS/2

The IBM Developer API Extensions for OS/2 Beta which can be found on this 
version of The Developer Connection can be installed on the 4 versions of 
OS/2 Warp listed above. However, The FixPak Beta, which can also be found 
on this version of the Developer Connection must first be installed.

Only the functions available in the operating system you have installed
will be available in the Toolkit.

Before you install the Toolkit, make sure you have:

   -  A personal computer that has an Intel386** (or higher) 
      microprocessor with the OS/2 operating system installed

   -  A minimum of 4MB of memory (8MB or more is recommended)

   -  A high capacity 3.5-inch diskette drive or CD-ROM drive

   -  A hard disk drive with 80MB of free disk space 
      (to install the entire Toolkit)

We recommend that you install a mouse.


Installation Program
________________________________________________________________

You install the Toolkit through a Presentation Manager/2* application:  the
Toolkit Installation Program.  This program is available through the CD-ROM
or through diskettes made from diskette images on the CD-ROM. Through the
Toolkit Installation Program, you can install:

   -  Development tools
   -  Headers and libraries
   -  Toolkit information
   -  Sample programs

You can install the entire Toolkit or selected components of the Toolkit
through the Toolkit Installation Program.  By default, the Toolkit
installation will copy chosen files to your machine and update 
CONFIG.SYS with respect to the locally installed files.


Installation Help
________________________________________________________________

When installing the Toolkit, to get online help for installation, do one
of the following:

   -  Press the F1 key
   -  Select the Help push button
   -  Choose one of the help choices from the Help menu


Installing from Diskette Images
________________________________________________________________

You can install the Toolkit from the CD-ROM or from diskettes made from
diskette images on the CD-ROM. To install from CD-ROM, go to the next
section "Installing the Toolkit." 

You can create diskettes using The Developer Connection for OS/2 
Catalog program as follows:

   1. Open The Developer Connection folder on your desktop.

   2. Open The Developer Connection for OS/2 folder from The Developer
      Connection folder.

   3. Open The Developer Connection Catalog program from The Developer
      Connection for OS/2 folder.

   4. Find the product entitled:

         IBM: The Developer's Toolkit for OS/2 Warp, Version 3: 3.5" Diskettes

      Note:  This product is located in the Developer Toolkits category.

   5. Start the diskette creation process by selecting the "Install product"
      pop-up menu item.  By default, all diskettes will be created.

   6. Select the "Proceed" button to start the diskette creation, and
      follow the instructions presented.

If you prefer to create the diskettes without using The Developer
Connection for OS/2 Catalog program, you create the diskettes as 
follows:

   1. Start an OS/2 Window or OS/2 Full Screen session.

   2. Change to the following directory on the compact disk drive:

         TOOLKITS\WARPTLKT\IMAGES

   3. Insert a blank diskette in drive A.  At the command prompt, type:

         LOADDSKF TK03401.IMG  A:/f

      This will create diskette one.

   4. Repeat step 3 for TK03402.IMG through TK03424.IMG.

   5. Once you have made all the diskettes, follow the steps in the next
      section "Installing the Toolkit."


Installing the Toolkit
________________________________________________________________

To install the Toolkit, do the following:

   1. Start the Toolkit Installation Program from the CD-ROM or diskettes
      as follows:

      -  CD-ROM: 
         From The Developer Connection for OS/2 Catalog, find
         the product entitled:

            IBM: The Developer's Toolkit for OS/2 Warp, Version 3: CD Install
 
         Note:  This product is located in the Developer Toolkits
         category.  Install the product by selecting the "Install product" 
         pop-up menu item.  This action will bring up the Toolkit 
         Installation program.

         If you prefer to install the Toolkit without using
         The Developer Connection for OS/2 Catalog, start an OS/2 Window
         or OS/2 Full Screen session.  Put the CD-ROM containing the
         Toolkit in the CD-ROM drive and change directories as follows:

            CD TOOLKITS\WARPTLKT

         Type the following and press Enter:

            TKINSTAL

      -  DISKETTES: 
         Put the first diskette into the a: drive (or other drive)
         and type the following:

            a:\TKINSTAL

   2. The system displays the "IBM Developer's Toolkit for OS/2 Warp
      Installation" window.  Select each component you want to install.
      Depending on the components you select for installation, additional
      components might be automatically selected for installation.
      A plus (+) sign in a box in front of a component indicates that
      the component has at least one level of subcomponents from which
      you can select.  Select the plus sign in front of the component to
      expand the list of components.

      Note:  The IBM Developer API Extensions for OS/2 Beta are not
      preselected by default.  To install this Beta, expand the BETA
      component and select the "Beta Developer API Extensions Support" 
      component.

   3. If desired, change the default destination for the selected 
      components by editing the "Destination" entry field.

   4. Select the "Options" push button to specify what updates to your
      system are required.  You can choose to:

         -  Install the selected files
         -  Register Workplace Shell* classes
         -  Create Workplace Shell objects
         -  Select the file where any CONFIG.SYS updates are to be made,
            or deselect the "Write CONFIG.SYS updates to:" check box to
            prevent the Toolkit Installation program from updating
            CONFIG.SYS.

   5. To install all selected components of the Toolkit:

         a. Select the "Install" push button.
         b. Follow the prompts in the message boxes to complete the installation.

   6. During installation, you may encounter a problem copying the file
      SOM.IR because the file is in use.  This file has not changed from 
      the last release, so you can select the "Ignore" push button on the
      "Installation Status" dialog box and continue with the installation.

   7. The system displays a message box indicating successful completion of
      the installation.

   8. To make the changes effective and have the Toolkit folder appear 
      on the Desktop, shut down and restart your system.  After the Toolkit
      is installed, the Toolkit folder appears on the desktop, represented
      by the toolbox icon.  If you installed the entire Toolkit, the folder
      will contain the following subfolders for the installed components:

         -  Beta
         -  C REXX Samples
         -  Development Tools
         -  Multimedia Bitmaps
         -  Multimedia Sample Programs
         -  OS/2 Samples
         -  Presentation Manager/2 Samples
         -  Toolkit Information
         -  Try Me!
         -  Workplace Shell Samples

Note:  If the entire Toolkit is not required, components may still be
deselected in the usual manner.  However, it is important that the 
paths are ot changed from their defaults for all components other than 
the root, because the directory structure on the CD cannot be changed.


UPDATES TO CONFIG.SYS
________________________________________________________________

The Toolkit Installation Program adds the paths of all needed environment
variables with the appropriate Toolkit path.  These variables include,
but are not limited to:

   -  BOOKSHELF
   -  DPATH
   -  HELP
   -  INCLUDE
   -  LIB
   -  LIBPATH
   -  PATH
   -  SMEMIT
   -  SMINCLUDE
   -  SOMBASE
   -  SOMIR
   -  TMP


KNOWN LIMITATIONS AND RESTRICTIONS
________________________________________________________________

This section provides up-to-the-minute testing information on:

   -  IBM Developer API Extensions for OS/2
   -  Real-time MIDI support and networking limitations
   -  File conflicts with the IBM VisualAge* C++ for OS/2 product


IBM Developer API Extensions for OS/2
________________________________________________________________

"IBM Developer API Extensions for OS/2 Guide" Changes:  Although 
documented in the Guide, these APIs are not supported:

   -  lstrcmp
   -  lstrcmpi
   -  GetTextExtentPoint32
   -  MapVirtualKey

WinMain Function:  To be able to use the Windows** WinMain function,
use the OS/2 Warp main function located in the following subdirectory:

   TOOLKIT\BETA\SAMPLES\DAPIE\WINMAIN\MAIN.C

You can also use the main function, a DLL, in the following subdirectory:

   TOOLKIT\BETA\SAMPLES\DAPIE\DLLMAIN\DLLMAIN.C

MAIN.C gets compiled and linked with the module containing WinMain and
creates an OS/2 Warp executable.  If you do not use the OS/2 Warp main
function, you will receive a link error stating that there is no starting
address for your program.

Recommended C Set++* Compiler Options:  Because the calling convention
for IBM Developer API Extensions for OS/2 APIs is always _System in OS/2
(the default calling convention for the C Set++ Compiler is _Optlink),
it is recommended that applications use the C Set ++ /Ms and /Wpro+
compiler options.

Resource Compiler Changes:  As an enhancement for IBM Developer API 
Extensions for OS/2, the Resource Compiler now supports string ids for 
resources in addition to integers.  The Resource Translator in SMART 
allows the choice to convert resources in one of the following formats:

   1. String id:  Use the "Supports String ID" check box choice when
      using the IBM Developer API Extensions for OS/2 APIs for resources.
      The .HHH file is not required. The Resource Compiler accepts the
      resources with ids specified as quoted strings.

   2. Integer id:  Ensure the check box for "Support String ID" is not
      selected in order to generate the required .HHH file.  This file
      defines the resource ids for use with the OS/2 native APIs.

Testing Items:  The following items, found during testing, will be fixed
for the GM product:

    Functions:

      CheckDlgButton:  Does not check the button.

      CheckMenuItem:  If a NULL handle is passed into this function, 
      the return code should be -1, but it is 0 (MF_UNCHECKED).

      CreateRoundRectRgn:  See SetWorldTransform.

      DlgDirList:  Does not sort the contents of the list box.

      DPtoLP:  When called with valid parameters, this call returns 0, 
      but should return 1.

      DragQueryPoint:  Returns a negative y value.

      EnableScrollBar:

        1. When calling this function as follows, it should return FALSE,
           but it returns TRUE:

              EnableScrollBar(hWndParent, SB_BOTH, ESB_DISABLE_BOTH);

        2. When calling this function as follows, it always returns FALSE:

              EnableScrollBar(hWndParent, SB_VERT, ESB_ENABLE_BOTH);

      EnumFontFamilies:  When this function is passed valid parameters,
      it returns FALSE.

      FindResource:  When calling this function passing a valid resource 
      ID and resource type to DosQueryResourceSize, FindResource 
      returns 87 (indicating an invalid parameter).

      FlashWindow:  When this function is called and passed the handle 
      of an inactive window, this function should return FALSE.  
      However, it returns TRUE.

      GetClassLong:  For GCL_STYLE, returns 0 for edit controls.

      GetMenuState:  When this function is called as follows, 
      it returns -1:

         nRet = GetMenuState(hMenuSave, 2, MF_BYPOSITION);

      However, this call is valid and should return a value other than -1.

      FrameRgn:  See SetWorldTransform.

      GetDeviceCaps:  This function returns rather large numbers for 
      aspect x and y.  Overflow is possible if you multiply using these 
      numbers.

      GetExitCodeProcess:  Does not return the value passed to ExitProcess
      by the process in question when that process is not a child process.

      MessageBox:  Using Close from the system menu to dismiss a message 
      box that specifies MB_YESNO gives you an incorrect return code from 
      the MessageBox function.

      NameConvertUnicodeToPath:  Sporadically, when IBM Developer API 
      Extensions for OS/2 code tries to access the NameConvertUnicodeToPath 
      function, an access violation occurs.  Once this problem occurs, 
      none of the Registry functions can be used successfully.  To recover 
      from this problem, see the "IBM Developer API Extensions for OS/2 
      Guide."

      PrintDlg:  If you are using the PrintDlg dialog, and if you are 
      creating your own printer DC, and if your target printer has 
      "print to file" selected, then you will be presented with two 
      "Print to a file" dialogs.  Do the following:

         a. Cancel the first one
         b. Type the name of the file into the second one

      If you use the first one, a zero length file will be created.

      ScrollDC:  This function does not redraw the blank area left due to
      the scrolling of a rectangle of bits.

      ScrollWindow:  This function repaints the screen after bits are s
      crolled.

      ScrollWindowEx:  This function returns FALSE when it should return 
      TRUE.

      SendMessage:  For WM_CUT, WM_COPY, WM_PASTE and WM_CLEAR 
      messages to an edit control, this function does not work.  The 
      keyboard equivalents, however, do work.

      SetClassLong:  For GCL_BACKGROUND, this function does not work.

      SetParent:  This function returns 0 rather than the handle to the
      previous parent when a child window is created under hWnd 
      ownership.

      SetWorldTransform:  If this function is used to set a new world 
      space transformation matrix then regions may not be displayed 
      correctly with regards to the transformation.

      StretchBlt:  With negative values for x and y, this function does not
      invert in the y direction.

      TrackPopupMenu:  Menus created with this function are not visible;
      they blink but do not stay on the screen.

      WinExec:  If you are using this API to run a program, you may find
      that the program never runs or appears to hang. If this happens, 
      shut down and restart your system to clear the condition.

    Messages:

      WM_CHAR:  Not sent to dialog procedures or subclassed window 
      procedures.

      WM_DESTROY:  If you close an application by pressing ALT+F4, this
      message is not sent.

      WM_MDISETMENU:  Does not append the name to the title bar.

      WM_NC:  Non-client messages (WM_NC) are not functional.

      WM_SYSCHAR:  Not sent for menu items.

    Miscellaneous:

      1. Large pen sizes tend to distort shapes.

      2. Combination box lists may not collapse after selecting an item.

      3. Clipping the cursor to a window causes the cursor to disappear
         when the window is minimized.

      4. MDI child windows disappear when minimized--that is, no icons 
         are available and the WINDOW menu item does not have an entry 
         for the minimized window. Retrieve the windows by pressing 
         CTRL+F4.

         Also, a MDI child window should accept CTRL+F4 to exit the
         MDI child window and CTRL+F6 to move from one to another of
         the open MDI child windows.  These key sequences are not
         implemented at this time.  Both ALT+F4 and CTRL+F4 send a
         WM_CLOSE message to the frame window and therefore may cause
         your application to end prematurely.

      5. Using a control item's mnemonic in a dialog box does not change
         focus to that item.

      6. There is a memory leak in DDE when running a large number of
         transactions.

      7. The ESC key does not dismiss a dialog box.

      8. The default push buttons do not work:  You have to click on 
         the button.

      9. The owner drawn variable height list boxes and combination boxes
         are not functional in this Beta.  However, the styles are located
         in the header file OS2CTLWX.H to allow you to compile.

     10. The tab key does not change focus between dialog controls.  You
         must use your mouse.

     11. When using two SMART tables--W16DAPIE.TBL and DAPIE16.TBL--to
         calculate migration effort, the report that identifies 
         non-supported keywords provides an incorrect migration effort 
         calculation.


Tested Sound Cards for New Real-Time MIDI Support
________________________________________________________________

The real-time MIDI support that is being introduced in the BETA component
of the Toolkit has been successfully tested with the following sound cards:

   -  SoundBlaster** 16
   -  Jazz16
   -  SoundBlaster AWE32 (works with external MIDI synthesizer only)

Currently, the new real-time MIDI support does not work with the following
sound cards:

   -  Pro AudioSpectrum 16**
   -  SoundBlaster AWE32 (does not work with internal wave synthesizer)


Network Functions Limitations
________________________________________________________________

Currently, the receive function used for networking (WarpNetPackRecv) can
only receive header information without packet data.


IBM VisualAge C++ for OS/2
________________________________________________________________

This version of the Toolkit supports the C Set ++ Version 2.1 Compiler.

A version of the Toolkit ships with the IBM VisualAge C++ for OS/2 product.
The SOM files that ship with IBM VisualAge C++ for OS/2, including IDL and
DLL files, are more recent than those shipped with this version of the
Toolkit.  If you are using IBM VisualAge C++ for OS/2, be sure to use the
SOM files shipped with that product instead of those shipped with this
version of the Toolkit.

However, the Warp Toolkit Development Tools, such as the Resource Compiler,
shipped with this version of the Toolkit are more recent than those
shipped with IBM VisualAge C++ for OS/2.  Therefore, be sure to use the
development tools shipped with this version of the Toolkit for your OS/2
development.

Do not install the Toolkit samples shipped with this version of the Toolkit
if you are using the VisualAge C++ compiler.  Use instead the sample programs
shipped with the VisualAge C++ compiler; they are more recent than those
shipped with this version of the Toolkit.  If you use the samples shipped
with this version of the Toolkit and compile them with the VisualAge C++
compiler, the compiler will generate link errors.

________________________________________________________________

Thank you for your continued interest in the OS/2 Operating System.
________________________________________________________________


TRADEMARK INFORMATION
_____________________


The following terms, denoted by an asterisk (*) in this file, are trademarks or
registered trademarks of the IBM Corporation in the United States or other
countries:

   -------------------------------------------------------
   C Set ++
   -------------------------------------------------------
   IBM
   -------------------------------------------------------
   OS/2
   -------------------------------------------------------
   Presentation Manager/2
   -------------------------------------------------------
   VisualAge
   -------------------------------------------------------
   Workplace Shell
   -------------------------------------------------------


The following terms, denoted by a double asterisk (**) in this publication, are
trademarks of other companies:

   -------------------------------------------------------
   Intel386                    Intel
   Pro AudioSpectrum 16        Media Vision, Inc.
   Sound Blaster               Creative Technology, Ltd.
   Windows                     Microsoft Corporation
   -------------------------------------------------------

IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING WITHOUT
LIMITATION, WARRANTIES OF FITNESS AND MERCHANTABILITY WITH RESPECT TO THE
INFORMATION IN THIS DOCUMENT.  BY FURNISHING THIS DOCUMENT, IBM GRANTS NO
LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS.

Copyright IBM Corporation, 1995, all rights reserved.

________________________________________________________________

END-OF-README-FILE
________________________________________________________________
