Open Class Library (OCL) FAQ

By Stéphane Charette

History of the Open Class Library FAQ
The revision history is as follows:

How to obtain a copy of the FAQ
To obtain a HTML copy of the FAQ for local installation, download the file ocl_faq.zip.

Unzip this file in it's own directory (if using PKUNZIP, remember to use the /D option to create the subdirectories) and use your favourite web browser to access the files locally.

Where to obtain additional information
The on-line reference for OCL is located in your VisualAge folder, under the VisualAge C++ Information folder. The reference .INF file should be titled Open Class Library Reference (\IBMCPP\HELP\CLREF.INF) while a second .INF user's guide is called Open Class Library User's Guide (\IBMCPP\HELP\CPPCLSUG.INF).

The first book, Open Class Library Reference has all of the documented methods, objects, and necessary include files. The easiest way to find what you need is probably to click on Classes By Name, normally the second option from the top (may depend on the version of the documentation).

Note that one of the most useful .INF books which IBM ships with VisualAge can easily be overlooked; in the VisualAge C++ Information folder is a book called VisualAge C++ Frequently Asked Questions which deals with quite a few OCL topics.

Additional information on programming using OCL can be obtained from a variety of sources. There is an increase in books published (some of which by IBM) which deal with OCL, as well as numerous sources on the Internet.

For more information, consult:
 * [ocl*.zip] ([hobbes_index.html index of samples])
 * ftp://service.boulder.ibm.com/ps/products/visualagecpp/tools (IBM VB and OCL sample code)
 * (Chinese version of the OCL-FAQ)
 * http://www.davebsoft.com/Programming/tips (Dave Briccetti's OS/2 Warp Programming Tips and Samples)
 * news://comp.os.os2.programmer.oop
 * news://productnews.taligent.com/taligent.products.openclass (Taligent's OCL News Server)
 * news://productnews.taligent.com/taligent.products.openclass (Taligent's OCL News Server)

Books which deal with OCL are:


 * OS/2 Class Library: Power GUI Programming with C/Set++
 * Written by Leon, Law, Love Tsuji & Olson
 * Published by John Wiley & Sons
 * ISBN 0-471-13117-2
 * (Obsolete and replaced by the following book)


 * Power GUI Programming with VisualAge C++
 * Written by Law, Love, Olson & Tsuji
 * Published by John Wiley & Sons
 * ISBN 0-471-16482-8
 * (recommended by Mark Anderson, os2team@romeop03.fishkill.ibm.com)

Index of samples on Hobbes
Starting mid-June, 1997, I have begun to upload to ftp://hobbes.nmsu.edu/pub/os2/dev/cplusplus a series of Open Class Library samples that I have written. The following table is the index of these samples.


 * Note:See also

How to Compile
If you wish to correctly compile your OCL application, then the following should be used:
 * if you are using the project templates and WorkFrame that come with Visual Age, then
 * click on
 * make certain that  is set to
 * expand the  subtree
 * right-mouse-click on
 * select
 * select the  tab
 * select the  option for   (this sets the /Gm+ flag)
 * click on
 * close the tools setup
 * regenerate the makefile and recompile
 * if you are compiling from the command-line, or using your own makefiles, then
 * use the command


 * Note:
 * See also, , and

Required compiler flag
There is one flag that absolutely must be specified when compiling source code which uses OCL calls. This flag is described as follows in the on-line help:
 * /Gm+
 * Link with multithread runtime libraries.

The default for ICC is to use /Gm- (no support for the multithreaded libraries) so the /Gm+ flag must be specified. Typical compiler behaviour when this flag is not specified is: D:\IBMCPP\INCLUDE\ibase.hpp(226:3) : error EDC3086: Error: Use of IBM Open Class Library requires the /Gm+ compiler option. D:\IBMCPP\INCLUDE\ibase.hpp(227:3) : error EDC3086: Check the makefile (or its profile) for a missing /Gm+ option. Note: See also and

Errors in IBM's include files
If your source code has the extension .c and you are including some OCL #includes, then the compiler may generate many errors which seem to come from the IBMCPP include files. These errors are generated because the compiler assumes that .c files only contain C code, not C++, and the OCL include files require the compiler to be in the C++ mode.

To get around this problem, use the compiler flag /Tdp to tell the VAC++ to treat all files as C++ files.

