Using name-lookup method resolution

For C/C++ programmers: Offset resolution is the most efficient way to select the method procedure appropriate to a given method call. Client programs can, however, invoke a method using "name-lookup" resolution instead of offset resolution. The C and C++ bindings for method invocation use offset resolution by default, but methods defined with the namelookup SOM IDL modifier result in C bindings in which the short form invocation macro uses name-lookup resolution instead. Also, for both C and C++ bindings, a special lookup_<methodName> macro is defined.

Name-lookup resolution is appropriate in the case where a programmer knows at compile time which arguments will be expected by a method (that is, its signature), but does not know the type of the object on which the method will be invoked. For example, name-lookup resolution can be used when two different classes introduce different methods of the same name and signature, and it is not known which method should be invoked (because the type of the object is not known at compile time).

Name-lookup resolution is also used to invoke dynamic methods (that is, methods that have been added to a class's interface at run time rather than being specified in the class's IDL specification). For more information on name-lookup method resolution, see the topic "Method Resolution" in Chapter 4, "SOM IDL and the SOM Compiler."

For C: To invoke a method using name-lookup resolution, when using the C bindings for a method that has been implemented with the namelookup modifier, use either of the following macros:

_<methodName> (receiver, args)

lookup_<methodName> (receiver, args)

Thus, the short-form method invocation macro results in name-lookup resolution (rather than offset resolution), when the method has been defined as a namelookup method. (The long form of the macro for offset resolution is still available in the C usage bindings.) If the method takes a variable number of arguments, then the first form shown above is used when supplying a variable number of arguments, and the second form is used when supplying a va_list argument in place of the variable number of arguments.

For C++: To invoke a method using name-lookup resolution, when using the C++ bindings for a method that has been defined with the namelookup modifier, use either of the following macros:

lookup_<methodName> (receiver, args)

<className>_lookup_<methodName> (receiver, args)

If the method takes a variable number of arguments, then the first form shown above is used when supplying a variable number of arguments, and the second form is used when supplying a va_list argument in place of the variable number of arguments. Note that the offset-resolution forms for invoking methods using the C++ bindings are also still available, even if the method has been defined as a namelookup method.

For C/C++ To invoke a method using name-lookup resolution, when the method has not been defined as a namelookup method:

• Use the somResolveByName procedure (described in the following section), or any of the methods somLookupMethod, somFindMethod or somFindMethodOk to obtain a pointer to the procedure that implements the desired method.

• Then, invoke the desired method by calling that procedure, passing the method's intended receiver, the Environment pointer (if needed), the context argument (if needed), and the remainder of the method's arguments, if any.

The somLookupMethod, somFindMethod and somFindMethodOK methods are invoked on a class object (the class of the method receiver should be used), and take as an argument the somId for the desired method (which can be obtained from the method's name using the somIdFromString function). For more information on these methods, see the System Object Model Programming Reference.

Important Note: SOM provides many ways for a SOM user to acquire a pointer to a method procedure. Once this is done, it becomes the user's responsibility to make appropriate use of this procedure.

• First, the procedure should only be used on objects for which this is appropriate-otherwise, run-time errors are likely to result.

• Second, when the procedure is used, it is essential that the compiler be given correct information concerning the signature of the method and the linkage required by the method. (On many systems, there are different ways to pass method arguments, and linkage information tells a compiler how to pass the arguments indicated by a method's signature).

SOM method procedures on OS/2 must be called with "system" linkage. On AIX, there is only one linkage convention for procedure calls. While C and C++ provide standard ways to indicate a method signature, the way to indicate linkage information depends on the specific compiler and system. For each method declared using OIDL or IDL, the C and C++ usage bindings therefore use conditional macros and a typedef to name a type that has the correct linkage convention. This type name can then be used by programmers with access to the usage bindings for the class that introduces the method whose procedure pointer is used. The type is named somTD_<className>_<methodName>. This is illustrated in the following example, and further details are provided in the section below, titled "Obtaining a method's procedure pointer."