IBM VisualAge for C++ for Windows - README
 
IBM* VisualAge* for C++ for Windows** Version 3.5.9
(C) Copyrights by IBM Corp and by others 1988, 2000.
All rights reserved.
 
US Government Users Restricted Rights - Use, duplication or 
disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 
 
NOTICE CONCERNING OPERATING SYSTEM SUPPORT
 
IBM VisualAge for C++ Version 3.5.9 ("Version 3.5.9") supports only
Windows 95, Windows NT 4.0 and Windows 2000 Professional.
Notwithstanding any information in the License Agreement (and license
information, if applicable) or specifications for the product,
Version 3.5.9 does NOT support Windows 3.1, Win32s or Windows NT 3.51.
In addition, Version 3.5.9 may not support certain functions and procedures
as stated in the specifications, to the extent such functions and
procedures require Windows 3.1, Win32s or Windows NT 3.51 support, and
IBM is not responsible for any such unsupported functions and
procedures.
 
This file contains important information about the IBM VisualAge for
C++ for Windows product.  You should read the Introduction section
before you install this product.
 
 
Support
 
For information about support, see:
 
o   The file SUPPORT.TXT in the IBMCPPW directory.
 
Or
 
o   The section called What If I Still Have Questions in the
    Frequently Asked Question (FAQ) information in the Online
    Information Notebook.
 
NOTE:  The User's Guide refers to a 60 day Getting Started Support
Period for the U.S. and Canada.  The Getting Started Support is no
longer available.  Similar technical support is available via the
Personal Systems Support Line fee offering.
 
 
Trademarks
 
The following terms are trademarks of International Business Machines
Corporation in the United States or other countries or both:
 
    IBM
    DB2
    Open Class
    OS/2
    VisualAge
 
Other terms used in this README, which may be denoted by a double
asterisk(**), are trademarks or service marks of others.
 
    Excel, Windows, Windows NT, Win32, Windows 2000 are trademarks of
    Microsoft Corporation.
    PostScript is a trademark of Adobe Systems Incorporated.
 
 
Contents
 
1.0  INTRODUCTION
1.1  Contents
1.2  Prerequisites for WIndows 2000 Windows NT and Windows 95
1.3  Installation
  1.3.1  Important Note - Before You Install On Windows 95
  1.3.2  Installing This Product
  1.3.3  Known Problems During Installation
  1.3.4  Known Problems During Deinstallation on Windows NT
 
2.0  LATE-BREAKING NEWS
2.1  License Information Notes
2.2  General
  2.2.1  Windows NT
  2.2.2  Windows 95
  2.2.3  WIndows 2000
2.3  Compiling and Linking
  2.3.1  Usage Notes
  2.3.2  Restrictions
  2.3.3  Known Problems
2.4  Working with Resources
  2.4.1  Usage Notes
  2.4.2  Known Problems
2.5  Using the User Interface Class Libraries
  2.5.1  Portability Differences between Windows and OS/2
  2.5.2  Restrictions and Known Problems
  2.5.3  Specific Class Information
2.6  Using the Data Type and Exception Class Libraries
  2.6.1  Usage Notes
  2.6.2  Factors Affecting Performance With IString
2.7  Using the Collection Class Libraries
  2.7.1  Restrictions
2.8  Using the Compound Document Framework Class Libraries
  2.8.1  Installation On Windows NT
  2.8.2  Usage Notes
2.9  Using the Editor
  2.9.1  Usage Notes
  2.9.2  Known Problems
2.10  Using WorkFrame
  2.10.1  Differences from OS/2 and Restrictions
  2.10.2  Usage Notes
  2.10.3  Known Problems
2.11  Using the Visual Builder
  2.11.1  Known Problems and Restrictions
2.12  Debugging
  2.12.1  Usage Notes
  2.12.2  Known Problems on WIndows 2000, Windows NT and Windows 95
2.13  Using the Performance Analyzer
  2.13.1  Usage Considerations
  2.13.2  Restrictions and Known Problems
2.14  Using the Data Access Builder
  2.14.1  Prerequisites
  2.14.2  Usage Notes
  2.14.3  Creating a SOM library of Multiple Classes
  2.14.4  Features
  2.14.5  Known Problems
  2.14.6  Known Problems on DB2 That Affect the Data Access
   Builder
  2.14.7  Using the Data Access Builder with the AS/400
2.15  Using the Browser
  2.15.1  Known Problems
  2.15.2  Permanent Restrictions
2.16  SOM
  2.16.1  Known Problems
 
3.0  SAMPLES
3.1  General Information
  3.1.1  Usage Notes
3.2  SOM/WorkStation DSOM Samples
  3.2.1  Known Problems and Restrictions

4.0  Information Pertinent to version 3.5.9
4.1  IBM Open Class Changes
4.2  Microsoft SDK changes
4.3  Win32 SDK Online Help
4.4  Known Problems
  4.4.1 Win95 Visual Builder problem

5.0  DOCUMENTATION
5.1  Printing
  5.1.1  Known Problems With Printing
  5.1.2  How to Print

 
1.0  Introduction
 
The VisualAge for C++ for Windows product runs on Windows NT**, Windows
2000 and on Windows 95 on Intel machines.  The product generates code 
that runs on Windows 2000, Windows NT, and Windows 95.
 
Unless otherwise described, Windows refers to Windows 2000, Windows NT
and Windows 95, while Windows 2000 refers to Windows 2000 Professional.
 
 
1.1  Contents
 
The contents of this product are:
 
o   Compiler (ICC)
 
o   Linker (ILINK)
 
o   Tools and utilities for defining and creating Windows resources,
    such as dialogs and bitmaps
 
o   Tools and utilities for creating and displaying online help text
 
o   Message compiler
 
o   System header files and libraries
 
o   Library Manager (ILIB)
 
o   Open Class Library, header files, and DLLs for:
 
    -   Data Type and Exception classes
 
    -   Collection classes
 
    -   User interface classes
 
    -   Compound Document Framework classes
 
o   Editor
 
o   WorkFrame
 
o   Visual Builder
 
o   Debugger
 
o   Performance Analyzer
 
o   Data Access Builder
 
o   Browser
 
o   SOM WorkStation and SOM Developer's Toolkit Version 2.1
 
o   Publications in online and PostScript format
 
 
1.2  Prerequisites for Windows 2000, Windows NT and Windows 95
 
o   Windows NT 4.0 is required.  This product will not run on earlier
    versions of Windows NT.
 
Or
 
o   Windows 95
 
o   The disk space required for Windows is below:
 
    -   Minimal install of the product requires 48MB.
 
    -   The entire product including the documentation requires 370MB.
 
 
1.3  Installation
 
This section describes important information about installing the
product.
 
To view the Installation Guide prior to running the install program,
type the following:
 
  x:       (Where x: is the drive containing the CD-ROM)
  cd ibmcppw\bin
  iview ..\help\cppwigde.inf
 
Following the installation of the product, you can view details about
installation and deinstallation.  Select the Install Guide on the At a
Glance cascade menu in the Help pulldown in any component, such as
WorkFrame or the Browser.
 
 
1.3.1  Important Note - Before You Install On Windows 95
 
This section describes what you need to do before you install the
product on Windows 95.
 
 
 
1.3.1.1  Required Tasks Before You Install the Product
 
Before you install, you must increase the system environment size.
 
The VisualAge for C++ for Windows product updates a number of system
environment variables during installation and the default system
environment size is too small.
 
The required changes are described below.
 
 
1.3.1.2  C:\CONFIG.SYS change
 
Use the editor of choice to add the following line to your
C:\CONFIG.SYS file.  Create the file with this line if the file does
not exist.
 
    SHELL=C:\WINDOWS\COMMAND.COM /p /e:20000
 
This line sets the environment size to 20,000 bytes, which is
sufficient for the VisualAge for C++ product.  If you have other
products that use a significant amount of environment space, you may
need to increase this value.  You may also want to use a smaller value
on systems that are constrained by memory.
 
This change will set the environment size for programs run directly
from folders.
 
