SOM Compiler qualified modifiers

Qualified modifiers are categorized according to the IDL component (class, attribute, method, or type) to which each modifier applies. Listed below are the SOM Compiler-defined identifiers used as qualified modifiers, along with the IDL component to which it applies. Descriptions of all qualified modifiers are then given in alphabetical order. Recall that qualified modifiers are defined using the syntax qualifier: modifier[=value].

For classes:

releaseorder
For attributes:
indirect, nodata, noget, noset
For methods:
caller_owns_parameters, caller_owns_result, const, init, method, migrate, namelookup, nocall, noenv, nonstatic, nooverride, noself, object_owns_parameters, object_owns_result, offset, override, procedure, reintroduce, and select
For variables:
staticdata
For types:
impctx

caller_owns_parameters ="p1,p2,...,pn"

Specifiesthenamesofthemethod ' sparameterswhoseownershipisretainedby( inthecaseof" in " parameters )ortransferredto( for" inout "or" out "parameters )thecaller .Thismodifierisonlyvalidintheinterfacespecificationofthemethod ' sintroducingclass . ThismodifieronlymakessenseforparameterswhoseIDLtypeisadataitemthatcanbefreed( string ,object ,array ,pointer ,orTypeCode ) ,oradataitemcontainingmemorythatcanbefreed( forexample ,asequenceorany ) ,orastructorunion .

For parameters whose type is an object, ownership applies to the object reference rather than to the object (that is, the caller should invoke release on the parameter, rather than somFree).

caller_owns_result
Specifies that ownership of the return result of the method is transferred to the caller, and that the caller is responsible for freeing the memory. This modifier is only valid in the interface specification of the method's introducing class. This modifier only makes sense when the method's return type is a data type that can be freed (string, object, array, pointer, or TypeCode), or a data item containing memory that can be freed (for example, a sequence or any). For methods that return an object, ownership applies to the object reference rather than to the object (that is, the caller should invoke release on the result, rather than somFree).
const
Indicates that implementations of the related method should not modify their target argument. SOM provides no way to verify or guarantee that implementations do not modify the targets of such methods, and the information provided by this modifier is not currently of importance to any of the Toolkit emitters. However, the information may prove useful in the future. For example, since modifiers are available in the Interface Repository, there may be future uses of this information by DSOM.
impctx
Supports types that cannot be fully defined using IDL. For full information, see "Using the tk_foreign TypeCode" in Chapter 7, "The Interface Repository Framework."
indirect
Directs the SOM Compiler to generate "get" and "set" methods for the attribute that take and return a pointer to the attribute's value, rather than the attribute value itself. For example, if an attribute x of type float is declared to be an indirect attribute, then the "_get_x" method will return a pointer to a float, and the input to the "_set_x" method must be a pointer to a float. (This modifier is provided for OIDL compatibility only.)
init
Indicates that a method is an initializer method. For information concerning the use of this modifier, see "Initializing and Uninitializing Objects: in Chapter 5, "Implementing Classes in SOM"
method or nonstatic or procedure

Indicates the category of method implementation. Refer to the topic "The four kinds of SOM methods" in Chapter 5, "Implementing Classes in SOM," for an explanation of the meanings of these different method modifiers. If none of these modifiers is specified, the default is method. Methods with the procedure modifier cannot be invoked remotely using DSOM.
migrate = ancestor
Indicates that a method originally introduced by this interface has been moved upward to a specified <ancestor> interface. When this is done, the method introduction must be removed from this interface (because the method is now inherited). However, the original releaseorder entry for the method should be retained, and migrate should be used to assure that clients compiled based on the original interface will not require recompilation. The ancestor interface is specified using a C-scoped interface name. For example, "Module_InterfaceName", not "Module::InterfaceName". See the later topic "Name usage in client programs" for an explanation of C-scoped names.
namelookup
See "offset or namelookup."
nocall
Specifies that the related method should not be invoked on an instance of this class even though it is supported by the interface.
nodata
Directs the SOM Compiler not to define an instance variable corresponding to the attribute. For example, a "time" attribute would not require an instance variable to maintain its value, because the value can be obtained from the operating system. The "get" and "set" methods for "nodata" attributes must be defined by the class implementer; stub method procedures for them are automatically generated in the implementation template for the class by the SOM Compiler.
noenv
Indicates that a direct-call procedure does not receive an environment as an argument.
noget
Directs the SOM Compiler not to automatically generate a "get" method procedure for the attribute in the .ih/.xih binding file for the class. Instead, the "get" method must be implemented by the class implementer. A stub method procedure for the "get" method is automatically generated in the implementation template for the class by the SOM Compiler, to be filled in by the implementer.
nonstatic
See "method or nonstatic or procedure."
nooverride
Indicates that the method should not be overridden by subclasses. The SOM Compiler will generate an error if this method is overridden.
noself
Indicates that a direct-call procedure does not receive a target object as an argument.
noset
Directs the SOM Compiler not to automatically generate a "set" method procedure for the attribute in the .ih/.xih binding file for the class. Instead, the "set" method must be implemented by the class implementer. A stub method procedure for the "set" method is automatically generated in the implementation template for the class by the SOM Compiler.

