SG24-4719-00 Open32 Developer API Extensions for OS/2 Warp December 1996 SG24-4719-00 International Technical Support Organization Open32 Developer API Extensions for OS/2 Warp December 1996 IBML Take Note! Before using this information and the product it supports, be sure to read the general information in Appendix B, “Special Notices” on page 263. First Edition (December 1996) This edition applies to the Developer API Extensions of OS/2 Warp Version 3 with FixPak 17 or greater installed. The programs described in this edition will also execute on OS/2 Warp Version 4 utilizing the Open32 support included in OS/2 Warp Version 4. Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. JN9B Building 045 Internal Zip 2834 11400 Burnet Road Austin, Texas 78758-3493 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation 1996. All rights reserved. Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. Contents Figures ........................................ ix Tables ........................................ xv Preface ...................................... xvii How This Redbook Is Organized ....................... xviii The Team That Wrote This Redbook ..................... xix Comments Welcome ............................... xx Chapter 1. Open32 Overview .......................... 1 1.1 Why Open32? ................................. 3 1.2 Open32 Architecture ............................. 3 1.3 What is Open32? ............................... 4 1.4 Independent Software Vendors Benefits ................. 6 1.5 Tools ...................................... 6 1.5.1 OS/2 Warp Toolkit ............................ 6 1.5.2 VisualAge C++ ............................ 7 1.5.3 SMART .................................. 7 1.5.4 Hyperwise ................................ 7 1.6 Application Design Considerations .................... 8 1.6.1 Common versus Mixed Mode Code ................. 8 1.6.2 New verses Existing Code ....................... 9 1.6.3 How much can be Shared? ...................... 10 1.7 Overview of Scenarios ............................ 12 Chapter 2. Tools Used with OS/2 Developer API Extensions ....... 15 2.1 The Developer Connection for OS/2 Volume 10 ............. 15 2.1.1 Installing The Developer Connection for OS/2 Volume 10 .... 16 2.1.2 Starting The Developer Connection for OS/2 Volume 10 ..... 22 2.2 FixPak 17 (XR_W017) ............................. 24 2.2.1 Installing FixPak 17 ........................... 25 2.3 OS/2 Warp Toolkit .............................. 31 2.3.1 Installing OS/2 Warp Toolkit ...................... 31 2.3.2 Configuring the Resource Compiler ................. 40 2.3.3 Where to Learn More About the Toolkit ............... 46 2.4 SMART ..................................... 47 2.4.1 Installing SMART ............................ 47 2.4.2 Where to Learn More About SMART ................. 56 2.5 VisualAge C++ ............................... 57 2.5.1 Installing VisualAge C++ ...................... 57 2.5.2 Where to Learn More About VisualAge C++ ........... 69 Copyright IBM Corp. 1996 iii 2.6 Developer API Extensions .......................... 70 2.6.1 Installing Developer API Extensions ................. 70 Chapter 3. Howdy, World! ............................ 79 3.1 Overview of the Migration Process .................... 79 3.1.1 Copying the Source Files ....................... 81 3.1.2 Changing the Source Code ...................... 82 3.1.3 Recompiling the Source Code .................... 83 3.1.4 Converting Resource Compiler Files ................. 83 3.1.5 Converting the Resources ....................... 86 3.1.6 Recompiling the Resource Compiler file .............. 87 3.1.7 Compiling MAIN.C ............................ 88 3.1.8 Creating a New DEF File ........................ 89 3.1.9 Linking the Application and Binding the Resources ........ 90 3.1.10 Testing the Application ........................ 91 3.2 Enhancing Your Application ........................ 92 3.2.1 Adding a Menu ............................. 92 3.2.2 Adding Accelerators .......................... 95 3.2.3 Adding Dialog Boxes .......................... 96 3.2.4 Resource Differences and SMART Limitations .......... 100 Chapter 4. MDI Sample Program ....................... 103 4.1 Application's Overview .......................... 103 4.2 User's Interface ............................... 105 4.3 Summary of Win32 API Functions Used ................. 108 4.4 Source Files ................................. 110 4.5 Coding .................................... 110 4.5.1 Resources ............................... 111 4.5.2 WinMain() ................................ 112 4.5.3 MainWndProc() ............................ 114 4.5.4 MDIWndProc() ............................. 118 4.5.5 Drawing Functions .......................... 122 4.6 Migration ................................... 129 Chapter 5. Mixed Mode Sample Program .................. 133 5.1 Application Overview ........................... 133 5.2 Source Files ................................. 137 5.3 Application Design ............................. 137 5.4 Coding .................................... 138 5.4.1 Resources ............................... 139 5.4.2 Common Source Code ........................ 140 5.4.3 Platform Specific Code ........................ 141 5.5 Migration ................................... 149 5.5.1 Converting Resources ........................ 149 iv Open32 for OS/2 Warp 5.5.2 Converting Common Source Code ................. 151 5.5.3 Converting Platform Specific Source Code ............ 151 5.6 Application Enhancement on OS/2 ................... 167 Chapter 6. Named Pipe Sample Program .................. 179 6.1 Application's Overview .......................... 179 6.1.1 Named Pipe Server Application's Overview ........... 179 6.1.2 Named Pipe Client Application's Overview ............ 181 6.2 Source Files ................................. 183 6.3 Application Design ............................. 184 6.4 Coding .................................... 186 6.4.1 Server Application Coding ...................... 186 6.4.2 Client Application Coding ...................... 188 6.5 Migration ................................... 189 6.5.1 Unsupported API Function Classification ............. 190 6.5.2 Unsupported API Function Prototyping .............. 191 6.5.3 Unsupported API Function Coding ................. 192 6.6 Run the Applications ............................ 193 Chapter 7. Tree View Control Sample Program .............. 195 7.1 How the OS/2 Tree View Control Works ................ 196 7.1.1 Translation Technique Advantages ................ 198 7.1.2 How the OS/2 Tree View Control is Written ............ 198 7.1.3 Overview of the Translation Process ............... 201 7.1.4 Details on How the Tree View Control Works .......... 205 7.1.5 Handling the Image List ....................... 210 7.2 Using the Tree View Translation Control ................ 213 7.2.1 Copying the Source Files ...................... 213 7.2.2 Changes to the Source Code .................... 214 7.2.3 Converting Resources ........................ 219 7.2.4 Creating a Makefile .......................... 220 7.2.5 Creating a DEF File .......................... 221 7.2.6 Building the Application ....................... 221 7.2.7 Running the New TVTest for OS/2 ................. 223 7.3 Extending the OS/2 Tree View Control ................. 224 7.4 Creating your own Translation Controls ................ 225 7.4.1 Template Source Files ........................ 225 7.4.2 Modifying the Template ....................... 226 7.4.3 Hints on Creating Translation Controls .............. 229 Chapter 8. Existing Windows 16-bit Application Ported to OS/2 ..... 235 8.1 Overview of the Program Structure ................... 235 8.2 Overview of the Migration Process ................... 236 8.2.1 Changes to the Source Code .................... 237 Contents v 8.2.2 Converting the Resource Compiler File .............. 243 8.2.3 Converting Graphical Resources .................. 245 8.3 Converting the Help File .......................... 245 8.3.1 Creating a New Makefile ....................... 246 8.3.2 Creating the DEF File ......................... 247 8.3.3 Creating the Executable ....................... 247 8.3.4 Running Address ........................... 249 Chapter 9. Hints and Tips for Open32 .................... 251 9.1 General Design Hints and Tips ...................... 251 9.1.1 New Program Design Hints & Tips ................. 251 9.1.2 Existing Program Migration Hints and Tips ............ 252 9.1.3 General Coding Hints and Tips ................... 253 Appendix A. Common Problems and Easy Solutions ........... 255 A.1 Compiler Errors .............................. 255 A.1.1 SYS1041: The name specified is not recognized ........ 255 A.1.2 Errors in Compiling <OS2WIN.H> ................ 256 A.2 Linker Errors ................................ 256 A.2.1 Obsolete #pragma Warning ..................... 256 A.2.2 L1104: not valid library ........................ 256 A.2.3 Unresolved External on Win32 Functions ............. 256 A.2.4 LNK4021: no stack segment ..................... 257 A.2.5 LNK4038: program has no starting address ........... 257 A.3 Resource Compiler