IBM VisualAge(R) C++ Professional for OS/2(R), Version 4.0 - README
-------------------------------------------------------------------

IBM VisualAge(R) C++ Professional for OS/2(R), Version 4.0
(C) Copyright IBM Corporation 1991, 1998 - All Rights Reserved.

US Government Users Restricted Rights - Use, duplication or disclosure
restricted by GSA ADP Schedule Contract with IBM Corp.

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

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.

Microsoft, Windows, and Windows NT, are trademarks or registered trademarks of Microsoft Corporation.


Contents
========

TUTORIAL
NEW INFORMATION
DBCS (Double Byte Character String) NOTES
TECHNOLOGY PREVIEWS

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

TUTORIAL
________

o We recommend that you review the Tutorial included with this product to familiarize yourself with the IDE. To access the Tutorial, select the Help Home Page from the VisualAge C++ Professional 4.0 program group and click on "Tutorial".

NEW INFORMATION
_______________

This section contains information about new functions and known problems.

Migration
=========
o MAKE2CFG automatically adds a number of options for compatibility in building pre-existing code in the option group "compatibility_options". However, this does not include all the options necessary for building with the IBM Open Class (IOC) libraries, such as gen(rtti,yes). If IOC libraries are used in the project, refer to the IBM Open Class Libraries section below for a list of the options that must be present in the configuration file.

o MAKE2CFG converts all rules that are in the makefile. It filters the "clean" rule into a separate clean.icc file but other rules that perform a similar function will be present in the regular .icc files. The run directives for these commands should be removed or the "run" can be changed to "run cleanup" so that the command is only performed during a cleanup rather than during a regular build.

o MAKE2CFG will not successfully migrate a makefile if you specify only some targets to be built. For example:
nmake -f appl.mak appl.exe
builds appl.exe using rules from appl.mak. You cannot produce a configuration file for building only appl.exe using make2cfg -f appl.mak appl.exe. Attempting this will result in an error. Instead, do not specify the target, then remove unwanted targets from the produced configuration files.

o You can use DLLs built with the IBM C/C++ Compilers Version 3.6 product with this product. You must use DLLRNAME to rename the DLLs to the appropriate "Forwarding" DLLs. For example, if your DLL is called SERVICES.DLL, and it was built using the /Gm+ flag, run the following command:
DLLRNAME SERVICES.DLL CPPRMI36=CPPZM40I
If your DLL was built with /Gm- (single-threaded), run:
DLLRNAME SERVICES.DLL CPPRSI36=CPPZS40I
If your DLL was built with the /Ge- /Rn options, you cannot use this DLL with the DLLs built with this product.

o To use DLLs build with VisualAge C++ Versions 3.0, or 3.5, see the online documentation. Search for "cppws35i".

o DBCS note: the Configuration Exporter does not handle DBCS filenames when exporting to makefiles.

IDE
===
o To avoid color palette problems while running the IDE and Netscape simultaneously, do one of the following:

1) If your video card is capable of displaying more than 256 colors at your desired resolution, select either 65536 or 16777216 colors in the System setup. A reboot will be required before the setting takes effect.

2) In Netscape, select Options->General Preferences->Colors and disable the "Palette Aware" check box.

3) If color palette problems persist, try disabling "Workplace shell palette aware" checkbox in OS2 System setup under the "256 Colors" tab.

o The IDE will display, and parse, source views based upon the extension of the file being viewed. The new ANSI Standard Template Library header files shipped with VisualAge C++ Professional do not have a file extension. For instance, the file "algorithm", is a C++ header file, yet when viewed in the IDE is not parsed as a C++ file. If you wish to have these files parsed as C++ source then do the following

In the macros directory of the installed product
'copy lpex.lxl oldlpex.lxl'
'copy cpp.LXL lpex.lxl'

WARNING: This changes the behaviour for files without default extensions so files like 'makefile' will be parsed as C++ source files, which may not be the behaviour that you want.

Configuration Optimizer
=======================
o When running the configuration optimizer (COT), compile errors may be reported. This may be due to changes the configuration optimizer makes to your configuration file (.icc). Part of the configuration optimizations made by this tool involve automatically promoting system run-time header files that are #included in your application. In some cases this may cause incorporation errors if these runtime header files contain a reference to a macro name that is defined in your application header files.

There are two ways you can resolve this problem: 1) Edit the new configuration file and manually promote your application header file to precede the system header file. 2) Edit the new configuration file and enclose the promoted system header file with the necessary options to define the macros it requires. We recommend you use the latter approach. Here is an example of the problem and the two possible solutions.

t.cpp                  t.h                             t.icc (COT generated)
******                 ***                             **********************
#include "t.h"         #define _OS_LEVEL 0x0400        target "t.exe"
#include                                   {
                                                        option macros(global,yes)
                                                         { 
                                                          source type(hpp) "sys\types.h"
                                                         }
                                                        source type(cpp) "t.cpp"
                                                       }