Some of the errors you may be seeing include the following: imsgtext.hpp(24:1) : error EDC0166: Definition of function class requires parentheses. imsgtext.hpp(24:7) : error EDC0275: Unexpected text IMessageText encountered. imsgtext.hpp(27:19) : error EDC0046: Syntax error. imsgtext.hpp(28:33) : error EDC0045: Undeclared identifier messageFileName. imsgtext.hpp(29:33) : error EDC0045: Undeclared identifier textInsert1.


 * Note:
 * See also

How to link
The recommended method of linking when some or all of the object files have references to OCL function calls is to use ICC, and not LINK386, ILINK, etc.

To link an object file (.OBJ) which makes use of OCL, the following should be used:
 * if you are using the project templates and WorkFrame that come with VisualAge C++, then
 * click on
 * make certain that  is set to
 * right-mouse-click on
 * click on
 * make certain that:
 * general.class ==
 * general.name ==
 * general.program ==
 * general.session ==
 * general.action applies to, not
 * types.source ==
 * types.target ==
 * support.name ==
 * support.entrypoint ==
 * click on
 * close the tools setup
 * regenerate the makefile to use the new link method, recompile and link
 * if you are linking from the command-line, or using your own makefiles, then
 * use the command


 * Note:
 * See also, and

Static linking
Static linking will combine the IBM Open Class Library files with your object files to create a stand-alone application. This means that you are not required to have a copy of the  files on your system in order to run the application.

The side effect of using this will be that your application may appear to be quite enormous in size.

To use 'static linking' you must specify the  (this is the default) option when compiling your .CPP files. You can change this setting by one of the following methods:


 * if you are using the project templates and WorkFrame that come with VisualAge, then
 * click on
 * make certain that  is set to
 * expand the  subtree
 * right-mouse-click on
 * select
 * select the  tab
 * select the  option for
 * click on
 * close the tools setup
 * regenerate the makefile and recompile
 * if you are compiling from the command-line, or using your own makefiles, then
 * make certain that the  option is specified


 * Note:
 * See also [dynamic_linking.html Dynamic Linking] and [how_to_link.html How to Link]


 * Note:
 * Need info on rights, etc...are you allowed to distribute an application that was statically linked? Isn't there something in the docs? I haven't had the time to look it up yet -- if someone has references handy, please let me know.

Dynamic linking
Dynamic linking will setup your application to call the necessary OCL functions dynamically using DLLs. This assumes that the required DLL files are already referenced somewhere in LIBPATH before the application will run.

This is much faster to link, and the resulting application will be much smaller than using static linking. Of course, if the IBM VisualAge DLLs are not on the system which will be using this application, then it will fail to run. A typical application nearing 800Kb when linked statically may barely surpass 40Kb when linked dynamically.

To use 'dynamic linking' you must specify the  (this is not the default) option when compiling your .CPP files. You can change this setting by one of the following methods:


 * if you are using the project templates and WorkFrame that come with Visual Age, then
 * click on
 * make certain that  is set to
 * expand the  subtree
 * right-mouse-click on
 * select
 * select the  tab
 * select the  option for
 * click on
 * close the tools setup
 * regenerate the makefile and recompile
 * if you are compiling from the command-line, or using your own makefiles, then
 * make certain that the /Gd+ option is specified.


 * Note:
 * See also [static_linking.html Static Linking] and [how_to_link.html How to Link]


 * Note:
 * Need info on rights, etc...are you allowed to distribute the DLLs with an application that was dynamically linked? Isn't there something in the docs? I haven't had the time to look it up yet - if someone has references handy, please let me know.

Application dies when starting
If your application compiles and links without problems, but it then dies during startup (you may or may not see the frame window start to come up) then check for the following common mistakes:
 * is more than one resource using the same number in your .RC or .DLG file?
 * are you trying to allocate/create a resource in your .CPP file - say an IPushButton - when in reality it has been defined as something else in your .RC or .DLG file?
 * Bill Law (law@netscape.com) also says: The most common occurrence is that your app is throwing an (uncaught) exception during construction of the first (frame) window. This terminates silently, unless you take steps to capture the exception information. To do that, follow the instructions provided in the on-line VACPP FAQ (in the section "Coding With User Interface Classes"->"Exceptions"->"Why Does My Program Just Exit").


 * did you specify the type of application when linking? If the application is compiled with the default value of  then your window will not come up. Make certain you use   from the linker, or   when linking directly from the compiler.

Application-modal windows
To create an application modal dialog window, the parent and the owner of the window being created must be different. The parent should be the desktop window handle, while the owner should be the calling dialog window's handle. For example: IFrameWindow *anotherDlg = new IFrameWindow( MY_RES_ID,        /* resource id of new window */                    desktopWindow,   /* parent window handle */                    this );            /* owner window handle */ anotherDlg->showModally;

