For C programmers with usage bindings: To invoke a method in C, use the macro:
_<methodName> (receiver, args)
(that is, an underscore followed by the method name). Arguments to the macro are the receiver of the method followed by all of the arguments to the method. For example:
_foo(obj, somGetGlobalEnvironment(), x, y)
This invokes method "foo" on "obj" (the remaining arguments are arguments to the method "foo"). This expression can be used anywhere that a standard function call can be used in C.
Required arguments
In C, calls to methods defined using IDL require at least two arguments- a pointer to the receiving object (the object responding to the method) and a value of type (Environment *). The Environment data structure is specified by CORBA, and is used to pass environmental information between a caller and a called method. For example, it is used to return exceptions. (For more information on how to supply and use the Environment structure, see the later section entitled "Exceptions and error handling.")
In the IDL definition of a method, by contrast, the receiver and the Environment pointer are not listed as parameters to the method. (Unlike the receiver, the Environment pointer is considered a method parameter, even though it is never explicitly specified in IDL. For this reason, it is called an implicit method parameter.) For example, if a method is defined in a .idl file with two parameters, as in:
int foo (in char c, in float f);
then, with the C usage bindings, the method would be invoked with four arguments, as in:
intvar = _foo(obj, somGetGlobalEnvironment(), x, y);
where "obj" is the object responding to the method and "x" and "y" are the arguments corresponding to "c" and "f", above.
If the IDL specification of the method includes a context specification, then the method has an additional (implicit) context parameter. Thus, when invoking the method, this argument must follow immediately after the Environment pointer argument. (None of the SOM-supplied methods require context arguments.) The Environment and context method parameters are prescribed by the CORBA standard.
If the IDL specification of the class that introduces the method includes the callstyle=oidl modifier, then the (Environment*) and context arguments should not be supplied when invoking the method. That is, the receiver of the method call is followed immediately by the arguments to the method (if any). Some of the classes supplied in the SOMobjects Toolkit (including SOMObject, SOMClass, and SOMClassMgr) are defined in this way, to ensure compatibility with the previous release of SOM. The System Object Model Programming Reference specifies for each method whether these arguments are used.
If you use a C expression to compute the first argument to a method call (the receiver), you must use an expression without side effects, because the first argument is evaluated twice by the _<methodName> macro expansion. In particular, a somNew method call or a macro call of <className>New can not be used as the first argument to a C method call, because doing so would create two new class instances rather than one.
Following the initial, required arguments to a method (the receiving object, the Environment, if any, and the context, if any), you enter any additional arguments required by that method, as specified in IDL. For a discussion of how IDL in/out/inout argument types may to C/C++ data types, see the topic "Parameter list" in Chapter 4, "SOM IDL and the SOM Compiler."
Short form vs long form
If a client program uses the bindings for two different classes that introduce or inherit two different methods of the same name, then the _<methodName> macro described above (called the short form) will not be provided by the bindings, because the macro would be ambiguous in that circumstance. The following long form macro, however, is always provided by the usage bindings for each class that supports the method:
<className>_<methodName> (receiver, args)
For example, method "foo" supported by class "Bar" can be invoked as: Bar_foo(obj,
somGetGlobalEnvironment(), x, y) (in C)
where "obj" has type "Bar" and "x" and "y" are the arguments to method "foo".
In most cases (where there is no ambiguity, and where the method is not a va_list method, as described in the subsequent subtopic "Using 'va_list' methods"), a C programmer may use either the short or the long form of a method invocation macro interchangeably. However, only the long form complies with the CORBA standard for C usage bindings. If you wish to write code that can be easily ported to other vendor platforms that support the CORBA standard, use the long form exclusively. The long form is always available for every method that a class supports. The short form is provided both as a programming convenience and for source code compatibility with release 1 of SOM.
In order to use the long form, a programmer will usually know what type an object is expected to have. If this is not known, but the different methods have the same signature, the method can be invoked using name-lookup resolution, as described in a following subtopic of this section.
For C++ programmers with usage bindings: To invoke a method, use the standard C++ form shown below:
obj-><methodName> (args)
where args are the arguments to the method. For instance, the following example invokes method "foo" on "obj":
obj->foo(somGetGlobalEnvironment(), x, y)Required arguments
All methods introduced by classes declared using IDL (except those having the SOM IDL callstyle=oidl modifier) have at least one parameter-a value of type (Environment *). The Environment data structure is used to pass environmental information between a caller and a called method. For example, it is used to return exceptions. For more information on how to supply and use the Environment structure, see the later section entitled "Exceptions and error handling."
The Environment pointer is an implicit parameter; in the IDL definition of a method, the Environment pointer is not explicitly listed as a parameter to the method. For example, if a method is defined in IDL with two explicit parameters, as in:
int foo (in char c, in float f);
then the method would be invoked from C++ bindings with three arguments, as in:
intvar = obj->foo(somGetGlobalEnvironment(), x, y);
where "obj" is the object responding to the method and "x" and "y" are the arguments corresponding to "c" and "f", above.
If the IDL specification of the method includes a context specification, then the method has a second implicit parameter, of type context, and the method must be invoked with an additional context argument. This argument must follow immediately after the Environment pointer argument. (No SOM-supplied methods require context arguments.) The Environment and context method parameters are prescribed by the CORBA standard.
If the IDL specification of the class that introduces the method includes the callstyle=oidl modifier, then the (Environment *) and context arguments should not be supplied when the method is invoked. Some of the classes supplied in the SOMobjects Toolkit (including SOMObject, SOMClass, and SOMClassMgr) are defined in this way, to ensure compatibility with the previous release of SOM. The System Object Model Programming Reference specifies for each method whether these arguments are used.
Following the initial, required arguments to a method (the receiving object, the Environment, if any, and the context, if any), you enter any additional arguments required by that method, as specified in IDL. For a discussion of how IDL in/out/inout argument types map to C/C++ data types, see the topic "Parameter list" in Chapter 4, "SOM IDL and the SOM Compiler."
For non-C/C++ programmers: To invoke a static method (that is, a method declared when defining an OIDL or IDL object interface) without using the C or C++ usage bindings, a programmer can use the somResolve procedure. The somResolve procedure takes as arguments a pointer to the object on which the method is to be invoked and a method token for the desired method. It returns a pointer to the method's procedure (or raises a fatal error if the object does not support the method). Depending on the language and system, it may be necessary to cast this procedure pointer to the appropriate type; the way this is done is language-specific.
The method is then invoked by calling the procedure returned by somResolve (the means for calling a procedure, given a pointer to it, is language-specific), passing the method's receiver, the Environment pointer (if necessary), the context argument (if necessary) and the remainder of the method's arguments, if any. (See the section above for C programmers; the arguments to a method procedure are the same as the arguments passed using the long form of the C-language method-invocation macro for that method.)
Using somResolve requires the programmer to know where to find the method token for the desired method. Method tokens are available from class objects that support the method (via the method somGetMethodToken), or from a global data structure, called the ClassData structure, corresponding to the class that introduces the method. In C and C++ programs with access to the definitions for ClassData structures provided by usage bindings, the method token for method methodName introduced by class className may be accessed by the following expression:
<className>ClassData.<methodName >
For example, the method token for method "sayHello"introduced by class "Hello" is stored at location HelloClassData.sayHello, for C and C++ programmers. The way method tokens are accessed in other languages is language-specific.
As an example of using offset resolution to invoke methods from a programming language other than C/C++, one would do the following to create an instance of a SOM Class X in Smalltalk:
In addition to somResolve, SOM also supplies the somClassResolve procedure. Instead of an object, the somClassResolve procedure takes a class as its first argument, and then selects a method procedure from the instance method table of the passed class. (The somResolve procedure, by contrast, selects a method procedure from the instance method table of the class of which the passed object is an instance.) The somClassResolve procedure therefore supports casted method resolution. See the System Object Model Programming Reference for more information on somResolve and somClassResolve.
If the programmer does not know at compile time which class introduces the method to be invoked, or if the programmer cannot directly access method tokens, then the procedure somResolveByName can be used to obtain a method procedure using name-lookup resolution, as described in the next section.
If the signature of the method to be invoked is not known at compile time, but can be discovered at run time, use somResolve or somResolveByName to get a pointer to the somDispatch method procedure, then use it to invoke the specific method, as described below under "Method name or signature not known at compile time."