home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / cppbeta / read.me < prev   
Encoding:
Text File  |  1992-10-29  |  61.2 KB  |  1,575 lines
  1. ===============================================================================
  2.      IBM* C/C++ for OS/2* read.me file:
  3.      IBM  WorkFrame/2* read.me file:
  4.  
  5.      IBM C/C++ for OS/2 V2.0 Beta Driver 1
  6.      (C) Copyright IBM Corp., 1991, 1992. All Rights Reserved.
  7.      IBM WorkFrame/2  Version 1.00B
  8.      (C) Copyright IBM Corp., 1991, 1992. All Rights Reserved
  9.      US Government Users Restricted Rights - Use, duplication or disclosure
  10.      restricted by GSA ADP Schedule Contract with IBM Corp.
  11.  
  12.      This product contains Unix Systems Laboratories (USL) copyrighted 
  13.      material which is being reproduced with permission.
  14. ===============================================================================
  15.  
  16. NOTE:  This beta driver has only been tested on the OS/2 2.0 operating
  17. system at the GA level.  We will test this driver on the OS/2 Service
  18. Pack as soon as it is available, and inform our beta customers of the
  19. results through the OS2DEV forum on CompuServe.
  20. We anticipate several advantages to using our product with the
  21. Service Pack:
  22.  
  23.      - LINK386 fixes and upgrades
  24.      - new operating system support leading to increased debugger
  25.        stability
  26.      - Protected Dynamic Link Library (PDLL) support
  27.  
  28.  
  29. IMPORTANT:
  30.   The class libraries provided on this CD-ROM demonstrate the power
  31.   and complexity of the compiler and provide a base from which to use
  32.   and test the C/C++ for OS/2 compiler and the tools associated with it.
  33.   If you are migrating existing C++ applications, you should be aware
  34.   that the standard USL classes (such as iostream, complex, and task),
  35.   referred to in this product as the Basic Class Library or basic classes,
  36.   are NOT included on this CD-ROM.  Code containing a #include directive
  37.   for any of the header files for the basic classes will not compile
  38.   compile correctly and will generate the following error message:
  39.  
  40.      This is an information version of the header file you have
  41.      referenced in the #include. Please refer to the README
  42.      file in the compiler root directory for further instructions.
  43.  
  44.   These classes will be an integral part of the final C/C++ for OS/2
  45.   product, but because of USL licensing restrictions they are being made
  46.   available separately for this beta release.  To obtain the Basic Class
  47.   Library, please follow the instructions on the C++ information card
  48.   included with this CD-ROM.  The documentation for the Basic Class
  49.   Library has been included on this CD-ROM.
  50.  
  51.  
  52. INSTALLATION
  53. _____________
  54.  
  55. INSTALLATION PROCEDURE:
  56.  
  57. The installation procedure will vary slightly depending on the medium
  58. you are using to install from.  You can install directly from the CD-ROM
  59. or you can create diskettes using the diskette images on the CD-ROM.
  60.  
  61. If you are also installing the Developer's Toolkit, and/or WorkFrame/2, the
  62. products should be installed in the following order:
  63.  
  64.         - Developer's Toolkit
  65.         - WorkFrame/2
  66.         - IBM C/C++ for OS/2 V2
  67.  
  68. 1.  From an OS/2 window or full screen, change the current drive and
  69.     directory to the drive and directory where this file is located.  Type
  70.                 INSTALL
  71.     and press Enter.  If you have not disabled the logo display from the
  72.     operating system, the IBM logo appears.  Click on the OK button or
  73.     press Enter to proceed.  A dialog box appears, instructing you to
  74.     wait.  Another dialog box appears to inform you that no online help
  75.     is available.  A dialog box with the installation option
  76.     appears.  The IBM-supplied defaults are preselected.
  77.  
  78. 3.  Choose the options you want to install.  Some options are not
  79.     available in this driver and have been disabled in the dialog box.
  80.     Help is currently not available for the option fields or
  81.     pushbuttons.
  82.  
  83.     NOTE: You do not have to install all the options now.  You can use
  84.           the installation program any time to reinstall or install
  85.           additional options.  At the installation of each option, the
  86.           installation program informs you of the amount of disk space
  87.           which will be used.
  88.  
  89. 4.  When you have chosen the installation options you want, select OK
  90.     or press Enter.  If you are installing from diskettes, the program
  91.     prompts you for the proper diskettes during the installation.
  92.     A window appears and shows you the status of the installation
  93.     program, including which files are being installed and the
  94.     percentage of the total bytes that has been installed.  This window
  95.     can be hidden by clicking on the Hide button and re-opened by
  96.     selecting Option from the menu bar and clicking on the Status button.
  97.  
  98. 5.  If you chose to have your CONFIG.SYS file modified, or are updating
  99.     a previous installation, the installation program creates a backup
  100.     file. A dialog box appears with the default backup name, which you
  101.     can keep, or you can create a new backup file name.
  102.     Then select OK or press Enter.
  103.  
  104.     NOTE: If you do not have the installation program update your
  105.           CONFIG.SYS file, a command file CSETENV.CMD is created,
  106.           which sets up the environment for you, except that
  107.           you must add the DLL subdirectory to your
  108.           LIBPATH statement.  For the full path of this subdirectory,
  109.           see the File Structure diagram.  To use the Execution Trace
  110.           Analyzer, you must add
  111.                    DEVICE = X:\CSETV2\SYS\PROFIT.SYS
  112.           to your CONFIG.SYS file, where X: is the drive where the
  113.           product is installed.
  114.  
  115. 6. When the installation is complete, a message box appears.  Select OK
  116.    to return to the main installation window, and then select Exit from
  117.    the Options pull-down menu to end the installation program.
  118.  
  119. 7. If your CONFIG.SYS file was modified, reboot the system to make the
  120.    changes take effect.
  121.  
  122.    NOTE: Ensure that:
  123.       1) On any system where the Service Pack is not installed,
  124.          your PATH variable is set to point to the compiler's BIN
  125.          directory before the Toolkit's OS2BIN directory or the operating
  126.          system's OS2 directory.  This ensures that the linker
  127.          (LINK386.EXE) shipped with the compiler is used, rather than
  128.          the linker shipped with the Toolkit or operating system.
  129.       2) Your INCLUDE variable is set to point to the compiler's INCLUDE
  130.          directory before the Toolkit's INCLUDE directory.  This ensures
  131.          that all the correct header files are used.  You must also
  132.          ensure that you include os2.h and only os2.h when you use
  133.          OS/2 APIs.
  134.       3) The TMP environment variable is set.  The install program currently
  135.          does not set this variable.  The TMP variable contains the path
  136.          where temporary files are placed.
  137.  
  138. 8. If you install the Execution Trace Analyzer, its device driver must
  139.    reside in a local directory, meaning that it cannot be in a LAN
  140.    directory.  If you are installing on a LAN, when the installation is
  141.    complete, copy PROFIT.SYS to a directory on your workstation and
  142.    ensure that your CONFIG.SYS file contains the statement:
  143.                   DEVICE = X:\dir\PROFIT.SYS
  144.    where X:\dir is the drive and directory where you placed PROFIT.SYS
  145.    It is recommended you put PROFIT.SYS in X:\CSETV2\SYS.
  146.  
  147.  
  148. FILE STRUCTURE:
  149.  
  150.    The subdirectory CSETV2 (or the name you gave in the Target Path
  151.    field) is created automatically by the installation program, and
  152.    contains all other subdirectories and files.
  153.  
  154.    If you install all the options, the file structure is as follows:
  155.  
  156.           ---CSETV2
  157.                |---IBMCLASS
  158.                |---LIB
  159.                |---DLL
  160.                |---BIN
  161.                |---HELP
  162.                |---INCLUDE
  163.                |     +---SYS
  164.                |   LOCALE
  165.                |   SYS
  166.                |   SAMPLES
  167.                |     |---SAMPLE01
  168.                |     |---SAMPLE02
  169.                |     |---SAMPLE03
  170.                |     |---SAMPLE04
  171.                |     |---SAMPLE05
  172.                |     |---SAMPLE06
  173.                |     |---BBXX
  174.                |     |---PROFIT
  175.                |     +---ICLUI
  176.                |           |---TESTCNR
  177.                |           |---TESTDRG
  178.                |           |---TESTMENU
  179.                |           +---TESTWIN
  180.                +---WKFRAME
  181.                      |---PMLINES
  182.                      |---GREP
  183.                      |---TOUCH
  184.                      +---MAHJONGG
  185.  
  186.  
  187. NOTE: The WKFRAME directory contains sample WorkFrame/2 projects for the
  188.       IBM C/C++ Compiler for OS/2.  Do not install WorkFrame/2 in this
  189.       directory.
  190.  
  191.  
  192. NEW FEATURES
  193. _____________
  194.  
  195. COMPILER:
  196.  
  197.    IMPORTANT: Any features mentioned in the documentation accompanying
  198.    this driver that are not mentioned in this list have not yet been
  199.    implemented.
  200.  
  201. 1.  C++
  202.  
  203.     A native 32-bit C++ compiler is now available.  It is based on the
  204.     ANSI working paper, X3J16/92-0060, of June 5, 1992, and also
  205.     implements features of CFRONT 3.0, including template and exception
  206.     handling support.
  207.  
  208. 2.  Precompiled Headers
  209.  
  210.     Precompiled header files are available in this driver, but must be
  211.     written to and read from an HPFS drive.  The FAT file system is not
  212.     yet supported.
  213.  
  214. 3.  Diagnostic Messages
  215.  
  216.     The diagnostic messages have been revised, along with the
  217.     compiler options and #pragma directives that control them,
  218.     to give the user more control over which diagnostics are to be
  219.     performed.  Some messages have been reduced in severity
  220.     from warning to informational.
  221.  
  222. 4.  Virtual Device Driver Support
  223.  
  224.     Support for building virtual device drivers has been added,
  225.     including support for the _Far32  _Pascal calling convention
  226.     and 48-bit function pointers.  This support is only available in
  227.     C programs.  See the Programming Guide for details.
  228.  
  229. 5.  Inlining User Code
  230.  
  231.     Inlining of user code is supported with the /Oi option and the
  232.     _Inline keyword.  Note that the /Oi option only is supported for
  233.     C++ programs.  See the Programming Guide and the C Language
  234.     Reference for more information.
  235.  
  236. 6.  Anonymous Unions
  237.  
  238.     Anonymous unions are now supported for C programs.  See the
  239.     C Language Reference for details.
  240.  
  241. 7.  Compiler Options
  242.  
  243.     The following compiler options have been modified:
  244.  
  245.     /K  - All /K options, which control diagnostic messages, are now
  246.           mapped to the /Wgrp options.  They will not be supported at all
  247.           in future releases of the IBM C/C++ for OS/2 product.
  248.     /La - Now includes a layout of struct and union variables referenced
  249.           by the user.  In C Set/2 V1.0, it included all structures and unions.
  250.           NOTE: This option is only available for C programs.
  251.     /Lx - Generates a cross-reference table of all external variables
  252.           referenced by the user.  In C Set/2 V1.0, it generated
  253.           a cross-reference of all names global and external variables,
  254.           plus all local variables referenced by the user.
  255.           NOTE: This option is only available for C programs.
  256.     /Sm - Controls compiler interpretation of 16-bit keywords.  Does not
  257.           set the migration language level.  See point 9 about the
  258.           removal of migration mode.
  259.  
  260.     The following compiler options are new:
  261.  
  262.     /Fi  - Controls creation of precompiled header files.
  263.     /Gp  - generates code for inclusion in a PDLL. See point 11.
  264.     /G5  - Optimizes code for use with a Pentium** processor.
  265.     /Lb  - Includes a layout of all struct and union variables.
  266.            NOTE: This option is only available for C programs.
  267.     /Ly  - Generates a cross-reference table of all global and external
  268.            variables, plus all local variables referenced by the user.
  269.            NOTE: This option is only available for C programs.
  270.     /Nd  - Specifies names of default data and constant segments.
  271.     /Nt  - Specifies name of default text segments.
  272.     /Oi  - Controls inlining of user code.
  273.     /Pe  - Removes #line directives in preprocessor output.
  274.     /Si  - Controls use of precompiled header files.
  275.     /Su  - Controls size of enum variables (1, 2, or 4 bytes).
  276.            NOTE: For C++ programs, /Su can specify only 1 or 4 bytes.
  277.     /Sv  - Enables memory file support.
  278.            NOTE: This option is currently not supported for C++.
  279.     /Tc  - Tells icc to compile the following file as a C file.
  280.     /Tdc - Tells icc to compile all following source files as C files.
  281.     /Tdp - Tells icc to compile all following source files as C++ files.
  282.     /Tp  - Tells icc to compile the following file as a C++ file.
  283.     /Wgrp - Controls diagnostic messages.
  284.  
  285.     The /Gd+ option can be used for C++ programs; however, only
  286.     C library functions are available.
  287.  
  288. 8.  #pragma Directives
  289.  
  290.     The following #pragma directives have been added or modified:
  291.  
  292.     checkout - Is now mapped to #pragma info.  Is not supported for
  293.                C++ files and will not be supported in future releases.
  294.     entry    - Specifies entry point to the program being built.
  295.                NOTE: This directive is supported for C programs only.
  296.     info     - Controls diagnostic messages.  Replaces the #pragma
  297.                checkout directive.
  298.  
  299. 9.  New Functions
  300.  
  301.     The following low-level functions for port input and output have
  302.     been implemented:
  303.  
  304.     _inp   - Reads a byte from an input port.
  305.     _inpd  - Reads a doubleword from an input port.
  306.     _inpw  - Reads an unsigned short value from an input port.
  307.     _outp  - Writes a byte to an output port.
  308.     _outpd - Writes a doubleword to an output port.
  309.     _outpw - Writes a unsigned short value to an output port.
  310.  
  311.  
  312. 10. Removal of Migration Mode
  313.  
  314.     There is no longer a migration language level.  All migration
  315.     features have been moved under extended mode (/Se).  The migration
  316.     libraries have been merged with the standard libraries.  The /Sm
  317.     option no longer sets the language level; it enables migration
  318.     support, such as ignoring unsupported keywords.
  319.  
  320.  
  321. 11. Optimization
  322.  
  323.     Optimization has been improved.  Among the improvements is the
  324.     utilization of the instruction scheduler.  To invoke the scheduler,
  325.     use the /Ys option.  THIS IS A TEMPORARY OPTION ONLY.
  326.     NOTE: If you encounter problems with optimization, try turning
  327.           optimization on and inlining off (/O+ /Oi-).
  328.  
  329.  
  330. 12. Protected Dynamic Link Libraries (PDLL's)
  331.  
  332.     DLL protection prevents EXEs and non-protected DLLs
  333.     from accidentally accessing data within a protected DLL.
  334.     This is especially important if there is data within the protected
  335.     DLL that is shared among different processes.  A DLL contains shared
  336.     data if the module definition file for the DLL contains
  337.     DATA SINGLE SHARED or if it contains the SHARED attribute for one or
  338.     more segments listed under the SEGMENTS keyword.
  339.  
  340.     Although data in a DLL is usually referred to only by the code
  341.     in the DLL, it is possible for the process calling the DLL to write
  342.     to a DLL data segment.  Because this data segment is in the
  343.     addressable range of the calling process, the process can overwrite
  344.     data in the shared data segment without receiving an error.
  345.     Other processes using the shared data segment can then
  346.     have unexpected results because of the changes to the data.
  347.  
  348.     To create a protected DLL, use the /Gp+ compiler option when you
  349.     compile the DLL source code.  When you specify /Gp+, the
  350.     IBM C/C++ for OS/2 compiler generates special instructions
  351.     in the prolog and epilog of the module.  The calling process can
  352.     then use the data segment through the functions in the DLL, but
  353.     cannot access the segment directly.  If the calling process tries
  354.     to access data within the protected DLL, then a general protection
  355.     exception is raised.
  356.  
  357.     The special instructions are generated for all external functions
  358.     within the DLL.  If a function is not being exported from
  359.     the DLL, you should make it static if possible.  This will
  360.     prevent the compiler from generating the special instructions in
  361.     the prolog and epilog of that function.
  362.  
  363.     NOTE: It is really only necessary to create a protected DLL
  364.           if the DLL contains data segments that will be shared
  365.           by multiple processes. If your module definition file contains
  366.           DATA MULTIPLE NONSHARED and doesn't contain any named shared
  367.           segments, then data being overwritten by one process
  368.           will not affect any other process.
  369.  
  370.     This support is available only with the OS/2 Service Pack.
  371.  
  372.  
  373. DEBUGGER:
  374.  
  375. 1.  Enhancements
  376.  
  377.     The following features have been added to the debugger:
  378.  
  379.     1) A list of entry names is provided for the compilation unit.
  380.     2) You can now do a case-insensitive search on entry names
  381.        and case-insensitive searches within source.
  382.     3) Support for FileList has been added.
  383.     4) Support for executable code in header files has been added.
  384.     5) A new Register window has been added.
  385.     6) Breakpoint support is provided for overloaded entry names.
  386.     7) C++ Class Inheritance View
  387.     8) C++ Class Details Notebook
  388.     9) C++ class monitors
  389.    10) PM Window Analysis
  390.    11) Toolbar for run, step, registers, stack, and storage
  391.    12) Message Queue Monitoring
  392.    13) Improved Stack walking
  393.    14) C - typecast expressions
  394.    15) New font dialog
  395.  
  396.  
  397. EXECUTION TRACE ANALYZER:
  398.  
  399. 1.  Added Support
  400.  
  401.     The following features have been added to this driver:
  402.     1) C++ support
  403.     2) Contextual help (to be completed in a later driver)
  404.     3) File access support
  405.     4) Buffer wrap support
  406.     5) Support for multiple trigger procedures
  407.  
  408.     NOTE: Both /Ti and /Gh must be specified to use the execution
  409.           trace analyzer.
  410.  
  411. 2.  CUA* Conformance
  412.  
  413.     Some changes have been made to the panels in the interface to follow
  414.     the CUA '91 guidelines.  More changes will appear in future drivers.
  415.  
  416.  
  417. IBM CLASS LIBRARIES: COLLECTION CLASSES:
  418.  
  419. 1.  Samples Provided
  420.  
  421.     The CSETV2\SAMPLES\BBXX directory contains samples to familiarize you
  422.     with the IBM Class Libraries: Collection Classes.  Use NMAKE to
  423.     create the executable files from the source provided.  The correct
  424.     output from the executable files is provided in the .xpc files in
  425.     the same directory.
  426.  
  427.  
  428. IBM CLASS LIBRARIES: USER INTERFACE:
  429.  
  430. 1.  Prerequisites
  431.  
  432.     The IBM Class Libraries: User Interface is 32-bit code and only
  433.     supports the IBM C/C++ for OS/2 compiler that it is shipped with.
  434.     Applications built using the library will only run on the OS/2
  435.     2.0 operating system.  Portions of the library use collection classes
  436.     provided by the IBM Class Libraries: Collection Classes library,
  437.     which is also shipped with the IBM C/C++ for OS/2 compiler.
  438.  
  439. 2.  Classes to Replace the OS/2 Developer's Toolkit
  440.  
  441.     Header files from the Developer's Toolkit are not required to use
  442.     the IBM Class Libraries: User Interface classes.  Note that if
  443.     your application needs to call OS/2 or Presentation Manager
  444.     (PM) APIs directly or if it uses typedefs or #defines provided by the
  445.     Developer's Toolkit, you will need to use the Toolkit header files.
  446.  
  447.     Several classes are used to encapsulate constructs typically used
  448.     from the Toolkit header files.  These classes are:
  449.  
  450.     1) Handle classes (for example, IWindowHandle to represent HWND
  451.        values).  These provide automatic conversions to and from the
  452.        corresponding OS/2 types.
  453.  
  454.        Class hierarchy:
  455.        ----------------
  456.  
  457.          IHandle                     - abstract base class
  458.           |-- IAccelTblHandle        - HACCEL
  459.           |-- IAnchorBlockHandle     - HAB
  460.           |-- IBitmapHandle          - HBITMAP
  461.           |    +-- ISysBitmapHandle  - HBITMAP for system-provided bitmaps
  462.           |-- IModuleHandle          - HMODULE
  463.           |-- IMsgQueueHandle        - HMQ
  464.           |-- IPointerHandle         - HPOINTER
  465.           |    +-- ISysPointerHandle - HPOINTER for system-provided icons
  466.           |-- IPresSpaceHandle       - HPS
  467.           |-- IProcAddressHandle     - PID
  468.           |-- IProcessID             - PID
  469.           |-- IProfileHandle         - HINI
  470.           |-- ISemaphoreHandle       - HSEM
  471.           |-- IStringHandle          - HSTR
  472.           |-- IThreadID              - TID
  473.           +-- IWindowHandle          - HWND
  474.  
  475.     2) Style class objects to represent PM window styles and attributes
  476.        (for example, IWindow::visible for WS_VISIBLE).  More details
  477.        follow later.
  478.  
  479.     3) Other classes represent the typedefs for MPARAM and MRESULT.
  480.  
  481.        Class hierarchy:
  482.        ----------------
  483.  
  484.          IEventParam               - MPARAM
  485.          IEventResult              - general MRESULT
  486.           |-- IBooleanResult       - Boolean MRESULT
  487.           |-- IPairResult          - IPair MRESULT
  488.           |-- IPointResult         - IPoint MRESULT
  489.           |-- ISizeResult          - ISize MRESULT
  490.           +-- IUnsignedLongResult  - unsigned long MRESULT
  491.  
  492.     4) Color classes represent the PM CLR_xxx constants.
  493.  
  494.        Class hierarchy:
  495.        ----------------
  496.  
  497.          IColor                    - RGB and color indexes
  498.           |-- IDeviceColor         - device-independent colors (for
  499.           |                          example, default, background, and
  500.           |                          neutral)
  501.           +-- IGUIColor            - system colors
  502.  
  503. 3.  Application and Thread Classes
  504.  
  505.     The IApplication class represents the application.  Other classes
  506.     represent various units of execution and use reference counting to
  507.     support multiple uses of these functions.
  508.  
  509.     Class hierarchy:
  510.     ----------------
  511.  
  512.       IApplication              - process
  513.        +-- ICurrentApplication  - current process
  514.  
  515.       ICritSec                  - OS/2 critical section
  516.  
  517.       IReference                - reference counting
  518.       IRefCounted
  519.        +-- IThreadFn            - function to be executed on a thread
  520.             +-- IThreadMemberFn - class member function run on a thread
  521.  
  522.       IThread                   - thread
  523.        |-- ICurrentThread       - current thread
  524.  
  525.     Below is an example of how main() could be coded using the
  526.     IApplication class:
  527.  
  528.        void  main()
  529.        {
  530.          IApplication app = IApplication(0);
  531.          MyFrameWindow frame(ID_FRAME, 0, 0, IRectangle());
  532.                                   // desktop is parent/owner
  533.          app.current.run();
  534.        }
  535.  
  536. 4.  Handler Classes
  537.  
  538.     The IBM Class Libraries: User Interface library has adopted an
  539.     event-dispatching architecture called handlers.  This architecture
  540.     provides the ability to reuse event processing code.  Most importantly,
  541.     this architecture provides the ability to dispatch a new event when
  542.     extending the library.
  543.  
  544.     The IWindow class provides a setHandler() function to allow handler
  545.     objects to be "registered" for a window/control object.  All handler
  546.     objects for a window are added to a list; new handlers are always
  547.     added to the front of the list.  A window event is dispatched to each
  548.     of the handlers for the window until it is processed.  If the event is
  549.     not processed by any of the handlers in the list, it is then passed to
  550.     the window's handleWindowEvent() function.  If still not processed, it
  551.     is passed to the default window procedure.
  552.  
  553.     Handlers provide virtual functions (callbacks) for event processing.
  554.     Derived classes must override these functions to process an event.
  555.     In most cases, an event class is passed as an argument to the event
  556.     handler functions.  The event handling callback functions return a
  557.     Boolean value, which is used to indicate if the handler object
  558.     processed the event or if the event should be passed on.  A return
  559.     value of true indicates that an action has been taken and that the
  560.     class library should stop dispatching the event.
  561.  
  562.     Member functions in IEvent can be used to set the return result for
  563.     an event (an MRESULT to the system, as in the case of WM_FORMATFRAME).
  564.  
  565.     Control notification messages (WM_CONTROL) and the owner-draw control
  566.     messages (WM_MEASUREITEM and WM_DRAWITEM) are dispatched first to the
  567.     handlers for the control object, then if not processed, to the handlers
  568.     for the owner of the control.
  569.  
  570.     Usage:
  571.     ------
  572.     To handle an event you must subclass the handler class and override
  573.     the appropriate event handling function.
  574.  
  575.     You may subclass by multiply inheriting from the window and handler
  576.     classes. For example:
  577.  
  578.        MyWindow : public IFrameWindow, public ICommandHandler
  579.        {
  580.          //my window class definition
  581.        }
  582.  
  583.     You could also define a new class derived from the handler class
  584.     to provide your event handling processing code.  If the processing
  585.     code can be used in more than one window, for example, editing and
  586.     processing entry-field input, defining a new class may be a better
  587.     approach.  If you take this approach, you must manage your objects
  588.     between the window class and the handler class.
  589.  
  590.     You can either reuse the class and create multiple instances of the
  591.     handler objects to add to the windows, or reuse a single instance of
  592.     the handler object for all windows.  In the latter case, you might
  593.     have to switch on the window ID or an object in IEvent to control
  594.     your processing logic.
  595.  
  596.     Class hierarchy:
  597.     ----------------
  598.  
  599.       IHandler                  - abstract base class
  600.        |-- ICnrEditHandler      - container edit events
  601.        |-- ICnrHandler          - common container events
  602.        |-- ICommandHandler      - WM_COMMAND, WM_SYSCOMMAND
  603.        |-- IDragSourceHandler   - drag events
  604.        |    +--IDragDropEFHandler - drag entry field text
  605.        |-- IDragTargetHandler   - drag events
  606.        |    +--IDragDropEFHandler - drag entry field text
  607.        |-- IEditHandler         - edit (data change) events for
  608.        |                          IComboBox, IEntryField, IMLE, ISlider
  609.        |-- IFontHandler         - font dialog events
  610.        |-- IFocusHandler        - set and lose focus control for
  611.        |                          IListBox, IMultiLineEdit,
  612.        |                          IContainerControl, ISlider, ISpinButton
  613.        |-- IHelpHandler         - help events
  614.        |-- IKeyboardHandler     - WM_CHAR
  615.        |-- IMenuHandler         - menu events
  616.        |-- IMouseClickHandler   - mouse button events
  617.        |-- IPageHandler         - page size change, page selection, and
  618.        |                          page deletion events for INoteBook
  619.        |-- IPaintHandler        - WM_PAINT
  620.        |-- IResizeHandler       - WM_SIZE
  621.        |-- IScrollHandler       - scroll bar events
  622.        |-- ISelectHandler       - select/deselect, Enter key and
  623.        |                          double-click of IComboBox
  624.        |                          IContainerControl, IListBox, and
  625.        |                          non-push-button buttons
  626.        |-- IShowListHandler     - show list event for IComboBox
  627.        +-- ISpinHandler         - spinning events for ISpinButton
  628.  
  629. 5.  Event Classes
  630.  
  631.     The event classes represent PM messages and are the input to
  632.     handler objects.  Classes derived from IEvent typically contain
  633.     specialized member functions to easily obtain information
  634.     specific to that type of event.
  635.  
  636.     Note: IEvent does not support non-window-handle messages.
  637.  
  638.     Class hierarchy:
  639.     ----------------
  640.  
  641.       IEvent                          - base class for general events
  642.        |-- IBeginDragEvent            - drag/drop
  643.        |-- ICnrEvent                  - general container event
  644.        |    |-- ICnrEditEvent         - edit event
  645.        |    |    |-- ICnrBeginEditEvent - text to be edited event
  646.        |    |    |-- ICnrEndEditEvent - text edited event
  647.        |    |    +-- ICnrReallocStringEvent - text edited event
  648.        |    |-- ICnrEmphasisEvent     - emphasis change event
  649.        |    |-- ICnrEnterEvent        - enter/double-click event
  650.        |    |-- ICnrHelpEvent         - help event
  651.        |    +-- ICnrQueryDeltaEvent   - query event
  652.        |-- ICommandEvent              - WM_COMMAND and WM_SYSCOMMAND
  653.        |-- IControlEvent              - WM_CONTROL
  654.             +-- IPageEvent            - notebook page selection
  655.        |-- IDragOperationEvent        - drag/drop
  656.        |    |-- IDragOverEvent        - drag/drop
  657.        |    +-- IDropOnEvent          - drag/drop
  658.        |-- IEndConversationEvent      - drag/drop
  659.        |-- IPaintEvent                - WM_PAINT
  660.        |-- IKeyboardEvent             - WM_CHAR
  661.        |-- IMouseClickEvent           - mouse click messages
  662.        |-- IRenderEvent               - drag/drop
  663.        |    +-- IRenderCompleteEvent  - drag/drop
  664.        |-- IResizeEvent               - WM_SIZE
  665.        |-- IScrollEvent               - WM_VSCROLL, WM_HSCROLL
  666.        +-- IUDragDropRender           - drag/drop
  667.  
  668. 6.  Window Classes
  669.  
  670.     The window class hierarchy has been structured to support handlers,
  671.     frame extensions, and an explicit client area.
  672.  
  673.     IDialogWindow allows you to encapsulate a dialog box created from
  674.     a resource file.
  675.  
  676.     IFrameWindow allows you to create all standard windows.
  677.     This class provides an addControl() function to allow IBM Class
  678.     Library: User Interface control classes to be added as extensions
  679.     to the frame, and a function to set an explicit client area control.
  680.     For example, setting an IContainerControl as the client area will
  681.     create a main container window.
  682.  
  683.     Primary, secondary and child windows are created by specifying the
  684.     appropriate parent and owner of the IFrameWindow or IDialogWindow
  685.     being created.  ITitle, IActionBarMenu, and setIcon() in the
  686.     IApplicationWindow class allow you to set standard parts of a
  687.     standard window.
  688.  
  689.     Class hierarchy:
  690.     ----------------
  691.  
  692.       IWindow                   - abstract base class
  693.        +-- IApplicationWindow   - abstract base class
  694.             |-- IDialogWindow   - dialogs
  695.             |    +-- IFontDialog  - font dialog
  696.             +-- IFrameWindow    - standard windows
  697.  
  698. 7.  Control Classes
  699.  
  700.     Window control classes provide three types of constructors:
  701.  
  702.     - to construct a C++ object and a PM control with any window as
  703.       parent and/or owner
  704.     - to construct a C++ object from a PM control on a dialog
  705.       (the constructor takes the id of the control)
  706.     - to construct a C++ object from a PM control on a window
  707.       (the constructor takes the handle of the control)
  708.  
  709.     Class hierarchy:
  710.     ----------------
  711.  
  712.       IWindow                   - abstract base class
  713.        |-- IControl             - abstract base class for controls
  714.        |     |-- IBitmapControl
  715.        |     |-- IContainerControl
  716.        .     .
  717.        .     .
  718.        .     .
  719.  
  720. 8.  IBitFlag, Styles, and Attributes
  721.  
  722.     When you construct a control, do not specify window and control
  723.     styles as unsigned long values.  You must pass in a Style object
  724.     instead.  Generic window and control styles are listed in
  725.     iwindow.hpp and icontrol.hpp.  These are:
  726.  
  727.        IWindow::noStyle       IWindow::visible
  728.        IWindow::disabled      IWindow::clipChildren
  729.        IWindow::clipSiblings  IWindow::parentClip
  730.        IWindow::saveBits      IWindow::synchPaint
  731.        IControl::group        IControl::tabstop
  732.  
  733.     In general Style and Attribute objects are scoped to a window
  734.     class.  That is, the definitions of the class (done with a macro
  735.     defined in ibitflag.hpp) and the objects are nested within a
  736.     window class definition.  As an example, the definition of the
  737.     IEntryField class in ientryfd.hpp contains the following macro
  738.     which defines a Style class:
  739.  
  740.       INESTEDBITFLAGCLASSDEF2(Style, IEntryField, IWindow, IControl);
  741.  
  742.     Although Style objects can only be constructed from existing Style
  743.     objects, they can be combined using the operator | if the Style
  744.     objects are compatible.  The above macro allows an IEntryField::Style
  745.     object to be combined (using |) with any IEntryField::Style,
  746.     IWindow::Style, or IControl::Style object, but not with any other
  747.     objects (for example, not with an ICheckBox::Style).
  748.  
  749.     The following examples show how Style objects can be used when
  750.     constructing an entry field:
  751.  
  752.     a) IEntryField(ID_EF1, this, this, IRectangle(10, 10, 100, 20),
  753.                    IWindowStyle::visible | IControl::tabstop |
  754.                      IControl::group | IEntryField::margin |
  755.                      IEntryField::autoscroll);
  756.  
  757.     b) IEntryField::Style efsStyle = (IWindowStyle::visible |
  758.                                         IControl::tabstop |
  759.                                         IControl::group |
  760.                                         IEntryField::margin |
  761.                                         IEntryField::autoscroll);
  762.        IEntryField(ID_EF2, this, this, IRectangle(10, 40, 100, 20),
  763.                    efsStyle);
  764.  
  765.     c) IEntryField(ID_EF3, this, this, IRectangle(10, 70, 100, 20),
  766.                    IEntryField::defStyle | IControl::tabstop |
  767.                      IControl::group);
  768.  
  769.     d) IEntryField::setDefaultStyle(IWindowStyle::visible |
  770.                                       IControl::tabstop |
  771.                                       IControl::group |
  772.                                       IEntryField::margin |
  773.                                       IEntryField::autoscroll);
  774.        IEntryField(ID_EF4, this, this, IRectangle(10, 100, 100, 20));
  775.  
  776.     Example (d) shows an entry field being constructed with the default
  777.     style.  The example also shows how the default style provided by
  778.     the class library can be replaced by a user-chosen default in the call
  779.     to setDefaultStyle().
  780.  
  781.     After a control has been constructed, you can query and set its styles
  782.     only through member functions, for example, through the isDisabled(),
  783.     disable() and enable() functions.  Note that not all member functions
  784.     have been yet been added.
  785.  
  786.     Class hierarchy:
  787.     ----------------
  788.  
  789.       IBitFlag                  - abstract base class for bitwise styles
  790.        |                          and attribute flags
  791.        |-- Style                \
  792.        |-- Frame                 \ generally, nested classes
  793.        .                         /
  794.        .                        /
  795.        .
  796.  
  797. 9.  Menu Classes
  798.  
  799.     The menu classes let you construct an action bar or system menu for
  800.     a standard window, or a popup menu for any window.  The ISubMenu
  801.     class provides functions for dynamically changing a menu.
  802.     Just before an IPopUpMenu is displayed it is wrapped in an
  803.     ISubMenu object by IMenuHandler which then calls the overridden
  804.     version of menuShowing().  This call passes a pointer to the newly
  805.     created ISubMenu wrapper. You can then use any of the ISubMenu
  806.     member functions to dynamically refresh the IPopUpMenu before it is
  807.     displayed. When the popup is dismissed, the IMenuHandler calls
  808.     ISubMenu::refresh() to return the IPopUpMenu to its original state.
  809.  
  810.     Class hierarchy:
  811.     ----------------
  812.  
  813.       IMenu                     - abstract base class
  814.        |-- IActionBarMenu
  815.        |-- IPopUpMenu
  816.        |-- ISubMenu
  817.        +-- ISystemMenu
  818.  
  819. 10. Application Resource Library
  820.  
  821.     The IResourceMgr class represents an application resource library.
  822.     The IResourceId class represents a specific resource in a resource
  823.     library.  The default resource library for an IResourceId object
  824.     is supplied by the IApplication::current.resourceLib() function.
  825.  
  826.     Reference counting is provided for all bitmaps and icons to
  827.     support multiple uses of these resources.
  828.  
  829.     Examples:
  830.     ---------
  831.     Given the following function foo:
  832.          foo(const IResourceId&);
  833.  
  834.     a) if the resource is in the default location (see
  835.        IApplication::current.setResourceLib()), you can call:
  836.          foo(ID_MY_RESOURCE);
  837.  
  838.     b) if the resource is in a DLL (not the default location), call:
  839.          IDynamicLinkLibrary dll("mydll");
  840.          foo(IResourceId(ID_MY_RESOURCE, dll));
  841.  
  842.     Class hierarchy:
  843.     ----------------
  844.  
  845.       IResourceLibrary          - resource library
  846.        |-- IDynamicLinkLibrary  - .dll resource library
  847.  
  848.       IResourceId               - resource in a resource library
  849.  
  850. 11. Exception Handling
  851.  
  852.     Classes for exception handling are provided and are used throughout
  853.     the class library.
  854.  
  855.     The IBM Class Libraries: User Interface library has adopted the
  856.     philosophy that exception handling is error handling.  This strategy
  857.     does not attempt to address OS/2 exception processing (signals),
  858.     because they do not fit the C++ exception handling model.  Note that
  859.     a stack-exhausted situation is an out-of-stack exception, and
  860.     therefore is not addressed.
  861.  
  862.     All exceptions should be derived from the base exception class
  863.     IException, which contains the following information:
  864.  
  865.     - A severity (defined as an enumeration) of recoverable or
  866.       unrecoverable.
  867.     - An error code defined by OS/2, PM, the user, or a library.  The
  868.       error code is OPTIONAL.
  869.     - A "stack" of text strings providing detailed information about
  870.       the exception.  This stack captures low-level system information
  871.       about the failure, as well as high-level text that is more
  872.       suitable as message-box text for the end user.  This field is
  873.       OPTIONAL but highly recommended.
  874.     - The module name, function name, and line where the exception is
  875.       thrown and re-thrown.  You can obtain this information with
  876.       IASSERT and ITHROW macros.  You can also call the addLocation
  877.       function yourself to get the same information.
  878.  
  879.     The exception handling component has been designed to integrate
  880.     seamlessly with the exception handling component of the IBM Class
  881.     Libraries: Collection Classes library.
  882.  
  883.     Usage:
  884.     ------
  885.     The exception handling component has been split into 3 header files:
  886.  
  887.     1) iexcbase.hpp
  888.        Contains IException, IExceptionLocation, and derived classes of
  889.        IException.  The IASSERT, ITHROW, IRETHROW, and IEXCEPTIONLOCATION
  890.        macros are also in this header. The header has no dependencies on
  891.        any other classes.
  892.  
  893.     2) iexcept.hpp
  894.        Used to support exception handling in the IBM Class Library: User
  895.        Interface library, and includes iexcbase.hpp.  IExceptionText,
  896.        IErrorInfo (abstract), IGUIErrorInfo, and ISystemErrorInfo are
  897.        "helper" classes in this file.  IExceptionText is used to retrieve
  898.        text from a resource file.  The other classes retrieve the error ID
  899.        and error text from either PM or the OS/2 system.
  900.  
  901.     3) bexcept.hpp
  902.        Contains all of the information specific to the IBM Class Libraries:
  903.        Collection Classes library, primarily their subclasses of
  904.        IException.  These are all collection-specific exception types.
  905.        The exception subclasses in iexcbase.hpp are used for all other
  906.        exception types.
  907.  
  908.     The ITHROW or IASSERT macro should be used to throw an exception.
  909.     IASSERT takes a test expression argument.  If evaluation of the test
  910.     returns 0, an IAssertionFailure exception will be thrown with the
  911.     ITHROW macro.  You can use IASSERT conditionally so that the
  912.     assertions are not delivered in production-level code.  Unconditional
  913.     versions of these checks should be implemented using the
  914.     IInvalidParameter and IInvalidRequest exception classes.
  915.  
  916.     ITHROW takes an exception instance as its only argument.  It captures
  917.     the current location information, and log this information along
  918.     with the rest of the available instance data.  Use IRETHROW to
  919.     re-throw an exception.  You must provide an instance variable in the
  920.     catch statement to log information about where the exception is
  921.     caught and re-thrown, in addition to the original failure information.
  922.  
  923.     Following are all of the constructors necessary to create and throw
  924.     exceptions, followed by some examples.
  925.  
  926.       IException(const char* msg,
  927.                  unsigned long errorId = 0,
  928.                  ExceptionSeverity sev = unrecoverable);
  929.  
  930.       IExceptionText(const IResourceId& resid);
  931.  
  932.       IGUIErrorInfo(const char* GUIFunctionName = 0);
  933.  
  934.       ISystemErrorInfo(unsigned long sysErrorId,
  935.                        const char* sysFunctionName = 0);
  936.  
  937.     Examples:
  938.     ---------
  939.     a) Load the message text from a resource file:
  940.  
  941.         Boolean bSuccess = WinBroadcastMsg(IWindowHandle((unsigned long)hCl),
  942.                                            ulClEvtId, epCl1, epCl2, ulCmd);
  943.         if (bSuccess == false)
  944.         {
  945.            IInvalidRequest ex(IExceptionText(IResourceId(IC_BROADCASTMSGFAIL,
  946.                                                      IIBMClass::resource())),
  947.                               IC_BROADCASTMSGFAIL,
  948.                               recoverable);
  949.            ITHROW(ex);
  950.         }
  951.  
  952.     b) Use the system-provided text for an error detected by PM:
  953.  
  954.        void* pv = WinQueryWindowPtr(hCl, sThisPtrOffset);
  955.        if (pv == 0)
  956.        {
  957.           IGUIErrorInfo err("WinQueryWindowPtr");
  958.           IInvalidRequest ex(err.text(), err.errorId(), recoverable);
  959.           ITHROW(ex);
  960.        }
  961.  
  962.     c) Use the system-provided text for an error detected by OS/2:
  963.  
  964.        unsigned long ulErrorCode = DosFreeModule(hmodClResource);
  965.        if(ulErrorCode != 0)
  966.        {
  967.           ISystemErrorInfo errinf(ulErrorCode, "DosFreeModule");
  968.           IAccessError exc(errinf.text(), errinf.errorId(), recoverable);
  969.           ITHROW(exc);
  970.        }
  971.  
  972.     Note: You may want to provide your own message loaded from a
  973.           resource file for an OS/2 or PM error as in example a).
  974.           You should also use the IGUIErrorInfo or ISystemErrorInfo
  975.           as appropriate to retrieve the error ID and pass it in on
  976.           the constructor of the exception.
  977.  
  978.     Class hierarchy:
  979.     ----------------
  980.  
  981.       IException                - base class
  982.        |-- IAccessError         - logical, for example, resource not found
  983.        |-- IAssertionFailure    - generated by the IASSERT macro
  984.        |-- IDeviceError         - for example, hardware problem
  985.        |-- IInvalidParameter    - out of range, null pointer, or
  986.        |                          value not valid
  987.        |-- IInvalidRequest      - for the object's current state
  988.        |-- IResourceExhausted
  989.             |-- IOutOfMemory
  990.             |-- IOutOfSystemResource
  991.             |-- IOutOfWindowResource
  992.  
  993. 12. Resource locking
  994.     The IResourceLock class represents OS/2 semaphores.
  995.  
  996.  
  997. WORKFRAME/2:
  998.  
  999. 1.  This version will function properly in a DBCS codepage.
  1000.  
  1001. 2.  In the Program Type group, a radio button labeled "Windows"
  1002.     has been added.  You can use this button to install Windows-based
  1003.     tools in the Tools pulldown menu.  However, the tool can only
  1004.     be started in Windows full-screen mode.
  1005.  
  1006. 3.  A special program and sample language profile have been provided to
  1007.     help users whose compilers experience "out-of-file-handles" problems
  1008.     during compilation.  The WCL.EXE program has been customized to
  1009.     invoke CL.EXE by default.  To override the compiler invoked, set the
  1010.     WCL environment variable to your compiler before you start the
  1011.     WorkFrame/2 product.
  1012.     NOTE: When the compiler is running outside of the WorkFrame/2
  1013.     product, this solution will not help.
  1014.  
  1015. 4.  If you use tools (compilers, linkers, or other tools) that
  1016.     are DOS-hosted, output from these tools are sent to a DOS
  1017.     session.  Therefore you cannot select or drag an error
  1018.     message to an editor session to see the context of the error
  1019.     or get help for it.  However, if your tool is an OS/2 tool
  1020.     with DOS as the target environment, this restriction does not
  1021.     apply.
  1022.  
  1023. 5.  Special considerations when using hidden windows and the
  1024.     Switch list pulldown:
  1025.  
  1026.     Windows or folders that are hidden (not minimized) appear
  1027.     in the Configure Switch List dialog as visible / jumpable, just
  1028.     as they would if they were minimized.
  1029.  
  1030.     However, if you select a hidden window or folder in the Configure
  1031.     Switch List dialog so that it will appear in the Switch
  1032.     list pull-down menu, selecting that menu item from the Switch
  1033.     List will not resurface the window or folder.
  1034.  
  1035.     Hidden windows and folders must be resurfaced from the OS/2
  1036.     Window List.
  1037.  
  1038.     Alternatively, you can use the Window page of the Settings
  1039.     notebook to change the minimized button behavior for the window
  1040.     or folder.
  1041.  
  1042. 6.  Default Editor
  1043.  
  1044.     This version of the WorkFrame/2 product automatically sets up
  1045.     the OS/2 Enhanced editor as the default editor.   To change
  1046.     the default editor, select Configure->Editor... from the
  1047.     main action bar.
  1048.  
  1049. 7.  User Interface
  1050.  
  1051.     The user interface in this version is identical to the WorkFrame/2
  1052.     V1.0 product.  Upcoming versions will contain significant changes
  1053.     to this user interface.
  1054.  
  1055.  
  1056.  
  1057. RELEASE CONSIDERATIONS:
  1058. _______________________
  1059.  
  1060. COMPILER IN GENERAL:
  1061.  
  1062. 1. Predefined Macros
  1063.  
  1064.    The __TIMESTAMP__ macro is not supported in this driver for C or
  1065.    C++ programs.  If this macro is used, it will expand to the wrong
  1066.    value. The __DATE__ and __TIME__ macros are fully supported.
  1067.  
  1068. 2. chmod() Function
  1069.  
  1070.    chmod() will permit you to change the access mode of a directory
  1071.    that is under a FAT file system.  This is due to a malfunction in
  1072.    the OS/2 API DosSetPathInfo which will be fixed in later releases
  1073.    of the OS/2 operating system.
  1074.  
  1075. 3. Restrictions on Freeing Memory
  1076.  
  1077.    When you use the debug memory management functions (defining the
  1078.    __DEBUG_ALLOC__ macro), you must use the normal version of free()
  1079.    to free the memory for the following functions:
  1080.  
  1081.         asctime          strdup
  1082.         _fullpath        tempnam
  1083.         getcwd           tmpnam
  1084.         _getdcwd
  1085.  
  1086.    To ensure the correct version of free is called, place parentheses
  1087.    around the function call.
  1088.  
  1089. 4. #pragma alloc_text
  1090.  
  1091.    In programs containing both #pragma alloc_text and #pragma data_seg,
  1092.    all #pragma data_seg directives must precede the #pragma alloc_text
  1093.    directives.
  1094.  
  1095.    #pragma data_seg applies only to 32-bit data segments.  Data
  1096.    placed in 16-bit segments because of the /Gt option or
  1097.    #pragma seg16 are not affected by #pragma data_seg, and are
  1098.    placed in 16-bit data segments.
  1099.  
  1100.    #pragma alloc_text is not yet supported for use in C++ programs.
  1101.  
  1102.  
  1103. 5. Bit-Fields and Postfix Operators
  1104.  
  1105.    Programs containing post-increment or post-decrement operations
  1106.    on bit-fields will not compile correctly.
  1107.  
  1108. 6. Stack Probes
  1109.  
  1110.    The code to provide stack probes may not be generated when stack
  1111.    frames contain more than 2KB of automatic storage but less than 4KB
  1112.    of automatic storage.  The code generated for stack probing may be
  1113.    incorrect.
  1114.  
  1115. 7. Binding Runtime Messages
  1116.  
  1117.    You can use the MSGBIND utility from the OS/2 2.0 Developer's
  1118.    Toolkit to bind the C/C for OS/2 run-time messages to your application.
  1119.    To do so, you must use the message identifiers, not the message
  1120.    numbers listed in the IBM C/C++ for OS/2 Online Reference.  To get
  1121.    the identifiers from the message numbers, change the EDC prefix to
  1122.    DDE, and subtract 5000 from the message number.  For example, to
  1123.    bind message EDC5101 to your application, use DDE0101 in your
  1124.    message bind file.
  1125.  
  1126. 8. 48-bit Function Pointers
  1127.  
  1128.    You cannot convert other types to a 48-bit function pointer, and
  1129.    you cannot return a 48-bit function pointer that is a structure
  1130.    or union member.
  1131.  
  1132. 9. Listing Files
  1133.  
  1134.    The line and column numbers given in listing files may not be
  1135.    correct.  Use the coordinates from the console files instead.
  1136.  
  1137.  
  1138. FOR C++ PROGRAMS:
  1139.  
  1140. 1. Compiler Options
  1141.  
  1142.    /Fd  -  You must compile ALL files with the /Fd+ option.  You can
  1143.            specify this option on the command line or using the ICC
  1144.            environment variable.
  1145.  
  1146.    /G3  -  You must compile C++ files with this option (it is the default).
  1147.            The /G4 and /G5 options are not available for C++ files in
  1148.            this driver.
  1149.  
  1150. 2. Multithread Support
  1151.  
  1152.    The multithread library provides multithread versions of the C
  1153.    runtime and iostream libraries ONLY.  The C++ runtime library remains
  1154.    single-thread.
  1155.  
  1156. 3. Template Support
  1157.  
  1158.    There are two ways to structure your program using templates:
  1159.  
  1160.    1) Include the function template definition in all files that may
  1161.       reference the corresponding template functions.
  1162.  
  1163.    2) Include the declaration for a function template in all files that  may
  1164.       reference the corresponding template functions, but only include
  1165.       the function definition in one file.
  1166.  
  1167.    These methods use DDE4MNCH (see the DDE4MNCH.DOC file in the HELP
  1168.    subdirectory for more information).
  1169.  
  1170.    The following example uses 2 files to illustrate both methods:
  1171.  
  1172.    File stack.h:
  1173.        #ifndef _STACK_TPL_H
  1174.           #define _STACK_TPL_H
  1175.  
  1176.           template<class T>
  1177.           class stack
  1178.           {
  1179.              private:
  1180.                 T*  v;
  1181.                 T*  p;
  1182.                 int sz;
  1183.  
  1184.              public:
  1185.                       stack( int );
  1186.                       ~stack();
  1187.                  void push( T );
  1188.           };
  1189.        #endif
  1190.     File stackdef.h
  1191.        #include "stack.h"
  1192.  
  1193.        template<class T> stack<T>::stack( int s )
  1194.        {
  1195.           v = p = new T[sz=s];
  1196.        }
  1197.  
  1198.        template<class T> stack<T>::~stack()
  1199.        {
  1200.           delete [] v;
  1201.        }
  1202.  
  1203.        template<class T> void stack<T>::push( T a )
  1204.        {
  1205.           *p++ = a;
  1206.        }
  1207.  
  1208.    To instantiate a stack of 50 objects of type int, declare
  1209.        stack<int> intStack(50);
  1210.    in each source file.
  1211.  
  1212.    For method 1), each source file using the template would include both
  1213.    stack.h and stackdef.h.
  1214.    For method 2), each source file would include stack.h but only one
  1215.    of the files would include stackdef.h.
  1216.  
  1217.    For more information on using templates, see the IBM C/C++ for
  1218.    OS/2 C++ Language Reference.
  1219.  
  1220.    NOTE:
  1221.       a) You should explicitly initialize static data members of a
  1222.          template class for each instance of the template,
  1223.          rather than using a template initializer.  The following
  1224.          example demonstrates this point:
  1225.  
  1226.             template <class T>  X {
  1227.                   static int thing;
  1228.             };
  1229.  
  1230.             template <class T>  int X<T>::thing = 1;    // linker error
  1231.  
  1232.             X<char>  anXOfChar;
  1233.  
  1234.             int X<char>::thing = 1;  // OK
  1235.  
  1236.       b) A virtual non-inlined member function X defined in a template
  1237.          that is included in more than one compilation unit may result
  1238.          in multiply-defined symbols at link time.  A way around this
  1239.          problem is to define the function X as inlined.  The following
  1240.          example demonstrates the problem and a workaround:
  1241.  
  1242.  
  1243.          // file: Object.h
  1244.          //---------------------------------------------------------
  1245.          //
  1246.          #ifndef _OBJECT_H
  1247.             #define _OBJECT_H
  1248.  
  1249.             template<class T> struct BaseStack
  1250.             {
  1251.                virtual void push( T ) {};
  1252.             };
  1253.  
  1254.  
  1255.             template<class T> struct stack : public BaseStack<T>
  1256.             {
  1257.                virtual void push( T );     // This will produce the error
  1258.          /*
  1259.                virtual inline void push( T );
  1260.                                      // This will not produce the error
  1261.          */
  1262.             };
  1263.  
  1264.  
  1265.             template<class T>
  1266.              void stack<T>::push( T a ) {} // This will produce the error
  1267.          /*
  1268.            template<class T>
  1269.             inline void stack<T>::push( T a ) {}
  1270.                                     // This will not produce the error
  1271.          */
  1272.  
  1273.             class TestObject
  1274.             {
  1275.                stack<int> stack1;
  1276.             };
  1277.          #endif
  1278.  
  1279.  
  1280.          // file: Object1.cpp
  1281.          //------------------------------------------------------
  1282.          //
  1283.          #include "object.h"
  1284.  
  1285.          void func1() { }
  1286.  
  1287.  
  1288.          // file: Object2.cpp
  1289.          //------------------------------------------------------------
  1290.          //
  1291.          #include "object.h"
  1292.  
  1293.          void main() { }
  1294.  
  1295.  
  1296.  
  1297. 4. Memory and Space Requirements
  1298.  
  1299.    The current driver requires a large amount of memory.  Compiling the
  1300.    compiler produces swap files of up to 12M.
  1301.  
  1302.    Including debug information (with the /Ti+ option) can greatly
  1303.    increase the size of your object and executable files.
  1304.  
  1305. 5. System Header Files
  1306.  
  1307.    New versions of several system header files have been provided
  1308.    for C++ support.  These files are: os2.h, bsedos.h, and os2def.h.
  1309.    Ensure that the CSETV2\INCLUDE directory appears before the Toolkit's
  1310.    INCLUDE directory so you include the correct header files.
  1311.    You must also ensure that you include os2.h and ONLY os2.h when you
  1312.    use system APIs.
  1313.  
  1314. 6. Nested Parentheses
  1315.  
  1316.    You can use approximately 25 levels of nested parentheses.  After
  1317.    that level, the compiler runs out of stack space and traps.
  1318.  
  1319. 7. static Keyword
  1320.  
  1321.    The keyword static cannot be used with prototypes that contain
  1322.    linkage keywords.
  1323.  
  1324. 8. TMP Environment Variable
  1325.  
  1326.    The compiler will not work if the TMP environment is not set.
  1327.  
  1328. DEBUGGER:
  1329.  
  1330. 1.  Unsupported C++ Constructs
  1331.  
  1332.     The following C++ constructs are not supported in this driver:
  1333.  
  1334.      1) The pointer to member operator.
  1335.  
  1336.      2) Static members.
  1337.  
  1338.      3) The && and || operators are not supported in expressions.
  1339.  
  1340.      4) Assignments are not supported and will not be supported in
  1341.         an expression.  Assignments within an expression will cause
  1342.         the debugger to terminate abnormally.
  1343.  
  1344.      5) Data members within member functions cannot be monitored.
  1345.  
  1346.      6) Pointers within a class cannot be dereferenced.
  1347.  
  1348.      7) Nested classes are only partially supported.  They can be
  1349.         displayed in the monitor of the enclosing class, but you cannot
  1350.         monitor expressions involving elements of the nested class.
  1351.  
  1352.      8) Data displayed for virtual base classes is incorrect.
  1353.  
  1354. 2.  Problems with Views
  1355.  
  1356.     The inheritance and class details views do not provide the correct
  1357.     information.  The inheritance view graph has nodes that are blank.
  1358.     Double-clicking on the blank nodes or any node connectected
  1359.     to a blank node will cause the debugger to terminate abnormally.
  1360.  
  1361. 3.  Templates
  1362.  
  1363.     Templates are partially supported in this driver.
  1364.     It is possible to step in all views, source, disassembly, and
  1365.     annotated.  Local variables are supported.  Monitor popups are
  1366.     not always supported.  Line breakpoints are not supported.
  1367.  
  1368. 4.  Message Queue Monitoring
  1369.  
  1370.     Message Queue Monitoring cannot be enabled until after
  1371.     the PM message queue has been created.  The message queue
  1372.     monitoring must be closed before the message queue is
  1373.     deleted.
  1374.  
  1375. 5.  Breakpoint Dialogs
  1376.  
  1377.     New breakpoint dialogs are under development and are not yet
  1378.     fully functional.  Only the SET and LIST functions currently work.
  1379.  
  1380.  
  1381. EXECUTION TRACE ANALYZER:
  1382.  
  1383. 1. Execution Density Diagram
  1384.  
  1385.    At very high scale setting, the Execution Density Diagram (PEXCDENS)
  1386.    may end abnormally and return to the command prompt.
  1387.  
  1388. 2. Response Delay
  1389.  
  1390.    When you invoke the display program, the system response may be
  1391.    delayed.  For large trace files, the system might lock up for up
  1392.    to 1 minute.
  1393.  
  1394. 3. Dynamic Call Graph Display
  1395.  
  1396.    In the dynamic call graph display, the data representing the number
  1397.    of calls between functions may not be correct.  The other data
  1398.    representations in this display are correct.
  1399.  
  1400. 4. Permanent Restrictions
  1401.  
  1402.    The following restrictions for the analyzer are permanent:
  1403.  
  1404.    1) The Execution Trace Analyzer only works for applications generated
  1405.       by the IBM C/C++ for OS/2 compiler.  Executables and DLLs produced
  1406.       by other compilers (including 16-bit) cannot be used.
  1407.  
  1408.    2) The analyzer can trace up to 16 threads per application.
  1409.  
  1410.    3) The analyzer cannot generate or analyze trace data for child
  1411.       processes in a multiprocess application.
  1412.  
  1413.    4) Dynamically-loaded DLLs cannot be traced.
  1414.  
  1415.  
  1416. IBM CLASS LIBRARIES: COLLECTION CLASSES:
  1417.  
  1418. 1. Using Multiple Compilation Units
  1419.  
  1420.    Using the Collection Classes in more than one compilation unit
  1421.    results in multiply-defined symbols at link time.
  1422.  
  1423.    For information on other restrictions, please refer to the chapter
  1424.    'Current Restrictions' in the IBM Class Libraries: Collection Classes
  1425.    Reference.
  1426.  
  1427.  
  1428. IBM CLASS LIBRARIES: USER INTERFACE:
  1429.  
  1430. 1. DLL Support
  1431.  
  1432.    The class library is currently shipped only in the form of object
  1433.    libraries; there are no DLLs.  To build an executable module (.EXE),
  1434.    you must statically link object modules from the shipped .LIB files.
  1435.    In a future driver, both DLLs and object libraries will be provided.
  1436.  
  1437. 2. Collections
  1438.  
  1439.    The set and link list classes currently provided by the class library
  1440.    will be removed in a future driver.  Of these, only the IGSet1
  1441.    template class is externalized by the rest of the library (the other
  1442.    set and link list classes are only used internally).  These
  1443.    externalized uses of IGSet1, primarily in the container and drag/drop
  1444.    classes, will be changed to use the IGSet template class provided by
  1445.    the IBM Class Libraries: Collection Classes library.
  1446.  
  1447.    To ease the migration from IGSet1 to IGSet, functions provided in
  1448.    the IGSet1 class have interfaces that are identical to the IGSet
  1449.    classes provided by the IBM Class Libraries: Collection Class
  1450.    library.  Note, however, that not all functions supported by IGSet
  1451.    are supported by IGSet1 (for example, iterators).  The other set and
  1452.    link list classes should not be used because no migration path will
  1453.    be provided to the IBM Class Libraries: Collection Class library
  1454.    when they are removed.
  1455.  
  1456. 3. Control Classes
  1457.  
  1458.    Some control classes are missing member functions to query and change
  1459.    individual styles.
  1460.  
  1461. 4. Container Restrictions
  1462.  
  1463.    The following restrictions apply to containers:
  1464.    - The drag and drop interface is not yet supported.
  1465.    - Popup menus are not yet supported.
  1466.    - ICnrSelectActionHandler has not yet been implemented.
  1467.  
  1468. 5. Missing Classes
  1469.  
  1470.    The following classes were planned for, but are missing from this
  1471.    driver:
  1472.  
  1473.      IFileDialog, IFilePkg, IFontPkg, IComboBox,
  1474.      ISlider, IProgressIndicator
  1475.  
  1476. 6. NLS/DBCS Support
  1477.  
  1478.    At this time, full NLS and DBCS is not yet provided.
  1479.  
  1480. 7. Future Changes
  1481.  
  1482.    The class names, function names and function arguments are subject
  1483.    to change.  Changes may result from IBM Quality and Usability reviews,
  1484.    function corrections, fixes to bugs, or feedback from beta users.
  1485.  
  1486.  
  1487. WORKFRAME/2:
  1488.  
  1489. 1. Library Manager
  1490.  
  1491.    The Library Manager (LIB) cannot access read-only object files.
  1492.  
  1493. 2. Window Positions
  1494.  
  1495.    If you save the window positions while the main WorkFrame/2 window
  1496.    is maximized, the main window will not appear the next time you
  1497.    start the WorkFrame/2 program.  If the main window and its action
  1498.    bar are not visible when you start the program, select the Action
  1499.    Log window and press Ctrl-F6 followed by Ctrl-F5 until the main
  1500.    window is restored.
  1501.  
  1502.  
  1503. DOCUMENTATION
  1504. _____________
  1505.  
  1506. The following documentation is provided with this driver in .INF format.
  1507. Use the  view  command to read these files:
  1508.  
  1509.   DDE4CLRM.INF - C Language Reference
  1510.   DDE4CPP.INF  - C++ Language Reference
  1511.   DDE4CLIB.INF - C Library Reference
  1512.   DDE4BCL.INF  - Basic Class Library Reference
  1513.   DDE4CCL.INF  - IBM Class Libraries: Collection Classes Reference
  1514.   DDE4UIL.INF  - IBM Class Libraries: User Interface Library Reference
  1515.  
  1516. The C++ Language Reference and Basic Class Library Reference are
  1517. undergoing a change in format and are not yet finished.  For this
  1518. reason, they are also provided in their original format and can be
  1519. printed on a PostScript printer.
  1520.  
  1521. The following documentation is provided in PS or LISTPS format and
  1522. can be printed on a PostScript printer:
  1523.  
  1524.   DDE4PG     -  Programming Guide
  1525.   DDE4RSUM   -  Reference Summary
  1526.   DDE4CPP    -  C++ Language Reference
  1527.   DDE4BCL    -  Basic Class Library Reference
  1528.   DDE4DEBG   -  Debugger Introduction
  1529.   DDE4XANL   -  Execution Trace Analyzer Introduction
  1530.   DDE3WINT   -  WorkFrame/2 Introduction
  1531.   DDE3WAPI   -  WorkFrame/2 API Guide
  1532.  
  1533. These documents are also available in BookManager* READ format in the
  1534. BOOKS directory on the CD-ROM, and can be read using the IBM Library Reader.
  1535.  
  1536. IMPORTANT:  BookManager books will NOT be shipped with IBM C/C++ for OS/2
  1537.             when the product becomes generally available.  They will be
  1538.             separately orderable from the product.
  1539.  
  1540.  
  1541. SUPPORT
  1542. _______
  1543.  
  1544. Support is on a best-effort basis and will most likely result in a fix
  1545. being provided in a subsequent driver.  Please report all problems, questions,
  1546. suggestions, and so on to the OS2DEV forum on CompuServe.
  1547.  
  1548. Please include a complete description of the problem as well as a small
  1549. (up to 100 lines if possible) testcase that demonstrates the problem.
  1550.  
  1551.  
  1552. Enjoy,
  1553.  
  1554.    Your IBM Development Team
  1555.  
  1556.  
  1557. TRADEMARKS AND SERVICE MARKS:
  1558. _____________________________
  1559.  
  1560. The following items are trademarks of the IBM Corporation and are
  1561. indicated by an asterisk the first time they appear in the text:
  1562.  
  1563.     BookManager
  1564.     C Set/2
  1565.     CUA
  1566.     IBM
  1567.     OS/2
  1568.     Presentation Manager
  1569.     WorkFrame/2
  1570.  
  1571. The following item is a trademark of the Intel Corporation and is
  1572. indicated by a double asterisk the first time it appears in the text:
  1573.  
  1574.     Pentium
  1575.