NOTE:  The above assumes that Windows 95 was installed in the
C:\WINDOWS directory.  If you installed in another directory,
substitute the directory name.
 
 
1.3.1.3  MS-DOS Prompt change
 
Start an MS-DOS Prompt.  If you are using the Start button, select
'Programs' and then 'MS-DOS Prompt'.  Open the MS-DOS Prompt
Properties window by doing one of the following:
 
o   Opening the system menu by clicking on the MS-DOS icon at the
    top-left corner of the MS-DOS Prompt, and then selecting the
    'Properties' item
 
Or
 
o   Selecting the 'Properties' icon on the Toolbar if the Toolbar is
    active.
 
Switch to memory page by selecting the 'Memory' tab at the top.
Within the 'Conventional memory' area is a drop-down entry field.
Click on the arrow, scroll down until the '4096' entry is visible and
select it.  Now click on the OK button at the bottom of the Properties
sheet.
 
This change sets the environment size for each MS-DOS prompt started.
 
 
1.3.2  Installing This Product
 
Refer to the Installation Guide for details.  To view the Installation
Guide prior to running the install program, type the following:
 
  x:       (Where x: is the drive containing the CD-ROM)
  cd ibmcppw\bin
  iview ..\help\cppwigde.inf
 
Following the installation of the product, you can view details about
installation and deinstallation.  Select the Install Guide on the At a
Glance cascade menu in the Help pulldown in any component, such as
WorkFrame or the Browser.
 
The default path where the files are installed is IBMCPPW.
 
 
1.3.2.1  Installing Files for Compound Document Framework Classes
 
Refer to the section called Using the Compound Document Framework
Class Libraries for information about installation.
 
 
1.3.3  Known Problems During Installation
 
o   We recommend that you do not minimize the install window during
    the installation.  The setup screen sometimes freezes if it is
    minimized while the installation is running.  If the hard drive
    runs out of space, you cannot continue with the installation
    because when you restore the window, the error dialog is no longer
    shown.
 
    You need to ensure you have enough hard disk space available, and
    then restart the installation.
 
 
1.3.4  Known Problems During Deinstallation on Windows NT
 
o   On Windows NT and Windows 2000, a problem exists when you try to 
    deinstall the product after you have more than one install image 
    on the same machine.  This applies only to a full install of the
    product onto your hard disk.  You can successfully deinstall one
    image, and you receive an error message when you try to deinstall
    the second image.  Some files needed by the deinstall program have
    been deleted.  Copy all the files from the CD-ROM directory called
    IBMCPPW\INSTALL\UTILS, to the \WINNT\VACPPINS directory where the
    operating system is installed.  Run the deinstall again.
 
 
2.0  Late-Breaking News
 
This sections describes late-breaking news and restrictions.
 
 
2.1  License Information Notes
 
The License Information booklet includes the terms and conditions for
redistributing files.  The list of files that you can redistribute is
contained in the file called REDISTR.TXT.
 
Note that currently you cannot rename CPPWOT3.DLL and ILIBIPF32.DLL.
 
 
2.2  General
 
This section describes news and restrictions that apply to more than
one component in the product.
 
o   The Online Information notebook is more current than the
    PostScript files and the printed books.
 
 
2.2.1  Windows NT
 
o   Windows NT has a known problem in screen saver code.  When the
    used environment space reaches a certain size, the WINLOGON.EXE
    program traps.  When this program traps, Windows NT stops the
    machine.  Only a power off/on sequence can clear this.  If you are
    using the Screen Saver feature, you are strongly encouraged to
    disable the Screen Saver feature either immediately or if you
    encounter this problem in the future.
 
 
2.2.2  Windows 95
 
o   Sometimes the VisualAge for C++ tools have unpredictable behavior
    when the Windows 95 system experiences virtual memory problems.
    Virtual memory problems such as full swap space can produce system
    lockups and abnormal terminations without system notification.  It
    is recommended that you run the VisualAge for C++ tools with at
    least 40MB of free space available for your swap file.
 
o   When you bring up the MS-DOS command prompt and type in the letter
    of the drive where you installed the product, you are placed into
    the following path.
 
      drive:\IBMCPPW\IBM VA FOR C++ FOR WINDOWS
 
    The path is not correct.  Change the directory to the appropriate
    working directory.
 
o   Sometimes the Windows 95 pointer is displayed as both a pointer
    and an hour glass.  You can proceed to do other tasks.  It appears
    that you can not take any action until the hour glass disappears,
    but this is not the case.
 
o   The PSTAT and WinPerf programs are not available.
 
2.2.3 Windows 2000
    The Debugger that is shipped in the product is not supported on
    Windows 2000. Use IBM Distributed Debugger V8.5 instead.

    This version (3.5.9) uses a new version of the Microsoft SDK.
    Consequently the tools supported are different.

 
2.3  Compiling and Linking

This section contains important information about compiling and
linking.

This version contains an improved linker which has fewer limitations and
may be faster in some cases.  This linker is based on the V3.6 linker.   

Executing ILINK without any parameters will return an banner indicating
this is a V3.6 linker.

On Windows 95 a base address of lower than 0x400000 can not be specified
when generating an executable due to a systems limitation.  If the 
/base:0xADDRESS option is used (where ADDRESS < 0x400000), the linker
option /NOFIXed must also be used. Doing so will allow the system to
determine and relocate the application as required.

The error message "LNK2029:  unresolved external" may contain a meaningless
mangling prefix in the referenced names. To demangle them, delete the
characters  "__imp_" at the beginning of the symbol.    

The linker will only handle one resource file (.res) at a time. An error
message will be issued if two or more resource files for an application
linked.

The linker now will no longer issue a warning when a dll is created without
".dll" in the extension.

 
2.3.1  Usage Notes
 
o   System Header Files and Libraries
 
    The system header files have been modified to work with the
    compiler.  The libraries are shipped with no changes from the
    versions supplied by Microsoft.
 
o   Working with NMAKE
 
    If nmake finds more than one rule in a makefile that can be used
    to build a certain target, it will use the rule found last.
 
o   By default, VisualAge for C++ links to the KERNEL32.LIB system
    import library.  Any other system import libraries must be linked
    manually.  For a list of the mapping of Windows APIs to system
    import libraries, refer to the file called WINAPI.TXT in the
    \IBMCPPW\HELP directory on the CD-ROM.
 
    There are entries that are identical except one ends with "A" and
    other ends with "W".  For example, there is a windows API called
    StartService. In the WINAPI file there are two entries -
    StartServiceA and StartServiceW.  You can ignore the trailing A or
    W.
 
o   Structured exception handling is not ported to VisualAge for C++
    on other platforms.  You should avoid using structured exception
    handling in applications you want to port.
 
 
2.3.2  Restrictions
 
o   In Windows 95 only, nmake does not handle filenames that contain
    spaces. You may need to use the short version of the filename,
    which you can find using the "dir" command.
 
o   If you link statically, do not terminate your process with
    ExitThread or ExitProcess APIs, because the run-time termination
    will not occur, and buffers will not be flushed.  If you link
    dynamically, the same restriction applies only to Windows 95 and
    ExitThread. For portability, always use the exit library function.
 
o   Do not pass file handles between different library environments.
    For example, do not open a file in the EXE (with fopen, open, or
    any other library function) and then pass it to a DLL if both of
    them link statically to the run time.
 
o   If you use Thread Local Storage in C++, a restriction in Windows
    95 can affect you.  No initialization or termination code is run
    for variables within a thread.
 
      __thread int i = 5; /* OK, statically initialized */
      __thread int j = f(); /* f() not called in Windows 95*/
 
    In both Windows NT and Windows 95, the order of thread termination
    is not predictable.  In a DLL, this means the following.
    PROCESS_DETACH notification can occur on a thread other than
    thread 1.  Termination code registered with the atexit() function,
    as well as destructors of static C++ objects, will run on the
    thread in which the PROCESS_DETACH notification occurs.
 
 
2.3.3  Known Problems
 