Note: The "set" method procedure that the SOM Compiler generates by default for an attribute in the .h/.xh binding file (when the noset modifier is not used) does a shallow copy of the value that is passed to the attribute. For some attribute types, including strings and pointers, this may not be appropriate. For instance, the "set" method for an attribute of type string should perform a string copy, rather than a shallow copy, if the attribute's value may be needed after the client program has freed the memory occupied by the string. In such situations, the class implementer should specify the noset attribute modifier and implement the attribute's "set" method manually, rather than having SOM implement the "set" method automatically.

object_owns_parameters ="p1, p2, ..., pn"

Specifies the names of the method's parameters whose ownership is transferred to (in the case of "in" parameters) or is retained by (for "inout" or "out" parameters) the object. For "in" parameters, the object can free the parameter at any time after receiving it. (Hence, the caller should not reuse the parameter or pass it as any other object-owned parameter in the same method call.) For "inout" and "out" parameters, the object is responsible for freeing the parameter sometime before the object is destroyed. This modifier is only valid in the interface specification of the method's introducing class. This modifier only makes sense for parameters whose IDL type is a data item that can be freed (string, object, array, pointer, or TypeCode), or a data item containing memory that can be freed (for example, a sequence or any), or a struct or union.

For parameters whose type is an object, ownership applies to the object reference rather than to the object (that is, the object will invoke release on the parameter, rather than somFree). For "in" and "out" parameters whose IDL-to-C/C++ mapping introduces a pointer, ownership applies only to the data item itself, and not to the introduced pointer. (For example, even if an "out string" IDL parameter (which becomes a "string *" C/C++ parameter) is designated as "object-owned," the object assumes ownership of the string, but not of the pointer to the string.)

object_owns_result
Specifies that the object retains ownership of the return result of the method, and that the caller must not free the memory. The object is responsible for freeing the memory sometime before the object is destroyed. This modifier is only valid in the interface specification of the method's introducing class. This modifier only makes sense when the method's return type is a data type that can be freed (string, object, array, pointer, or TypeCode), or a data item containing memory that can be freed (for example, a sequence or any). For methods that return an object, ownership applies to the object reference rather than to the object (that is, the object will be responsible for invoking release on the result, rather than somFree).
offset or namelookup
Indicates whether the SOM Compiler should generate bindings for invoking the method using offset resolution or name lookup. Offset resolution requires that the class of the method's target object be known at compile time. When different methods of the same name are defined by several classes, namelookup is a more appropriate technique for method resolution than is offset resolution. (See Chapter 3, the section entitled "Invoking Methods.") The default modifier is offset.
override
Indicates that the method is one introduced by an ancestor class and that this class will re-implement the method. See also the related modifier, select.
procedure
See "method or nonstatic or procedure."
reintroduce
Indicates that this interface will "hide" a method introduced by some ancestor interface, and will replace it with another implementation. Methods introduced as direct-call procedures or nonstatic methods can be reintroduced. However, static methods (the default implementation category for SOM met hods) cannot be reintroduced.
releaseorder: a, b, c, ...
Specifies the order in which the SOM Compiler will place the class's methods in the data structures it builds to represent the class. Maintaining a consistent release order for a class allows the implementation of a class to change without requiring client programs to be recompiled.

The release order should contain every method name introduced by the class (private and nonprivate), but should not include any inherited methods, even if they are overridden by the class. The "get" and "set" methods defined automatically for each new attribute (named "_get_<attributeName>" and "_set_<attributeName>") should also be included in the release order list. The order of the names on the list is unimportant except that once a name is on the list and the class has client programs, it should not be reordered or removed, even if the method is no longer supported by the class, or the client programs will require recompilation. New methods should be added only to the end of the list. If a method named on the list is to be moved up in the class hierarchy, its name should remain on the current list, but it should also be added to the release order list for the class that will now introduce it.

If not explicitly specified, the release order will be determined by the SOM Compiler, and a warning will be issued for each missing method. If new methods or attributes are subsequently added to the class, the default release order might change; programs using the class would then require recompilation. Thus, it is advisable to explicitly give a release order.

select = parent
Used in conjunction with the override modifier, this, indicates that an inherited static method will use the implementation inherited from the indicated <parent> class. The parent is specified using the C-scoped name. For example, "Module_InterfaceName", not "Module:: InterfaceName". See the later topic "Name usage in client programs" for an explanation of C-scoped names.
staticdata
Indicates that the declared variable is not stored within objects, but, instead, that the ClassData structure for the implementing class will contain a pointer to the staticdata variable. This is similar in concept to C++ static data members. The staticdata variable must also be included in the releaseorder. The class implementor has responsibility for allocating the staticdata variable and for loading the ClassData structure's pointer to the staticdata variable during class initialization. (The pointer is accessible as <className>ClassData.<variableName>.) The implementor's responsibility can be facilitated by writing a special class initialization function and indicating its name using the classinit unqualified modifier. (See also the examples that follow.)

Note: Attributes can be declared as staticdata. This is an important implementation technique that allows classes to introduce attributes whose backing storage is not inherited by subclasses.

The following example illustrates the specification of qualified modifiers:

implementation{
  releaseorder : op1, op3, op2, op5, op6, x, y, _set_z, _get_z;
  op1 : persistent;
  somDefaultInit : override, init;
  op2: reintroduce, procedure;
  op3: reintroduce, nonstatic;
  op4: override, select = ModuleName_parentInterfaceName;
  op5: migrate = ModuleName_ancestorInterfaceName;
  op6: procedure, noself, noenv;
  long x;
  x: staticdata;
  y: staticdata; // y and z are attributes
  _set_z: object_owns_parameters = "name";
  _get_z: object_owns_result;
  mymod : a, b;
};

As shown above for attribute z, separate modifiers can be declared for an attribute's _set and _get methods, using method modifiers. This capability may be useful for DSOM applications. (See the DSOM sample program "animal" that is distributed with the SOMobjects Toolkit.)

The next example for classes "X" and "Y" illustrates the use of a staticdata modifier, along with its corresponding classinit modifier and the template procedure generated for classinit by the SOM Compiler.

/* IDL for staticdata and classinit example: */

#include <somobj.idl>

interface X : SOMObject {
        attribute long staticAttribute;
        attribute long normalAttribute;
        implementation {
                staticAttribute: staticdata;
                classinit = Xinit;
                releaseorder: staticAttribute,
                                    _get_staticAttribute,
                                    _set_staticAttribute,
                                    _get_normalAttribute,
                                    _set_normalAttribute;
        };
};

interface Y : X { };

/* Template procedure for classInit: */

#ifndef SOM_Module_classinit_Source
#define SOM_Module_classinit_Source
#endif
#define X_Class_Source

#include "classInit.ih"

static long holdStaticAttribute = 1234;
void SOMLINK Xinit(SOMClass *cls)
{
        XClassData.staticAttribute = &holdStaticAttribute;
}

main()
{
        X *x = XNew();
        Y *y = YNew();

        somPrintf("initial staticAttribute = x(%d) = y(%d)\n",
                                _get_staticAttribute(x,0),
                                _get_staticAttribute(y,0));

        _set_staticAttribute(x,0,42);
        _set_staticAttribute(y,0,4321);

        somPrintf("changed staticAttribute = x(%d) = y(%d)\n",
                                _get_staticAttribute(x,0),
                                _get_staticAttribute(y,0));
}

/* Program output:

        initial staticAttribute = x(1234) = y(1234)
        changed staticAttribute = x(4321) = y(4321)
        after setting normalAttribute, x(10) != y(20)
*/

---

[Back: SOM Compiler unqualified modifiers]
[Next: Passthru statements]