System-modal windows
(Nothing here yet...feel free to submit something)

How to convert a native PM item to OCL
Most native PM windows have an equivalent in OCL, and an item that already exists on a window can at any time be "converted" to OCL. This is advantageous for example if some of the functionality you need has already been implemented using OCL. For example: > Can a pointer to a 'low-level' listbox be converted into a pointer to an > Open Class listbox?

Dave Briccetti says:

Most of the OC UI controls have a constructor that takes the HWND of an existing control. In this case, the constructor looks like IListBox (const IWindowHandle &) IWindowHandle is an "alias" for HWND.

Bill Law (law@netscape.com) also adds the following:

Perhaps you should add that if an OCL window already exists for a given HWND, then constructing another one from its HWND will result in an exception being thrown. Generally, if there is a chance that an existing OCL window exists (or you know that one does and you just want to locate it), then you can use IWindow::fromHandle to get the existing IWindow (or derived-class) object. If that returns 0, then you can safely construct another IWindow (or derived-class) object.

How to create a thread
There are different ways of creating threads using OCL, and the method chosen will often depend on what you want the thread to do.

Example of creating a thread to call an object method: MyDlgClass     *frame            = new MyDlgClass; IThreadMemberFn *myThreadMemberFn = new IThreadMemberFn(frame, MyDlgClass::doSomething)); IThread        *myThread         = new IThread(myThreadMemberFn);

