Using the CTOI Tool

by Amy Conner

Do you want to extend your SOM 1.0 programs to include multiple inheritance, or define methods that return structures? This is some of the new function provided in the SOMobjects Developer Toolkit Version 2.0. To be able to extend your programs, you need to convert your programs from SOM 1.0 format to SOM 2.0 format.

The SOMobjects 2.0 toolkit contains the CTOI tool, which automates the conversion process from the SOM 1.0 format (.CSC) to SOM 2.0 format (.IDL). Unfortunately this tool is not magic, so you must prepare your program before you use the tool.

''So what's the preparation, you ask? Glad you want to know...''

Preparing for the Conversion
Set up the environment variables needed by the CTOI tool and the SOM compiler, as shown by the following sample code. You might need to create a file or be able to use the Workplace Shell class file, WPTYPES.IDL, if your program subclasses Workplace Shell classes. The BROWCLS.IDL file was created to define the LINERECORD structure:

Converting the Program
Now you're ready to call on the conversion tool - CTOI. Either add the statement drive:som\bin (where drive is the drive on which you've installed the SOMobjects Toolkit) to the path directory or prefix the tool request with the path. You can try this on one of the SOM 1.0 samples found on The Developer Connection for OS/2, Volume 3 or the SOM 1.0 directory of OS/2 2.x toolkit samples in The Developer Connection for OS/2, Volume 4. From a command-line prompt, enter CTOI BROWSE.CSC to create a BROWSE.IDL file.

SOM 2.0 doesn't support the private header file (.PH). Instead, a private definition #define __PRIVATE__ excludes information from the public header files. The next step in the conversion process is to convert any references of passthru C_ph to #ifdef __PRIVATE__, passthru C_h, #endif in the .CSC file. Also, passthru statements intended for .C files should be changed to .IH (implementation header). BROWSE.CSC original passthru statements follow: BROWSE.IDL with changed passthru statements follow: Now, use the SOM compiler to create the .H, .IH, and .C files. Add an environment variable SET SMEMIT=h,ih,sc,c to set the emitters that will be used to create the header, implementation header, and source files. At a command-line prompt, enter sc -sh browse</tt> to create the header file. If you need to include private definitions, enter sc -D__PRIVATE__ -sh browse</tt>. The following sample shows BROWSE.H emitted from BROWSE.IDL using the private definition: To create the implementation header file, enter sc -sih browse</tt>; to create the implementation header file, and if you need to include private definitions, enter sc D__PRIVATE__ -sih browse</tt>. The following shows BROWSE.IH emitted from BROWSE.IDL: At a command-line prompt, enter sc -sc browse</tt> to create the stub source file (if you already have a source file from the .CSC format, this step will update the source file). You will have to put in the function code. To add private definitions, enter sc -D__PRIVATE__ -sc browse</tt>.

BROWSE.C already is created, so the file is modified: Now, you're ready to update your program's makefile to reflect the .IDL file types. Remove any references to the .PH (private header), change any references of .CSC to .IDL, and update the paths to point to the .IDL files, rather than the .SC class files. You will also need to reference the new library, SOMTK.LIB, instead of SOM.LIB. You can add the SOM compilation to your makefile. However, be sure that this comes before the compilation of any source files. Then, invoke the makefile and create your SOM 2.0 executable. Note: Change any references to .CSC and .SC to .IDL.

To install your application, copy an installation and de-installation command file from the sample subdirectory in the Developer's Toolkit for OS/2 2.1. These command files will properly register your classes and objects at installation time and de-register your classes and objects after application execution. Simply replace the sample names with your application names.

Conclusion
''Now that you have converted your program to SOM 2.0. How about adding multiple inheritance and methods that return structures? Refer to the SOMobjects Developer Toolkit User's Guide'' for more information on these and other SOM 2.0 functions.

Happy converting and programming!