Example 1-Implementing a Simple Class with One Method

Example 1 defines a class "Hello" which introduces one new method, "sayHello". When invoked from a client program, the "sayHello" method will print the fixed string "Hello, World!" The example follows the six steps described in the preceding topic, "Basic Steps for Implementing SOM Classes."

• Define the interface to class "Hello", which inherits methods from the root class SOMObject and introduces one new method, "sayHello". Define these IDL specifications in the file "hello.idl".

  The "interface" statement introduces the name of a new class and any parents (base classes) it may have (here, the root class SOMObject). The body of the interface declaration introduces the method "sayHello." Observe that method declarations in IDL have syntax similar to C and C++ function prototypes:

  #include <somobj.idl>  //# Get the parent class definition.
  
  interface Hello : SOMObject
  /*  This is a simple class that demonstrates how to define the
   *  interface to a new class of objects in SOM IDL.
   */
  {
      void sayHello();
      // This method outputs the string "Hello, World!".
         /* On Windows, use: string sayHello();
          * This method returns the string "Hello, World!". */
  };
  

  Note that the method "sayHello" has no (explicit) arguments and returns no value (except on Windows, which returns a string). The characters "//" start a line comment, which finishes at the end of the line. The characters "/*" start a block comment which finishes with the "*/". Block comments do not nest. The two comment styles can be used interchangeably. Throw-away comments are also permitted in a .idl file; they are ignored by the SOM Compiler. Throw-away comments start with the characters "//#" and terminate at the end of the line.

  Note: For simplicity, this IDL fragment does not include a releaseorder modifier; consequently, the SOM Compiler will issue a warning for the method "sayHello". For directions on using the releaseorder modifier to remove this warning, see the topic "Modifier statements" in Chapter 4, "Implementing Classes in SOM."

  2.
  Run the SOM Compiler to produce binding files and an implementation template (that is, issue the sc command):

  > sc -s"c;h;ih" hello.idl      (for C bindings on AIX or OS/2)
  > sc -s"xc;xh;xih" hello.idl   (for C++ bindings on AIX or OS/2)
  

  When set to generate C binding files, the SOM Compiler generates the following implementation template file, named "hello.c". The template implementation file contains stub procedures for each new method. These are procedures whose bodies are largely vacuous, to be filled in by the implementor. (Unimportant details have been removed for this tutorial.)

  #include <hello.ih>
  /*
   *  This method outputs the string "Hello, World!".
   */
  
  SOM_Scope  void   SOMLINK  sayHello(Hello somSelf, Environment *ev)
  {
      /* HelloData *somThis = HelloGetData(somSelf); */
      HelloMethodDebug("Hello", "sayHello");
  }
  

  The terms SOM_Scope and SOMLINK appear in the prototype for all stub procedures, but they are defined by SOM and are not of interest to the developer. In the method procedure for the "sayHello" method, "somSelf" is a pointer to the target object (here, an instance of the class "Hello") that will respond to the method. A "somSelf" parameter appears in the procedure prototype for every method, since SOM requires every method to act on some object.

  The target object is always the first parameter of a method's procedure, although it should not be included in the method's IDL specification. The second parameter (which also is not included in the method's IDL specification) is the parameter (Environment *ev). This parameter can be used by the method to return exception information if the method encounters an error. (Contrast the prototype for the "sayHello" method in steps 1 and 2 above.)

  The remaining lines of the template above are not pertinent at this point. (For those interested, they are discussed in section 5.4 of Chapter 5, "Implementing SOM Classes.") The file is now ready for customization with the C code needed to implement method "sayHello".

  When set to generate C++ binding files, the SOM Compiler generates an implementation template file, "hello.C" (on AIX) or "hello.cpp (on OS/2), similar to the one above. (Chapter 5 discusses the implementation template in more detail.)

  Recall that, in addition to generating a template implementation file, the SOM Compiler also generates implementation bindings (in a header file to be included in the implementation file) and usage bindings (in a header file to be included in client programs). These files are named "hello.ih" and "hello.h" for C bindings, and are "hello.xih" and "hello.xh" for C++ bindings. Notice that the "hello.c" file shown above includes the "hello.ih" implementation binding file.

  3.
  Customize the implementation, by adding code to the template implementation file.

  Modify the body of the "sayHello" method procedure in the "hello.c" (or, for C++,"hello.C" on AIX, "hello.cpp" on OS/2) implementation file so that the "sayHello" method prints "Hello, World!":

  SOM_Scope void   SOMLINK sayHello(Hello somSelf, Environment *ev)
  {
      /* HelloData *somThis = HelloGetData(somSelf); */
      HelloMethodDebug("Hello","sayHello");
  
      printf("Hello, World!\n");
  }
  

  4.
  Create a client program that uses the class.

  Write a program "main" that creates an instance (object) of the "Hello" class and invokes the method "sayHello" on that object.

  A C programmer would write the following program in "main.c", using the bindings defined in the "hello.h" header file:

  #include <hello.h>
  
  int main(int argc, char *argv[])
  {
      /* Declare a variable to point to an instance of Hello */
      Hello obj;
  
      /* Create an instance of the Hello class */
      obj = HelloNew();
  
      /* Execute the "sayHello" method */
      _sayHello(obj, somGetGlobalEnvironment());
  
      /* Free the instance: */
      _somFree(obj);
      return (0);
  }
  

  Notice the statement obj = HelloNew(); The "hello.h" header file automatically contains the SOM-defined macro <className>New(), which is used to create an instance of the <className> class (here, the "Hello" class).

  Also notice that, in C, a method is invoked on an object by using the form:

  _<methodName>(<objectName>, <environment_argument>, <other_method_arguments>)
  

  as used above in the statement _sayHello(obj, somGetGlobalEnvironment()). As shown in this example, the SOM-provided somGetGlobalEnvironment function can be used to supply the (Environment *) argument of the method.

  Finally, the code uses the method somFree, which SOM also provides, to free the object created by HelloNew(). Notice that somFree does not require an (Environment *) argument. This is because the method procedures for some of the classes in the SOMobjects Toolkit (including SOMObject, SOMClass, and SOMClassMgr) do not have an Environment parameter, to ensure compatibility with the previous release of SOM. The documentation for each SOM-kernel method in the SOMobjects Developer Toolkit: Programmers Reference Manual indicates whether an Environment parameter is used.

  A C++ programmer would write the following program in "main.C" (on AIX) or "main.cpp" (on OS/2), using the bindings defined in the "hello.xh" header file:

  #include <hello.xh>
  
  int main(int argc, char *argv[])
  {
      /* Declare a variable to point to an instance of Hello */
      Hello *obj;
  
      /* Create an instance of the Hello class */
      obj = new Hello;
  
      /* Execute the "sayHello" method */
      obj->sayHello(somGetGlobalEnvironment());
  
      obj->somFree();
      return (0);
  }
  

  Notice that the only argument passed to the "sayHello" method by a C++ client program is the Environment pointer. (Contrast this with the invocation of "sayHello" in the C client program, above.

  5.
  Compile and link the client code with the class implementation.

  Note: On AIX or OS/2, the environment variable SOMBASE represents the directory in which SOM has been installed.

  Under AIX, for C programmers:

  > xlc -I. -I$SOMBASE/include -o hello main.c hello.c  -L$SOMBASE/lib -l somtk
  

  Under AIX, for C++ programmers:

  > xlc -I. -I$SOMBASE/include -o hello main.C hello.C  -L$SOMBASE/lib -lsomtk
  

  Under OS/2, for C programmers:

  > set LIB=%SOMBASE%\lib;%LIB%
  > icc -I. -I%SOMBASE%\include -Fe hello main.c hello.c  somtk.lib
  

  Under OS/2, for C++ programmers:

  > set LIB=%SOMBASE%\lib;%LIB%
  > icc -I. -I\%SOMBASE%\include -Fe hello main.cpp hello.cpp  somtk.lib
  

  6.
  Execute the client program.

  > hello
  Hello, World!
  

  Example 2 will extend the "Hello" class to introduce an "attribute."

  File Extensions for SOM Files

  ┌───────────────────────────────────┬────────┬───────────────────────────┐
  │IDL source file:                   │.idl    │for all users              │
  ├───────────────────────────────────┼────────┼───────────────────────────┤
  │Implementation template file:      │.c      │for C, all systems         │
  │                                   │.C      │for C++, on AIX            │
  │                                   │.cpp    │for C++, on OS/2 or Windows│
  ├───────────────────────────────────┼────────┼───────────────────────────┤
  │Header file for implementation     │.ih     │for C                      │
  │file:                              │.xih    │for C++                    │
  ├───────────────────────────────────┼────────┼───────────────────────────┤
  │Header file for program file:      │.h      │for C                      │
  │                                   │.xh     │for C++                    │
  └───────────────────────────────────┴────────┴───────────────────────────┘
  

  ---

  [Back: Basic Steps for Implementing SOM Classes]
  [Next: Example 2-Adding an Attribute to the Hello class]