Example of creating a thread to call an entire class: class MyThreadClass : public IThreadFn ... int main {   ...    MyThreadClass  *myThreadFn = new MyThreadClass; IThread       *myThread   = new IThread( myThreadFn );


 * Warning: When using IThreadFn as opposed to IThreadMemberFn, the class being created must inherit from IThreadFn, and must contain the method
 * Note: See also

How to assign an icon to a window
In the .RC file, you must assign an icon to the same resource ID that the dialog window is using in the .DLG file, and then load it when you create the window. This is done as follows:

In your .H file, you would have: #define MY_DIALOG_RCID 0x1000

In your .RC file, you would have: ICON MY_DIALOG_RCID myicon.ico

In your .DLG file, you would have: DLGTEMPLATE MY_DIALOG_RCID PRELOAD MOVEABLE DISCARDABLE BEGIN DIALOG "My Dialog Title", MY_DIALOG_RCID, ...

In your .CPP file, you would have: IFrameWindow *myDlg = new IFrameWindow( MY_DIALOG_RCID );  // create the window myDlg->setIcon( MY_DIALOG_RCID );                          // set the icon


 * Note:
 * See also

How to prevent the minimized icon from being overwritten
If your dialog window contains or consists of a canvas, then when you minimize the window, the icon which is being used will be drawn correctly on the screen. However, if you have some controls which are not on a canvas, then you will run into a problem where the minimized icon is being overwritten by some of your controls.

This is a common problem - I believe with native PM applications as well - that can very easily be fixed.

In your application, you will need to create a command handler for your window to capture all of the system commands. This can be done by inheriting from, and declaring the function. Then when you detect the  event, you need to   the offending controls. Likewise, when you detect the  event, you need to   the controls that have previously been hidden.

For example:  /* this is part pseudo-code and will not compile without modifications */ class myClass : public IFrameWindow, public ICommandHandler {  myClass :                // constructor for class...      IFrameWindow(...),      // ...inherit from IFrameWindow... ICommandHandler {;}; // ...and from ICommandHandler Boolean systemCommand( ICommandEvent &event ); // inherited from ICommandHandler };

int main {  myClass *frame = new myClass;  // create class frame->setIcon( MY_ICON_RCID ); // set default icon frame->(ICommandHandler)handleEventsFor( frame );  // setup handler ...do some more stuff here... frame->(ICommandHandler)stopHandlingEventsFor( frame ); // stop handler return 0; }

myClass::systemCommand( ICommandEvent &event ) {  if( event.commandId == ISystemMenu::idMinimize ) {     ...hide controls overwriting the icon by calling their hide method... }  if( event.commandId == ISystemMenu::idRestore ) {     ...show controls overwriting the icon by calling their show method... }  return false;  // return as if the event hasn't been handled } 
 * Note:
 * See also and

How to print
Support for printing using OCL calls has not yet been included. IBM has promised that this will be included "soon", but no date has been given.

For now, you may want to refer to the  for more information on traditional printing in OS/2. This FAQ can be found at anyone know where?.

Valuesets (WC_VALUESET)
It seems that valuesets are not directly supported in OCL. You can still create them in DLGEDIT.EXE, and access them with OCL code, but with some limitations.

In your code, you can use the following: IWindow *vs = new IWindow( MY_VALUESET_RCID, this );

Thus, you can then change all of the standard window attributes using OCL calls, but all of the valueset-specific information will have to be handled using standard PM programming.

Custom-drawing in a container
To draw your own items in a container (IContainerControl) you will need to make use of the ICnrDrawHandler class. For an example of how this can be done in a details-view container (same principal can be applied to other views) please see the OCL_CON2.ZIP example from Hobbes.


 * Note:
 * See also

Error EDC3086
The error EDC3086 is caused by the compiler detecting OCL calls in a source file which was not compiled with the /Gm+ parameter.

You can fix this error by making certain you are compiling with the multithreaded libraries.


 * Note:
 * See also

Error LNK2029
The error LNK2029 is caused by the linker when you have OCL calls in your source, but you didn't compile with the  parameter. The error may look as follows: CPPOOC3.LIB (iexcept.cpp) : error LNK2029: "_errno" : unresolved external

Charlie Choc (cchoc@mindspring.com) says:
 * Make sure you are compiling with the Gm+ option, the Open Class Library requires the multi-threaded otpion. In a multi-thread environment _errno is a function, in a single thread environment it is an int.

Another situation that will cause a LNK2029 error is when a method for a class has been declared, but not defined in any of the source files. For example, the linker will generate the following error: test.obj(test.cpp) : error LNK2029: "{MyWindow}IVBase::virtual-fn-table-ptr" : unresolved external

if the following source file is compiled & linked: "(note that while the constructor has been declared and defined, the destructor was declared but accidently left out undefined)" #include  class mywindow : public IFrameWindow { public: MyWindow; ~MyWindow; };  MyWindow::MyWindow : IFrameWindow { return; } int main { return 0; }


 * Note: See also and

Error EDC0166, EDC0275, EDC0045 and EDC0046
If your source code has the extension .c and you are including some OCL #includes, then the compiler may generate many errors which seem to come from the IBMCPP include files. These errors are generated because the compiler assumes that .c files only contain C code, not C++, and the OCL include files require the compiler to be in the C++ mode.

To get around this problem, use the compiler flag /Tdp to tell the VAC++ to treat all files as C++ files.

Some of the errors you may be seeing include the following: imsgtext.hpp(24:1) : error EDC0166: Definition of function class requires parentheses. imsgtext.hpp(24:7) : error EDC0275: Unexpected text IMessageText encountered. imsgtext.hpp(27:19) : error EDC0046: Syntax error. imsgtext.hpp(28:33) : error EDC0045: Undeclared identifier messageFileName. imsgtext.hpp(29:33) : error EDC0045: Undeclared identifier textInsert1.


 * Note:
 * See also

OCL - Fixpacks and CSDs
The latest CSDs (corrective service disks) available from IBM for VisualAge C++ can be downloaded for free from: ftp://service.boulder.ibm.com/ps/products/visualagecpp/fixes/

For users of the US English version of VisualAge for OS/2, you need all of the files located in: ftp://service.boulder.ibm.com/ps/products/visualagecpp/fixes/v30os2/english-us/fixpak7

For other language users or for the Win32 VAC++ version, you will need to go into the appropriate subdirectory specified from the first link noted above.


 * Note: this fixpack represents more than 20MB of .ZIP files, so you may want to plan ahead before starting your download.
 * Note: the file called cts306.zip is generally not needed - this file is a source fix to the IBM Open Class Library Source Files, a separate product that can be purchased from IBM at a cost of many hundreds of dollars, and not included by default when you purchase VisualAge C++.

To apply the fixpacks, follow the order prescribed by IBM (VAC++ v3.0 for OS/2):
 * 1) reboot
 * 2) CTC308
 * 3) CTO308
 * 4) CTW308
 * 5) reboot
 * 6) CTV308</tt>
 * 7) CTD308</tt>
 * 8) CTU308</tt>
 * 9) reboot
 * 10) if you have the OpenClass source code, apply CTS308</tt> at any time

Contributors
This document is (will be?!) the result of input from many sources. These include the following people who have been kind enough to submit hints, tips, examples, and other contributions:
 * Stéphane Charette
 * Charlie Choc
 * Mark Anderson
 * Dave Briccetti
 * Bill Law
 * Tsung-Hsun Yang