t.icc (solution1)                    t.icc (solution2)      
*****************                    *****************
target "t.exe"                       option define("_OS_LEVEL","0x0400")
{                                    {
 option macros(global,yes)            target "t.exe"
  {                                    {
     source type(hpp) "t.h"             option macros(global,yes)
     source type(hpp) "sys\types.h"      {
  }                                       source type(hpp) "sys\types.h"
 source type(cpp) "t.cpp"                }
}                                       source type(cpp) "t.cpp"  
                                       }
                                     }

Debugging
=========
o You may, in rare circumstances, experience problems using the "Set Function Breakpoint" operation on a function. If you set a function breakpoint, and the IDE does not stop in the function, set a statement breakpoint on the first statement in the function and try again.

o Step debug has been provided with a timeout. If the step debug operation has not completed within the timeout, the debugger will stop. If the step-debug started from a source line, then it will instead do a step over and stop. If not, it will stop immediately. The default timeout is 10 seconds. The timeout can be set with the environment variable "MAXIMUM_DEBUG_STEP". For example, "SET MAXIMUM_DEBUG_STEP=55" will set the timeout to 55 seconds.

o The debugger will display MMX registers, even if the debuggee machine does not have an MMX installed.

o When you are debugging a PM application locally, the debugger must process PM messages on behalf of the debuggee when the debuggee is stopped. This may cause unusual or unexpected behavior in the debuggee when debugging code that handles mouse movement, menus, window focus, and the like. The debugger does not handle PM messages for the debuggee when debugging remotely.

o When using gen(debug) to compile C source code to produce object files containing debug information, or using link(debug) to generate targets containing debug information, for your C applications, you cannot use any previous debuggers. Specifically, idebug (from VisualAge for C++ for Windows, Version 3.5) cannot be used to debug such applications. The debugger from the IBM C and C++ Compilers Version 3.6.5 is required to debug these applications.

Data Access Builder
===================
o The access app forms generated by DAX can be edited in the Visual Builder. However if DAX is re-launched and the session saved, the forms will be resaved, and your customized changes will be lost.

o If a parameter type is unknown to the compiler when an SQL statement is validated, the SQL type will be marked as 'UNKNOWN'. The user must then choose the proper SQL type from the combo box that shows the type. This will work properly, but if the type requires a length or precision and scale values, there is currently no way to enter this information. The resulting generated code will not work because of the missing information.

o Refer to the Data Access Builder online HTML help for information on building and running the Database samples.

o The Database mini-samples are easily rebuilt using the REBUILD.CMD files in each of the directories.

o For the Data Access Visual Sample (DB2 ESQL Versions Directory), VisSamp.exe can be compiled successfully from the command line. However, after you build this application, if you want to load the VisSamp.icc project into the IDE, before you do so, you must manually delete the VisSamp.ics file. After you open this project in IDE, you need to rebuild the project. This workaround applies to all Data Access Visual Embedded SQL projects.

o Mapping an SQLCHAR of length 1 from the database to the C++ type 'char' may not do what you expect. ODBC will convert the contents of the database column to a numeric value. For example, if the database value was the character '7' then the char value in the C++ class would be 0x07, not the ASCII code for the character '7'. If you map the column to an IString instead, you will get a string of length one.

o Under DB2, User Defined Types (UDTs) may sometimes incorrectly return a length value of zero. OS/2 Fixpack 8180 addresses this problem and is available at:
ftp://ftp.software.ibm.com/ps/products/db2/fixes/english-us/db22v21/us8180

o You must be logged on to a userid that has database access privileges for DB2 for ESQL (embedded SQL extension), for the DB2 precompiler to be called. If you are not logged on with a userid that has sufficient access privileges, then the precompilation step will fail, and the DLL will not be built.

o If you are connecting to DB2 UDB (DB2 Version 5), and you need to use multiple connections to the same or different databases, then you must install DB2 UDB fixpak 2.

o If you are migrating a Data Access/Visual Builder application from VisualAge for C++ for OS/2, Version 3.0, promoted IString attributes of Data Access parts will not migrate correctly. To fix them, use the Visual Builder and delete the promotions and re-promote the attributes.

o For the mapping of ODBC SQL (and DB2 CLI) data types to C++ data types, see the ODBC Data Type Conversion Table in the online information.

o When using a method that calls a stored procedure that has a DATE parameter, you may encounter problems executing the call at runtime depending on the database you are using and whether the parameter type is IN, OUT, or INOUT.

o When you migrate a Data Access Builder session (.DAX file) created in VisualAge for C++ Version 3.5 (on NT) and Version 3.0 (on OS/2), if this dax file contains mappings for Views, then you need to make the following modification after migration:
1. Migrate the .dax file that is created in previous version of VisualAge C++ to VisualAge C++ Professional 4.0.
2. Start Data Access Builder from the IDE, and for each attribute in the mappings for Views that is a data identifier, right click on it and select "Properties" and then uncheck "Data Identifier".
3. Save the DAX session.