o   The C++ compiler may not work when you are compiling C++ source
    that is located on the Z: drive.
 
    The C++ compiler may terminate with a General Protection Fault and
    a Register Dump.  This problem can be avoided by moving the source
    to a directory that is not located on the Z: drive or by using the
    /Ft- command-line option.
 
o   The ILINK option /OPTFUNC will incorrectly remove functions that
    are only referenced from a COFF object.  This is likely to be a
    problem when building a DLL but unlikely when building an EXE.
 
o   According to the documentation, ILINK will search directories
    given on the command line before searching directories specified
    by the LIB environment variable.  Currently the reverse is true.
 
o   When linking  a dll created  by this product with a dll created by 
    another compiler and using a single icc command, such as the
    example below where "ibm.obj" is the source object of "ibm.dll" and
    "microsoft.lib" is the import library of the "microsoft.dll".

    icc /ge- ibm.obj microsoft.lib

    The following error message may be returned:

    "Fatal error : invalid object 'microsoft.dll' at offset xxxx xxxx"

    The following workarounds may be used to avoid the problem:
    1. Add the linker flag of "/B" in front of any Microsoft import 
       library.  Thus icc will only pass those libraries to ilink,
    2. Provide an export object file for linking a dll. In this case, 
       icc will not call ilib for generating xxx.exp file,
    3. Use ilink to link the xxx.dll instead of icc.

 
2.4  Working with Resources
 
This section contains important information about working with
resources.
 
 
2.4.1  Usage Notes
 
o   The additional command-line options for ibmpcnv are:
 
        -B      : Input file is a bitmap
        -C      : Input file is a cursor
        -I      : Input file is an icon
        -P      : Input file is a pointer
 
    If -D is specified, the above options are ignored and ibmpcnv
    converts files with .ico, .bmp, .cur, .ptr extension in the
    "filein" dir.  The above options are added because ibmpcnv is
    sensitive to file suffixes.  It only convert files with .ico,
    .bmp, .cur, .ptr suffixes.  It uses the suffix to determine the
    type of resource image.
 
o   The IBM Resource Compiler (IRC) has the command line option -k
    codepageId to support compiling resources in the specified
    codepage.
 
o   To view books in .INF format from the command line use iview which
    is a 32-bit upgrade of the xview tool referenced in the IPF User's
    Guide and IPF Programmer's Guide and Reference.  In addition
    libipfx.dll has been upgraded to libipf32.dll.
 
 
2.4.2  Known Problems
 
