Using SOM Classes in Client Programs

This chapter discusses how to use SOM classes that have already been fully implemented. That is, these topics describe the steps that a programmer uses to instantiate an object and invoke some method(s) on it from within an application program.

Who should read this chapter?

�Programmers who wish to use SOM classes that were originally developed by someone else will need to know the information in this chapter. These programmers often may not need the information from any subsequent chapters.

�By contrast, class implementers who are creating their own SOM classes should continue with Chapter 4, "SOM IDL and the SOM Compiler," and Chapter 5, "Implementing Classes in SOM "for complete information on the SOM Interface Definition Language (SOM IDL) syntax and other details of class implementation.

Programs that use a class are referred to as client programs. A client program can be written in C, in C++, or in another language. As noted, this chapter describes how client programs can use SOM classes (classes defined using SOM, as described in Chapter 2, "Tutorial for Implementing SOM Classes" and in Chapter 4, "SOM IDL and the SOM Compiler"and Chapter 5 "Implementing Classes in SOM"). Using a SOM class involves creating instances of a class, invoking methods on objects, and so forth. All of the methods, functions, and macros described here can also be used by class implementers within the implementation file for a class.

Note: "Using a SOM class," as described in this chapter, does not include subclassing the class in a client program. In particular, the C++ compatible SOM classes made available in the .xh binding file can not be subclassed in C++ to create new C++ or SOM classes.

Some of the macros and functions described here are supplied as part of SOM's C and C++ usage bindings. These bindings are functions and macros defined in header files to be included in client programs. The usage bindings make it more convenient for C and C++ programmers to create and use instances of SOM classes. SOM classes can be also used without the C or C++ bindings, however. For example, users of other programming languages can use SOM classes, and C and C++ programmers can use a SOM class without using its language bindings. The language bindings simply offer a more convenient programmer's interface to SOM. Vendors of other languages may also offer SOM bindings; check with your language vendor for possible SOM support.

To use the C or C++ bindings for a class, a client program must include a header file for the class (using the #include preprocessor directive). For a C language client program, the file <classFileStem>.h must be included. For a C++ language client program, the file <classFileStem>.xh must be included. The SOM Compiler generates these header files from an IDL interface definition. The header files contain definitions of the macros and functions that make up the C or C++ bindings for the class. Whether the header files include bindings for the class's private methods and attributes (in addition to the public methods and attributes) depends on the IDL interface definition available to the user, and on how the SOM Compiler was invoked when generating bindings.

Usage binding headers automatically include any other bindings upon which they may rely. Client programs not using the C or C++ bindings for any particular class of SOM object (for example, a client program that does not know at compile time what classes it will be using) should simply include the SOM-supplied bindings for SOMObject, provided in the header file "somobj.h" (for C programs) or"somobj.xh" (for C++ programs).

For each task that a user of a SOM class might want to perform, this chapter shows how the task would be accomplished by:

�a C programmer using the C bindings, �a C++ programmer using the C++ bindings, or �a programmer not using SOM's C or C++ language bindings.

If neither of the first two approaches is applicable, the third approach can always be used.

An Example Client Program

Following is a C program that uses the class "Hello" (as defined in the Tutorial in Chapter 2). The "Hello" class provides one attribute, "msg", of type string, and one method, "sayHello". The "sayHello" method simply displays the value of the "msg" attribute of the object on which the method is invoked.

  #include <hello.h>  /* include the header file for Hello */

  int main(int argc, char *argv[])
  {
      /* declare a variable (obj) that is a
       * pointer to an instance of the Hello class: */
      Hello obj;

      /* create an instance of the Hello class
       * and store a pointer to it in obj: */
      obj = HelloNew();

      /* invoke method _set_msg on obj with the argument
       * "Hello World Again". This method sets the value of
       * obj's 'msg' attribute to the specified string.
       */
       __set_msg(obj, somGetGlobalEnvironment(), "Hello World Again");

       /* invoke method sayHello on obj. This method prints
        * the value of obj's 'msg' attribute.  */
       _sayHello(obj, somGetGlobalEnvironment());

       _somFree(obj);
       return(0);
  }

The C++ version of the foregoing client program is shown below:

  #include <hello.xh>  /* include the header file for Hello */

  int main(int argc, char *argv[])
  {
      /* declare a variable (obj) that is a
       * pointer to an instance of the Hello class: */
      Hello *obj;

      /* create an instance of the Hello class
       * and store a pointer to it in obj: */
      obj = new Hello;

     /* invoke method _set_msg on obj with the argument
      * "Hello World Again". This method sets the value of
      * obj's 'msg' attribute to the specified string.  */
     obj->_set_msg(somGetGlobalEnvironment(), "Hello World Again");

     /* invoke method sayHello on obj. This method prints
      * the value of obj's 'msg' attribute.  */
     obj->sayHello(somGetGlobalEnvironment());

     obj->somFree();
     return(0);
  }

These client programs both produce the output:

Hello World Again

Using SOM Classes: the Basics

This section covers the following subjects:

• Declaring object variables
• Creating instances of a class
• Invoking methods on objects
• Using class objects
• Compiling and linking

Invoking methods on objects

Obtaining a method's procedure pointer

           Offset resolution
           Name-lookup method resolution 

Method name or signature not known at compile time

           Dispatch-function method resolution 

Using class objects

Creating a class object

           Using Renew or somRenew
           Using NewClass
           Using somFindClass or somFindClsInFile 

Language-neutral Methods and Functions

Exceptions and error handling

Standard exceptions

       The Environment
       Setting an exception value
       Getting an exception value
       Example 
   Memory management
   SOM manipulations using somId's