o When Data Access Builder imports a .DAX file from VisualAge for C++ Version 3.5 (on NT) and Version 3.0 (on OS/2), all attributes for Decimal datatype may be incorrectly mapped. To correct this, start the Data Access Builder and for each attribute in the mappings that failed to compile, right click on it and select "Properties" and then change the Type from "IBinaryCodedDecimal" to "double".

o Mapping of BLOB (binary large object) and CLOB (character large object) datatypes that are located on same column in separate tables may result in compilation error. For example, Table 1 has BLOB in 3rd column and Table 2 has CLOB in 3rd column. Then if you map these 2 tables and proceed with compilation, it may result in a compilation error. The workaround for this problem is to avoid mapping these two tables in the same DLL or executable. Mapping of BLOB and CLOB in the same table is fine.

Visual Builder
==============
o Starting the Visual Builder using IVB from the command line is not supported. VBF files created through this mechanism will not be compatible with Version 4.0 projects.

o Packaging multiple parts in a file -- You can only export 1 part into a part interface file (.vbe file) from the IDE. If you want multiple parts to export their interface into 1 interface file, you must follow these instructions:
To indicate that there are multiple parts in the file, you can define an informational part as the first part in the file. See the vbcc.vbe and vbmm.vbe files in the ivb directory for examples of informational part definition. Specify the noAdd constraint for the informational part to prevent its use in the Composition Editor. All other parts in the file are available in the Add Part window.

o In some situations, builds containing Visual Builder Parts leave the codestore file locked. This can result in a subsequent build of the same project, or a build of a second Parts-based project to fail. If this happens, exit the IDE and end the IVB.EXE and CPPVBB40.EXE processes. Your builds will now be successful.

o Window ID -- A window that is a client of a frame window requires the ID of IC_FRAME_CLIENT_ID. Although the ID property can be altered, VisualAge ignores the setting and sets the property to the required ID.

IBM Open Class Libraries
========================

Bidirectional Language Support
------------------------------
Detailed information regarding support of bidirectional languages in Open Class can be found on the support page of the VAC++ web site.

IImage Class
------------
If you create an IImage object from an IGImage object, the creation should be treated as an adopt, and as such, the IGImage should not be explicitly deleted. (ie. IImage will take care of the deletion).

Compiler directives
-------------------
o All Projects using IOC must have the following lines in their configuration file for the project.
See any of the .icc (configuration) files in IOC Samples for an example.

       gen(rtti,yes)
       lang(nokeyword,"bool")
       lang(nokeyword,"true")
       lang(nokeyword,"false")

       link (linkwithmultithreadlib)
       link (subsystem,PM)        //for GUI applications //

IString Update
--------------
o To optimize the IString+= operation, the IBuffer/IDBCSBuffer class now allocates memory in 32-byte chunks. To turn this optimization off, you can set the static boolean IBuffer::is32BytesAligned to false. By default, if IBuffer::setDefaultBuffer() is called, the boolean is set to false unconditionally.

DBCS (Double Byte Character String) NOTES
_________________________________________

o When using the English version of VisualAge C++ on a DBCS language environment (such as OS/2 V4.0J), you need to change the LANG environment variable in SETENV.CMD (for OS/2) manually. (If you don't make this change, you may not build DBCS application correctly, because the compiler assumes an English environment.)

o To access Graphic Data type via UDB ODBC driver, we need to set PATCH1 and PATCH2 in db2cli.ini. See the detailed information at http://www.software.ibm.com/data/db2/java/dbcsjava.html

HTML Documentation
==================
o Search Limitations for Single Byte Search (English only): Sometimes simple search queries can return incorrectly ranked results. For instance, if you simply type 'IFrameWindow' into the search form you will see results from the class description, but these results may be ranked lower than less relevant documents. That's because, by default, the search engine is set up for "fuzzy" searches: more complex queries that include word stemming for different variants of a word or a phrase. For best results in these cases, scope your searches by picking the appropriate category of information (like "IBM Open Class Library"). For even more control over results ranking, precede your search term with a plus sign and surround the term with quotation marks (for example, +"IFrameWindow"). Select "Exact" instead of fuzzy search from the drop-down box on the search form. For more details, see Search Help available from the search page.

TECHNOLOGY PREVIEWS
___________________

The following components are available for use in the VisualAge C++ Professional, Version 4.0 product as a Technology Preview:

o Components of the VisualAge C++ Integrated Development Environment:
-3D Inheritance View
-Performance Analyzer
o Tivoli Development Toolkit and Connection Parts (not available on OS/2)

See the International Program License Agreement and License Information for the VisualAge C++ Professional, Version 4.0 product for additional terms and conditions regarding these components. Support for these components will not be provided.

To install the IDE Tech Previews, you must select 'IDE - Tech Preview' from the list of features to install.

For more information on the Performance Analyzer Technology Preview, see the file TECHPREV\readme.pa.

The 3D Inheritance View adds an additional page to the IDE, called the "Perspective Overview", containing a new view, the "3D Inheritance View" where the class hierarchy can be browsed in 3 dimensions.