o   Message Compiler Bug
 
    Comments are allowed in the input message (.mc) file. Comments
    must begin with a semicolon (;) in the first column and are
    terminated by the end of the line.
 
    As the User's Guide states, comments that exist by themselves on a
    line are copied, as is, to the output include (.h) file. However,
    the semicolon is not converted to the C end-of-line comment syntax
    (//).  The semicolon is stripped from the beginning of the comment
    line.
 
    You will have to manually update your include file to add the
    slashes to indicate to the compiler that the line is a comment.
 
o   The resource compiler cannot decompile a binary resource file with
    a MENUEX resource defined in it.  The resource workshop will treat
    the resource as a MENU resource.   When you see "__VERSION 1" and
    "__OFF 4" defined under the MENU resource, it means that it is a
    MENUEX resource.  The menu items may not be decompiled correctly
    in this case.
 
o   In the DBCS environment, when you save a file as a resource file,
    the resource workshop will work very slowly.  To improve this, set
    the "Foreground and Background Application Equally Responsive" in
    the Tasking setup under System setup in the Control Panel.
 
o   If you install the product to the root directory of a partition,
    such as E:, then the IPF Compiler will not work unless you make
    the following changes to your environment:
 
    -   On Windows 95, the variable "IPF_PATH32" is set to "E:\" in
        the autoexec.bat file.  Remove the backslash and change the
        setting to "E:".
    -   On Windows NT, the variable "IPF_PATH32" is set to "E:\" in
        the registry.  Remove the backslash and change the setting to
        "E:".  You can use System tool in the Control Panel window.
 
o   If you have coded empty help resources you need to add a line of
    null terminators to ensure the proper processing of these tags.
    See the following examples.
 
      100 HELPTABLE
      {
        10, ID_SUBTABLE, 20
      }
      ID_SUBTABLE HELPSUBTABLE
      {
         0,0   /* Null termination string here for empty table */
      }
 
      100 HELPTABLE
      {
         0,0,0 /* Null termination string here for empty table */
      }
 
 
2.5  Using the User Interface Class Libraries
 
The following information refers to the User Interface Classes
contained in the IBM Open Class Library.  These notes are in addition
to what is documented in the Open Class Library User's Guide and the
Open Class Library Reference manuals.
 
 
2.5.1  Portability Differences between Windows and OS/2
 
Refer to the Portability section of the Open Class Library User's
Guide and the platform support information contained in the function
descriptions of the Open Class Library Reference, Volumes I - IV.
 
 
2.5.2  Restrictions and Known Problems
 
This section describes the restrictions and known problems, including
documentation problems.
 
 
2.5.2.1  Colors
 
The following member overrides were added to query and set the
background color of the font and file dialogs:
 
In ifontdlg.hpp:
 
    virtual IColor backgroundColor () const;
    virtual IFontDialog &setBackgroundColor (Const IColor& color);
 
In ifiledlg.hpp:
 
    virtual IColor backgroundColor () const;
    virtual IFileDialog &setBackgroundColor (Const IColor& color);
 
 
2.5.2.2  Graphics
 
The set of pen types, styles, and patterns that can be set through
IGraphicBundle is limited on Win32s and Windows 95.  On these
environments, the best available approximation is chosen.
 
Due to a limitation in the Graphic Device Interface (GDI) on Windows
95, only the pen patterns IGraphicBundle::filled and
IGraphicBundle::hollow are supported.
 
 
2.5.2.3  Multimedia
 
USE OF IMMDEVICE::MODE IN NOTIFICATION HANDLERS
 
As part of its execution, IMMDevice::mode generates a notification
event.  When writing a notification handler, you should keep this in
mind.  Consider the following code, which is part of a
dispatchNotificationEvent routine:
 
     IMMNotifyEvent* notifyEvent =
        (IMMNotifyEvent*)(event.eventData().asUnsignedLong());
 
     if (notifyEvent->command() == IMMNotifyEvent::play)
     {
        panel.playbtn.unlatch();
        if (panel.playerDevice == CDID)
          if (panel.cdPlayer->mode() == IMMDevice::playing)
          {
             panel.playbtn.latch();
          }
     }
 
In this example, the mode function is called within the if clause.
But consider the following, where it is moved outside:
 
     IMMNotifyEvent* notifyEvent =
  (IMMNotifyEvent*)(event.eventData().asUnsignedLong());
     if (notifyEvent->command() == IMMNotifyEvent::play)
     {
        panel.playbtn.unlatch();
     }
     if (panel.playerDevice == CDID)
       if (panel.cdPlayer->mode() == IMMDevice::playing)
       {
          panel.playbtn.latch();
       }
 
This causes the following set of events to occur:
 
1.  The "mode()" command generates a notify event
2.  The notify event re-enters "dispatchNotificationEvent()"
3.  Since the "mode()" command is not inside the if clause, it is
    executed again
4.  Loop through steps 1-3 recursively until a stack overflow occurs
 
Care should be taken when using the "mode()" command in this
situation.
 
RECORDING IN THE 32-BIT WINDOWS ENVIRONMENT
 
In 32-bit Windows, the only device that supports recording is
WAVEAUDIO (IMMWaveAudio). In addition, certain recording parameters
can only be specified when opening a new data file for recording.
Once recording has begun, they cannot be altered.  This also applies
when adding recorded material to an existing file.  The IBM Open Class
functions that get or set these parameters are listed below:
 
o   IMMConfigurableAudio::setBytesPerSecond
o   IMMConfigurableAudio::setBitsPerSample
o   IMMConfigurableAudio::setBlockAlignment
o   IMMConfigurableAudio::setChannels
o   IMMConfigurableAudio::setFormat
o   IMMConfigurableAudio::setSamplesPerSecond
o   IMMConfigurableAudio::bytesPerSecond
o   IMMConfigurableAudio::bitsPerSample
o   IMMConfigurableAudio::blockAlignment
o   IMMConfigurableAudio::channels
o   IMMConfigurableAudio::format
o   IMMConfigurableAudio::samplesPerSecond
 
If the setters are used on a device that already contains recorded
material, an exception is thrown.  The use of either the setters or
getters on a device that does not support recording (for example, any
device other than IMMWaveAudio in 32-bit Windows) throws an exception.
 
Use IMMDevice::supportsRecord to determine if the getters can be used.
It is recommended that you maintain a "new record file" flag for use
of the setters.  Once recording has initiated, this flag should be set
to false and access to the setters should be disabled.
 
NEW MEMBER FUNCTIONS IN IMMAUDIOCD
 
The following functions were added to IMMAudioCD, but are not in the
product documentation:
 
The following function returns the current table of contents entry.
 
  public:
     unsigned long IMMAudioCD::currentContentsEntry() const
 
The following function returns the current track.
 
  public:
     unsigned long IMMAudioCD::currentTrack() const
 
32-BIT WINDOWS SUPPORTED MEMBER FUNCTIONS IN IMMPLAYABLEDEVICE
 
The following functions in IMMPlayableDevice are listed as not
supported under 32-bit Windows, when in fact they are:
 
  public:
  IMMPlayableDevice&
    IMMPlayableDevice::startPositionTracking(const IMMTime &time,
                                                         CallType call)
  public:
  IMMPlayableDevice&
    IMMPlayableDevice::stopPositionTracking(CallType call)
 
USE OF IMMDIGITALVIDEO::SETDESTINATION
 
When using ICoordinateSystem::originLowerLeft, the setDestination
rectangle specified is mapped relative to the lower-left corner of the
video window.  This may cause clipping of the video image.
 
COMPOUND DEVICES IN 32-BIT WINDOWS
 
In general, 32-bit Windows MCI compound devices (those that require a
file for data, such as WAVEAUDIO, SEQUENCER, and DIGITALVIDEO) have
limited function until they are loaded with a file.  Because of this,
it is recommended that actions on these devices be limited until a
file is loaded, using the IMMFileMedia::load member function.
 
MCI_LOAD EMULATION
 
In 32-bit Windows, device element (data file) for a compound device
can only be specified when the device is opened.  The MCI_LOAD
function is not supported, so the device element cannot be changed
after that time.
 
The following protected virtual functions are used to emulate the
MCI_LOAD command, allowing an IBM Open Class multimedia object change
its filename:
 
  virtual IMMDevice
    &saveDeviceSettings     (),
    &restoreDeviceSettings  (Boolean newRecordMode = false);
 
For compound devices, when IMMFileMedia::load is called, the following
events occur to emulate MCI_LOAD:
 
1.  All classes in the object's hierarchy are requested to save
    pertinent parameters or settings using saveDeviceSettings.
 
2.  The current device associated with the object is closed.
 
3.  A new device is opened with the new filename, and is associated
    with the object.
 
4.  All classes in the object's hierarchy are requested to restore
    pertinent parameters or settings using restoreDeviceSettings.
 
Derived classes should use these classes as necessary. The final
statement before the return should be a call to the parent's same
function, allowing all inherited classes to save or restore settings.
 
IMMDEVICE::SETVOLUME LIMITATION
 
The 32-bit Windows MCI does not support MCI_OVER so the "over"
parameter is ignored.
 
IMMDEVICE::SENDCOMMAND LIMITATION
 
The 32-bit Windows mciSendCommand function does not support the
passing of an arbitrary user parameter, so this capability is not
available.
 
 
2.5.3  Specific Class Information
 
 
2.5.3.1  IAcceleratorKey and IAcceleratorTable
 
Accelerator keys have the following restrictions on Windows NT and
Windows 95:
 
o   If you assign a key to run both an application command and a
    system command, the assignment to the application command is
    ignored.  The distinction on the type of command event generated
    when the key is pressed is determined by the Windows presentation
    system based on the command identifier.  If the system menu
    contains an item with the same identifier, the accelerator key
    generates a system command event.  Otherwise, it generates an
    application command.
 
o   Assigning a key to generate a help request causes the key to
    generate an IC_ID_HELP command.  IFrameHandler processes the
    command as a help request.  You must do one of the following:
 
    -   The accelerator table with this key must be assigned to a
        canvas, container, or frame window for the IFrameHandler to
        process this command.
    Or
    -   You must create a command handler that sends the command event
        up the chain of the owner window, and attach this handler to
        the window with the accelerator table.
 
 
2.5.3.2  IBaseComboBox
 
Horizontal scrollbars are only supported for simple combo boxes in
Windows NT newshell applications.  This is due to a Windows bug.  They
are supported for all combo box types in Windows 95 applications.
Horizontal scrollbars are not supported in Windows NT oldshell
applications.
 
 
2.5.3.3  IContainerControl
 
When calling IContainerControl::refresh after calling
IContainerControl::setRefreshOff, refresh should be called with a true
parameter.  This solves any painting problems that occur after calling
IContainerControl::setRefreshOff.
 
 
2.5.3.4  IContainerControl::ColumnCursor
 
The documentation for this class in the Open Class Library Reference
is incorrect as the columns are iterated in the expected order.  The
Windows information for this class should then read as follows:
 
WINDOWS INFORMATION:  The native Windows container has a required
first column.  If an IContainerColumn object is not inserted for this
required column, the cursor does not iterate them.  See the
IContainerColumn documentation for more details.
 
 
2.5.3.5  IFileDialog
 
The SAVE AS DIALOG fails to save a file to a network drive under the
following circumstances:
 
1.  Windows 95 environment
2.  File already exists
3.  Network drive is an HPFS drive
 
The error that is reported states that the path does not exist.
However, this scenario does work when the network drive is a FAT
drive.
 
An ICommandHandler cannot be used to handle events for an IFileDialog.
Currently, command and systemCommand events are not passed to handlers
but are routed directly to the default file dialog procedure.
 
 
2.5.3.6  IFont
 
If an IFont object is being used for a printer, plotter, FAX, or other
non-display device, some of the attribute-setting functions assume a
display presentation space (device context) for use in recalculating
the font metrics.  There is no way to pass a presentation space as a
parameter to the these functions.  The result is that pointSize
returns an incorrect size for the actual presentation space afterward.
There is no problem for IFont objects used with display presentation
spaces.
 
The IFont member functions involved are listed below:
 
    setBold
    setItalic
    setUnderscore
    setAllEmphasis
    useBitmapOnly
    setDirection
 
A solution is to save the pointSize across a call to one of these
functions.  This solution is only needed if the font is not being used
for a display.  For example:
 
    size = pointSize();
    setBold();
    setPointSize(size, printerPs);
 
 
2.5.3.7  IInfoArea
 
Menu items that have a submenu do not display text in an information
area.
 
 
2.5.3.8  IKeyboardEvent
 
The IKeyboardEvent::sysRq enumerator is not supported on the Windows
platform.
 
 
2.5.3.9  IMultiLineEdit
 
Due to a 16-bit Windows limitation, importing a large file into a MLE
does not work properly.  Windows 95 implements some window management
features in 16 bits.  The use of 16 bits imposes some restrictions on
parameters in functions and messages and places limits of about 64
kilobytes of text.
 
 
2.5.3.10  IThread
 
If you are building a statically linked (Gd-) multithreaded
application for Windows 95, restrictions apply.  You should use only
the IThread constructors to create threads that contain IWindow
objects or are referenced using IThread.  You should avoid using the
CreateThread 32-bit Windows function or the beginthread C library
function to create threads.  The following IThread constructor may not
function correctly when applied to a thread created with the
CreateThread or beginthread functions:
 
    IThread ( const IThreadId&     threadID,
              const IThreadHandle& threadHandle =
              IThreadHandle::noHandle );
 
This restriction does not apply to Windows NT applications or to
dynamically linked Windows 95 applications.
 
 
2.6  Using the Data Type and Exception Class Libraries
 
 
2.6.1  Usage Notes
 
A new capability has been added to ITrace to enable capturing trace
output to a file.  To direct ITrace output to a file, set the
following environment variables before starting the application.
 
  SET ICLUI_TRACETO=FILE       <- causes the next environment to
                                  be checked and used
  SET ICLUI_TRACEFILE=<file>   <- trace output will be place into
                                  <file>
 
 
 
 
 
 
 
 
2.6.2  Factors Affecting Performance With IString
 
When the IString class is enabled for internationalization,
performance may be degraded.  Factors that affect performance are:
 
o   Strings that are thousands of bytes long
o   Frequency of string parsing and indexing.
 
 
2.7  Using the Collection Class Libraries
 
 
2.7.1  Restrictions
 
 
2.7.1.1  Copying Key Collection Class objects
 
If you use your own copy constructor to add an object to a key
collection, be sure that the key of the object is not changed.
Changing the key can cause unpredictable results, including program
traps.  In general, it is recommended that you use the default copy
constructor, rather than defining your own.
 
The Key collection classes can be recognized by the word "key" in
their name.  For example IKeyBag and IKeySetAsBSTTree.
 
 
2.8  Using the Compound Document Framework Class Libraries
 
This section describes important information about the the Compound
Document Framework Class Libraries.
 
 
2.8.1  Installation On Windows NT
 
To insert a CDF server into an OLE container or to activate a CDF
server within an OLE container, you must do the following.  Set the
system path to point to the DLLs in the \IBMCPPW\BIN directory.
 
 
2.8.2  Usage Notes
 
o   You need the following program:
 
    -   UUIDGEN.EXE from the Win32 Development Toolkit.  It is in the
        \IBMCPPW\SDK\BIN directory.
 
o   If your application model needs to stream input or output from an
    ICLUI or user-defined class which does not define stream
    operators, you can define your own operators.  When you define
    operators you need to include a prototype statement in your .HPP
    file, or you will receive the message about INCLUDE\IBASSTRM.C.
 
    For example, if the .CPP file contains:
 
      IBaseStream& operator>>=(IPoint pt, IBaseStream& strm) {....}
 
    The .HPP file needs to contain:
 
      IBaseStream& operator>>=(IPoint pt, IBaseStream& strm);
 
 
2.9  Using the Editor
 
This section contains important information about using the Editor.
 
 
2.9.1  Usage Notes
 
o   In Windows 95, when entering characters using the Alt key +
    numeric pad, use Alt + 0 + the character code for the character
    you are entering.
 
o   In the Font selection window, some font selections will indicate
    the availability of extended font styles, such as Italics or Bold.
    The Editor ignores extended font style selections, and uses only
    the underlying (Regular) font.  To set additional font effects,
    use the Token Attributes window, available from the Options
    pull-down menu.
 
o   If the Editor window does not appear, or it is unusable when it
    does appear, erase the LPEX.ini file, then restart the Editor.
    The LPEX.ini file can be found in the directory where Windows is
    installed.
 
 
2.9.2  Known Problems
 
o   When using the Editor on Windows 95, certain character effect
    combinations such as bold and italics may not be readable in some
    fonts or font sizes.
 
o   On Windows 95, you cannot use the Save As dialog to save to an
    existing file on a remote HPFS drive.
 
 
2.10  Using WorkFrame
 
This section contains important information about using WorkFrame.
 
 
2.10.1  Differences from OS/2 and Restrictions
 
o   No project inheritance or Tool Setup is available.  Actions
    (tools), and types are defined in the product solution file, which
    is called vacpp.iws.
 
o   WorkFrame does not support user defined types.
 
o   Environment variables can be defined through the Project Settings
    notebook.
 
o   Options defined by using the option dialogs are stored on a
    per-project basis in the options file for the project.  The
    options file has the extension .iwo.  You can access the option
    dialogs using the Options pulldown menu in a project view. If you
    delete the options file, you can recover by using the editor to
    create a new options file.  Use the same file name with an
    asterisk for the extension.  Then use the options dialogs to reset
    your options for the project.
 
    Other project specific information e.g. project settings, is kept
    on a per-project basis in the project's project file.  The project
    file has the extension .iwp.
 
o   Note:  You should not directly change the above configuration
    files, such as the *.iws, *.iwp, and *.iwo files.
 
o   No drag and drop is available
 
o   A details view of the project is not available, but icon and tree
    views are supported.
 
o   Monitored actions are implemented through the Editor rather than
    WorkFrame.  The monitor is an Editor monitor, not a WorkFrame
    monitor.
 
 
2.10.2  Usage Notes
 
o   The IBUILD and IMKMK commands have been updated to remove the
    limit on the number of parameters they will accept. There is now
    NO restriction on the number of parameters for IBUILD and IMKMK.
 
 
2.10.3  Known Problems
 
o   In notebooks, the help that is displayed from the Help pushbuttons
    may depend on what has focus.  If a notebook tab has focus,
    sometimes no help is displayed from the Help pushbutton.  In most
    cases for the Options notebooks, holding down the left mouse
    button and pressing F1 over the notebook Help pushbutton will
    display general help.
 
o   Pressing F1 when focus is on a notebook tab sometimes changes
    notebook files instead of displaying help.
 
o   Keyboard navigation and accelerators don't work properly for some
    dialogs.
 
o   Opening options notebooks and changing options for two projects at
    the same time may cause problems.
 
o   If multiple .EXE files are selected to Run Monitored at the same
    time, only one of them will be run multiple times.
 
o   If the option to create a dependency file is specified, not all
    dependencies are put into this file; some are left in the
    makefile.
 
o   Occasionally when running on Windows 95, WorkFrame windows will
    not respond to the mouse.  To correct this, click on the desktop
    and then click on the WorkFrame window again.
 
o   When you use WorkFrame for several hours, sometimes you receive a
    warning about low virtual memory.  The log file for the monitor
    operations becomes too large.  To avoid the problem, you need to
    exit from the project monitor window occasionally.  The exit
    action erases the log file.
 
o   When you build and run applications that use HLP and INF files
    from WorkFrame, a problem exists.  The application seems to build
    correctly.  When you run the application, you receive a message
    saying that the HLP file and the INF file cannot be found.  You
    need to do the following.  In the WorkFrame settings, set the Help
    environment variable to point to the HELP subdirectory.  Then
    build and run your application again.
 
 
2.11  Using the Visual Builder
 
This section contains important information about using the Visual
Builder.
 
 
2.11.1  Known Problems and Restrictions
 
o   Part files (.vbb) from the OS/2 release can be loaded and saved
    under this release, but part files saved in this release cannot be
    loaded in the OS/2 release.
 
    When you load an OS/2 part file, Visual Builder asks you if you
    want to convert it to the Windows format.  If you answer YES to
    this message, the part file is converted and it will no longer be
    readable on OS/2.  If you want to keep a copy of your OS/2 part
    files, back them up before loading them into the Windows release.
 
o   When using the native details-view container, you will have
    problems selecting container columns other than column 1 directly
    from the free-form surface.  To edit the unreachable container
    columns, do the following:
 
    1.  Select the container.
 
    2.  Click mouse button 2.  The contextual menu for the part
        appears.
 
    3.  Select VIEW PARTS LIST.  The Parts List window appears.
 
    4.  Double-click the icon that represents the container column you
        want to edit.  The settings window opens for the part.
 
o   If you use container columns in a native Windows container, set
    the container to details view only.  Using any other container
    view might cause Visual Builder to close without warning, and you
    could lose unsaved updates to your part.
 
o   Situations exist where use of a native progress indicator
    sometimes causes the Builder to shut down.  To avoid this problem,
    set the pmCompatible style to ON to use the CUA progress
    indicator.
 
o   Minor changes have been made to the Visual Builder User's Guide
    since it was printed.  For the most current information, see the
    online version of the book.  The sections affected are as follows:
 
        Starting Visual Builder
        Learning to Use Parts
        Constructing Containers and Notebooks
        Hints and Tips
 
o   Minor changes have been made to the Visual Builder Parts Reference
    since it was printed.  For the most up-to-date information, see
    the online version of the book.  Portability information has been
    added to include features that are unique to Windows or ignored by
    the Windows compiler.
 
 
2.12  Debugging
 
This section contains important information about debugging.
N.B. The debugger shipped in the product is not supported on 
Windows 2000 
 
2.12.1  Usage Notes
 
o   To enable debug on demand, add the directory for your program to
    the PATH environment variable or start the program from its
    directory.
 
    To run debug on demand, enter the command:
 
      DOD path_name
 
    The User's Guide incorrectly states that you need to enter DOD
    path_name \idebug.
 
 
2.12.2  Known Problems on Windows NT and Windows 95
 
o   You cannot use the Step Over or Step Debug functions to step into
    a structured exception handling __finally block.
 
o   Attaching to the debugger itself causes unpredictable results.
 
o   For applications running under the debugger, asynch exception
    handling is disabled. If the application uses a signal to register
    an asynch handler, there is no way to detect the exception and
    invoke the handler.
 
o   Toggling breakpoints at an execution line clears all breakpoints
    on that line.
 
o   A stack entry is missed when you single step into a one line
    function, for example constructor code.
 
o   On Windows 95, the system hangs in one situation when a breakpoint
    is hit.  The situation is when you are debugging a GUI application
    and you resize one of the windows of the application.
 
o   On Windows 95, multithread application requires closing the
    debugger (F3) twice for complete clean up.
 
o   On Windows 95, make sure all change address breakpoints are
    deleted before closing the debugger. The system hangs if any
    change address breakpoint remains on the stack when the program
    being debugged runs to completion.
 
o   On Windows 95, not all exception signals are passed on to the
    debugger. For some illegal operations, the debugger is not able to
    catch the exception for the offending application.
 
o   Closing the application using the system menu, while the
    application is stopped by the debugger, produces unpredictable
    results on Windows 95.
 
o   Due to system limitation on Windows 95, the debugger is not able to
    step over certain system services such as WaitForSingleObject.
 
o   Some hexadecimal values may not be displayed correctly in the
    Character column of the Storage window. To fix this, set the
    LC_ALL environment variable to the ANSI locale (codepage) which
    corresponds to the country/language setting of your machine.
 
    For example, for US English:
 
    SET LC_ALL=En_US.IBM-1252
 
    You can find the correct locale name in the "Compiled locales
    supplied with VisualAge for C++" table in the Programming Guide.
    You should use the locale name whose number is in the range of
    1250 to 1257.
 
 
2.13  Using the Performance Analyzer
 
This section contains important information about using the
Performance Analyzer.
 
 
2.13.1  Usage Considerations
 
o   To activate file access tracing, do both of the following:
 
    1.  Link _KERNEL.LIB into your program.
 
    2.  Set environment variable PA FILEACCESS to ON.  (Note that the
        environment variable contains a blank.)  Performance Analyzer
        queries this environment variable each time it displays the
        Trace Generation window.
 
    When the file access tracing is activated and the traced program
    calls a Win32 function that uses a file handle, the Performance
    Analyzer keeps track of the file handle associated with the call.
    When the Performance Analyzer displays information about the call,
    it qualifies the Win32 function name with the associated file name
    in parentheses.  For example, in the Call Nesting diagram, the
    CreateFile function could appear as CreateFile(MyFile.dat).
 
    The Win32 functions that use file handles are:
 
    CloseHandle
    CreateFile
    FlushFileBuffers
    GetFileInformationByHandle
    GetFilePointer
    GetFileSize
    GetFileTime
    GetFileType
    LockFile
    LockFileEx
    ReadFile
    ReadFileEx
    SetEndOfFile
    SetFilePointer
    SetFileTime
    UnlockFile
    UnlockFileEx
    WriteFile
    WriteFileEx
 
o   If you are running a multithreaded application that creates
    threads after existing threads of execution have been terminated,
    the operating system may reuse the thread numbers that
    corresponded to the terminated threads.  If this occurs, the
    Performance Analyzer may report fewer threads than were actually
    executed.
 
o   If the object file containing the first executable function is not
    traceable, part or all of your application will run before the
    TRACE GENERATION window is displayed.  If this is the case, the
    Performance Analyzer will run to the first traceable function,
    halt execution, and then display the TRACE GENERATION window.
 
o   To enable the Performance Analyzer in WorkFrame do the following:
 
    -   The best way to enable the performance analyzer is to use the
        option in Build Smarts.  This will correctly set up both the
        compiler and linker options.
 
    -   Enabling the option in the compiler dialog will only turn on
        the compiler /Gh option, but will not add the required
        CPPWPA3.OBJ at link time.
 
o   The following feature is available but is not documented:
 
    When preparing a program for the Performance Analyzer, you can
    also compile with option /Tn+ (generate partial debug information)
    rather than option /Ti+ (generate complete debug information).
    The /Tn+ option usually produces smaller executables than the /Ti+
    option.  However, if you use the /Tn+ option, then the Performance
    Analyzer will not be able to determine the name sof the functions
    that have internal linkage.  These include non-member functions
    declared as static and functions declared as inline.  In the
    Performance Analyzer diagrams, these functions will appear as hex
    addresses.
 
 
2.13.2  Restrictions and Known Problems
 
o   The first function traced (usually main) cannot be set as a
    trigger or disabled.
 
o   Six system calls used by the Performance Analyzer are not traced
    in your program when the _KERNEL.DLL intercept library is used.
    These are: InitializeCriticalSection, EnterCriticalSection,
    LeaveCriticalSection, LoadLibrary, GetProcAddress, and
    GetCurrentThreadId.
 
o   After generating a trace file, you may not be able to erase or
    rebuild your executable while the Performance Analyzer is running.
    You may have to exit the Performance Analyzer and then rebuild
    your executable.
 
o   If your program contains a function preceded by an underscore (_),
    the Performance Analyzer will display the function without the
    underscore in the trace file.
 
o   The pattern recognition feature (on the CALL NESTING diagram) has
    the following limitations:
 
    -   The Performance Analyzer only searches for patterns in the
        first 32,768 events in the selected thread.
    -   The maximum number of patterns for which the Performance
        Analyzer searches is 8191.
 
    When the Performance Analyzer reaches either of these limits, it
    stops searching for patterns.
 
o   The compiler should only produce profile hooks for user-defined
    functions.  Currently the compiler produces profile hooks for
    several compiler-generated functions in addition to user-defined
    functions.  These compiler-generated functions will appear in the
    trace file as unrecognizable names made up of random characters.
 
o   If you are analyzing a C++ program in the DYNAMIC CALL GRAPH or
    STATISTICS diagram and select PROJECT > EDIT FUNCTION while a
    class or an executable is highlighted, the Performance Analyzer
    will not invoke the editor.  The Performance Analyzer will only
    display source code in the editor if the highlighted item is a
    function.
 
 
2.14  Using the Data Access Builder
 
This section contains important information about using the Data
Access Builder.
 
 
2.14.1  Prerequisites
 
o   There are no database prerequisites to run the Data Access
    Builder.
 
    If you want to use a DB2 database, you must install DB2 for the
    Windows NT or Windows 95 platform.
 
 
2.14.2  Usage Notes
 
o   An SVGA screen is recommended to run the idata tool.
 
o   Only 32-bit datasources are displayed in the database selection
    list.
 
o   The 32-bit Driver manager is \WINNT\SYSTEM32\ODBC32.DLL.
 
o   You do not have to use the "Register Database" option each time a
    database product is installed or removed.  This option is needed
    if you:
 
    -   Add DB2
    -   Remove DB2
    -   Go from none to at least one ODBC data source
    -   Go from at least one ODBC data source to none
 
 
2.14.2.1  Using the IDatastore Class in a Windows NT Application
 
You must do the following if your application uses the IDatastore
class on any database other than the one which you used for the Data
Access Builder to generate the code.  You must bind the file
CPPWACL2.BND to all the databases accessed by your application.  This
allows IDatastore to connect, disconnect, and complete transactions
against the database.
 
To bind the file, enter the following commands:
 
  DB2START
  DB2 CONNECT TO database
  DB2 BIND D:\IBMCPPW\BND\CPPWACL2.BND
  DB2 TERMINATE
 
where database is the name of your database and D:\IBMCPPW is the path
where you installed the code.
 
 
2.14.3  Creating a SOM library of Multiple Classes
 
A C procedure called SOMInitModule is implicitly generated during SOM
code generation when you check the makefile option or the automatic
link option. These two options imply that a SOM DLL, which requires
the existence of this procedure, is created.  If you do not want to
create a SOM DLL, make sure that the options are not checked. If not,
you will receive multiple definition errors for this routine when
linking multiple SOM OBJ files together.
 
 
2.14.4  Features
 
o   Data Access Builder also supports the following ODBC drivers:
 
    -   dBase
    -   Excel
    -   SQL Server
    -   Text
 
    For configuration information for the above drivers, use WINHLP32
    to view the driver's HLP file, that is found in the
    \ibmcppw\odbc32 or \ibmcppw\odbc16 directory.
 
    For example, for information on the dBase driver, type:
 
         winhlp32 ibdbf08.hlp
 
o   A new "Save window size" option is added to the View pulldown
    menu.  The option restores the size and the position of the Data
    Access Builder on restart.  The option is off by default.
 
o   On Windows 95, use the 'clean95' option in the generated
    makefiles, rather than the 'clean' option which should be used on
    Windows NT.
 
 
2.14.5  Known Problems
 
o   Data Access Builder is limited to accessing a finite number of
    tables (in the order of tens of thousands, depending on virtual
    memory size), in any one database.  If you access a database with
    more than this number of tables, tables after the limit will not
    be displayed in the tables listbox.  Aliasing these tables so that
    they appear closer to the beginning of the list of tables does not
    provide a workaround; a trap will occur when you try to generate
    classes.
 
    To avoid this problem, use the filter provided in the Create
    Classes dialog to view a subset of the tables according to their
    owner, name, and type.
 
o   If an invalid class or attribute name is entered in the class
    settings notebook, the previous value is restored as designed, but
    no warning is issued.
 
o   If a data identifier is mapped to a nullable column, database
    operations with the data identifier set to null will not work.
 
o   The help button on the class settings notebook does not work when
    the notebook page has focus.  Use the F1 key to obtain the help
    for the page.
 
o   After creating a class, the mouse pointer remains in the busy
    state until the mouse is moved.  Move the mouse after creating a
    class to exit the busy state.
 
 
2.14.6  Known Problems on DB2 That Affect the Data Access Builder
 
o   Loading tables with a foreign key column name greater than 15
    characters will cause the Data Access Builder to crash.
 
o   DB2 user-defined types based on character types are not mapped
    correctly.
 
o   DB2 maps DECIMAL to the C/C++ data type double which may result in
    round-off errors and loss of precision.  Data Access Builder also
    maps DECIMAL to the date type double.
 
 
2.14.7  Using the Data Access Builder with the AS/400
 
o   We recommend using the OWNER field while filtering.  The owner
    field must be specified in UPPER CASE.
 
o   AS/400 does not yet support Windows NT Japanese version code page
    943.
 
    As a work around, set the DB2CODEPAGE environment variable to 932
    before trying to connect to the AS/400.
 
o   You must create a collection named NULLID on the AS/400 system.
 
o   If you are using a US/ENGLISH system with code page 1252 and you
    are interacting with a V3R1 AS/400 System, then you must load PTF
    SF24582 onto the AS/400.
 
    1252 is the default code page for US/ENGLISH systems.
 
    1252 cannot interact with AS/400s supporting V2R3.
 
    In this case, you should change the DB2CODEPAGE environment
    variable to 850 before connecting to the AS/400 system.
 
 
2.15  Using the Browser
 
This section contains important information about using the Browser.
 
 
2.15.1  Known Problems
 
1.  When printing on Windows 95, if you have your printer configured
    to print to a file, a Print To File dialog will be shown to prompt
    you for the file name.  This dialog will show beneath other
    windows, but you can access the dialog from the Task bar or you
    can move the other windows aside.  Enter the file name and the
    Browser continues with the printing request.
 
 
2.15.2  Permanent Restrictions
 
1.  You can use PDB files generated by the VisualAge C++ for OS/2
    version 3.0 product in this Browser.  You cannot use PDB files
    generated by VisualAge for C++ for Windows and use them on OS/2,
    nor can you use PDL or PDE or PDD files across systems.
2.  If you browse a program that contains .OBJ files created from C
    source files, the Browser Files Dialog informs you that the .PDB
    files for the C files cannot be found.  Ignore this message and
    select the Load button.  Note that no Browser information exists
    for the C files.
3.  If you choose to Generate Browser information, the compiler
    creates a PDB file even if the compilation fails.  The file
    sometimes contains incorrect data.  The browser cannot always
    detect this problem.
4.  In the list of file names that are fully-qualified, the list
    contains the names after compilation and not necessarily the names
    on your system.  For example, if you List All Files in any of the
    VisualAge for C++ libraries, the files may appear to be located in
    C:\IBMCPPW.  If the browser cannot find the files it searches the
    path defined in the Browser Settings notebook.
5.  The browser loads all the information from a program (.EXE or
    DLL), including information from any LIB files used.  If the
    project that builds the .EXE or DLL does not contain the project
    that builds the LIB file, the Refresh function in the Browser
    cannot refresh the information and the information is not
    displayed.
6.  If you load some browser information with QuickBrowse and some
    with compiler-generated .PDB files, you sometimes get the message
    "An error occurred while loading the file filename.pdb".  Either
    delete the .PDB files and load only QuickBrowse information, or
    rebuild your project to generate .PDB files for all of your source
    files.  If the problem persists, contact VisualAge for C++ Service
    and Support.
7.  QuickBrowse does not correctly identify SOM classes.
8.  If you try to run the Browser on the executable files for the
    VisualAge for C++ sample projects, you may see the message "Will
    not QuickBrowse the following files after analysis of the make
    file."  If you see this message, choose Cancel, exit the Browser,
    and the do one of the following:
    o   Rebuild the project.
    o   Rename the target of the project.
    o   Delete the target of the project.
 
    You can then browse the project.
9.  Due to the 16-bit GDI coordinate system used by Windows 95, the
    Browser is unable to render highly complex graphs that can be
    rendered on OS/2 or Windows NT. If the Browser encounters such a
    situation, a message is displayed, and possible workarounds are
    suggested in the on-line help for the message.  Unfortunately,
    there will be some complex graphs which cannot be displayed on
    Windows 95, even after all workarounds have been tried.
 
 
2.16  SOM
 
This section contains the important information about using the SOM
toolkit.
 
 
2.16.1  Known Problems
 
o   When using the DTS hh emitter:
 
    -   Sometimes it generates duplicate constructors.
    -   Sometimes it causes a runtime heap error R6018.
 
o   The following code causes an access violation on Windows NT:
 
         SOMClass * pClass = NULL;
         somId aClassId = somIdFromString( "MyClass");
         Class = SOMClassMgrObject->somFindClsInFile(aClassId, 0, 0, "mydll");
 
 
3.0  Samples
 
This section contains important information about using the samples.
 
 
3.1  General Information
 
 
3.1.1  Usage Notes
 
Because all samples are enabled for Performance Analyzer, CPPWPA3.DLL
must be present to Run the sample and CPPWPA3.OBJ must be present to
Build the sample without errors.  These objects are automatically
installed if you install the Performance Analyzer component.
Otherwise, copy the CPPWPA3.DLL from the /BIN directory and the
CPPWPA3.OBJ from the /LIB directory of the CD-ROM to the corresponding
directories on your system.
 
Copying CPPWPA3.DLL and CPPWPA3.OBJ simply allows you to invoke Run
and Build without errors.  To use the Performance Analyzer or any
other component with the samples, you must install those components.
 
 
3.2  SOM/WorkStation DSOM Samples
 
This section contains important information about the samples.
 
 
3.2.1  Known Problems and Restrictions
 
o   The Build Notes give you a generic description, which is different
    from the way the samples are built. You need to consult the
    individual readme.txt files for specific information.  Click on
    the "View Readme" selection box to see the readme file in an
    editor. Also, refer to the rest of this section for additional
    information.
 
o   Building and Running Samples: General Information
 
    -   Sometimes problems exist when VisualAge for C++ is installed
        in an environment that has another compiler already installed.
        Check your PATH, INCLUDE, and LIB environment variables to
        ensure that you are using the correct executables, include
        files, and libraries.
 
    -   Selecting the "Project/Build Normal" will not work because
        WorkFrame does not currently  support rules for compiling IDL
        files.  Instead, you need to select "Project/Make" to use the
        makefile "vac.mak" that has been supplied. Or you can right
        click on "vac.mak" and choose "make" from the pop-up menu.
 
    -   Only "Project/Make" and "Project/Run" are supported by
        WorkFrame.
 
o   Building and Running Samples: Sample Specific Information
 
    -   ALL DSOM SAMPLES (location:  samples\som\somd\cpp\* )
 
        After running each WorkStation DSOM sample, you need to kill
        the daemon "somdd" before you can run another sample.  Close
        the window where somdd is running.
 
    -   Event (location:  samples\som\somd\event )
 
        There is a potential race condition in starting the four
        interacting programs for this sample.  You can start the
        programs manually by executing the commands in run.bat one at
        a time from the Project Monitor or from the command line.
 
    -   If the client for a DSOM sample is invoked without starting
        the daemon or server first, the client hangs and cannot be
        terminated by a CTRL-C.
 
        It has to be terminated explicitly from the "Task Menu" by
        invoking "End Task".
 
4.0  This section contains important information pertinent to version 3.5.9
     which includes a new version of Microsoft SDK. 

4.1 IBM Open Class
This package contains fixes for the Open Class component of VisualAge C++
for Windows, version 3.5. 

This fix pack level makes use of a more recent version of the MS SDK.  Due 
to some SDK changes we needed to implement various changes to Open Class 
(see below).

The following list of items describes the change made to Open Class since the
last official Fixpak WTO356:

4.1.1  All open class applications will require the /DNO_STRICT compiler option
     or have an Open Class header defined before the MS headers.  
     This change may require a change to the users build procedure if an Open
     Class header is not first in the list.  The error message you will get
     when you compile is: 
       Error: Use of IBM Open Class Library requires /DNO_STRICT compiler option.

     If you get this error message, please add the "/DNO_STRICT" compiler option
     to your make or build file and try again.

4.1.2 MS COM interface class IFont has been renamed to:  __IWinFont
     Be advised that if you need to inherit from the MS version of IFont, you
     should use __IWinFont.

4.1.3 The IFileDialog class now includes a new style, IFileDialog::explorer.
      The new style can be used to create "Windows Explorer" file dialogs. 
      This style is not on by default, but to make it so, add the following
      in the begining of your "main()" function:
      IFileDialog::setDefaultStyle( IFileDialog::classDefaultStyle |
                                    IFileDialog::explorer );
      Using the "Windows Explorer" file dialog has one side effect. 
      The IFileDialog::Settings::setPosition() function becomes a NO-OP on Windows.
      This is because the "Windows Explorer" file dialog is always
      positioned at 0,0 (top left corner) of the owner frame's client area.

4.1.4 IFileDialog will now present a Windows 2000 compliant Dialog box if you are
      running on Windows 2000 and have specified the IFileDialog::explorer style 
      mentioned in point 4.1.3 above.

4.1.5 The IFileDialog::Settings class includes a new function to add file types
      in the filter list.  The signature of the function is same as the function
      included with IBM OpenClass found in VAC++ v4.  Basically the new function
      is as follows:
      IFileDialog::Settings& IFileDialog::Settings::addFileType(
                    const char* fileType, const char* filter=0)

     Here is an example of using this function:
     IFileDialog::Settings settings;

     settings.setOKButtonText( "Open" );
     settings.setTitle( "Select file to view" );
     settings.addFileType( "Object Files (*.obj)", "*.obj" );
     settings.addFileType( "Source Files (*.c, *.cpp)", "*.c;*.cpp" );
     settings.addFileType( "Header Files (*.h, *.hpp, *.inl)", "*.h;*.hpp;*.inl" );
     settings.addFileType( "All Files (*.*)", "*.*" );
     IFileDialog sampleDialog( IWindow::desktopWindow(), 0, 
            IFileDIalog::defaultStyle,
           settings );
              ....

     Both the 'fileType' and 'filter' must be specified (non NULL) for the filter
     to be added.  Multiple filter extensions can be specified as long as they are
     separated by semicolors (';') as shown above.

4.1.6 PM Compatible Container Changes
     There were changes made in the IContainerControl::objectUnderPoint() function
     in post fixpack 62, which is FP6 with level 2 changes.
     Consideration must be taken when calling this function for pmCompatible 
     containers in details view.  For these type of containers, the point must be
     relative to the details view window and not the container.  Having a
     mouse handler or menu handler attached to the container, and calling
     the IMouseEvent::mousePosition() or IMenuEvent::mousePosition() will
     result in the correct point being returned.

     However, mapping a point from desktop coordinates to the coordinates
     required by IContainerControl::objectUnderPoint() you will need to do
     something like the following:

   IContainerControl* ctrlWin;     // The container control
   IPoint pos;                     // The current mouse position in
	                                   // desktop coordinates.

   IPoint pt = IWindow::mapPoint( pos,
                              	  IWindow::desktopWindow()->handle(),
               	                  ctrlWin->handle() );
   //
   // Adjust the point if in details view and it's
   // PM compatible.  This is to account of the
   // change in the IContainerControl::objectUnderPoint
   // function.
   //
   if ( ctrlWin->isPMCompatible() && ctrlWin->isDetailsView() )
   {
     // If origin lower left we need to add the height of the
     // cnr title otherwise we subtract.
     IPair::Coord coef=-1;
     if ( ICoordinateSystem::isConversionNeeded() )
       coef=1;

     if ( ctrlWin->areDetailsViewTitlesVisible() )
       pt.setY( pt.y() +
               coef * ctrlWin->detailsTitleRectangle().height() );
	
     if ( ctrlWin->isTitleVisible() )
       pt.setY( pt.y() +
                coef * ctrlWin->titleRectangle().height() );
   }


4.2 Makefile changes

   In the version of Microsoft Platform SDK supplied with this release, the files:

   include\BkOffice.Mak
   include\Copyfile.Mak
   include\INetSDK.Mak
   include\Win32.Mak

   contain structures:

   !ELSEIF

   !ELSE IFDEF

   which are not recognized by the nmake supplied.

   If you have makefiles that include any of these, then you will need to modify them to the two line structure:

   !ELSE
   !IF
 
   !ELSE
   !IFDEF

   and add the corresponding !ENDIF.


4.3 Win32 SDK Online Help
   Win32 SDK Online Help in the User Guides of Online Information is inoperable.
   Please see "Platform SDK Documentation" of "Microsoft Platform SDK"

4.4 Known problems
  4.4.1 On Windows 95, termination of Visual Builder causes a memory fault.

5.0  Documentation
 
This section contains important information about the documentation.
 
NOTE:  The online versions of the documentation are more current than
the PostScript publications.
 
To view the publications online, open the icon representing the Online
Information Notebook, select the radio button for a publication, and
click on the View pushbutton.
 
 
5.1  Printing
 
 
5.1.1  Known Problems With Printing
 
o   Problems exist with printing because of the large amount of
    printer memory required to load the large files.  If you do not
    have enough printer memory, you cannot print the large files.
 
 
5.1.2  How to Print
 
To print the PostScript files on a workstation-connected PostScript
printer, copy the file to the printer destination.  The required fonts
are imbedded in the files.  You can also print these files on a
host-connected PostScript printer; make sure you upload them in binary
format.


