IBM VisualAge C++ Professional for Windows NT, Version 4.0 FIXPAK 3 IBM VisualAge(R) C++ Professional for Windows NT(R), Version 4.0 (C) Copyright IBM Corporation 1991, 2000 - All Rights Reserved. (C) Copyright IBM Corp and another 1991, 2000 - All Rights Reserved. (C) Copyright Microsoft Corp. 1985, 2000 - 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, Windows 2000, and Windows NT, are trademarks or registered trademarks of Microsoft Corporation. -------- NOTE: -------- New information lines are prefixed with "*** " except for the section on "IBM OPEN CLASS LIBRARIES" which contains many changes/additions. Installation ------------ *** To install this Fixpak perform the following steps : *** (1) Reboot your machine. *** (2) Unzip the Fixpak into a temporary directory. The unzipped Fixpak occupies about 360M bytes. *** (3) Make sure you are currently in the directory into which the fixpak was unzipped. *** (4) Issue the following command : SETUP *** (5) Follow the instructions carefully. This Fixpak uninstalls the old product before installing itself. *** (6) Reboot the machine. 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 in the Windows NT Start menu, and click on "Tutorial". You can also access it by selecting "Tutorial" on the Help menu in the IDE. NEW INFORMATION _______________ This section contains information about new functions and known problems. SUPPORTED PLATFORMS =================== *** This fixpak enables the product to run on and produce code for *** Windows 2000. It contains the Windows 2000 SDK. IDE === 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. 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. To use DLLs built with VisualAge C++ Versions 3.0, or 3.5, see the online documentation. Search for "cppws35i". o The configuration file exporter does not handle DBCS filenames correctly when exporting icc files to makefiles. The DBCS filenames sometimes get mangled. Configuration Optimizer ======================= o If you are programming with the "winsock2.h" header file, and you perform a Configuration optimization (in the IDE via Tools->Optimize Configuration), you may receive errors like: "The macro name "FD_SET" is already defined with a different definition". You can correct this by adding source type(cpp) "winsock2.h" to your configuration file anywhere prior to source type(cpp) "windows.h" Lastly, remove the line tools "config_opt" Then do a build. 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 ***** #include "t.h" #include t.h *** #define _WIN32_WINNT 0x0400 t.icc (COT generated) ********************* target "t.exe" { option macros(global,yes) { source type(hpp) "windows.h" } source type(cpp) "t.cpp" } t.icc (solution1) ***************** target "t.exe" { option macros(global,yes) { source type(hpp) "t.h" source type(hpp) "windows.h" } source type(cpp) "t.cpp" } t.icc (solution2) ***************** option define("_WIN32_WINNT","0x0400") { target "t.exe" { option macros(global,yes) { source type(hpp) "windows.h" } 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 The debugger will display MMX registers, even if the debuggee machine does not have an MMX installed. o Step debug has been provided with a timeout. If the step debug operation has not completed within the timeout, the step will terminate immediately. You can then step-debug again to continue the operation. 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 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. o When using the debugger on a machine running Windows NT 4.0, service pack 3, with QA Partner installed, you may see access violation exceptions occur as the debuggee application starts up. These exceptions are part of the normal startup of QA Partner on NT 4.0. Either: -disable access violation exceptions, and run the exceptions, or -select "run exception" for these exceptions (there should normally be only 3 or 4 of them) o When running a debuggee remotely on Win98, the debugger-initiated heap-checking functions will hang the debuggee. Both the "Check the Heap" and "Enable Automatic Heap Checking" functions fail. This does not affect heap checking initiated by the debuggee. The debugger will notify you of heap problems should the debuggee detect them at a heap call. 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'. You 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 You cannot build the Data Access Builder DB/2 Samples without having DB/2 installed. The IDE will trap if DB/2 is not installed. o The Database mini-samples are easily rebuilt using the REBUILD.BAT 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. This problem is fixed in DB2 FixPak U449586 located at: ftp://ftp.software.ibm.com/ps/products/db2/fixes/english-us/db2ntv21/ us8135/, for DB2 Windows NT Server, and at: ftp://ftp.software.ibm.com/ps/products/db2/fixes/english-us/db2ntv21/ us8136/, for DB2 Windows NT Client. 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++ Version 3.5, 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 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 Windows NT) and Version 3.0 (on OS/2), if this file contains mappings for Views, then you will need to manually make the following modification after migration: Step 1. Migrate the .dax file that is created in previous version of VisualAge C++ to VisualAge C++ Professional 4.0. Step 2. Start Data Access Builder from 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". Step 3. Save the Data Access Builder 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 errors. For example, if Table 1 has BLOB in 3rd column and Table 2 has CLOB in 3rd column, mapping these 2 tables and proceeding with compilation may result in a compilation error. The workaround for this is to not map these two tables in the same DLL or executable. Mapping of BLOB and CLOB in the same table does not result in an error. o Samples requiring DB2 such as the db2cli and db2esql samples will only build and run if DB2 client and the DB2 SDK is installed on your machine. Similarily ODBC samples such as VisSamp will only build and run if the ODBC SDK is installed on your machine. 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 VisualAge C++ Version 4.0 has created a third choice for *** property type when mapping a DAX BLOB field: IDABlobDO. The *** other choices for property type are IString (default) and char*. *** Please refer to the Data Access Builder online HTML help for *** information on IDABlobDO. *** o In addition to the DLLRNAME exceptions listed in the file *** "Redistr.txt", the following exception exists for DAX DLLs: *** -If you rename \Programs\IBM\Runtime\cppa**40.dll, then only the *** 5th and 6th characters of this renamed DLL can be changed (eg. *** CPPAxx40.DLL) Visual Builder ============== 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, go to the NT Task Manager, 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 ======================== Compiler directives ------------------- 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,WINDOWS) //for any GUI applications // Bidirectional Language Support ------------------------------ Conflicts in the bidi support provided by Open Class and that provided by the operating system result in the following limitations: - Controls created with the pmCompatible style of the IContainerControl, INotebook, IProgressIndicator, and IBaseSpinButton classes are not bidi-enabled. - Other IContainerControl windows show limited right-to-left behavior. For example, columns in details view will not appear right-to-left and icons will not be grouped from right to left. - Other INotebook windows show limited right-to-left behavior. For example, tabs will not appear from right to left. - Help windows displayed by IHelpWindow objects created with the IHelpWindow::ipfCompatible style are not bidi enabled. - Other help windows show limited right-to-left behavior. - ICircularSlider is not bidi enabled. Additional information regarding support of bidirectional languages in Open Class can be found on the support page of the VAC++ web site. IString optimization -------------------- To optimize the IString+= operation, the IBuffer/IDBCSBuffer class now allocates memory in 32 bytes chunk(s). 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. Changes/Clarifications for Windows 2000 --------------------------------------- IFileDialog ----------- The file dialog has a different appearance under Windows 2000, displaying a tool bar on the left edge of the window. Users can use this tool bar to quickly select common save areas as presented by the operating system. For Windows 2000, the default work directory for the open/save dialog is specified by the CSIDL_PERSONAL folder path as returned by the SHGetFolderPath API. The CSIDL_PERSONAL folder path translates to the file system directory that serves as a common repository for documents for the current user. Thus, if you do not specify an initial path to IFileDialog, the default directory used by the dialog is the CSIDL_PERSONAL folder path. Applications that need access to other Windows folders should query the operating system for the correct path and pass it to IFileDialog::Settings::setInitialDrive. IFileDialog::Settings::setInitialDrive -------------------------------------- If you do not call this function and you are running on Windows 2000, IFileDialog uses the CSIDL_PERSONAL folder path as the initial drive. The CSIDL_PERSONAL folder path translates to the file system directory that serves as a common repository for documents for the current user. IProfile changes ---------------- The following constructor has been added to this class: public: IProfile( const char* profileName, EType type, EAccess access ) This is supported on Windows only. Constructs an IProfile object that creates or opens a system or user profile with read-only or read/write permission, depending on the value of the EType and EAccess values passed to the constructor. This constructor is useful for opening or creating a user profile. On Windows, the constructor that takes only a profile name will open a system profile with read/write access. Note that on the Windows 2000, only an administrator can open system profiles with read/write permission. profileName Name of the profile to open or create. type Specifies whether the profile is a user or system profile. access Specifies whether the profile should be opened with read-only access or created/opened with read/write access. Exceptions IInvalidParameter The IProfile object was not constructed. The profile name is missing. IAccessError The IProfile object was not constructed. The profile name may be invalid or the user is not authorized to create or open the specified type of profile. The following enumerations have been added: EAccess enum EAccess { kReadOnly, kReadWrite } This is supported on Windows only. Use this enumeration to specify the access mode for a profile. kReadOnly Open the profile with read only permission if it exists. kReadWrite Create or open the profile with read and write permission. EType enum EType { kSystem, kUser } This is supported on Windows only. Use this enumeration to specify the profile type. kSystem Create or open the profile under HKEY_LOCAL_MACHINE\Software in the Windows registry. Note that on Windows 2000, only a user with administrator permissions can do this. kUser Create or open the profile under HKEY_CURRENT_USER\Software in the Windows registry. IWindow::setFocus ----------------- This function does not change the foreground window on Windows 2000 if another application is in the foreground. In this case, the other application will continue to receive keyboard input. System Objects -------------- Windows Terminal Server programs have two name spaces available for system objects: the session name space and the global name space. The IOC classes ISharedResource and ISharedCondition both create system objects. You can explicitly specify whether these classes should create their system objects in the global or session name space through the names you pass to their constructors. To specify a name space, add a "Global\" or "Local\" prefix to the name you pass when constructing an ISharedResource or ISharedCondition object. A prefix of "Global\" causes the system object to be created in the global name space. A prefix of "Local\" cause the object to be created in the session name space. On Windows 2000 systems without Terminal Services running, the "Global\" and "Local\" prefixes are ignored. For example: ISharedCondition("Global\\keyName") will create the name in global name space. ISharedCondition("Local\\keyName") will create the name in session name space. ISharedCondition("keyName") will create the name in session which is the default. Changes/Clarifications Regarding the Windows SDK ------------------------------------------------ Changes to support compiling with STRICT ---------------------------------------- The Windows SDK supports stronger type checking for its handle types, such as HWND, HICON, and HDC, so that the compiler will not treat them as interchangable equivalents to void*. The SDK provides this stronger type checking when the STRICT macro is defined at compile time. Without the stronger type checking, you can pass an HWND value to an API that requires an HICON. In the previous version of the SDK, NO_STRICT was defined by default. IBM Open Class Library did not support compiling with STRICT defined with the previous SDK. In the updated SDK, STRICT is now the default. Simply by recompiling, you will get stronger type checking on code that uses the SDK handle types directly, such as application code that calls Windows APIs that take or return SDK handle types. The stronger type checking in the SDK handle types could identify errors in code that used to compile cleanly. If you encounter new handle-related compiler errors, you should either correct the code causing the errors, or change your builds to define the NO_STRICT macro at compile time. The handle classes in IBM Open Class Library have been enhanced to support compiling applications with either STRICT or NO_STRICT defined, through the addition of new Windows-only constructors and operators. In order to avoid introducing excessive compiler errors to existing code, however, the IOC handle class do not enforce stronger type checking when STRICT is defined. If you want stronger type checking in the IOC handle classes, similar to the stronger type checking you can get in the SDK handle types, you should compile your application code with IC_WIN_STRICT_HANDLES defined and without NO_STRICT defined. This stronger type checking allows you to construct an IWindowHandle object only from an HWND value, and not an HDC or even a void* value. IFont ----- The COM IFont class in the SDK file ocidl.h can conflict with the IFont class provided by IBM Open Class Library in ifont.hpp. This conflict existed in the previous SDK, but is more likely with the updated SDK because many more SDK header files now include ocidl.h. To avoid a conflict, IBM has redefined the COM IFont class to __IWinFont. If you have code that uses the COM IFont class, you must do one of the following to refer to that version of the IFont class instead of the version in IBM Open Class Library: - Define the macro __WIN_IFONT__ at compile time, or - Replace all occurences of IFont in your code (references to the COM version of IFont) with __IWinFont Note that you can use the COM IFont and IOC IFont classes in the same compilation unit only by using __IWinFont to reference the COM class. Other Changes or Clarifications ------------------------------- IGImage file support -------------------- The tasks and concepts section of the online reference incorrectly states that the IGImage class supports PCX and TIFF files. Deletion of IThreadFn objects ----------------------------- IBM Open Class now deletes IThreadFn objects when the threads running those function objects complete, to match behavior in previous versions of IOC. Before this fix, IOC was incorrectly leaking IThreadFn objects. Note that with this fix, incorrectly coded applications may fail in the following cases: - The application deletes an IThreadFn object that IOC has already deleted or will delete. - The application creates IThreadFn objects on the stack instead of via operator new. - The application starts another thread using an IThreadFn object that IOC has already deleted. Deletion of IWindow attributes ------------------------------ The pointer returned by IWindow::addOrReplaceAttribute is no longer valid after the IWindow object is deleted, or after the attribute is replaced by another call to IWindow::addOrReplaceAttribute. Search Limitations for this product =================================== o Some search rankings are wrong, especially from the simple search. For example, searching for "IFrameWindow" from the Simple Search forms or from the Free text field will return the class description, but it will be lower ranked than less relevant hits. For best results, use the Boolean search fields in Advanced Search and specify an "exact" search. DBCS (Double Byte Character String) NOTES _________________________________________ o When using the English version of VisualAge C++ on a DBCS language environment, you need to change the LANG environment variable in SETENV.BAT 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 TECHNOLOGY PREVIEWS ___________________ The following components are available for use in the VisualAge C++ Professional, Version 4.0 product as a Technology Preview and are provided on an "AS-IS" BASIS, WITHOUT WARRANTY OR CONDITION OF ANY KIND, INCLUDING THE IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE: 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. o For more information on the Tivoli Technology Preview, you must install it. Go to the main product directory, and unzip the file: X:\TIVOLI\TIVOLI.ZIP, where X is the drive of your CD. Next: - Create a temporary directory: MKDIR TDK - Change to the temporary directory: CD TDK - Run the TDK self-extracting install program ..\BIN\TDKVA - Run the TDK Setup program: SETUP - Install the Tivoli Development Kit to a directory other than under the IBMCPPW directory - Change to the IBMCPPW\HELP directory - Unzip the Tivoli Connection Parts documentation: UNZIP TIVUGR40.ZIP - Read the Tivoli Connection Parts documentation using your favorite browser. o For more information on the Performance Analyzer Technology Preview, see the file TECHPREV\readme.pa. o 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.