home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v2.zip
/
OS2CPP
/
READ.ME
< prev
next >
Wrap
Text File
|
1993-10-21
|
49KB
|
1,155 lines
===============================================================================
IBM* C Set ++* read.me file:
IBM C Set ++ Version 2.1
(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++ Tools
components of C Set ++. 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
IBM
IBMLink
OS/2
Presentation Manager
WorkFrame/2
WorkPlace Shell
XGA
The following items are trademarks of other corporations in the United States
or other countries. They are denoted by a double asterisk (**) when they
first appear in the text.
Microsoft
Windows
IBM C SET ++ INSTALLATION
_________________________
To install and run WorkFrame/2 V2.1, you require:
o OS/2 V2.1
o 21WPSF fix for the OS/2 WorkPlace Shell*
To obtain the 21WSPF fix, call 1-800=237-5511 with your customer number.
If you are installing WorkFrame/2 V2.1, the correct order to install the
components is:
1. Toolkit
2. WorkFrame/2
3. C/C++ Tools
This is not the order described in the Read Me First: Installing and Getting
Started booklet.
If you installed the WorkFrame/2 before the Toolkit, you will need to
manually add the NMAKE action to the default actions profile (if you install
the Toolkit first, this is done for you). For instructions on how to add an
action, see the WorkFrame/2 READ.ME file.
If you are installing both V1.1 and V2.1 of the WorkFrame/2, install V1.1
first. Note that both versions have a READ.ME file with the same name. If
you install both versions in the same directory, the second installation will
overwrite the first installation's READ.ME file. To avoid this, either
install them in different directories, or rename the READ.ME file from the
first installation before installing the second version.
Follow the other installation instructions from the Read Me First booklet.
A full installation of the C Set ++ files requires approximately 58MB of disk
space, broken down in the following manner:
Toolkit 25.4MB
WorkFrame/2 V1.1 1.8MB
WorkFrame/2 V2.1 2.7MB
C/C++ Tools 30MB
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++ Tools 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, C Set ++ Version
2.0, or C Set ++ FirstStep*, make sure that the directories for C Set ++
Version 2.1 come before their earlier counterparts in the following
statements in your CONFIG.SYS file:
o PATH
o DPATH
o LIB
o INCLUDE
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 2.1 versions.
3. Add the d:\TOOLKT21\CPLUS\OS2H directory to your INCLUDE variable,
ensuring it either replaces or precedes the d:\TOOLKT21\C\OS2H directory.
4. Ensure that you are using the LINK386 linker from the Developer's Toolkit
2.1.
5. To use the context-sensitive help feature in EPM, you must either add the
d:\TOOLKT21\BOOK directory to your DPATH variable or copy the
EPMKWHLP.NDX file to a directory specified in your DPATH.
6. Do not delete the file DDE4FIX.DLL.
7. The C/C++ Tools installation program shows a negative value if the space
available is greater than or equal to 2GB.
8. The C Set ++ folder icon created by the installation is not immediately
displayed on the OS/2* 2.0 operating system. It should display after the
operating system is restarted. This does not happen with the OS/2 2.0
Service Pack, Pre-installed OS/2 2.0, or OS/2 2.1.
9. C/C++ 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 ++, 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.
NEW FEATURES AND LATE DOCUMENTATION CHANGES
___________________________________________
This section lists the new features that have been added to each component
and the changes that have been made which could not be incorporated into the
documentation.
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. The I/O Stream library is not available for subsystem development. The
Programming Guide incorrectly says that it is.
3. 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".
4. If your DLLs export any functions that could be a match for template
functions, you must build an import library.
5. 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 IBM C/C++ Tools Programming Guide.
PRECOMPILED HEADER FILES
WHEN TO USE THEM
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 precompiled header 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, then 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.
NOTE: When creating precompiled headers, you must have write access to the
subdirectory where the precompiled headers will be placed (CSET2PRE under the
directory where the normal headers reside). If you are using C/C++ Tools
from a LAN and do not have write access, ask the system administrator to
precompile the headers for you. Then you need only specify the /Si option to
use the precompiled headers; you do not need to specify /Fi.
PERFORMANCE
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.
NEW OPTIONS AND #PRAGMA DIRECTIVES
This section lists compiler options and #pragma directives that have been
added, deleted, or changed. These changes are reflected in the Online
Language Reference (DDE4LRM.INF), but are not included in the hardcopy
documentation.
Compiler Options
The following options have been added:
/Om Limit the amount of memory used by the compiler's optimizer and code
generator to approximately 35MB (as measured by swapper growth).
NOTE: Because /Om may cause the inliner to avoid some inlining
opportunities, the code generated with /Om may be less efficient than
code generated with /Om-.
/Tl Control preloading of compiler components. Note that if you are running
the OS/2 Version 2.0 operating system, you must have the Service Pack
installed for this option to have any effect.
/Tm Enable the debug versions of the memory management functions for both C
(malloc family) and C++ (new and delete). See the C Library Reference
(DDE4CLIB.INF) for a description of the C debug memory management
functions. For a description of the debug versions of new and delete,
see the Online Language Reference.
/Ts This option has been removed. It generated code for the debugger to
maintain the call stack. The debugger now provides equivalent function
without compiler support.
#pragma Directives
The following #pragma directives have been changed or modified:
#pragma disjoint
This directive will be parsed, but has no effect. It has been removed
from the Online Language Reference.
#pragma isolated_call
This directive will be parsed, but has no effect. It has been removed
from the Online Language Reference.
#pragma margins
This directive is valid for C code only.
#pragma sequence
This directive is valid for C code only.
#pragma sourcedir
Defines a new path to the directory containing the original source from
which the compiler generates files in the TEMPINC directory. This
directive is only valid for C++ code.
DEBUGGER
________
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.
EXECUTION TRACE ANALYZER (EXTRA)
________________________________
1. The IBM C/C++ Tools: Execution Trace Analyzer Introduction states on
page 9 that "EXTRA" is the name of the executable. The name of the
executable is "IXTRA".
2. In Figure 1 on page 4 of the EXTRA Introduction, the name of the library
link into the samples is shown as as "doscall". The name should be
"_doscall".
3. The Execution Density window allows movement of the current column
indicator anywhere in the client area. Double-clicking on a column that
is not currently selected moves the current column indicator to the
appropriate column. Double-clicking on the currently selected column
brings up the search dialog. You can drag the current column indicator
only if you choose the current column indicator.
BROWSER
_______
1. Arrows in a Graph window inheritance graph now point upwards, towards the
base classes. An illustration in the Browser Introduction shows the
arrows pointing downwards.
2. Dotted lines in a Graph window indicate a virtual relationship between
classes. Black lines indicate a private relationship.
3. Ring icons are now available in the Text window so you can access the
Next and Previous controls for rotating through the list of occurrences.
4. Occasionally the browser is unable to display information about variables
used in functions generated from templates.
C LIBRARY
_________
The _msize function has been added. This function is documented in the
online C Library Reference (DDE4CLIB.INF), but is not in the hardcopy
documentation.
STANDARD CLASS LIBRARY
______________________
The hardcopy version of the IBM C/C++ Tools Standard Class Library Reference
states that all output operators << reset ios::x_width to 0. In fact, only
the numeric and string output operation reset ios::x_width to 0.
For example,
cout.width(5)
cout << '{' << 12 << '}' ;
generates the following:
{ 12}
This error has been corrected in the online version (DDE4SCL.INF).
COLLECTION CLASS LIBRARIES
__________________________
1. The following changes are reflected in the online Collection Class
Library Reference (DDE4CCL.INF), but not in the hardcopy version.
a. User-defined individual memory management cannot be used with the
Tabular and Diluted sequences. Global operators new and delete are
used with these.
b. The functions unionWith, intersectionWith, differenceWith, addUnion,
addIntersection, and addDifference are not provided for
EqualitySequences.
c. The functions unionWith, addUnion, addIntersection, and addDifference
do not throw IIdenticalCollectionException when the identical
collection is provided as a function argument (the addAllFrom
function throws this exception). Instead, the functions behave in
the mathematical sense as described for union, intersection, and
difference.
d. The <iglobals.h> file does not contain the definitions for the type
Boolean and the Boolean values "True" and "False". Instead, the
following definitions are found in <isynonym.hpp>:
typedef int Boolean;
typedef int IBoolean;
typedef enum {
false = 0,
False = 0,
true = 1,
True = 1
};
e. Functions locateOrAdd and locateOrAddElementWithKey return "True" if
the element was located. They return "False" if the element could
not be located but was added.
2. Dynamic Link Library
In addition to the static library IBMCPP\LIB\DDE4CC.LIB, there is a .DLL
file called IBMCPP\DLL\DDE4CC.DLL with the corresponding import library
IBMCPP\LIB\DDE4CCI.LIB.
3. Samples Provided
The IBMCPP\SAMPLES\ICLCC directory contains samples to familiarize you
with the Collection class library. Use NMAKE (from the Toolkit) to
create the executable files from the source provided. The correct output
from the executable files is provided in the .XPC files in the same
directory.
4. Tutorial Files
A number of files have been provided in IBMCPP\TUTORIAL\ICLCC to get you
started with the Collection classes. These files contain blank spaces
for you to fill in. The complete versions of the files are also included
in the SOLUTION directory.
5. Support for Translatable Messages
Exception Messages are read from a message file that can be specified by
setting the environment variable ICLCCMSG. The default is the US English
message file DDE4C01E.MSG.
USER INTERFACE CLASS LIBRARY
____________________________
1. The version of User Interface library code in this product has been
identified with two macros that are defined in <ibase.hpp>:
IC_MAJOR_VERSION is defined to 201
IC_MINOR_VERSION is defined to 0
You can use these macros in your programs to conditionally use the new
and changed interfaces introduced in this product. For example:
#if IC_MAJOR_VERSION >= 201
// code using new interfaces
#endif
2. IContainerColumn::iconOffset will be removed in future releases.
WORKFRAME/2 V1.1 SUPPORT
________________________
If you are migrating projects from C Set/2 and WorkFrame/2 V1.0 to
WorkFrame/2 V1.1:
1. The first time you invoke an action on the migrated project, a message
box appears and asks if you want to convert the project. If you select
"Yes", the program traps (select "Cancel" instead). To work around this
problem, before you invoke any action on the project, open its Compiler
Options dialog instead. A message box appears and asks if you want to
convert the project. Select "Yes", the new option dialogs appear. You
can make changes if you want, but you do not need to. Save the options.
The project is then converted, and you can invoke actions on it.
2. The WorkFrame/2 interface has been modified slightly from V1.0 to V1.1.
On the Linker Options dialog, there is a button that also brings up the
compiler options. The options are always saved with the project (the
SAVE WITH PROJECT button has been removed), in the extended attributes of
the project. These options are retrieved to compile the templates. The
last setting of the options is always used.
WORKFRAME/2 V2.1 SUPPORT
________________________
When you migrate projects from C Set/2 or C/C++ Tools V2.0, the names of the
compiler and linker options DLLs are not changed. The projects continue to
use the DLLs from the earlier version of the product. You can use
WorkFrame/2 V2.1 with these migrated projects, but the full V2.1 capabilities
will not be available. For example, because C/C++ Tools V2.0 option DLLs
(for WorkFrame/2 V1.1) stored information in the extended attributes of a
project, under WorkFrame/2 V2.1 you can have only one Compile and one Link
action for the project. To have multiple Compile or Link actions, you must
change the project to use the C/C++ Tools V2.01 options DLLs (DDE4ICC2.DLL
for compiler and DDE4ICL2 for linker options).
To change the options DLLs, you can either modify the Options page of the
migration project's actions profile, or you can drag the WorkFrame/2 V2.1
Default Actions Profile and drop it on the project. Note that when you
change the DLLs, you will need to reset your options.
DOCUMENTATION
_____________
1. 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.
2. In the C/C++ Tools Programming Guide:
o In Appendix E, "Component Files", some of the file names listed are
incorrect. The names of the Collection class libraries should be
DDE4CC.LIB and DDE4CCI.LIB (import library); the DLL is DDE4CC.DLL.
The names of the User Interface libraries should be DDE4MUIB.LIB,
DDE4MUIC.LIB, DDE4MUID.LIB, and DDE4MUII.LIB (import library); the
DLL is DDE4MUI.DLL.
The names of the .NDX files should be DDE4CCL.NDX, DDE4CLIB.NDX,
DDE4LRM.NDX, DDE4SCL.NDX, and DDE4UIL.NDX.
o In Chapter 3, "An Introduction to Using the C/C++ Tools Compiler",
the names of the sample programs should be SAMPLE1A\PMLINES.C and
SAMPLE1B\PMLINES.CPP, instead of SAMPLE1A.C and SAMPLE1B.CPP.
o In Chapter 17, "Developing Subsystems", it states that the I/O Stream
library can be used for subsystem development. This is not the case.
RELEASE CONSIDERATIONS AND NOTES
________________________________
This section lists information that is necessary to you in running the
C Set ++ product.
C/C++ COMPILER
______________
1. When compiling C++ code, you may encounter a trap screen from a detached
process, indicating that a trap occurred in DDE4CPP.EXE. This is caused
by preloading the compiler and can be ignored; compilation of your
program is not affected. In order to avoid receiving the trap screen,
you can either use the /Tl- compiler option (to not preload the compiler)
or set AUTOFAIL=YES in your CONFIG.SYS file (to not display trap
screens).
2. You cannot use the intermediate code linker to link C++ files that are
compiled with the /Gu option and that contain variables that have been
renamed using #pragma map.
Intermediate code linking of such files without /Gu is supported.
3. Programs that use templates cannot be compiled with the intermediate code
linker and the /Gu+ option. Using them together may cause the
intermediate code linker to remove any unused symbols as part of the
intermediate code linker optimization process, and you may get error
messages about unresolved symbols. Using the intermediate code linker
without specifying /Gu+ will yield the expected results.
4. 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.
5. 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.
6. 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.
DEBUGGER
________
This section contains notes on the debugger functions.
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 current problem that has been noted is a failure to
produce a disassembly or mixed view for some programs.
3. Although debugging optimized code is supported, there is some loss of
function because of the nature of optimized code. If you single-step
through the source, it may result in seemingly erratic movements of
the current line. It may not be possible to display the value of
variables, or to set line breakpoints accurately. However, you can
set breakpoints at function entry and exit.
4. Although debugging inlined code is supported, inlined code may have a
different appearance than non-inlined code when it is being debugged.
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
1. A new environment variable has been added, PMDTABGRID, which can be
used to define tab stops at a particular interval for the Source
display windows. For example, setting SET PMDTABGRID=5 will cause
text after a tab to begin in columns 6, 11, 16, 21, 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. Do not use Step Debug (Ctrl-D) over a DosReleaseMutexSem or a
DosRequestMutexSem. Use Step Over(Ctrl-O).
MONITORS/REGISTERS/STACK/STORAGE
1. The pointer-to-member operator is not supported.
2. To typecast a pointer in a monitor window, the type must have been
defined using a typedef. A variable can only be cast 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 will be shown. Therefore, if the application is stopped in ring
2, the stack of ring 3 stack is not shown.
SOURCE WINDOW
The debugger now supports executable code in included files. The source
can be viewed 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 will be
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 application, it is possible that
IPMD will 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 have 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 PMDOS21 (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. If you are using OS/2 2.0 GA and a Service Pack, there is a problem with
the storage window being in insert mode. Set the environment variable
PMDOSSP (SET PMDOSSP=1) to eliminate the problem.
7. When debugging a Presentation Manager application in synchronous mode,
other multithread Presentation Manager applications running in the
background that send messages between threads may experience problems.
Avoid running programs like EXTRA while debugging.
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
filename to have invalid characters in it. This problem is infrequent
and does not cause the debugger problems.
9. If the Desktop Automatic Lockup feature is enabled and the debugger is
active, the system will permanently lock up when the timer expires.
Currently, the only solution is to reboot.
10. If you use a screen saver program, it may be necessary to disable it to
allow use of IPMD.
11. If you installed MMPM/2, you may have problems running IPMD on
applications 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 focussed debugger screen 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.
EXECUTION TRACE ANALYZER (EXTRA)
________________________________
This section contains notes on the EXTRA functions.
PROGRAM PREPARATION
1. Remember to install DDE4XTRA.SYS in your CONFIG.SYS file. If you do not
install this file, EXTRA cannot run the target application.
2. If you want to trace "Dos" calls or Presentation Manager "Win" or "Gpi"
calls, add the EXTRA intercept libraries to your link step.
RUNTIME NOTES
1. If you use the Application Termination Window to stop your application
before it places the initialization data in the trace file, EXTRA
produces a corrupted trace file. This can happen only if you terminate
your application immediately after EXTRA begins tracing.
2. If you have written customized setjmp or longjmp functions to replace the
C Set ++ library versions, EXTRA will not function correctly.
3. A user event can be created as a constant character string or can be
specified as an area into which a character string has been built. After
the application has terminated, EXTRA accesses the data area of the
target application so that the user events can be written to disk.
Therefore, each user event must occupy a unique storage location.
4. EXTRA's timing counter wraps after approximately one hour of program
execution. If your application runs longer than one hour, the time
stamps are not accurate.
5. When loading a large executable or large trace files, EXTRA does not
change the mouse pointer to a clock to indicate that it is still working.
6. The call stack may not be accurate near thread switches. Also, EXTRA's
timing of thread switches is approximate.
7. If you minimize the Trace Generation Window, the window of the target
application remains in its original state.
8. If you minimize the Overview Window in the Dynamic Call Graph, it does
not appear in the Task List.
9. Although you can attach annotations to user events, EXTRA does not
display the annotations.
10. File access calls are not traced for I/O flush operations that occur
after the target application has finished. They are not included in the
function-called counts for those file accesses.
11. In the Name Trace File option of the Trace Generation window, you can
enter a path and file name of up to 256 characters, but the program uses
only the first 32 characters entered.
12. If the last event of a trace file in the time-scale diagrams (Time Line
and Execution Density) appears to be missing, adjust the scale of the
diagram.
LIMITATIONS
1. EXTRA traces only the first 16 threads in your application. It does not
trace additional threads.
2. EXTRA can trace and analyze applications generated by the IBM C Set ++
compiler. You cannot use EXTRA to trace files produced by other 16-bit
or 32-bit compilers.
3. EXTRA cannot generate or analyze trace data for child processes in a
multi-process application.
4. Dynamically-loaded DLLs cannot be traced.
5. If you do not install the device driver DDE4XTRA.SYS, EXTRA cannot run
the target application.
6. Do not trace applications that are currently being debugged by IPMD.EXE
or analyzed by EXTRA in another session. Unpredictable results may
occur.
OPERATING SYSTEM NOTES
1. If you are using the XGA device driver on OS/2 2.0, printing does not
work. The device driver support has been improved with OS/2 2.1 to
support the print function in EXTRA.
2. The Dynamic Call Graph does not function if a program that uses
WinLockInput is also running under OS/2. The design of WinLockInput does
not allow messages to be sent between threads.
3. In the Dynamic Call Graph, when you move the cross hair by using the
keyboard, the cross hair may leave an after image on slower machines.
This can be corrected by repainting the window with the RE-LAY GRAPH menu
option or by resizing the window.
4. EXTRA uses DosStartSession to start the program being traced.
DosStartSession may give error messages which you do not see when the
program is run outside EXTRA. 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.
5. In the Call Nesting diagram, any change in the System Proportional font
style is displayed inconsistently with the view of STYLE in the sample
window.
6. Point sizes for certain fonts are displayed one size greater than
actually selected in the font dialogs.
BROWSER
_______
1. The browser can now display the tutorial even if the tutorial is
installed in a directory with a plus (+) sign (for example, x:\IBMC++\).
2. The browser List window container has a limit of 64K. If this limit is
exceeded, the first 64K worth of data is retained and a warning message
is displayed. If a Find operation is performed on the truncated list and
the target is beyond the 64K limit, the cursor scrolls to the end of the
list.
3. Unless you specify the /S option, the Text window searches for source
files in the directories they were in when the browser file was created.
If the /S option is specified, the Text window searches for source files
only in the directories specified in the /S option.
If you rename a source file after its corresponding browser files have
been created, you can still perform searches and queries on program
components contained in the source file, but the browser cannot display
the text of the source file in the Text window.
4. If you did not install C Set ++ in the default directory, C:\IBMCPP,
specify the /S<path> option when browsing the sample programs in the
x:\IBMCPP\SAMPLES directory to indicate the location of the sample files.
For example, if the C/C++ Tools product is installed in the D:\COMPILER
directory, type the following command to to browse the sample programs
included with the browser:
ibrs /Sd:\compiler\samples\browser *.brs
You can also recompile the sample programs to obtain browser files
containing the updated source file paths.
STANDARD CLASS LIBRARY
______________________
1. To ensure that the correct stack tracebacks are generated for the task
library, you must compile the modules that are derived from the task
library with the following options (these are all defaults):
/Op- Disable all stack pointer optimization.
/O- Disable optimization.
/Gh- Disable profiler hook.
You may get unpredictable results if you do not compile your module with
these options.
2. There is no restriction on using #pragma handler within the task library.
Exception handling is done on a task-by-task basis. An exception handler
registered in one task will not be registered in any other task.
Register an exception handler for each task that needs one.
3. There is no longer a restriction on calling exit from within a task.
COLLECTION CLASS LIBRARY
________________________
1. The online Collection Class Library Reference now includes a section on
troubleshooting. Refer to Appendix, "Problem Determination" for
solutions to common problems you may encounter when using the Collection
classes. Note that this appendix does not appear in the hardcopy version
of this document.
2. When you use the Collection class library, compile your code 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()
3. 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)
USER INTERFACE CLASS LIBRARY
____________________________
1. If you have existing programs that use the User Interface class library,
you must recompile and relink them with Version 2.01 of the library in
order to run them with the updated DDE4MUI.DLL. This is because of
changes in the interface. See the Summary of Changes section in either
the User Interface Class Library Reference for a list of the interface
changes and new functions.
2. The procedure for building your own runtime libraries, described in
"Building Dynamic Link Libraries" in the C/C++ Tools Programming Guide,
does not apply to the User Interface class libraries. For instructions
on how to rebuild DDE4MUI.DLL, see the file DLLREBLD.DOC under the HELP
subdirectory.
3. If you are using OS/2 2.0, you may encounter false out-of-stack errors at
run time. For this reason, we recommend programs written using the User
Interface class library on OS/2 2.1 or OS/2 2.0 with fix PJ06959 applied
(you can obtain this fix on Service Pack 2, or by calling 1-800-237-5511
with your customer number and the fix number).
4. There are several OS/2 or Presentation Manager problems that you may
encounter when you use the User Interface class library:
ICheckBox
The right focus border disappears if the text assigned to a check box
is too large to be displayed within the check box. This happens if
the text is too long, the size of the check box is too small, or the
check box is using a font that is too large.
IContainerControl
a. Under OS/2 2.0:
o The expandTree and collapseTree functions do not work.
o You cannot apply source emphasis (with showSourceEmphasis) to
an object in a container with the orderedTargetEmphasis
attribute.
b. When you drag an OS/2 desktop object over a container created with
the User Interface library, a system hang might occur. This is an
OS/2 problem. You can prevent this problem by statically linking
to the OS/2 drag DLL, which you can do by putting any drag call
(for example, DrgAccessDragInfo) in your code.
IDDE* clases
There are various OS/2 problems establishing conversations and
exchanging data with Microsoft** Windows** applications on OS/2 2.0.
These problems have been corrected in OS/2 2.1.
IFont
o If you construct an IFont from a pointer to an IMultiLineEdit
control, the IFont is not initialized with the font currently used
by the MLE. This is due to a PM limitation.
o When you construct an IFont from a pointer to a Control, any Bold,
Italic, or Underscore attribute in the Control font is not picked
up by the resulting IFont. This is due to a PM limitation.
IMultiCellCanvas
a. The layout produced by an IMultiCellCanvas with expandable columns
may have an expected appearance when the canvas is not wide enough
for those columns to be expanded. This is also true for an
IMultiCellCanvas with expandable rows when the canvas is not tall
enough for the rows to be expanded.
b. When
o More than one child window has the same starting column in an
IMultiCellCanvas
o The child windows span different numbers of columns
o The minimum size of the longest child window exceeds the
summed minimum sizes of the columns that it occupies
the width of the starting column may be increased in such a way
that the other child windows end up larger than expected.
Similarly, when
o More than one child window has the same starting row
o The child windows span different numbers of rows
o The minimum size of the tallest child window exceeds the
summed minimum sizes of the rows that it occupies
the height of the starting row may be increased, causing the child
windows to be larger than expected.
IProgressIndicator
a. Various repaint problems can occur when the control is resized
using sizeTo or moveSizeTo and the width of the window is less
than the width of the entire control. This typically happens when
tick spacing has been specified on the constructor; otherwise the
control is able to resize itself.
b. Using moveArmToTick can result in an exception if the control
window has no size and if tick spacing has been specified on the
constructor.
c. The arm position may not be set to the same tick position when the
control window is resized. This typically occurs when the control
is on a canvas and the default for tick spacing is taken from the
constructor. The arm ends up at the same pixel offset from home.
instead of at the same relative position.
ISlider
When increment buttons are attached to the left side on an ISlider
object, the setShaftPosition function actually sets the lower-left
corner of the button, not the shaft, to the specified point.
ISpinButton
a. The following problems occur under OS/2 2.0, but are fixed
OS/2 2.1:
o The range function causes a trap.
o The setInputType function does not change the spin button from
alphanumeric to numeric and vice versa.
b. Calling the setLimit function with a limit that does not allow all
numbers in the spin button range to be displayed causes erratic
results when you spin the button. For example, if the range is 1
to 100 and the limit is set to 2, the spin button spins up to 99
and then wraps to 10 instead of 1. Spinning down, the button
wraps from 1 to 10. This is an OS/2 problem.
SUPPORT
_______
We are delighted to offer you IBM's comprehensive product support services.
If you come across a problem when using C Set ++, get in touch with us
through our NON-DEFECT SUPPORT CHANNELS:
* COMPUSERVE If you are already a CompuServe member, type GO OS2DF1 at the
! prompt to access the OS2DF1 forum. For information on
becoming a member, call 1-800-848-8199, press 1, and ask for
Representative 239.
* INTERNET For WorkFrame/2 questions, send a note to
workframe@vnet.ibm.com
For other C Set ++ questions, send a note to
cset2@vnet.ibm.com
* TALKLink Through IBMLink* - OS/2 Bulletin Boards
If you believe you have found a PRODUCT DEFECT:
* Call our Defect Support line at 1-800-237-5511 - 24 hours a day, 7 days a
week.
Included with the C Set++ product is a "HELP and how to get it" brochure that
gives further information on all the support channels provided.
ENJOY!!