IBM CD Showcase

home *** CD-ROM | disk | FTP | other *** search

/ IBM CD Showcase / OS2_CD_ROM.iso / smce0001 / cfirst11 / os2cpp / read.me < prev next >

Wrap

Text File | 1993-10-12 | 18.8 KB | 455 lines

=============================================================================== IBM* C Set ++ FirstStep* read.me file: (C) Copyright IBM Corp. 1993. All Rights Reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. =============================================================================== This README file contains information pertaining to the C/C++ FirstStep* Tools components of C Set ++ FirstStep. For the most recent information on the WorkFrame/2* product and OS/2* 2.1 Developer's Toolkit, please refer to their individual READ.ME files, found in the main installation directory for each product. The following items are trademarks of the IBM Corporation. They are denoted by an asterisk (*) when they first appear in the text. C Set ++ C Set ++ FirstStep C Set/2 C/C++ FirstStep IBM OS/2 Presentation Manager WorkFrame/2 WorkPlace Shell XGA INSTALLATION ____________ Follow the installation instructions in the Read Me First: Installing and Getting Started booklet. A full installation of the C Set ++ files requires approximately 47MB of disk space, broken down in the following manner: WorkFrame/2 1.8MB Toolkit 25.4MB C/C++ FirstStep Tools 19.5MB When you install each component, the installation program tells you how much space you have available on the selected drive and how much space is required for the options you select. To effectively use the C/C++ FirstStep compiler and debugger, you need a minimum of 8M of RAM for C applications and 12M for C++ applications. INSTALLATION NOTES 1. If problems occur, make sure the HELP environment variable points to the d:\OS2\HELP directory (where "d" is the startup drive). 2. If you installed Version 1.0 of the C Set/2* product or Version 2.x of the C Set ++* product, make sure that the directories for C Set ++ FirstStep come before their earlier counterparts in the following statements in your CONFIG.SYS file: o PATH o DPATH o LIB o ICLUDE o LIBPATH o BOOKSHELF o HELP If you change these environment variables frequently, you may want to erase the earlier versions of the files to ensure you do not access them before the C Set ++ FirstStep versions. 3. Ensure that you add the d:\TOOLKT21\CPLUS\OS2H directory (where "d" is the drive where you installed the Toolkit) to the beginning of your INCLUDE variable. This directory must precede the d:\TOOLKT21\C\OS2H directory. 4. If you are using OS/2 2.0, ensure that you are using the LINK386 linker from the Developer's Toolkit 2.1, not the one from the operating system. 5. To use the context-sensitive help feature in EPM, you must either add the d:\TOOLKT21\BOOK directory (where "d" is the drive where you installed the Toolkit) to your DPATH variable or copy the EPMKWHLP.NDX file to a directory specified in your DPATH. 6. The C/C++ FirstStep Tools installation program shows a negative value if the space available is greater than or equal to 2GB. 7. The C Set ++ FirstStep folder icon created by the installation is not displayed in the OS/2* 2.0 operating system. It should display after the operating system is restarted. This should not happen with the OS/2 2.0 first Service Pack, Pre-installed OS/2 2.0, or OS/2 2.1. 8. C/C++ FirstStep Tools 2.01 and WorkFrame/2 1.1 installations do not support the HPFS file names with imbedded spaces. IF YOU HAVE THE CD-ROM VERSION ______________________________ If you have the CD-ROM version of C Set ++ FirstStep, you can create diskettes from the CD-ROM for backup purposes, or to allow you to install on a workstation without a CD-ROM drive. For more information on how to do this, see the READ ME file in the "IMAGES" directory of the CD-ROM. NOTE: Refer to the License Information document to ensure that you observe licensing restrictions when creating and using the diskette images. RELEASE CONSIDERATIONS AND NOTES ________________________________ This section lists changes that have been made which could not be incorpo- rated into the documentation and additional information that you may need while using the C Set ++ FirstStep product. C/C++ COMPILER ______________ 1. The documentation states that you cannot call a destructor between a longjmp and the corresponding setjmp in a stack frame. This restriction no longer exists. However, you should only call setjmp from within C compiled code; otherwise, the destructor may delete automatic objects in the function that contains the setjmp call. 2. On OS/2 2.0, when you use code pages other than 437, messages retrieved using DosGetMessage are prefixed with "SYS" instead of the correct prefix "EDC". 3. If your DLLs export any functions that could be a match for template functions, you must build an import library. 4. 16-bit functions have been labelled in the .DEF files. If you want to build a pure 32-bit DLL, delete all of the 16-bit exports and refer to the chapter "Building DLLs" in the Programming Guide. 5. When you link C++ code, a common linker error is: X::virtual-fcn-table-ptr: undefined symbol where "X" is the name of a class, or "{X}Y", where both "X" and "Y" are class names. The missing "virtual-fcn-table" for a class is a compiler-generated data structure that is used to implement virtual function calls for that class. The compiler has to determine which compilation unit it should generate each table in. Often, the compiler generates the table in the compilation that contains your definition of a selected virtual function. If you never define that function, the table is never generated, and the result is this linker error. Recompile your code with the /Wvft+ option. The compiler will produce an informational message as follows: EDC3281: informational The virtual function table for X will be defined where <X::foo()> is defined. You will likely find that the function "X::foo()" has not been defined anywhere. 6. The compiler reserves OS/2 exceptions with a facility code of 2 (that is, exceptions 0x00020000 to 0x0002FFFF) for its own use. The generation or handling of these exceptions may lead to unpredictable and undefined behavior. 7. If you receive the following message: DDE4MNCH: cannot run "lib.exe" one of the following has occurred: o LIB.EXE is not on your specified PATH. o There is a network error with a directory on your PATH before the directory for LIB.EXE. 8. Precompiled Header Files Precompiled header files improve compile-time performance for headers that are included many times in an application. This improvement is achieved by converting the header to a form that the compiler can process more efficiently. When used together, the compiler options /Fi and /Si provide automatic maintenance of up-to-date precompiled headers. You should use these options once the headers in the application are relatively stable because: o A new precompiled version of a header is created every time it is changed. If headers change with each compilation, the compilation time may increase. o Debugging is more difficult. Listings are not available for these headers and coordinates provided by compiler error messages are less accurate. The compiler options are all that is required to use precompiled header files. No additional rules are required in your make files for keeping the precompiled headers up to date. The compiler does this automatically. Keep in mind that precompiled header files occupy space in your file system. Typically, the size of a precompiled header is close to the size of the original. The improvement in compile time using precompiled headers varies between applications. Factors that influence the amount of improvement include: o The amount of code in headers and the amount of code in the source file. Because only the headers are precompiled, large source files show less improvement in compile time. o The language (C or C++). Because C++ is more complex to compile, C applications generally show more compile-time improvement than C++ applications. Using preprocessor conditional compilation to protect header files is of particular benefit when you use precompiled headers. Preprocessor conditionals are coded as in the following example: #ifndef UNIQUE_HEADER_ID #define UNIQUE_HEADER_ID /* Header contents */ #endif Header files protected in this way get maximum precompilation benefit when they are included more than once during a compilation. 9. If you specify a compiler option that is not supported or does not exist, the compiler generates a warning message. However, if you specify /O (in uppercase) as a compiler option, no warning message is generated although /O is not a supported option. There is no effect on the compilation of your code. DOCUMENTATION _____________ If you are running on OS/2 2.0 GA or OS/2 2.0 with the Service Pack, you may encounter a problem with the cross-document links in the .INF files. In some cases, Help Manager does not interpret these links properly and, instead of going to the right panel, it opens a second instance of the document being viewed and pops up a "Link not found" message. If this happens, close the extra copy of the INF file; otherwise, you may end up with a number of copies open and run out of memory. To get to the panel you wanted to see, go through the Table of Contents, or use the Search facility. DEBUGGER ________ o PREPARATION 1. IPMD.EXE requires fixed-pitch bitmapped fonts, which are part of the OS/2 installation. 2. Debugging of code generated with the /G5 option is not supported. However, the only problem that has been noted to date is a failure to produce a disassembly or mixed view for some programs. 3. Although debugging inlined code is supported, inlined code may have a different appearance than non-inlined code when you debug it. Calls to inlined functions may appear as non-executable statements. When you step through the inlined call, the source view changes to show the statements of the inlined function, and you step through the statements. You may not be able to set breakpoints at the function entry or on lines within an inlined function. o ENVIRONMENT VARIABLES A new environment variable has been added, "PMDTABGRID", that you can use to define tab stops at a particular interval. For example, "SET PMDTABGRID=5" causes text after a tab to begin in columns 6, 11,21, 16, 26, and so on. o EXECUTION CONTROL STEP 1. Programs that use floating-point instructions and run on a machine without a math coprocessor cannot single step consistently across floating-point instructions. 2. Use Step Over (Ctrl-O) to step past a DosReleaseMutexSem or a DosRequestMutexSem. Do not use Step Debug (Ctrl-D) in this situation. 3. When you step over a throw statement, the debugger runs to the end of the program unless you set a break point in the catch clause or at some point after the catch clause. MONITORS/REGISTERS/STACK/STORAGE 1. The pointer-to-member operator is not supported. 2. To typecast a pointer in a monitor window, you must have defined the type using a typedef. You can cast a variable only to a type that has been referenced in the object module. 3. When you view the stack, only the stack associated with the current ring is shown. Therefore, if the application is stopped in ring 2, you do not see the ring 3 stack. SOURCE WINDOW The debugger now supports executable code in included files. You can view the source as a notebook, with the source file names on the tabs. There is an option to turn off the notebook (in the Source Window Properties window). However, if the program stops because of a breakpoint or exception in an included file, the source window is displayed as a notebook to show the current line, regardless of the notebook option selected. Similarly, if a routine is on the stack and that routine has code in an included file, double-clicking on the routine name brings up the source window in the notebook format. OPERATING SYSTEM NOTES 1. When debugging a Presentation Manager* (PM) application, IPMD may display the message "PM Resource Interlock" or "DosDebug Error". This is due to a design limitation in OS/2. OS/2 applications have access to system semaphores, and when the application stops (such as when a breakpoint is hit), a system semaphore contention problem can develop within the operating system. Some IPMD users have received the PM Resource Interlock message on OS/2 2.1 while debugging applications that did not encounter the condition on OS/2 2.0. Work is in progress on a fix to OS/2 that will alleviate this problem in some situations, particularly for drag/drop and scroll operations. The fix is unlikely to prevent all possible PM Resource Interlock conditions. You may be able to work around the problem by moving breakpoints around slightly, or by toggling the PM Debugging Mode (changing from synchronous to asynchronous, or vice versa). 2. If you are debugging with an XGA* display, the window from which you invoked IPMD.EXE may not return to the OS/2 prompt when you close the debugger. To recover, select any OS/2 full screen prompt to free up the window. 3. If a program uses DosRaiseException to raise an exception, the debugger will not run the exception handlers. A selective fix is available for the OS/2 2.0 Service Pack. Call 1-800-237-5511 with your customer number and reference PJ05512 to obtain the selective fix. You must set the environment variable "SET PMDOS21=1" to take advantage of this fix. 4. The Message Queue Monitoring Function has an automatic column resizing option from the display style dialog. This menu item is not available on OS/2 2.0. 5. Certain combinations of display drivers and fonts can result in a blank source window. If this occurs, change the font size. 6. On OS/2 2.0 with Service Pack, there is a problem when the storage window is in insert mode. Set the environment variable "SET PMDOSSP=1" to eliminate the problem. 7. When debugging a Presentation Manager application in synchronous mode, you may experience problems with other multithread PM applications running in the background that send messages between threads. 8. The Debug Session Control window gives you a list of object files for your executable. There is a known linker problem that can cause a file name to have invalid characters in it. This problem is infrequent and does not interfere with the debugger's function. 9. If the Desktop Automatic Lockup feature is enabled and the debugger is active, the system will permanently lock up when the timer expires. If this happens, the only solution is to reboot. 10. If you use a screen saver program, you may need to disable it to use IPMD. 11. If you installed MMPM/2, you may have problems running IPMD on applica- tions that use sound. You may need to de-install the sound portion of MMPM/2 using DINSTSND.CMD. HINTS AND SUGGESTIONS 1. Debugging Child Processes To debug a child process, start the debugger with the name of the child as the argument (that is, change "DosExecPgm <child>" to "DosExecPgm ipmd <child>"). 2. Debugging REXX DLLs a. Start IPMD.EXE with the command line: ipmd cmd.exe /K <your rexx.cmd>" b. When IPMD.EXE displays the code for CMD.EXE, set a load-type breakpoint to stop when the DLL is loaded. c. Run. d. When the breakpoint is hit, open the desired component in the DLL and set breakpoints. 3. Debugging WorkPlace Shell* Objects a. Replace the RUNWORKPLACE line in your CONFIG.SYS file with: SET RUNWORKPLACE=C:\OS2\CMD.EXE b. In an OS/2 window, type: ipmd c:\os2\pmshell c. Set a load-type breakpoint for the DLL containing the WPS program. d. When the breakpoint is hit, open the desired component in the DLL and set breakpoints. 4. Printing debugger screens If you have an active printer driver loaded under OS/2 and the printer can print in graphics mode, you can print the debugger screen with the current focus by pressing the Print Screen key. 5. The debugger uses DosStartSession to start the program being debugged. DosStartSession may give error messages which you do not see when the program is run outside the debugger. Two common errors are: "PROGRAM NOT LOADED. DOSSTARTSESSION FAILED (RC=2)." This error indicates that DosStartSession could not find one of the DLLs referenced in your program. "PROGRAM NOT LOADED. DOSSTARTSESSION FAILED (RC=127)." This error indicates that DosStartSession found the DLL but could not find one of the exported entry points. It may mean that the LIB does not match the DLL, or that "/IGNORECASE" was used improperly. The loader is case-sensitive, and it may fail to find an entry if you are running the linker as case-insensitive. COLLECTION CLASS LIBRARIES __________________________ 1. When you use the Collection class library, compile your code with with /Sp4 option to align structures and unions along 4-byte boundaries (this is the default). If you use a different /Sp option, you must use #pragma pack around the #include directives for the Collection class header files to ensure that they are aligned correctly. For example: #pragma pack(4) #include <iset.h> #pragma pack() 2. If you intend to use the extensive compiler diagnostic messages (using the /Wgrp compiler option or the #pragma info directive), use #pragma info to suppress the generation of warning messages from the included Collection class library code. For example: #pragma info(none) #include <iset.h> #pragma info(restore)