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.

SMINCLUDE=.;d:\.SOM\INCLUDE;d:\.toolkt2x\sc;
SOMIR=d:\SOM\ETC\som.ir;som.ir
SMTMP=d:\SOM\TMP
SMADDSTAR=1
SMNOTC=1
SMCLASSES=d:\som\bin\wptypes.idl;d:\toolkt2x\tlktbeta\samples\browse\browcls.idl;

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:

// ------------------------------------------------------------------
// File:  browcls.idl
//
// This file contains the IDL type definitions for the foreign types
// defined in the Browse IDL files.
//
// ------------------------------------------------------------------
// interface Browse_O_Matic : WPDataFile
struct   S_LINERECORD
{
  PSZ   pszLine;       /* Pointer to beginning of each line of text */
  UINT  unLength;      /* The length of each line of text */
};
typedef S_LINERECORD LINERECORD;

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:

#******************************************************************************
#   Passthru PRIVATE definitions to the .ph file
#******************************************************************************
passthru: C.ph;
       /***************/
       /* Window data */
       /***************/
       typedef struct _BROWSEDATA
       {
               USHORT          cb;            /* Size of _BROWSEDATA struct    */
               Browse_O_Matic* somSelf;       /* Pointer to instance           */
               USEITEM         UseItem;       /* Use Item structure            */
                                               .
                                               .
                                               .
               USHORT          usNumberOfTextLines; /* Maximum number of lines */
                                              /* of object displayed as text   */
               ULONG           ulFileLength;  /* Length of file system object  */
       } BROWSEDATA;
       typedef BROWSEDATA *PBROWSEDATA;
endpassthru;

BROWSE.IDL with changed passthru statements follow:

#ifdef __PRIVATE__
   passthru C_h_after =      ""
"        /*************************/"
"        /* Main View window data */"
"        /*************************/"
""
"        typedef struct _BROWSEDATA"
"        {"
"                USHORT          cb;            /* Size of _BROWSEDATA struct */"
""
"                Browse_O_Matic* somSelf;       /* Pointer to instance */"
"                USEITEM         UseItem;       /* Use Item structure  */"
                                        .
                                        .
                                        .
"                USHORT usNumberOfTextLines; /* Maximum number of lines    */"
"                                            /* of object displayed as text*/"
"                ULONG  ulFileLength;        /* Length of file system object*/"
""
"        } BROWSEDATA;"
""
"        typedef BROWSEDATA *PBROWSEDATA;"
#endif /*__PRIVATE__ */

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 to create the header file. If you need to include private definitions, enter sc -D__PRIVATE__ -sh browse. The following sample shows BROWSE.H emitted from BROWSE.IDL using the private definition:

#ifndef SOM_Browse_O_Matic_h
#define SOM_Browse_O_Matic_h
#include <som.h>
...

/*
 * Define the class name as an object type
 */
#ifndef Browse_O_Matic
#define Browse_O_Matic SOMObject
#endif
#include <wpdataf.h>
...

/*
 * Passthru lines: File: "C.h", "after"
 */
       /*************************/
       /* Main View window data */
       /*************************/
       typedef struct _BROWSEDATA
       {
               USHORT          cb;            /* Size of _BROWSEDATA struct */
               Browse_O_Matic* somSelf;       /* Pointer to instance */
               USEITEM         UseItem;       /* Use Item structure */
                                       .
                                       .
                                       .
               USHORT          usNumberOfTextLines; /* Maximum number of lines
                                              /* of object displayed as text*/
               ULONG           ulFileLength;  /* Length of file system object*/
       } BROWSEDATA;
       typedef BROWSEDATA *PBROWSEDATA;

To create the implementation header file, enter sc -sih browse; to create the implementation header file, and if you need to include private definitions, enter sc D__PRIVATE__ -sih browse. The following shows BROWSE.IH emitted from BROWSE.IDL:

#ifndef SOM_Browse_O_Matic_ih
#define SOM_Browse_O_Matic_ih
#pragma checkout(suspend)
/*
 * Passthru lines: File: "C.ih", "before"
 */
       #define   INCL_WIN
       #define   INCL_DOS
       #define   INCL_DOSERRORS
       #define   INCL_DOSMODULEMGR
       #define   INCL_WINSTDDRG
       #define   INCL_WPCLASS
       #include  <os2.h>
       #define   HELP_FILE     "browse.hlp"
       /*****************************/
       /* Text object record format */
       /*****************************/
       typedef  struct   _LINERECORD
       {
          PSZ   pszLine;       /* Pointer to beginning of each line of text */
          UINT  unLength;      /* The length of each line of text */
       } LINERECORD;
       typedef LINERECORD     *PLINERECORD; /* AMC 050494 */
#include <browse.h>
...

At a command-line prompt, enter sc -sc browse 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.

BROWSE.C already is created, so the file is modified:

#define Browse_O_Matic_Class_Source
#include "browse.ih"
#include "pmbrowse.h"
HMODULE hModule = NULLHANDLE;
/*
 * SOM_Scope VOID  SOMLINK Browse_O_Maticwps_BrowseOMatic(Browse_O_Matic *somSelf,
 *                 BOOL bMode,
 *                 PSZ pszName)
 */
/*
 * The prototype for Browse_O_Maticwps_BrowseOMatic was replaced by the following prototype:
 */
SOM_Scope void  SOMLINK Browse_O_Maticwps_BrowseOMatic(Browse_O_Matic *somSelf,
                                                       BOOL bMode,
                                                       PSZ pszName)
{
   HAB           hab;
   HWND          hwndClient = NULLHANDLE;
   HWND          hwndFrame  = NULLHANDLE;
   FRAMECDATA    flFrameData;
   PBROWSEDATA   pWindowData;
   /* Browse_O_MaticData *somThis = Browse_O_MaticGetData(somSelf); */
   Browse_O_MaticMethodDebug("Browse_O_Matic","Browse_O_Maticwps_BrowseOMatic");
                               .
                               .
                               .
   WinShowWindow( hwndFrame, TRUE);   /* Make the window visible */
}

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.

INCLUDEP = d:\som\include;d:\toolkt2x\c\os2h
!if [set INCLUDE=.;$(INCLUDEP);%include%] || \
    [set PATH=d:\som\bin;%path%] || \
    [set LIB=d:\som\lib;%lib%] || \
    [set SMEMIT=h;ih;c] || \
    [set DPATH=d:\som\msg;%dpath%]
!endif
DLLLIBS = $(DLLLIBS) somtk.lib

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!

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation