SC23-2681 Bull DPX/20 SOMobjects Base Toolkit Programmer’s Reference Manual AIX ORDER REFERENCE 86 A2 28AQ 01
Bull DPX/20 SOMobjects Base Toolkit Programmer’s Reference Manual AIX Software June 1995 BULL S.A.
The following copyright notice protects this book under the Copyright laws of the United States and other countries which prohibit such actions as, but not limited to, copying, distributing, modifying, and making derivative works. Copyright Bull S.A. 1992, 1995 Printed in France Suggestions and criticisms concerning the form, content, and presentation of this book are invited. A form is provided at the end of this book for this purpose.
About This Book This book gives reference material for the System Object Model (SOM) of the SOMobjects Base Toolkit. In particular, it contains a reference page for every class, method, function, and macro provided by the SOM run-time library, the DSOM run-time library, the Interface Repository Framework, and the Event Management Framework. It also includes documentation of the utility metaclasses provided by the SOMobjects Base Toolkit, and each of their methods.
Return Value A description of the method’s return value. Example An example of using or overriding the method, if available. Although methods of SOM classes are language neutral (that is, they can be invoked from any programming language that can use SOM), the examples given here are written in C. Original Class The name of the class that introduces the method (the class is documented separately in this book).
Contents Chapter 1. SOM Kernel Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somApply Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somBeginPersistentIds Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somBuildClass Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somCheckId Function . .
SOM_GetClass Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-56 SOM_InitEnvironment Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-57 SOM_MainProgram Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-58 SOM_NoTrace Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
somCastObj Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somDefaultInit Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somDestruct Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somDispatch, somClassDispatch Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
find_classes_by_impldef Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . find_impldef Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . find_impldef_by_alias Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . find_impldef_by_class Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
somdFindServerByName Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somdFindServersByClass Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SOMDServer Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somdCreateObj Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . somdDeleteObj Method . . . . . . . . . . .
x TypeCode_parameter Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TypeCode_print Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TypeCode_setAlignment Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TypeCode_size Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-47 3-49 3-50 3-51 Chapter 4.
Chapter 1.
somApply Function Purpose Invokes an apply stub. Apply stubs are never invoked directly by SOM users, the somApply function must be used instead. Syntax boolean somApply ( SOMObject objPtr, somToken *retVal, somMethodDataPtr mdPtr, va_list args); Description somApply provides a single uniform interface through which it is possible to call any method procedure.
args A pointer to a memory region in which all of the arguments to the method procedure have been laid out in consecutive addresses, according to the protocol implemented by va_lists. The first entry of the va_list must be objPtr. Furthermore, all arguments on the va_list must appear in widened form, as defined by ANSI C. For example, floats must appear as doubles, and chars and shorts must appear as ints. C++ Example #include #include #include
somBeginPersistentIds Function Purpose Tells SOM to begin a “persistent ID interval.” Syntax void somBeginPersistentIds ( ); Description The somBeginPersistentIds function informs the SOM ID manager that strings for any new SOM IDs that are registered will not be freed or modified. This allows the ID manager to use a pointer to the string in the unregistered ID as the master copy of the ID’s string, rather than making a copy of the string. This makes ID handling more efficient. C Example #include
somBuildClass Function Purpose Automates the process of building a new SOM class object. Syntax void somBuildClass ( unsigned long inheritVars, somStaticClassInfoPtr sciPtr, long majorVersion, long minorVersion); Description The somBuildClass function accepts declarative information defining a new class that is to be built, and performs the activities required to build and register a correctly functioning class object. The C and C++ implementation bindings use this function to create class objects.
somCheckId Function Purpose Registers a SOM ID. Syntax somId somCheckId (somId id); Description The somCheckId function registers a SOM ID and converts it into an internal representation. The input SOM ID is returned. If the ID is already registered, this function has no effect. Parameters id The somId to be registered. Return Value The registered somId. Example See the somBeginPersistentIds function.
somClassResolve Function Purpose Obtains a pointer to the procedure that implements a static method for instances of a particular SOM class. Syntax somMethodPtr somClassResolve (SOMClass cls, somMToken mToken); Description The somClassResolve function is used to obtain a pointer to the procedure that implements the specified method for instances of the specified SOM class. The returned procedure pointer can then be used to invoke the method.
C++ Example // SOM IDL for class A and class B #include module scrExample { interface A : SOMObject { void foo(); implementation { callstyle=oidl; }; }; interface B : A { implementation { foo: override; }; }; }; // Example C++ program to implement and test module scrExample #define SOM_Module_screxample_Source #include #include
somCompareIds Function Purpose Determines whether two SOM IDs represent the same string. Syntax int somCompareIds (somId id1, somId id2); Description The somCompareIds function returns 1 if the two input IDs represent strings that are equal; otherwise, it returns 0. Parameters id1 The first SOM ID to be compared. id2 The second SOM ID to be compared. Return Value Returns 1 if the two input IDs represent strings that are equal; otherwise, it returns 0. C Example #include
somDataResolve Function Purpose Accesses instance data within an object. Syntax somToken somDataResolve (SOMObject obj, somDToken dToken); Description The somDataResolve function is used to access instance data within an object. This function is of use primarily to class implementors (rather than class clients) who are not using the SOM C or C++ language bindings.
somEndPersistentIds Function Purpose Tells SOM to end a “persistent ID interval.” Syntax void somEndPersistentIds ( ); Description The somEndPersistentIds function informs the SOM ID manager that strings for any new SOM IDs that are registered might be freed or modified by the client program. Thus, the ID manager must make a copy of the strings. Example See the somBeginPersistentIds function.
somEnvironmentEnd Function Purpose Provides general cleanup for applications. Syntax void somEnvironmentEnd ( ); Description The somEnvironmentEnd function is a general cleanup function that must be called by all Windows applications before exiting. AIX and OS/2 programs may also invoke this function, but it is not required on these systems because all necessary SOM cleanup is performed by the operating system during program termination.
somEnvironmentNew Function Purpose Initializes the SOM runtime environment. Syntax SOMClassMgr somEnvironmentNew ( ); Description The somEnvironmentNew function creates the four primitive SOM objects (SOMObject, SOMClass, SOMClassMgr, and SOMClassMgrObject) and initializes global variables used by the SOM runtime environment. This function must be called before using any other SOM functions or methods (with the exception of somSetExpectedIds).
somExceptionFree Function Purpose Frees the memory held by the exception structure within an Environment structure. Syntax void somExceptionFree (Environment *ev); Description The somExceptionFree function frees the memory held by the exception structure within an Environment structure. Parameters ev A pointer to the Environment whose exception information is to be freed. Example See the somSetException function.
somExceptionId Function Purpose Gets the name of the exception contained in an Environment structure. Syntax string somExceptionId (Environment *ev); Description The somExceptionId function returns the name of the exception contained in the specified Environment structure. Parameters ev A pointer to an Environment structure containing an exception. Return Value The somExceptionId function returns the name of the exception contained in the specified Environment structure, as a string.
somExceptionValue Function Purpose Gets the value of the exception contained in an Environment structure. Syntax somToken somExceptionValue (Environment *ev); Description The somExceptionValue function returns the value of the exception contained in the specified Environment structure. Parameters ev A pointer to an Environment structure containing an exception. Return Value The somExceptionValue function returns a pointer to the value of the exception contained in the specified Environment structure.
somGetGlobalEnvironment Function Purpose Returns a pointer to the current global Environment structure. Syntax Environment *somGetGlobalEnvironment ( ); Description The somGetGlobalEnvironment function returns a pointer to the current global Environment structure. This structure can be passed to methods that require an (Environment *) argument.
somIdFromString Function Purpose Returns the SOM ID corresponding to a given text string. Syntax somId somIdFromString (string aString); Description The somIdFromString function returns the SOM ID that corresponds to a given text string. Ownership of the somId returned by somIdFromString passes to the caller, which has the responsibility to subsequently free the somId using SOMFree. Parameters aString The string to be converted to a SOM ID.
somIsObj Function Purpose Failsafe routine to determine whether a pointer references a valid SOM object. Syntax boolean somIsObj (somToken memPtr); Description The somIsObj function returns 1 if its argument is a pointer to a valid SOM object, or returns 0 otherwise. The function handles address faults, and does extensive consistency checking to guarantee a correct result. Parameters memPtr A somToken (a pointer) to be checked.
somLPrintf Function Purpose Prints a formatted string in the manner of the C printf function, at the specified indentation level. Syntax long somLPrintf (long level, string fmt, ...); Description The somLPrintf function prints a formatted string using SOMOutCharRoutine, in the same manner as the C printf function. The implementation of SOMOutCharRoutine determines the destination of the output, while the C printf function is always directed to stdout.
somMainProgram Function Purpose Performs SOM initialization on behalf of a new program. Syntax SOMClassMgr *somMainProgram ( ); Description The somMainProgram function informs SOM about the beginning of a new thread of execution (called a task on Windows). The SOM Kernel then performs any needed initialization, including the deferred execution of the SOMInitModule functions found in statically-loaded class libraries.
somParentNumResolve Function Purpose Obtains a pointer to a procedure that implements a method, given a list of method tables. Syntax somMethodPtr somParentNumresolve ( somMethod Tabs parentMtab, int parentNum, somMToken M Token); Methods: somGetMethodData, somGetNthMethodData, somGetRdStub, somAddStaticMethod, somAddDynamicMethod Description The somParentNumResolve function is used to make parent method calls by the C and C++ language implementation bindings.
C++ Example // SOM IDL for class A and class B #include module spnrExample { interface A : SOMObject { void foo(); implementation { callstyle=oidl; }; }; interface B : A { implementation { foo: override; }; }; }; // Example C++ program to implement and test #define SOM_Module_spnrexample_Source #include #include
somParentResolve Function Purpose Obtains a pointer to a procedure that implements a method, given a list of method tables. Obsolete but still supported. Syntax somMethodPtr somParentResolve (somMethodTabs parentMtab, somMToken mToken); Description The somParentResolve function is used by old, single-parent class binaries to make parent method calls. The function is obsolete, but is still supported. The somParentResolve function returns a pointer to the procedure that implements the specified method.
somPrefixLevel Function Purpose Outputs blanks to prefix a line at the indicated level. Syntax void somPrefixLevel (long level); Description The somPrefixLevel function outputs blanks (through the somPrintf function) to prefix the next line of output at the indicated level. (The number of blanks produces is 2*level.) This function is useful when overriding the somDumpSelfInt method, which takes the level as an argument. Parameters level The level at which the next line of output is to start.
somPrintf Function Purpose Prints a formatted string in the manner of the C printf function. Syntax long somPrintf (string fmt, ...); Description The somPrintf function prints a formatted string using function SOMOutCharRoutine, in the same manner as the C printf function. The implementation of SOMOutCharRoutine determines the destination of the output, while the C printf function is always directed to stdout.
somRegisterId Function Purpose Registers a SOM ID and determines whether or not it was previously registered. Syntax int somRegisterId (somId id); Description The somRegisterId function registers a SOM ID and converts it into an internal representation. If the ID is already registered, somRegisterId returns 0 and has no effect. Otherwise, somRegisterId returns 1. Parameters The somId to be registered. id Return Value If the ID is already registered, somRegisterId returns 0.
somResolve Function Purpose Obtains a pointer to the procedure that implements a method for a particular SOM object. Syntax somMethodPtr somResolve (SOMObject obj, somMToken mToken); Description The somResolve function returns a pointer to the procedure that implements the specified method for the specified SOM object. This pointer can then be used to invoke the method.
C Example // SOM IDL for class A and class B #include module srExample { interface A : SOMObject { void foo(); implementation { callstyle=oidl; }; }; interface B : A { implementation { foo: override; }; }; }; // Example C++ program to implement and test #define SOM_Module_srexample_Source #include #include
somResolveByName Function Purpose Obtains a pointer to the procedure that implements a method for a particular SOM object. Syntax somMethodPtr somResolveByName (SOMObject obj, string methodName); Description The somResolveByName function is used to obtain a pointer to the procedure that implements the specified method for the specified SOM object. The returned procedure pointer can then be used to invoke the method. The C and C++ usage bindings use this function to support name-lookup methods.
somSetException Function Purpose Sets an exception value in an Environment structure. Syntax void somSetException (Environment *ev, enum exception_type major, string exceptionName, somToken params); Description The somSetException function sets an exception value in an Environment structure. Parameters ev A pointer to the Environment structure in which to set the exception. This value must be either NULL or a value formerly obtained from the function somGetGlobalEnvironment.
C Example /* IDL declaration of class X: */ interface X : SOMObject { exception OUCH {long code1; long code2; }; void foo(in long arg) raises (OUCH); }; /* implementation of foo method */ SOM_Scope void SOMLINK foo(X somSelf, Environment *ev, long arg) { X_OUCH *exception_params; /* X_OUCH struct is defined in X’s usage bindings */ if (arg > 5) /* then this is a very bad error */ { exception_params = (X_OUCH*)SOM_Malloc(sizeof(X_OUCH)); exception_params–>code1 = arg; exception_params–>code2 = arg–5; somSetE
somSetExpectedIds Function Purpose Tells SOM how many unique SOM IDs a client program expects to use. Syntax void somSetExpectedIds (unsigned long numIds); Description The somSetExpectedIds function informs the SOM runtime environment how many unique SOM IDs a client program expects to use during its execution. This has the potential of slightly improving the program’s space and time efficiency, if the value specified is accurate.
somSetOutChar Function Purpose Changes the behavior of the somPrintf function. Syntax void somSetOutChar ( somTD_SOMOutCharRoutine * outCharRtn); Description The somSetOutChar function is called to change the output character routine that somPrintf invokes. By default, somPrintf invokes a character output routine that goes to stdout. The execution of somSetOutChar affects only the application (or thread) in which it occurs.
somStringFromId Function Purpose Returns the string that a SOM ID represents. Syntax string somStringFromId (somId id); Description The somStringFromId function returns the string that a given SOM ID represents. Parameters id The SOM ID for which the corresponding string is needed. Return Value Returns the string that the given SOM ID represents. Example See the somBeginPersistentIds function.
somTotalRegIds Function Purpose Returns the total number of SOM IDs that have been registered. Syntax unsigned long somTotalRegIds ( ); Description The somTotalRegIds function returns the total number of SOM IDs that have been registered so far. This value can be used as a parameter to the somSetExpectedIds function to advise SOM about expected ID usage in later executions of a client program. Return Value Returns the total number of SOM IDs that have been registered. C Example #include
somUniqueKey Function Purpose Returns the unique key associated with a SOM ID. Syntax unsigned long somUniqueKey (somID id); Description The somUniqueKey function returns the unique key associated with a SOM ID. The unique key for a SOM ID is a number that uniquely represents the string that the SOM ID represents. The unique key for a SOM ID is the same as the unique key for another SOM ID only if the two SOM IDs represent the same string. Parameters id The SOM ID for which the unique key is needed.
somVprintf Function Purpose Prints a formatted string in the manner of the C vprintf function. Syntax long somVprintf (string fmt, va_list ap); Description The somVprintf function prints a formatted string using SOMOutCharRoutine, in the same manner as the C vprintf function. The implementation of SOMOutCharRoutine determines the destination of the output, while the C printf function is always directed to stdout.
SOMCalloc Function Purpose Allocates sufficient zeroed memory for an array of objects of a specified size. Syntax somToken (*SOMCalloc) (size_t num, size_t size); Description The SOMCalloc function allocates an amount of memory equal to num*size (sufficient memory for an array of num objects of size size). The SOMCalloc function has the same interface as the C calloc function. It performs the same basic function as calloc with some supplemental error checking.
SOMClassInitFuncName Function Purpose Returns the name of the function used to initialize classes in a DLL. Syntax string (*SOMClassInitFuncName) ( ); Description The SOMClassInitFuncName function is called by the SOM Class Manager to determine what function to call to initialize the classes in a DLL. The default version returns the string “SOMInitModule.
SOMDeleteModule Function Purpose Unloads a dynamically linked library (DLL). Syntax int (*SOMDeleteModule) (somToken modHandle); Description The SOMDeleteModule function unloads the specified dynamically linked library (DLL). This routine is called by the SOM Class Manager to unload DLLs. SOMDeleteModule can be replaced (thus changing the way the Class Manager unloads DLLS) by changing the value of the global variable SOMDeleteModule. Parameters modHandle The somToken for the DLL to be unloaded.
SOMError Function Purpose Handles an error condition. Syntax void (*SOMError) (int errorCode, string fileName, int lineNum); Description The SOMError function inspects the specified error code and takes appropriate action, depending on the severity of the error. The last digit of the error code indicates whether the error is classified as SOM_Fatal (9), SOM_Warn (2), or SOM_Ignore (1).
SOMFree Function Purpose Frees the specified block of memory. Syntax void (*SOMFree) (somToken ptr); Description The SOMFree function frees the block of memory pointed to by ptr. SOMFree should only be called with a pointer previously allocated by SOMMalloc or SOMCalloc. The SOMFree function has the same interface as the C free function. It performs the same basic function as free with some supplemental error checking. If an error occurs, the SOMError function is called.
SOMInitModule Function Purpose Invokes the class creation routines for the classes contained in an OS/2 or Windows class library (DLL). Syntax SOMEXTERN void SOMLINK SOMInitModule ( long MajorVersion, long MinorVersion, string ClassName); Description On OS/2 or Windows, a class library (DLL) can contain the implementations for multiple classes, all of which should be created when the DLL is loaded.
For Windows, also include the following function: #include int CALLBACK LibMain (HINSTANCE inst, WORD ds, WORD Heapsize, LPSTR cmdLine) { SOM_IgnoreWarning (inst); SOM_ignoreWarning (ds); SOM_IgnoreWarning (heapSize); SOM_IgnoreWarning (cmdLine); SOM_ClassLibrary (”xyz.
SOMLoadModule Function Purpose Loads the dynamically linked library (DLL) containing a SOM class. Syntax int (*SOMLoadModule) ( string className, string fileName, string functionName, long majorVersion, long minorVersion, somToken *modHandle); Description The SOMLoadModule function loads the dynamically linked library (DLL) containing a SOM class. This routine is called by the SOM Class Manager to load DLLs.
SOMMalloc Function Purpose Allocates the specified amount of memory. Syntax somToken (*SOMMalloc) (size_t size); Description The SOMMalloc function allocates size bytes of memory. The SOMMalloc function has the same interface as the C malloc function. It performs the same basic function as malloc with some supplemental error checking. If an error occurs, the SOMError function is called. This routine is replaceable by changing the value of the global variable SOMMalloc.
SOMOutCharRoutine Function Purpose Prints a character. This function is replaceable. Syntax int (*SOMOutCharRoutine) (char c); Description SOMOutCharRoutine is a replaceable character output routine. It is invoked by SOM whenever a character is generated by one of the SOM error-handling or debugging macros. The default implementation outputs the specified character to stdout.
SOMRealloc Function Purpose Changes the size of a previously allocated region of memory. Syntax somToken (*SOMRealloc) (somToken ptr, size_t size); Description The SOMRealloc function changes the size of the previously allocated region of memory pointed to by ptr so that it contains size bytes. The new size may be greater or less than the original size. The SOMRealloc function has the same interface as the C realloc function.
SOM_Assert Macro Purpose Asserts that a boolean condition is true. Syntax void SOM_Assert ( boolean condition, long errorCode); Description The SOM_Assert macro is used to place boolean assertions in a program: • If condition is FALSE, and errorCode indicates a warning-level error and SOM_WarnLevel is set to be greater than zero, then a warning message is output. • If condition is FALSE and errorCode indicates a fatal error, an error message is output and the process is terminated.
SOM_ClassLibrary Macro Purpose Identifies the file name of the DLL for a SOM class library in a Windows LibMain function. Syntax void SOM_ClassLibrary (string “libname.dll ”); Description Each Windows SOM class library must supply a Windows LibMain function. In LibMain, the SOM_ClassLibrary macro identifies both the actual file name of the library as it would appear in a Windows LoadLibrary call and the location of the library’s SOMInitModule function.
SOM_CreateLocalEnvironment Macro Purpose Creates and initializes a local Environment structure. Syntax Environment * SOM_CreateLocalEnvironment ( ); Description The SOM_CreateLocalEnvironment macro creates a local Environment structure. This Environment structure can be passed to methods as the Environment argument so that exception information can be returned without affecting the global environment. Expansion The SOM_CreateLocalEnvironment expands to an expression of type (Environment *).
SOM_DestroyLocalEnvironment Macro Purpose Destroys a local Environment structure. Syntax void SOM_DestroyLocalEnvironment (Environment * ev); Description The SOM_DestroyLocalEnvironment macro destroys a local Environment structure, such as one created using the SOM_CreateLocalEnvironment macro. Parameters A pointer to the Environment structure to be discarded.
SOM_Error Macro Purpose Reports an error condition. Syntax void SOM_Error (long errorCode); Description The SOM_Error macro invokes the SOMError error handling procedure with the specified error code, supplying the filename and line number where the macro was invoked. The default implementation of SOMError outputs a message containing the error code, filename, and line number. Additionally, if the last digit of the error code indicates a serious error (that is, value SOM_Fatal), the process is terminated.
SOM_Expect Macro Purpose Asserts that a boolean condition is expected to be true. Syntax void SOM_Expect (boolean condition); Description The SOM_Expect macro is used to place boolean assertions that are expected to be true into a program: • If condition is FALSE and SOM_WarnLevel is set to be greater than zero, then a warning message is output. • If condition is TRUE and SOM_AssertLevel is set to be greater than zero, then an informational message is output.
SOM_GetClass Macro Purpose Returns a pointer to the class object of which a SOM object is an instance. Syntax SOMClass SOM_GetClass (SOMObject objPtr); Description The SOM_GetClass macro returns the class object of which obj is an instance. This is done without recourse to a method call on the object. The somGetClass method introduced by SOMObject is also intended to return the class of which an object is an instance, and the default implementation provided for this method by SOMObject uses the macro.
SOM_InitEnvironment Macro Purpose Initializes a local Environment structure. Syntax void SOM_InitEnvironment (Environment * ev); Description The SOM_InitEnvironment macro initializes a locally declared Environment structure. This Environment structure can then be passed to methods as the Environment argument so that exception information can be returned without affecting the global environment. Parameters A pointer to the Environment structure to be initialized.
SOM_MainProgram Macro Purpose Identifies an application as a SOM program and registers an end-of-program exit procedure to release SOM resources when the application terminates. Syntax SOMClassMgr SOM_MainProgram ( ); Description The SOM_MainProgram macro should appear near the beginning of each Windows application program that uses SOM or a SOM class library. It can also be used in OS/2 or AIX programs but is not generally required on these platforms.
SOM_NoTrace Macro Purpose Used to turn off method debugging. Syntax SOM_NoTrace ( className, methodName); Description The SOM_NoTrace macro is used to turn off method debugging. Within an implementation file for a class, before #including the implementation (.ih or .xih) header file for the class, #define the MethodDebug macro to be SOM_NoTrace. Then, MethodDebug will have no effect.
SOM_ParentNumResolve Macro Purpose Obtains a pointer to a method procedure from a list of method tables. Used by C and C++ implementation bindings to implement parent method calls. Syntax somMethodPtr SOM_ParentNumResolve ( IntroClass, long parentNum, somMethodTabs parentMtabs, methodName); Description The SOM_ParentNumResolve macro invokes the somParentNumResolve function to obtain a pointer to the static method procedure that implements the specified method for the specified parent.
SOM_Resolve Macro Purpose Obtains a pointer to a static method procedure. Syntax somMethodPtr SOM_Resolve ( SOMObject objPtr, className, methodName); Description The SOM_Resolve macro invokes the somResolve function to obtain a pointer to the static method procedure that implements the specified method for the specified object.
SOM_ResolveNoCheck Macro Purpose Obtains a pointer to a static method procedure, without doing consistency checks. Syntax somMethodPtr SOM_ResolveNoCheck ( SOMObject objPtr, className, methodName); Description The SOM_ResolveNoCheck macro invokes the somResolve function to obtain a pointer to the method procedure that implements the specified method for the specified object. This pointer can be used for efficient repeated invocations of the same method on the same type of objects.
SOM_SubstituteClass Macro Purpose Provides a convenience macro for invoking the somSubstituteClass method. Syntax long SOM_SubstituteClass ( oldClass, newClass); Description The method somSubstituteClass requires existing class objects as arguments. Therefore, the macro SOM_SubstituteClass first assures that the classes named oldClass and newClass exist, and then calls the method somSubstituteClass with these class objects as arguments.
SOM_Test Macro Purpose Tests whether a boolean condition is true; if not, a fatal error is raised. Syntax void SOM_Test (boolean expression); Description The SOM_Test macro tests the specified boolean expression: • If the expression is TRUE and SOM_AssertLevel is set to a value greater than zero, then an information message is output. • If the expression is FALSE, an error message is output and the process is terminated.
SOM_TestC Macro Purpose Tests whether a boolean condition is true; if not, a warning message is output. Syntax void SOM_TestC (boolean expression); Description The SOM_TestC macro tests the specified boolean expression: • If the expression is TRUE and SOM_AssertLevel is set to a value greater than zero, then an information message is output. • If the expression is FALSE and SOM_WarnLevel is set to a value greater than zero, then a warning message is output.
SOM_UninitEnvironment Macro Purpose Uninitializes a local Environment structure. Syntax void SOM_UninitEnvironment (Environment * ev); Description The SOM_UninitEnvironment macro uninitializes a locally declared Environment structure. Parameters A pointer to the Environment structure to be uninitialized. ev Expansion The SOM_UninitEnvironment invokes the somExceptionFree function on the specified Environment structure. C Example Environment ev; SOM_InitEnvironment(&ev); _myMethod(obj, &ev); ...
SOM_WarnMsg Macro Purpose Reports a warning message. Syntax void SOM_WarnMsg (string msg); Description If SOM_WarnLevel is set to a value greater than zero, the SOM_WarnMsg macro prints the specified message, along with the filename and line number where the macro was invoked. Parameters msg The warning message to be output.
SOMClass Class Description SOMClass is the root class for all SOM metaclasses. That is, all SOM metaclasses must be subclasses of SOMClass or some other class derived from it. It defines the essential behavior common to all SOM classes. In particular, it provides a suite of methods for initializing class objects, generic methods for manufacturing instances of those classes, and methods that dynamically obtain or update information about a class and its methods at run time.
New Methods Attributes: readonly attribute somOffsets somInstanceDataOffsets _get_somInstanceDataOffsets returns a sequence of structures, each of which indicates an ancestor of the receiver class (or the receiver class itself) and the offset to the beginning of the instance data introduced by the indicated class in an instance of the receiver class.
somGetNumStaticMethods somGetParents somGetVersionNumbers Group: Testing somCheckVersion somDescendedFrom somSupportsMethod Group: Dynamic somFindMethod, somFindMethodOk somFindSMethod, somFindSMethodOk somLookupMethod Overridden Methods somDefaultInit somDestruct somDumpSelfInt Deprecated Methods Use of the following methods is discouraged. There are three reasons for this: First, these methods are used in constructing classes, and this capability is provided by the function somBuildClass.
somInitClass somInitMIClass somOverrideMtab somOverrideSMethod somSetClassData somSetMethodDescriptor SOM Kernel Reference 1-71
somAddDynamicMethod Method Purpose Adds a new dynamic instance method to a class. Dynamic methods are not part of the declared interface to a class of objects, and are therefore not supported by implementation and usage bindings. Instead, dynamic methods provide a way to dynamically add new methods to a class of objects during execution. SOM provides no standard protocol for informing a user of the existence of dynamic methods and the arguments they take.
C Example /* New static static static static dynamic method ”newMethod1” for class ”XXX” */ char *somMN_newMethod1 = ”newMethod1”; somId somId_newMethod1 = &somMN_newMethod1; char *somDS_newMethod1 = ”XXX::newMethod1”; somId somDI_newMethod1 = &somDS_newMethod1; static void SOMLINK somAP_newMethod1(SOMObject somSelf, void *__retVal, somMethodProc *__methodPtr, va_list __ap) { void* __somSelf = va_arg(__ap, SOMObject); int arg1 = va_arg(__ap, int); SOM_IgnoreWarning(__retVal); ((somTD_SOMObject_newMethod1)
somAllocate Method Purpose Supports class-specific memory allocation for class instances. Cannot be overridden. IDL Syntax string somAllocate (in long size); Note: For backward compatibility, this method does not take an Environment parameter. Description When building a class, the somBuildClass function is responsible for registering the procedure that will be executed when this method is invoked on the class.
somCheckVersion Method Purpose Checks a class for compatibility with the specified major and minor version numbers. Not generally overridden. IDL Syntax boolean somCheckVersion ( In long majorVersion, In long minorVersion); Note: For backward compatibility, this method does not take an Environment parameter. Description The somCheckVersion method checks the receiving class for compatibility with the specified major and minor version numbers.
Assuming that the implementation of Animal is version 1.0, this program produces the following output: Animal IS compatible with 0.0 Animal IS NOT compatible with 1.
somClassReady Method Purpose Indicates that a class has been constructed and is ready for normal use. Designed to be overridden. IDL Syntax void somClassReady ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somClassReady method is invoked automatically by the somBuildClass function after constructing and initializing a class object.
somDeallocate Method Purpose Frees memory originally allocated by the somAllocate method from the same class object. Cannot be overridden. IDL Syntax void somDeallocate (in string memPtr); Note: For backward compatibility, this method does not take an Environment parameter. Description The somDeallocate method is intended for use to free memory allocated using its dual method, somAllocate.
somDescendedFrom Method Purpose Tests whether one class is derived from another. Not generally overridden. IDL Syntax boolean somDescendedFrom (in SOMClass aClassObj); Note: For backward compatibility, this method does not take an Environment parameter. Description Tests whether the receiver class is derived from a given class. For programs that use classes as types, this method can be used to ascertain whether the type of one object is a subtype of another.
somFindMethod, somFindMethodOk Methods Purpose Finds the method procedure for a method and indicates whether it represents a static method or a dynamic method. Not generally overridden. IDL Syntax boolean somFindMethod ( in somId methodId, out somMethodPtr m); boolean somFindMethodOk ( in somId methodId, out somMethodPtr m); Note: For backward compatibility, these methods do not take an Environment parameter.
Parameters receiver A pointer to the class object whose method is desired. methodId An ID that represents the name of the desired method. The somIdFromString function can used to obtain an ID from the method’s name. m A pointer to the location in memory where a pointer to the specified method’s procedure should be stored. Both methods store a NULL pointer in this location (if the method does not exist) or a value that can be called.
somFindSMethod, somFindSMethodOk Methods Purpose Finds the method procedure for a static method. Not generally overridden. IDL Syntax somMethodPtr somFindSMethod (in somId methodId); somMethodPtr somFindSMethodOk (in somId methodId); Note: For backward compatibility, these methods do not take an Environment parameter. Description The somFindSMethod and somFindSMethodOk methods perform name-lookup resolution in a similar fashion to somFindMethod and somFindMethodOk, but are restricted to static methods.
somGetInstancePartSize Method Purpose Returns the total size of the instance data structure introduced by a class. Not generally overridden. IDL Syntax long somGetInstancePartSize ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetInstancePartSize method returns the amount of space needed in an object of the specified class or any of its subclasses to contain the instance variables introduced by the class.
Original Class SOMClass Related Information Methods: somGetInstanceSize 1-84 SOMobjects Base Toolkit: Programmer’s Reference Manual
somGetInstanceSize Method Purpose Returns the size of an instance of a class. Not generally overridden. IDL Syntax long somGetInstanceSize ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetInstanceSize method returns the total amount of space needed in an instance of the specified class. Parameters receiver A pointer to the class object whose instance size is desired.
somGetInstanceToken Method Purpose Returns a data access token for the instance data introduced by a class. Not generally overridden. IDL Syntax somDToken somGetInstanceToken ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description Returns a data token “pointing” to the beginning of the instance data introduced by the receiving class.
somGetMemberToken Method Purpose Returns an access token for an instance variable. This is method is not generally overridden. IDL Syntax somDToken somGetMemberToken ( long memberOffset, somDToken instanceToken); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetMemberToken method returns an access token for the data member at offset memberOffset within the block of instance data identified by instanceToken.
somGetMethodData Method Purpose Returns method information for a specified method, which must have been introduced by the receiver class or an ancestor of that class. Not generally overridden. IDL Syntax boolean somGetMethodData ( in somId methodId, out somMethodData md); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetMethodData method loads a somMethodData structure with data describing the method identified by the passed methodId.
somGetMethodDescriptor Method Purpose Returns the method descriptor for a method. Not generally overridden. IDL Syntax somId somGetMethodDescriptor (in somId methodId); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetMethodDescriptor method returns the method descriptor for a specified method of a class.
somGetMethodIndex Method Purpose Returns a class-specific index for a method. Not generally overridden. IDL Syntax long somGetMethodIndex (in somId methodId); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetMethodIndex method returns an index that can be used in subsequent calls to the same receiving class to determine information about the indicated (static or dynamic) method, via the methods somGetNthMethodData and somGetNthMethodInfo.
somGetMethodToken Method Purpose Returns a method access token for a static method. Not generally overridden. IDL Syntax somMToken somGetMethodToken (in somId methodId); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetMethodToken method returns a method access token for a static method with the specified ID that was introduced by the receiver class or an ancestor of the receiver class.
somGetName Method Purpose Returns the name of a class. Not generally overridden. IDL Syntax string somGetName ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetName method returns the address of a zero-terminated string that gives the name of the receiving class.
somGetNthMethodData Method Purpose Returns method information for the nth (static or dynamic) method known to a given class. Not generally overridden. IDL Syntax boolean somGetNthMethodData ( in long index, out somMethodData md) Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetNthMethodData method loads a somMethodData structure with data describing the method identified by the passed index.
somGetNthMethodInfo Method Purpose Returns the somId of the nth (static or dynamic) method known to a given class. Also loads a somId with a descriptor for the method. Not generally overridden. IDL Syntax somId somGetNthMethodInfo ( in long index, out somId descriptor); Note: For backward compatibility, this method does not take an Environment parameter.
somGetNumMethods Method Purpose Returns the number of methods available for a class. Not generally overridden. IDL Syntax long somGetNumMethods ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetNumMethods method returns the number of methods currently supported by the specified class, including inherited methods (both static and dynamic).
somGetNumStaticMethods Method Purpose Obtains the number of static methods available for a class. Not generally overridden. IDL Syntax long somGetNumStaticMethods ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetNumStaticMethods method returns the number of static methods available in the specified class, including inherited ones.
somGetParents Method Purpose Gets a pointer to a class’s parent (direct base) classes. Not generally overridden. IDL Syntax SOMClassSequence somGetParents ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetParents method returns a sequence containing pointers to the parents of the receiver. Parameters receiver A pointer to the class whose parent (base) classes are desired.
somGetVersionNumbers Method Purpose Gets the major and minor version numbers of a class’s implementation code. Not generally overridden. IDL Syntax void somGetVersionNumbers ( out long majorVersion, out long minorVersion); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetVersionNumbers method returns, via its output parameters, the major and minor version numbers of the class specified by receiver.
somLookupMethod Method Purpose Performs name-lookup method resolution. Not generally overridden. IDL Syntax somMethodPtr somLookupMethod (in somId methodId); Note: For backward compatibility, this method does not take an Environment parameter. Description The somLookupMethod method uses name-lookup resolution to return the address of the method procedure that supports the indicated method on instances of the receiver class. The method may be either static or dynamic.
Original Class SOMClass Related Information Methods: somFindSMethod, somFindSMethodOk Methods, somFindMethod, somFindMethodOk Methods 1-100 SOMobjects Base Toolkit: Programmer’s Reference Manual
somNew, somNewNoInit Methods Purpose Creates a new instance of a class. IDL Syntax SOMObject somNew ( ); SOMObject somNewNoInit ( ); Note: For backward compatibility, these methods do not take an Environment parameter. Description The somNew and somNewNoInit methods create a new instance of the receiving class. Space is allocated as necessary to hold the new object. When either of these methods is applied to a class, the result is a new instance of that class.
somRenew, somRenewNoInit, somRenewNoInitNoZero, somRenewNoZero Methods Purpose Creates a new object instance using a passed block of storage. IDL Syntax SOMObject somRenew (in somToken memPtr); SOMObject somRenewNoInit (in somToken memPtr); SOMObject somRenewNoInitNoZero (in somToken memPtr); SOMObject somRenewNoZero (in somToken memPtr); Note: For backward compatibility, these methods do not take an Environment parameter.
Example #include main() { void *myAnimalCluster; Animal animals[5]; SOMClass animalClass; int animalSize, i; animalClass = AnimalNewClass(Animal_MajorVersion,Animal_MinorVersion); animalSize = _somGetInstanceSize (animalClass); /* Round up to double–word multiple */ animalSize = ((animalSize+3)/4)*4; /* * Next line allocates room for 5 objects * in a &odq.cluster” with a single memory* allocation operation.
somSupportsMethod Method Purpose Returns a boolean indicating whether instances of a class support a given (static or dynamic) method. IDL Syntax boolean somSupportsMethod (in somId methodId); Note: For backward compatibility, this method does not take an Environment parameter. Description The somSupportsMethod method determines if instances of the specified class support the specified (static or dynamic) method. Parameters receiver A pointer to the class object to be tested.
SOMClassMgr Class Description One instance of SOMClassMgr is created automatically during SOM initialization. This instance (pointed to by the global variable, SOMClassMgrObject ) acts as a run-time registry for all SOM class objects that exist within the current process and assists in the dynamic loading and unloading of class libraries. You can subclass SOMClassMgr to augment the functionality of its registry.
New Methods Group: Basic Functions somLoadClassFile somLocateClassFile somRegisterClass somUnloadClassFile somUnregisterClass Group: Access somGetInitFunction somGetRelatedClasses Group: Dynamic somClassFromId somFindClass somFindClsInFile somMergeInto somSubstituteClass Overridden Methods somDumpSelf somInit somUninit 1-106 SOMobjects Base Toolkit: Programmer’s Reference Manual
somClassFromId Method Purpose Finds a class object, given its somId, if it already exists. Does not load the class. IDL Syntax SOMClass somClassFromId (in somId classId); Note: For backward compatibility, this method does not take an Environment parameter. Description Finds a class object, given its somId, if it already exists. Does not load the class.
somFindClass Method Purpose Finds the class object for a class. IDL Syntax SOMClass somFindClass ( in somId classId, in long majorVersion, in long minorVersion); Note: For backward compatibility, this method does not take an Environment parameter. Description The somFindClass method returns the class object for the specified class. This method first uses somLocateClassFile (see the following paragraph) to obtain the name of the file where the class’s code resides, then uses somFindClsInFile.
C Example #include /* * * * * */ This program creates a class object (from a DLL) without requiring the usage binding file (.h or .xh) for the class. void main () { SOMClass myClass; somId animalId; somEnvironmentNew (); animalId = somIdFromString (”Animal”); /* The next statement is equivalent to: * #include ”animal.
somFindClsInFile Method Purpose Finds the class object for a class, given a filename that can be used for dynamic loading. IDL Syntax SOMClass somFindClsInFile ( in somId classId, in long majorVersion, in long minorVersion, in string file); Note: For backward compatibility, this method does not take an Environment parameter. Description The somFindClsInFile method returns the class object for the specified class.
C Example #include /* * This program loads a class and creates * an instance of it without requiring the * binding (.h) file for the class. * */ void main() { SOMObject myAnimal; SOMClass animalClass; char *animalName = ”Animal”; /* * Filenames will be different for AIX, OS/2 and Windows * * Set animalfile to ”C:\\MYDLLS\\ANIMAL.DLL” for OS/2 * or Windows. * Set animalfile to ”/mydlls/animal.dll” for AIX. * */ char *animalFile = ”/mydlls/animal.
somGetInitFunction Method Purpose Obtains the name of the function that initializes the SOM classes in a class library. IDL Syntax string somGetInitFunction ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetInitFunction method supplies the name of the initialization function for OS/2 class libraries (DLLs) that contain more than one SOM class.
Original Class SOMClassMgr Related Information Methods: somFindClass, somFindClsInFile Functions: SOMInitModule Macros: SOM_ClassLibrary SOM Kernel Reference 1-113
somGetRelatedClasses Method Purpose Returns an array of class objects that were all registered during the dynamic loading of a class. IDL Syntax SOMClass * somGetRelatedClasses (in SOMClass classObj); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetRelatedClasses method returns an array of class objects that were all registered during the dynamic loading of the specified class. These classes are considered to define an affinity group.
Example #include
somLoadClassFile Method Purpose Dynamically loads a class. IDL Syntax SOMClass somLoadClassFile ( in somId classId, in long majorVersion, in long minorVersion, in string file); Note: For backward compatibility, this method does not take an Environment parameter. Description The SOMClassMgr object uses the somLoadClassFile method to load a class dynamically during the execution of somFindClass or somFindClsInFile.
somLocateClassFile Method Purpose Determines the file that holds a class to be dynamically loaded. IDL Syntax string somLocateClassFile ( in somId classId, in long majorVersion, in long minorVersion); Note: For backward compatibility, this method does not take an Environment parameter. Description The SOMClassMgr object uses the somLocateClassFile method when executing somFindClass to obtain the name of a file to use when dynamically loading a class.
somMergeInto Method Purpose Transfers SOM class registry information to another SOMClassMgr instance. IDL Syntax void somMergeInto (in SOMClassMgr target); Note: For backward compatibility, this method does not take an Environment parameter. Description The somMergeInto method transfers the SOMClassMgr registry information from one object to another. The target object is required to be an instance of SOMClassMgr or one of its subclasses.
C Example /* * The following example is a hypothetical * implementation of an override of the somNew method * in a subclass of SOMClassMgr. It illustrates the * proper use of the somMergeInto method. */ SOM_Scope SOMAny * SOMLINK somNew (MySOMClassMgr somSelf) { SOMAny *newInstance; static int firstTime = 1; /* * Permit only one instance of MySOMClassMgr to be created.
somRegisterClass Method Purpose Adds a class object to the SOM run-time class registry. IDL Syntax void somRegisterClass (in SOMClass classObj); Note: For backward compatibility, this method does not take an Environment parameter. Description The somRegisterClass method adds a class object to the SOM run-time class registry maintained by SOMClassMgrObject. All SOM run-time class objects should be registered with the SOMClassMgrObject.
somSubstituteClass Method Purpose Causes the somFindClass, somFindClsInFile, and somClassFromId methods to substitute one class for another. IDL Syntax long somSubstituteClass ( in string origClassName, in string newClassName); Note: For backward compatibility, this method does not take an Environment parameter.
C Example #include ”student.h” #include ”mystud.h” /* Macro form */ SOM_SubstituteClass (Student, MyStudent); /* Direct use of the method, equivalent to * the macro form above.
somUnloadClassFile Method Purpose Unloads a dynamically loaded class and frees the class’s object. IDL Syntax long somUnloadClassFile (in SOMClass class); Note: For backward compatibility, this method does not take an Environment parameter. Description The somUnregisterClass method uses the somUnloadClassFile method to unload a dynamically loaded class. This releases the class’s code and unregisters all classes in the same affinity group.
somUnregisterClass Method Purpose Removes a class object from the SOM run-time class registry. IDL Syntax long somUnregisterClass (in SOMClass class); Note: For backward compatibility, this method does not take an Environment parameter. Description The somUnregisterClass method unregisters a SOM class and frees the class object. If the class was dynamically loaded, it is also unloaded using somUnloadClassFile (which causes its entire affinity group to be unloaded as well).
Original Class SOMClassMgr Related Information Methods: somLoadClassFile, somRegisterClass, somUnloadClassFile SOM Kernel Reference 1-125
SOMObject Class SOMObject is the root class for all SOM classes. That is, all SOM classes must be subclasses of SOMObject or of some other class derived from SOMObject. SOMObject introduces no instance data, so objects whose classes inherit from SOMObject incur no size increase. They do inherit a suite of methods that provide the behavior required of all SOM objects. Three of these methods are typically overridden by any subclass that has instance data — somDefaultInit, somDestruct, and somDumpSelfInt.
Group: Dynamic somDispatchA somDispatchD somDispatchL somDispatchV somDispatch somClassDispatch somCastObj somResetObj Group: Development Support somDumpSelf somDumpSelfInt somPrintSelf Overridden Methods None SOM Kernel Reference 1-127
somCastObj Method Purpose Changes the behavior of an object to that defined by any ancestor of the true class of the object. IDL Syntax boolean somCastObj (in SOMClass ancestor); Description The somCastObj method changes the behavior of an object so that its behavior will be that of an instance of the indicated ancestor class (with respect to any method supported by the ancestor). The behavior of the object on methods not supported by the ancestor remains unchanged.
Original Class SOMObject Related Information Methods: somResetObj SOM Kernel Reference 1-129
somDefaultInit Method Purpose Initializes instance variables and attributes in a newly created object. Replaces somInit as the preferred method for default object initialization. For performance reasons, it is recommended that somDefaultInit always be overridden by classes. Syntax void somDefaultInit ( inout somInitCtrl ctrl ); Description Every SOM class is expected to support a set of initializer methods.
As mentioned previously, the object-initialization framework supported by SOMobjects allows a class to support additional initializer methods besides somDefaultInit. These additional initializers will typically include special-purpose arguments, so that objects of the class can be initialized with special capabilities or characteristics. For each new initializer method, the implementation section must include the method name with the init modifier.
somDestruct Method Purpose Uninitializes the receiving object, and (if so directed) frees object storage after uninitialization has been completed. Replaces somUninit as the preferred method for uninitializing objects. For performance reasons, it is recommended that somDestruct always be overridden. Not normally invoked directly by object clients. Syntax void somDestruct (in octet dofree, inout somDestructCtrl ctrl); Description Every class must support the somDestruct method.
Parameters receiver A pointer to an object. dofree A boolean indicating whether the caller wants the object storage freed after uninitialization of the current class has been completed. Passing 1 (true) indicates the object storage should be freed. ctrl A pointer to a somDestructCtrl data structure. SOMobjects uses this data structure to control the uninitialization of the ancestor classes, thereby ensuring that no ancestor class receives multiple uninitialization calls.
somDispatch, somClassDispatch Methods Purpose Invokes a method using dispatch method resolution. The somDispatch method is designed to be overridden. The somClassDispatch method is not generally overridden. IDL Syntax boolean somDispatch ( out somToken retValue, in somId methodId, in va_list args); boolean somClassDispatch ( in SOMClass clsObj, out somToken retValue, in somId methodId, in va_list args); Note: For backward compatibility, these methods do not take an Environment parameter.
Parameters receiver A pointer to the object whose class will be used for method resolution by somDispatch. clsObj A pointer to the class that will be used for method resolution by somClassDispatch. retValue The address of the area in memory where the result of the invoked method procedure is to be stored. The caller is responsible for allocating enough memory to hold the result of the specified method.
C Example Given class Key that has an attribute keyval of type long and an overridden method for somPrintSelf that prints the value of the attribute (as well as the information printed by SOMObject’s implementation of somPrintSelf), the following client code invokes methods on Key objects using somDispatch and somClassDispatch. (The Key class was defined with the callstyle=oidl class modifier, so the Environment argument is not required of its methods.) #include
somDispatchX Methods (Obsolete) Purpose Invoke a method using dispatch method resolution. These methods are obsolete.
Return Value Four families of return values are supported, corresponding to the four forms of the somDispatchX method. The somDispatchX method chosen should have a return type compatible with the result of the method identified by methodId. Within each of the four families, only the largest representation is supported. The four families are: Pointer somDispatchA returns an address as a somToken. Floating point somDispatchD returns a floating point number as a double.
somDumpSelf Method Purpose Writes out a detailed description of the receiving object. Intended for use by object clients. Not generally overridden. IDL Syntax void somDumpSelf (in long level); Note: For backward compatibility, this method does not take an Environment parameter. Description The somDumpSelf method performs some initial setup, and then invokes the somDumpSelfInt method to write a detailed description of the receiver, including its state.
somDumpSelfInt Method Purpose Outputs the internal state of an object. Intended to be overridden by class implementors. Not intended to be directly invoked by object clients. IDL Syntax void somDumpSelfInt (in long level); Note: For backward compatibility, this method does not take an Environment parameter. Description The somDumpSelfInt method should be overridden by a class implementor, to write out the instance data stored in an object.
Following is a client program that invokes the somDumpSelf method on “List” objects: #include
somFree Method Purpose Releases the storage used by an object and frees the object. Intended for use by object clients. Not generally overridden. IDL Syntax void somFree ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somFree method releases the storage containing the receiver object by calling the method somDeallocate. No future references should be made to the receiver once this is done.
somGetClass Method Purpose Returns a pointer to an object’s class object. Not generally overridden. IDL Syntax SOMClass somGetClass ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description somGetClass obtains a pointer to the receiver’s class object. The somGetClass method is typically not overridden. Important : For C and C++ programmers, SOM provides a SOM_GetClass macro that performs the same function.
somGetClassName Method Purpose Returns the name of the class of an object. Not generally overridden. IDL Syntax string somGetClassName ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetClassName method returns a pointer to a zero-terminated string that gives the name of the class of an object. This method is not generally overridden; it simply invokes somGetName on the class of the receiver.
somGetSize Method Purpose Returns the size of an object. Not generally overridden. IDL Syntax long somGetSize ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somGetSize method returns the total amount of contiguous space used by the receiving object. The value returned reflects only the amount of storage needed to hold the SOM representation of the object. The object might actually be using or managing additional space outside of this area.
somInit Method Purpose Initializes instance variables or attributes in a newly created object. Designed to be overridden. Note: The newer somDefaultInit method is suggested instead. IDL Syntax void somInit ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somInit method is invoked to cause a newly created object to initialize its instance variables or attributes.
More information and examples on object initialization (especially regarding the somDefaultInit method) are given in the topic “Initializing and Uninitializing Objects” in Chapter 5, “Implementing Classes in SOM,” of the SOM Toolkit User’s Guide. Parameters receiver A pointer to the object to be initialized.
somIsA Method Purpose Tests whether an object is an instance of a given class or of one of its subclasses. Not generally overridden. IDL Syntax boolean somIsA (in SOMClass aClass); Note: For backward compatibility, this method does not take an Environment parameter. Description Use the somIsA method to determine if an object can be treated like an instance of aClass. SOM guarantees that if somIsA returns true, then the receiver will respond to all (static or dynamic) methods supported by aClass.
Original Class SOMObject Related Information Methods: somDescendedFrom, somIsInstanceOf, somRespondsTo, somSupportsMethod SOM Kernel Reference 1-149
somIsInstanceOf Method Purpose Determines whether an object is an instance of a specific class. Not generally overridden. IDL Syntax boolean somIsInstanceOf (in SOMClass aClass); Note: For backward compatibility, this method does not take an Environment parameter. Description Use the somIsInstanceOf method to determine if an object is an instance of a specific class. This method tests an object for inclusion in one specific class.
Original Class SOMObject Related Information Methods: somDescendedFrom, somIsA SOM Kernel Reference 1-151
somPrintSelf Method Purpose Outputs a brief description that identifies the receiving object. Designed to be overridden. IDL Syntax SOMObject somPrintSelf ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description somPrintSelf should output a brief string containing key information useful to identify the receiver object, rather than a complete dump of the receiver object state as provided by somDumpSelfInt.
somResetObj Method Purpose Resets an object’s class to its true class after use of the somCastObj method. Syntax boolean somResetObj ( ); Description The somResetObj method resets an object’s class to its true class after use of the somCastObj method. Parameters receiver A pointer to a SOM object. Return Value The somResetObj method returns 1 (TRUE) always. Example #include
somRespondsTo Method Purpose Tests whether the receiving object supports a given method. Not generally overridden. IDL Syntax boolean somRespondsTo (in somId methodId); Note: For backward compatibility, this method does not take an Environment parameter. Description The somRespondsTo method tests whether a specific (static or dynamic) method can be invoked on the receiver object. This test is equivalent to determining whether the class of the receiver supports the specified method on its instances.
somUninit Method Purpose Un-initializes the receiving object. Designed to be overridden by class implementors. Not normally invoked directly by object clients. IDL Syntax void somUninit ( ); Note: For backward compatibility, this method does not take an Environment parameter. Description The somUninit method performs the inverse of object initialization.
C Example Following is the implementation for a class Animal that introduces an attribute sound of type string and overrides somInit and somUninit, along with a main program that creates and then frees an instance of class Animal: #define Animal_Class_Source #include #include
Chapter 2.
Notes The following information should be considered when using the Distributed SOM (DSOM) framework. DSOM and CORBA Distributed SOM (DSOM) is a framework that supports access to objects in a distributed application. DSOM can be viewed as both: • An extension to basic SOM facilities • An implementation of the “Object Request Broker” (ORB) technology defined by the Object Management Group (OMG), in the Common Object Request Broker Architecture (CORBA) specification and standard, Revision 1.1. The CORBA 1.
get_next_response Function Purpose Returns the next Request object to complete, after starting multiple requests in parallel. C Syntax ORBStatus get_next_response ( Environment* env, Flags response_flags, Request *req ); Description The get_next_response function returns a pointer to the next Request object to complete after starting multiple requests in parallel. This is a synchronization function used in conjunction with the send_multiple_requests function.
ORBfree Function Purpose Frees memory allocated by DSOM for return values and out arguments. C Syntax void ORBfree (void* ptr); Description The ORBfree function is used to free memory for method return values or out arguments which are placed in memory allocated by DSOM (versus the calling program). For example, strings, arrays, sequence buffers, and “any” values are returned in memory which is dynamically allocated by DSOM.
send_multiple_requests Function Purpose Initiates multiple Requests in parallel. C Syntax ORBStatus send_multiple_requests ( Request reqs[ ], Environment* env, long count, Flags invoke_flags ); Description The send_multiple_requests function initiates multiple Requests “in parallel”. (The actual degree of parallelism is system dependent.) Each Request object is created using the create_request method, defined on SOMDClientProxy.
Example #include
somdExceptionFree Function Purpose Frees the memory held by the exception structure within an Environment structure, regardless of whether the exception was returned by a local or a remote method call. C Syntax void somdExceptionFree (Environment *ev); Description The somdExceptionFree function frees the memory held by the exception structure within an Environment structure, regardless of whether the exception was returned by a local or a remote method call.
SOMD_Init Function Purpose Initializes DSOM in the calling process. C Syntax void SOMD_Init (Environment* env); Description Initializes DSOM in the calling process. This function should be called before any other DSOM functions or methods. This function should only be invoked (a) at the beginning of a DSOM program (client or server), to initialize the program, or (b) after SOMD_Uninit has been invoked, to reinitialize the program.
SOMD_NoORBfree Function Purpose Specifies to DSOM that the client program will use the SOMFree function to free memory allocated by DSOM, rather than using the ORBfree function. C Syntax void SOMD_NoORBfree (); Description The SOMD_NoORBfree function is used in a DSOM client program to specify to DSOM that the client program will use the SOMFree function to free memory allocated by DSOM, rather than using the ORBfree function.
SOMD_RegisterCallback Function Purpose Registers a callback function for handling DSOM request events. C Syntax void SOMLINK SOMD_RegisterCallback (SOMEEMan emanObj, EMRegProc *func); Description When writing event-driven applications where there are event sources other than DSOM requests (for example, user input, mouse clicks, and so forth), DSOM cannot be given exclusive control of the “main loop,” such as when execute_request_loop is called.
Example #include #include #ifdef __OS2__ #pragma linkage(SOMD_RegisterCallback, system) #pragma linkage(DSOMEventCallBack, system) #endif /* On Windows, this example would omit the SOMLINK keyword. */ void SOMLINK DSOMEventCallBack (SOMEEvent event, void *eventData) { Environment ev; SOM_InitEnvironment(&ev); _execute_request_loop (SOMD_SOMOAObject, &ev, SOMD_NO_WAIT); } main() { ...
SOMD_Uninit Function Purpose Free system resources allocated for use by DSOM. C Syntax void SOMD_Uninit (Environment* env); Description Frees system resources (such as, shared memory segments, semaphores) allocated to the calling process for use by DSOM. This function should be called before a process exits, to ensure system resources are reused. No DSOM functions or methods should be called after SOMD_Uninit has been called.
Context_delete Macro Purpose Deletes a Context object. Syntax ORBStatus Context_delete ( Context ctxobj, Environment *env, Flags del_flag); Description The Context_delete macro deletes the specified Context object. This macro maps to the destroy method of the Context class. Parameters ctxobj A pointer to the Context object to be deleted. env A pointer to the Environment structure for the caller. del_flag A bitmask (unsigned long).
Request_delete Macro Purpose Deletes the memory allocated by the ORB for a Request object. Syntax ORBStatus Request_delete ( Request reqobj, Environment *env); Description The Request_delete macro deletes the specified Request object and all associated memory. This macro maps to the destroy method of the Request class. Parameters reqobj A pointer to the Request object to be deleted. env A pointer to the Environment structure for the caller.
Example #include #include #include #include /* provided by user */ /* assume following method declaration in interface Foo: * long methodLong (in long inLong,inout long inoutLong); * then the following code sends a request to execute the call: * result = methodLong(fooObj, &ev, 100,200); * using the DII without waiting for the result. Then, later, * waits for and then uses the result.
BOA Class Description The Basic Object Adapter (BOA) defines the basic interfaces that a server process uses to access services of an Object Request Broker like DSOM. The BOA defines methods for creating and exporting object references, registering implementations, activating implementations and authenticating requests. For more information on the Basic Object Adapter, refer to Chapter 9 in the CORBA 1.1 specification.
change_implementation Method Purpose Changes the implementation associated with the referenced object. (Not implemented.) IDL Syntax void change_implementation ( in SOMDObject obj, in ImplementationDef impl); Description The change_implementation method is defined by the CORBA specification, but has a null implementation in DSOM. This method always returns a NO_IMPLEMENT exception. In CORBA 1.
create Method Purpose Creates a “reference” for a local application object which can be exported to remote clients. IDL Syntax typedef sequence ReferenceData; // in somdtype.idl SOMDObject create ( in ReferenceData id, in InterfaceDef intf, in ImplementationDef impl); Description The create method creates a SOMDObject which is used as a “reference” to a local application object.
Return Value The create method returns a pointer to a SOMDObject which refers to a local application object. Example #include #include #include Environment ev; ReferenceData id; InterfaceDef intfdef; SOMDObject objref; string fname; /* a file name to be saved with reference */ ... /* create the id for the reference */ id._maximum = id._length = strlen(fname)+1; id._buffer = (string) SOMMalloc(strlen(fname)+1); strcpy(id.
deactivate_impl Method Purpose Indicates that a server implementation is no longer ready to process requests. IDL Syntax void deactivate_impl ( in ImplementationDef impl); Description The deactivate_impl method indicates that the implementation is no longer ready to process requests. Parameters receiver A pointer to a BOA (SOMOA) object for the server. env A pointer to the Environment structure for the method caller.
deactivate_obj Method Purpose Indicates that an object server is no longer ready to process requests. (Not implemented.) IDL Syntax void deactivate_obj ( in SOMDObject obj); Description The deactivate_obj method is defined by the CORBA specification, but has a null implementation in DSOM. This method always returns a NO_IMPLEMENT exception. CORBA 1.1 distinguishes between servers that implement many objects (“shared”), versus servers that implement a single object (“unshared”).
dispose Method Purpose Destroys an object reference. IDL Syntax void dispose ( in SOMDObject obj); Description The dispose method disposes of an object reference. Parameters receiver A pointer to a BOA object for the server. env A pointer to the Environment structure for the method caller. obj A pointer to the object reference to be destroyed. Example #include #include #include SOMDObject objref; ReferenceData id; InterfaceDef intfdef; ...
get_id Method Purpose Returns reference data associated with the referenced object. IDL Syntax ReferenceData get_id ( in SOMDObject obj); Description The get_id method returns the reference data associated with the referenced object. Parameters receiver A pointer to a BOA (SOMOA) object for the server. env A pointer to the Environment structure for the method caller. obj A pointer to a SOMDObject object for which to return the ReferenceData.
get_principal Method Purpose Returns the ID of the principal that issued the request. IDL Syntax Principal get_principal ( in SOMDObject obj, in Environment* req_ev); Description The get_principal method returns the ID of the principal that issued a request. Parameters receiver A pointer to a BOA (SOMOA) object for the server. env A pointer to the Environment structure for the method caller. obj A pointer to the object reference which is the target of the method call.
impl_is_ready Method Purpose Indicates that the implementation is ready to process requests. IDL Syntax void impl_is_ready ( in ImplementationDef impl); Description The impl_is_ready method Indicates that the implementation is ready to process requests. Parameters receiver A pointer to a BOA (SOMOA) object for the server. env A pointer to the Environment structure for the method caller. impl A pointer to the ImplementationDef object indicating which implementation is ready. Example #include
obj_is_ready Method Purpose Indicates that an object (server) is ready to process requests. (Not implemented.) IDL Syntax void obj_is_ready ( in SOMDObject obj, in ImplementationDef impl); Description The obj_is_ready method is defined by the CORBA specification, but has a null implementation in DSOM. This method always returns a NO_IMPLEMENT exception. CORBA 1.1 distinguishes between servers that implement many objects (“shared”), versus servers that implement a single object (“unshared”).
set_exception Method Purpose Returns an exception to a client. IDL Syntax void set_exception ( in exception_type major, in string except_name, in void* param); Description The set_exception method returns an exception to the client. The major parameter can have one of three possible values: NO_EXCEPTION — indicates a normal outcome of the operation. It is not necessary to invoke set_exception to indicate a normal outcome; it is the default behavior if the method simply returns.
Context Class Description The Context class implements the CORBA Context object described in section 6.5 beginning on page 116 of CORBA 1.1. A Context object contains a list of properties, each consisting of a name and a string value associated with that name. Context objects are created/accessed by the get_default_context method defined in the ORB object.
create_child Method Purpose Creates a child of a Context object. IDL Syntax ORBStatus create_child ( in Identifier ctx_name, out Context child_ctx); Description The create_child method creates a child Context object. The returned Context object is chained to its parent. That is, searches on the child Context object will look in the parent (and so on, up the Context tree), if necessary, for matching property names. Parameters receiver A pointer to the Context object for which a child is to be created.
delete_values Method Purpose Deletes property value(s). IDL Syntax ORBStatus delete_values ( in Identifier prop_name); Description The delete_values method deletes the specified property value(s) from a Context object. If prop_name has a trailing wildcard character(“*”), then all property names that match will be deleted. Search scope is always limited to the specified Context object. If no matching property is found, an exception is returned.
destroy Method (for a Context object) Purpose Deletes a Context object. IDL Syntax ORBStatus destroy ( in Flags del_flag); Description The destroy method deletes the specified Context object. NOTE: This method is called “delete” in the CORBA 1.1 specification. However, the word “delete” is a reserved operator in C++, so the name “destroy” was chosen as an alternative. For CORBA compatibility, a macro defining Context_delete as an alias for destroy has been included in the C header files.
get_values Method Purpose Retrieves the specified property values. IDL Syntax ORBStatus get_values ( in Identifier start_scope, in Flags op_flags, in Identifier prop_name, out NVList values); Description The get_values method retrieves the specified Context property values(s). If prop_name has a trailing wildcard character(“*”), then all matching properties and their values are returned. OWNERSHIP of the returned NVList object is transferred to the caller.
Example #include Environment ev; Context cxt1, cxt2; string *cxt1props; long rc, i, numprops; NVList nvp; ...
set_one_value Method Purpose Adds a single property to the specified Context object. IDL Syntax ORBStatus set_one_value ( in Identifier prop_name, in string value); Description The set_one_value method adds a single property to the specified Context object. Parameters receiver A pointer to the Context object to which the value is to be added. env A pointer to the Environment structure for the method caller. prop_name The name of the property to be added. The prop_name should not end in an asterisk.
set_values Method Purpose Adds/changes one or more property values in the specified Context object. IDL Syntax ORBStatus set_values ( in NVList values); Description The set_values method sets one or more property values in the specified Context object. In the NVList, the flags field must be set to zero, and the TypeCode field associated with an attribute value must be TC_string. Parameters receiver A pointer to the Context object for which the properties are to be set.
ImplementationDef Class Description The ImplementationDef class defines attributes necessary for the DSOM daemon to find and activate the implementation of an object. Note: Details of the ImplementationDef object are not currently defined in the CORBA 1.1 specification; the attributes which have been defined are required by DSOM.
impl_refdata_file (string) Contains the full pathname of the file used to store ReferenceData for the server. impl_refdata_bkup (string) Contains the full pathname of the backup mirror file used to store ReferenceData for the server. impl_hostname (string) Contains the hostname of the machine where the server is located. Notes Currently, when stored in the Implementation Repository, file names used in ImplementationDefs are limited to 255 bytes.
ImplRepository Class Description The ImplRepository class defines operations necessary to query and update the DSOM Implementation Repository. Note: The Implementation Repository is described in concept in the CORBA 1.1 specification, but no standard interfaces have been defined. These interfaces have all been introduced by DSOM. In addition to using the following interfaces, the DSOM Implementation Repository can be queried and updated using the regimpl tool.
add_class_to_impldef Method Purpose Associates a class with a server. IDL Syntax void add_class_to_impldef ( in ImplId implid, in string classname ); Description Associates a class, identified by name, with a server, identified by its ImplId. This type of association is used to lookup server implementations via the find_impldef_by_class method. Parameters receiver A pointer to the ImplRepository object. env A pointer to the Environment structure for the method caller.
add_impldef Method Purpose Adds an implementation definition to the Implementation Repository. IDL Syntax void add_impldef ( in ImplementationDef impldef); Description Adds the specified ImplementationDef object to the Implementation Repository. Note: the impl_id field of the ImplementationDef is ignored. A new impl_id value will be created for the newly added ImplementationDef. Parameters receiver A pointer to the ImplRepository object.
delete_impldef Method Purpose Deletes an implementation definition from the Implementation Repository. IDL Syntax void delete_impldef ( in ImplId implid ); Description Deletes the specified ImplementationDef object from the Implementation Repository. Parameters receiver A pointer to the ImplRepository object. env A pointer to the Environment structure for the method caller. implid The ImplId that identifies the server implementation of interest.
find_all_impldefs Method Purpose Returns all the implementation definitions in the Implementation Repository. Syntax ORBStatus find_all_impldefs (out sequence outimpldefs); Description The find_all_impldefs method searches the Implementation Repository and returns all the ImplementationDef objects in it. Parameters receiver A pointer to an object of class ImplRepository. ev A pointer to the Environment structure for the calling method.
find_classes_by_impldef Method Purpose Returns a sequence of class names associated with a server. IDL Syntax sequence find_classes_by_impldef ( in ImplId implid ); Description The find_classes_by_impldef method searches the class index and returns the sequence of class names supported by a server with the specified implid. Parameters receiver A pointer to the ImplRepository object. env A pointer to the Environment structure for the method caller.
find_impldef Method Purpose Returns a server implementation definition given its ID. IDL Syntax ImplementationDef find_impldef ( in ImplId implid); Description Finds and returns the ImplementationDef object whose ID is implid. Parameters receiver A pointer to the ImplRepository object. env A pointer to the Environment structure for the method caller. implid The ImplId of the desired ImplementationDef. Return Value A copy of the desired ImplementationDef object is returned.
find_impldef_by_alias Method Purpose Returns a server implementation definition, given its user-friendly alias. IDL Syntax ImplementationDef find_impldef_by_alias ( in string alias_name); Description Finds and returns the ImplementationDef object whose alias is alias_name. Parameters receiver A pointer to the ImplRepository object. env A pointer to the Environment structure for the method caller. alias_name User-friendly name used to identify the implementation.
find_impldef_by_class Method Purpose Returns a sequence of implementation definitions for servers that are associated with a specified class. IDL Syntax sequence find_impldef_by_class ( in string classname); Description Returns a sequence of ImplementationDefs for those servers that have registered an association with a specified class. Typically, a server will be associated with the classes it knows how to implement by registering its known classes via the add_class_to_impldef method.
remove_class_from_all Method Purpose Removes the association of a particular class from all servers. Syntax void remove_class_from_all (in string className); Description The remove_class_from_all method removes the className from all of the ImplementationDefs. Parameters receiver A pointer to an object of class ImplRepository. ev A pointer to the Environment structure for the calling method. className A string whose value is the class name of interest. Example #include Environment ev; ...
remove_class_from_impldef Method Purpose Removes the association of a particular class with a server. IDL Syntax void remove_class_from_impldef ( in ImplId implid, in string classname ); Description Removes the specified class name from the set of class names associated with the server implementation identified by implid. Parameters receiver A pointer to the ImplRepository object. env A pointer to the Environment structure for the method caller. implid A pointer to an ImplRepository object.
update_impldef Method Purpose Updates an implementation definition in the Implementation Repository. IDL Syntax void update_impldef ( in ImplementationDef impldef); Description Replaces the state of the specified ImplementationDef object in the Implementation Repository. The ID of the impldef determines which object gets updated in the Implementation Repository. Parameters receiver A pointer to the ImplRepository object. env A pointer to the Environment structure for the method caller.
NVList Class Description The type NamedValue is a standard datatype defined in CORBA (see the CORBA 1.1 page 106). It can be used either as a parameter type or as a mechanism for describing arguments to a request. The NVList class implements the NVList object used for constructing lists composed of NamedValues. NVLists can be used to describe arguments passed to request operations or to pass lists of property names and values to context object routines.
add_item Method Purpose Adds an item to the specified NVList. IDL Syntax ORBStatus add_item ( in Identifier item_name, in TypeCode item_type, in void* value, in long value_len, in Flags item_flags); Description The add_item method adds an item to the end of the specified list. Parameters receiver A pointer to the NVList object to which the item will be added. env A pointer to the Environment structure for the method caller. item_name The name of the item to be added.
Original Class NVList Related Information Methods: free, free_memory, get_count, get_item, set_item, create_list 2-52 SOMobjects Base Toolkit: Programmer’s Reference Manual
free Method Purpose Frees a specified NVList. IDL Syntax ORBStatus free ( ); Description The free method frees an NVList object and any associated memory. It makes an implicit call to the free_memory method. Parameters receiver A pointer to the NVList object to be freed. env A pointer to the Environment structure for the method caller. Return Value The method returns an ORBStatus value representing the return code from the operation. Example #include
free_memory Method Purpose Frees any dynamically allocated out-arg memory associated with the specified list. IDL Syntax ORBStatus free_memory ( ); Description The free_memory method frees any dynamically allocated out-arg memory associated with the specified list, without freeing the list object itself. This would be useful when invoking a DII request multiple times with the same NVList. Parameters receiver A pointer to the NVList object whose out-arg memory is to be freed.
Original Class NVList Related Information Methods: free Functions: ORBfree DSOM Framework Reference 2-55
get_count Method Purpose Returns the total number of items allocated for a list. IDL Syntax ORBStatus get_count ( out long count); Description The get_count method returns the total number of allocated items in the specified list. Parameters receiver A pointer to the NVList object on which count is desired. env A pointer to the Environment structure for the method caller. count A pointer to where the method will store the long integer count value.
get_item Method Purpose Returns the contents of a specified list item. IDL Syntax ORBStatus get_item ( in long item_number, out Identifier item_name, out TypeCode item_type, out void* value, out long value_len, out Flags item_flags); Description The get_item method gets an item from the specified list. Items are numbered from 0 through N. The mode flags can be one of the following values: The get_item method transfers ownership of storage allocated for the item value to the caller.
Example #include Environment ev; long i, nArgs; ORBStatus rc; Identifier name; TypeCode typeCode; void *value; long len; Flags flags; NVList argList; ... /* get number of args */ rc = _get_count(argList, ev, &nArgs); for (i = 0; i < nArgs; i++) { /* get item description */ rc = _get_item(argList, &ev, i, &name, &typeCode, &value, &len, &flags); ...
set_item Method Purpose Sets the contents of an item in a list. IDL Syntax ORBStatus set_item ( in long item_number, in Identifier item_name, in TypeCode item_type, in void* value, in long value_len, in Flags item_flags); Description The set_item method sets the contents of an item in the list. Parameters receiver A pointer to an NVList which contains the item to be set. env A pointer to the Environment structure for the method caller. item_number The position (index) of the item in the list.
Example #include Environment ev; long i, nArgs; ORBStatus rc; Identifier name; TypeCode typeCode; void *value; long len; Flags flags; NVList argList; ... /* get number of args */ rc = _get_count(argList, ev, &nArgs); for (i = 0; i < nArgs; i++) { /* change item description */ rc = _set_item(argList, &ev, i, name, typeCode, value, len, flags); ...
ObjectMgr Class Description The ObjectMgr class provides a uniform, universal abstraction for any sort of object manager. Object Request Brokers, persistent storage managers, and OODBMSs are examples of object managers. This is an abstract base class, which defines the “core” interface for an object manager.
somdDestroyObject Method Purpose Requests destruction of the target object. IDL Syntax void somdDestroyObject ( in SOMObject obj); Description The somdDestroyObject method indicates that the object manager should destroy the specified object. Storage associated with the object is freed. In DSOM, the SOMDObjectMgr forwards the deletion request to the remote server, and then frees the local proxy object. Parameters receiver A pointer to an ObjectMgr object.
somdGetIdFromObject Method Purpose Returns an ID for an object managed by a specified Object Manager. IDL Syntax string somdGetIdFromObject ( in SOMObject obj); Description The somdGetIdFromObject method returns the persistent ID for an object managed by the specified Object Manager. This ID is unambiguous — it always refers to the same object. The somdGetIdFromObject method transfers ownership of storage allocated for the string to the caller. Parameters receiver A pointer to an ObjectMgr object.
somdGetObjectFromId Method Purpose Finds and activates an object implemented by a specified object manager, given its ID. IDL Syntax SOMObject somdGetObjectFromId ( in string id); Description The somdGetObjectFromId method finds and activates an object implemented by this object manager, given its ID. The somdGetObjectFromId method transfers ownership to the caller. Parameters receiver A pointer to an ObjectMgr object. env A pointer to the Environment structure for the method caller.
somdNewObject Method Purpose Returns a new object of the named class. IDL Syntax SOMObject somdNewObject ( in Identifier objclass, in string hints); Description The somdNewObject method returns a new object of the class specified by objclass. Application-specific creation options can be supplied via the hints parameter. In DSOM, the SOMDObjectMgr selects a random server which has advertised knowledge of the desired class objclass, and forwards the creation request to that server.
somdReleaseObject Method Purpose Indicates that the client has finished using the object. IDL Syntax void somdReleaseObject ( in SOMObject obj); Description The somdReleaseObject method indicates that the client has finished using the specified object. This allows the object manager to free the bookkeeping information associated with the object, if any. The object may also be passivated, but it is not destroyed.
ORB Class Description The ORB class implements the CORBA ORB object described in Chapter 8 of the CORBA 1.1 specification. The ORB class defines operations for converting object references to strings and converting strings to object references. The ORB also defines operations used by the Dynamic Invocation Interface for creating lists (NVlists) and determining the default context.
create_list Method Purpose Creates an NVList of the specified size. IDL Syntax ORBStatus create_list ( in long count, out NVList new_list); Description Creates an NVList list of the specified size, typically for use in Requests. Ownership of the allocated new_list is transferred to the caller. Parameters receiver A pointer to the ORB object. env A pointer to the Environment structure for the method caller. count An integer representing the number of elements to allocate for the list.
create_operation_list Method Purpose Creates an NVList initialized with the argument descriptions for a given operation. IDL Syntax ORBStatus create_operation_list ( in OperationDef oper, out NVList new_list); Description Creates an NVList list for the specified operation, for use in Requests invoking that operation. Parameters receiver A pointer to the ORB object. env A pointer to the Environment structure for the method caller.
get_default_context Method Purpose Returns the default process Context object. IDL Syntax ORBStatus get_default_context ( out Context ctx); Description The get_default_context method gets the default process Context object. Ownership of the allocated Context object is transferred to the caller. Parameters receiver A pointer to the ORB object. env A pointer to the Environment structure for the method caller. ctx A pointer to where the method will store a pointer to the returned Context object.
object_to_string Method Purpose Converts an object reference to an external form (string) which can be stored outside the ORB. IDL Syntax string object_to_string ( in SOMDObject obj); Description The object_to_string method converts the object reference to a form (string) which can be stored externally. Ownership of allocated memory is transferred to the caller. Parameters receiver A pointer to the ORB object. env A pointer to the Environment structure for the method caller.
string_to_object Method Purpose Converts an externalized (string) form of an object reference into an object reference. IDL Syntax SOMDObject string_to_object ( in string str); Description The string_to_object method converts the externalized (string) form of an object reference into an object reference. Parameters receiver A pointer to the ORB object. env A pointer to the Environment structure for the method caller.
Principal Class Description The Principal class defines attributes which identify the user id and host name of the originator of a specific request. This information is typically used for access control. A Principal object is returned by the get_principal method of the SOM Object Adapter. The parameters of the get_principal method identify the environment and target object associated with a particular request — the SOMOA uses this information to create a Principal object which identifies the caller.
Request Class Description The Request class implements the CORBA Request object described in section 6.2 on page 108 of CORBA 1.1. The Request object is used by the dynamic invocation interface to dynamically create and issue a request to a remote object. Request objects are created by the create_request method in SOMDObject.
add_arg Method Purpose Incrementally adds an argument to a Request object. IDL Syntax ORBStatus add_arg ( in Identifier name, in TypeCode arg_type, in void* value, in long len, in Flags arg_flags); Description The add_arg method incrementally adds an argument to a Request object. The Request object must have been created using the create_request method with an empty argument list. Parameters receiver A pointer to a Request object. env A pointer to the Environment structure for the method caller.
Return Value The add_arg method returns an ORBStatus value representing the return code of the operation. Example #include #include #include #include /* provided by user */ /* assume following method declaration in interface Foo: * long methodLong (in long inLong,inout long inoutLong); * then the following code builds a request to execute the call: * result = methodLong(fooObj, &ev, 100,200); *using the DII.
destroy Method (for a Request object) Purpose Deletes the memory allocated by the ORB for a Request object. IDL Syntax ORBStatus destroy ( ); Description The destroy method deletes the Request object and all associated memory. Note: This method is called “delete” in the CORBA 1.1 specification. However, the word “delete” is a reserved operator in C++, so the name “destroy” was chosen as an alternative.
Example #include #include #include #include /* provided by user */ /* assume following method declaration in interface Foo: * long methodLong (in long inLong,inout long inoutLong); * then the following code sends a request to execute the call: * result = methodLong(fooObj, &ev, 100,200); * using the DII without waiting for the result. Then, later, * waits for and then uses the result.
get_response Method Purpose Determines whether an asynchronous Request has completed. IDL Syntax ORBStatus get_response ( in Flags response_flags); Description The get_response method determines whether the asynchronous Request has completed. Parameters receiver A pointer to a Request object. env A pointer to the Environment structure for the method caller. response_flags A Flags bitmask (unsigned long) containing control information for the get_response method.
Example #include #include #include #include /* provided by user */ /* assume following method declaration in interface Foo: * long methodLong (in long inLong,inout long inoutLong); * then the following code sends a request to execute the call: * result = methodLong(fooObj, &ev, 100,200); * using the DII without waiting for the result. Then, later, * waits for and then uses the result.
invoke Method Purpose Invokes a Request synchronously, waiting for the response. IDL Syntax ORBStatus invoke ( in Flags invoke_flags); Description The invoke method sends a Request synchronously, waiting for the response. Parameters receiver A pointer to a Request object. env A pointer to the Environment structure for the method caller. invoke_flags A Flags bitmask (unsigned long) representing control information for the invoke method. There are currently no flags defined for the invoke method.
/* Get the OperationDef from the Interface Repository. */ opdef = _lookup_id(SOM_InterfaceRepository, &ev, ”Foo::methodLong”); /* Create a NamedValue list for the operation.
send Method Purpose Invokes a Request asynchronously. IDL Syntax ORBStatus send ( in Flags invoke_flags); Description The send method invokes the Request asynchronously. The response must eventually be checked by invoking either the get_response method or the get_next_response function. Parameters receiver A pointer to a Request object. env A pointer to the Environment structure for the method caller. invoke_flags A Flags bitmask (unsigned long) containing send method control information.
Example #include #include #include #include /* provided by user */ /* assume following method declaration in interface Foo: * long methodLong (in long inLong,inout long inoutLong); * then the following code sends * a request to execute the call: * result = methodLong(fooObj, &ev, 100,200); * using the DII.
SOMDClientProxy Class Description The SOMDClientProxy class implements DSOM proxy objects in Clients. SOMDClientProxy overrides the usual somDispatch methods with versions that build a DSOM Request for remote invocation and dispatch it to the remote object. It is intended that the implementation of this “generic” proxy class will be used to derive specific proxy classes via multiple inheritance.
Overridden methods create_request create_request_args is_proxy release somDispatch somDispatchA, somDispatchD, somDispatchL, somDispatchV somFree somGetClass somGetClassName somInit somUninit 2-86 SOMobjects Base Toolkit: Programmer’s Reference Manual
somdProxyFree Method Purpose Executes somFree on the local proxy object. IDL Syntax void somdProxyFree ( ); Description The somdProxyFree method executes the somFree method call on the local proxy object. This method has been provided when the application program wants to be explicit about freeing the proxy object vs. the target object. Parameters receiver A pointer to the SOMDClientProxy object. env A pointer to the Environment structure for the method caller.
somdProxyGetClass Method Purpose Returns the class object for the local proxy object. IDL Syntax SOMClass somdProxyGetClass ( ); Description The somdProxyGetClass method executes the somGetClass method call on the local proxy object and returns a pointer to the proxy’s class object. This method has been provided when the application program wants to be explicit about getting the class object for the proxy object vs. the target object. Parameters receiver A pointer to the SOMDClientProxy object.
somdProxyGetClassName Method Purpose Returns the class name for the local proxy object. IDL Syntax string somdProxyGetClassName ( ); Description The somdProxyGetClassName method executes the somGetClassName method call on the local proxy object and returns the proxy’s class name. This method has been provided when the application program wants to be explicit about getting the class name of the proxy object vs. the target object.
somdReleaseResources Method Purpose Instructs a proxy object to release any memory it is holding as a result of a remote method invocation in which a parameter or result was designated as “object-owned”. IDL Syntax void somdReleaseResources (); Description The somdReleaseResources method instructs a proxy object to release any memory it is holding as a result of a remote method invocation in which a parameter or result was designated as “object-owned”.
Original Class SOMDClientProxy Related Information Methods: release DSOM Framework Reference 2-91
somdTargetFree Method Purpose Forwards the somFree method call to the remote target object. IDL Syntax void somdTargetFree ( ); Description The somdTargetFree method forwards the somFree method call to the remote target object. This method has been provided when the application program wants to be explicit about freeing the remote target object vs. the proxy object. Parameters receiver A pointer to the SOMDClientProxy object for the desired remote target object.
somdTargetGetClass Method Purpose Returns (a proxy for) the class object for the remote target object. IDL Syntax SOMClass somdTargetGetClass ( ); Description The somdTargetGetClass method forwards the somGetClass method call to the remote target object and returns a pointer to the class object for that object. This method has been provided when the application program wants to be explicit about getting the class object for the remote target object vs. the local proxy.
somdTargetGetClassName Method Purpose Returns the class name for the remote target object. IDL Syntax string somdTargetGetClassName ( ); Description The somdTargetGetClassName method forwards the somGetClassName method call to the remote target object and returns the class name for that object. This method has been provided when the application program wants to be explicit about getting the class name of the remote target object vs. the proxy object.
SOMDObject Class Description The SOMDObject class implements the methods that can be applied to all CORBA object references: for example, get_implementation, get_interface, is_nil, duplicate, and release. (In the CORBA 1.1 specification, these methods are described in Chapter 8.) In DSOM, there is also another derivation of this class: SOMDClientProxy.
create_request Method Purpose Creates a request to execute a particular operation on the referenced object. IDL Syntax ORBStatus create_request ( in Context ctx, in Identifier operation, in NVList arg_list, inout NamedValue result, out Request request, in Flags req_flags); Description The create_request method creates a request to execute a particular operation on the referenced object. (For more information on the create_request call, see CORBA 1.1 page 109.
Example #include #include #include #include /* provided by user */ /* assume following method declaration in interface Foo: * long methodLong (in long inLong,inout long inoutLong); * then the following code builds a request to execute the call: * result = methodLong(fooObj, &ev, 100,200); *using the DII.
create_request_args Method Purpose Creates an argument list appropriate for the specified operation. IDL Syntax ORBStatus create_request_args ( in Identifier operation, out NVList arg_list. out NamedValue result); Description The create_request_args method creates the appropriate arg_list (NVList) for the specified operation. It is similar in function to the create_operation_list method. Its value is that it also creates the result structure whereas create_operation_list does not.
Example #include #include #include #include /* provided by user */ /* assume following method declaration in interface Foo: * long methodLong (in long inLong,inout long inoutLong); * then the following code builds a request to execute the call: * result = methodLong(fooObj, &ev, 100,200); * using the DII.
duplicate Method Purpose Makes a duplicate of an object reference. IDL Syntax SOMDObject duplicate ( ); Description The duplicate method makes a duplicate of the object reference. The release method should be called to free the object. Parameters receiver A pointer to a SOMDObject object. env A pointer to the Environment structure for the method caller. Return Value The duplicate method returns a SOMDObject that is a duplicate of the receiver.
get_implementation Method Purpose Returns the implementation definition for the referenced object. IDL Syntax ImplementationDef get_implementation ( ); Description The get_implementation method returns the implementation definition object for the referenced object. Parameters receiver A pointer to a SOMDObject object. env A pointer to the Environment structure for the method caller. Return Value The get_implementation method returns the ImplementationDef object for the receiver.
get_interface Method Purpose Returns the interface definition object for the referenced object. IDL Syntax InterfaceDef get_interface ( ); Description The get_interface method returns the interface definition object for the referenced object. Parameters receiver A pointer to a SOMDObject object. env A pointer to the Environment structure for the method caller. Return Value The get_interface method returns a pointer to the InterfaceDef object associated with the reference receiver.
is_constant Method Purpose Tests to see if the object reference is a constant (that is, its ReferenceData is a constant value associated with the reference). IDL Syntax boolean is_constant ( ); Description The is_constant method tests to see if the object reference was created using the create_constant method in the SOMOA class. Parameters receiver A pointer to a SOMDObject object. env A pointer to the Environment structure for the method caller.
is_nil Method Purpose Tests to see if the object reference is nil. IDL Syntax boolean is_nil ( ); Description The is_nil method tests to see if the specified object reference is nil. Parameters receiver A pointer to any object, either a SOMObject or a SOMDObject. The pointer can be NULL. env A pointer to the Environment structure for the method caller. Return Value The is_nil method returns TRUE if the object reference is empty. Otherwise, is_nil returns FALSE. Example #include
is_proxy Method Purpose Tests to see if the object reference is a proxy. IDL Syntax boolean is_proxy( ); Description The is_proxy method tests to see if the specified object reference is a proxy object. Parameters receiver A pointer to a SOMDObject object. env A pointer to the Environment structure for the method caller. Return Value The is_proxy method returns TRUE if the object reference is a proxy object. Otherwise, is_proxy returns FALSE. Example #include
is_SOM_ref Method Purpose Tests to see if the object reference is a simple reference to a SOM object. IDL Syntax boolean is_SOM_ref ( ); Description The is_SOM_ref method tests to see if the specified object reference is a simple (transient) reference to a SOM object. Parameters receiver A pointer to a SOMDObject object. env A pointer to the Environment structure for the method caller.
release Method Purpose Releases the memory associated with the specified object reference. IDL Syntax void release ( ); Description The release method releases the memory associated with the object reference. Parameters receiver A pointer to a SOMDObject object. env A pointer to the Environment structure for the method caller. Example #include SOMDObject objref; Environment ev; SOMObject obj; ... objref = _create_SOM_ref(SOMD_SOMOAObject, &ev, obj); ...
SOMDObjectMgr Class Description The SOMDObjectMgr class is derived from ObjectMgr class and provides the DSOM implementations for the ObjectMgr methods.
somdFindAnyServerByClass Method Purpose Finds a server capable of creating the specified object. IDL Syntax SOMDServer somdFindAnyServerByClass ( in Identifier objclass); Description The somdFindAnyServerByClass method finds a server capable of creating an object of the specified type with the specified properties. Parameters receiver A pointer to a SOMDObjectMgr object. env A pointer to the Environment structure for the method caller.
somdFindServer Method Purpose Finds a server given its ImplementationDef ID. IDL Syntax SOMDServer somdFindServer ( in ImplId serverid); Description The somdFindServer method finds a server capable of creating an object of the specified type with the specified properties. Parameters receiver A pointer to a SOMDObjectMgr object. env A pointer to the Environment structure for the method caller. serverid An ImplId string which identifies the ImplementationDef of the desired server.
somdFindServerByName Method Purpose Finds a server given its ImplementationDef name (alias). IDL Syntax SOMDServer somdFindServerByName ( in string servername); Description The somdFindServerByName method finds a server with the specified name. Parameters receiver A pointer to a SOMDObjectMgr object. env A pointer to the Environment structure for the method caller. servername An string which specifies the name of the ImplementationDef of the desired server.
somdFindServersByClass Method Purpose Finds all servers capable of creating a particular object. IDL Syntax sequence somdFindServersByClass ( in Identifier objclass); Description The somdFindServersByClass method finds all servers capable of creating a particular object with the specified properties. Parameters receiver A pointer to a SOMDObjectMgr object. env A pointer to the Environment structure for the method caller.
SOMDServer Class Description The SOMDServer class is a base class that defines and implements methods for managing objects in a DSOM server process. This includes methods for the creation and deletion of SOM objects, and for getting the SOM class object for a specified class. The SOMDServer class also defines and implements methods for the mapping between object references (SOMDObjects) and SOM objects, and dispatching methods on objects.
somdCreateObj Method Purpose Creates an object of the specified class. IDL Syntax SOMObject somdCreateObj ( in Identifier objclass, in string hints); Description The somdCreateObj method creates an object of the specified class. Parameters receiver A pointer to a SOMDServer object capable of creating an instance of the specified class. env A pointer to the Environment structure for the method caller. objclass The class of the object for which an instance is to be created.
somdDeleteObj Method Purpose Deletes the specified object. IDL Syntax void somdDeleteObj ( in SOMObject somobj ); Description The somdDeleteObj method deletes the specified object. Parameters receiver A pointer to a SOMDServer object. env A pointer to the Environment structure for the method caller. somobj An object “managed” by the server object. Example #include #include
somdDispatchMethod Method Purpose Dispatch a method on the specified SOM object. IDL Syntax void somdDispatchMethod ( in SOMObject somobj, out somToken retValue, in somId methodId, in va_list ap ); Description The somdDispatchMethod method is used to intercept method calls on objects in a server. When a request arrives, the request parameters are extracted from the message, and the target object is resolved.
somdGetClassObj Method Purpose Creates a class object for the specified class. IDL Syntax SOMClass somdGetClassObj ( in Identifier objclass); Description The somdGetClassObj method creates a class object of the specified type. Parameters receiver A pointer to a SOMDServer object. env A pointer to the Environment structure for the method caller. objclass An identifier specifying the type of the class object to be created.
somdObjReferencesCached Method Purpose Indicates whether a server object retains ownership of the object references it creates via the somdRefFromSOMObj method. Syntax boolean somdObjReferencesCached ( ); Description The somdObjReferencesCached method indicates whether a server object retains ownership of the object references it creates via the somdRefFromSOMObj method.
somdRefFromSOMObj Method Purpose Returns an object reference corresponding to the specified SOM object. IDL Syntax SOMDObject somdRefFromSOMObj ( in SOMObject somobj); Description The somdRefFromSOMObj method creates a simple (transient) reference to a SOM object. This method is called by SOMOA as part of converting the results of a local method call into a result message for a remote client. By default the somdRefFromSOMObj method turns over ownership of the object reference it creates to the caller.
somdSOMObjFromRef Method Purpose Returns the SOM object corresponding to the specified object reference. IDL Syntax SOMObject somdSOMObjFromRef ( in SOMDObject objref); Description The somdSOMObjFromRef method returns the SOM object associated with the DSOM object reference, objref. This method is called by SOMOA as part of converting a remote request into a local method call on an object. Parameters receiver A pointer to a SOMDServer object.
SOMDServerMgr Class Description The SOMDServerMgr class provides a programmatic interface to manage server processes. At present, the server processes that can be managed are limited to those present in the Implementation Repository. The choice of Implementation Repository is determined by the environment variable SOMDDIR.
somdDisableServer Method Purpose Disables a server process from starting until it is explicitly enabled again. IDL Syntax ORBStatus somdDisableServer (in string server_alias); Description The somdDisableServer method disables the server process associated with the server alias. Once a server process has been disabled, it cannot be restarted until it is explicitly enabled again. Initially, all server processes are enabled by default.
somdEnableServer Method Purpose Enables a server process so that it can be started when required. Initially, all server processes are enabled by default. IDL Syntax ORBStatus somdEnableServer (in string server_alias); Description The somdEnableServer method enables a server process associated with the server alias. Initially, all server processes are enabled by default. Server processes can be disabled by using the somdDisableServer method.
somdIsServerEnabled Method Purpose Determines whether a server process is enabled or not. IDL Syntax boolean somdIsServerEnabled (in ImplementationDef impldef); Description The somdIsServerEnabled method returns a boolean corresponding to the current state (enabled/disabled) of the server process. Parameters receiver A pointer to an object of class SOMDServerMgr. ev A pointer to the Environment structure for the calling method.
somdListServer Method Purpose Queries the state of a server process. IDL Syntax ORBStatus somdListServer (in string server_alias); Description The somdListServer method is invoked to query the status of the server process associated with the server alias. If the server process is running, the return code will be 0 indicating success. Status codes of SOMDERROR_ServerDisabled or SOMDERROR_ServerNotFound may also be returned.
somdRestartServer Method Purpose Restarts a server process. IDL Syntax ORBStatus somdRestartServer (in string server_alias); Description The somdRestartServer method is invoked to restart a server process. If the server process currently exists, it will be stopped and started again. If the server process does not exist, a new server process will still be started. If the server process cannot be stopped and/or started for any reason, the method returns a DSOM error code.
somdShutdownServer Method Purpose Stops a server process. IDL Syntax ORBStatus somdShutdownServer (in string server_alias); Description The somdShutdownServer method is invoked to stop a server process. If the server process corresponding to the server alias exists, it will be stopped and a code indicating success is returned. If the server process does not exist, then the SOMDERROR_ServerNotFound error is returned.
somdStartServer Method Purpose Starts a server process. IDL Syntax ORBStatus somdStartServer (in string server_alias); Description The somdStartServer method is invoked to start a server process. If the server process does not exist, the server process is started and the code indicating success is returned. If the server process already exists, then the return code will still indicate success and the server process will be undisturbed. Parameters receiver A pointer to an object of class SOMDServerMgr.
SOMOA Class Description The SOMOA class is DSOM’s basic object adapter. SOMOA is a subclass of the abstract BOA class, and provides implementations of all the BOA methods. The SOMOA class also introduces methods for receiving and dispatching requests on SOM objects. SOMOA provides some additional methods for creating and managing object references.
activate_impl_failed Method Purpose Sends a message to the DSOM daemon indicating that a server did not activate. IDL Syntax void activate_impl_failed ( in ImplementationDef implDef, in long rc); Description The activate_impl_failed method sends a message to the DSOM daemon (somdd) indicating that the server did not activate. Parameters receiver A pointer to the SOMOA object that attempted to activate the implementation. env A pointer to the Environment structure for the method caller.
change_id Method Purpose Changes the reference data associated with an object. IDL Syntax void change_id ( in SOMDObject objref, in ReferenceData id ); Description The change_id changes the ReferenceData associated with the object identified by objref. The ReferenceData previously stored in the SOMOA’s reference data table is replaced with the value of id. The new ID cannot be larger than the maximum size of the original ReferenceData (usually specified as 1024 bytes).
create_constant Method Purpose Creates a “constant” object reference. IDL Syntax SOMDObject create_constant ( in ReferenceData id, in InterfaceDef intf, in ImplementationDef impl); Description The create_constant method is a variant of the create method. Like create, it creates an object reference for an object with the specified interface and associates the supplied ReferenceData with the object reference. The ReferenceData can later be retrieved using the get_id method.
Example #include #include #include Environment ev; ReferenceData id; InterfaceDef intfdef; SOMDObject objref; string fname; /* file name to be saved with reference */ ... /* create the id for the reference */ id._maximum = id._length = strlen(fname)+1; id._buffer = (string) SOMMalloc(strlen(fname)+1); strcpy(id.
create_SOM_ref Method Purpose Creates a simple, transient DSOM reference to a SOM object. IDL Syntax SOMDObject create_SOM_ref ( in SOMObject somobj, in ImplementationDef impl); Description The create_SOM_ref method creates a simple DSOM reference (SOMDObject) for a local SOM object. The reference is “special” in that there is no explicit ReferenceData associated with the object. Also, this object reference is only valid while the target SOM object exists.
execute_next_request Method Purpose Receive a request message, execute the request, and return to the caller. IDL Syntax ORBStatus execute_next_request ( in Flags waitFlag ); Description The execute_next_request method receives the next request message, executes the request, and sends the result to the caller. If the server’s ImplementationDef indicates the server is multi-threaded (the impl_flags has the IMPLDEF_MULTI_THREAD flag set), each request will be run by SOMOA in a separate thread.
execute_request_loop Method Purpose Receives a request message, executes the request, and returns the result to the calling client. IDL Syntax ORBStatus execute_request_loop ( in Flags waitFlag); Description The execute_request_loop method initiates a loop that waits for a request message, executes the request, and returns the result to the client who invoked the request. When called with the SOMD_WAIT flag, this method loops infinitely (or until an error).
Related Information Functions: SOMD_RegisterCallback Methods: execute_next_request See Chapter 12 of the SOM Toolkit User’s Guide for a description of the Event Management (EMan) framework, for writing event-driven applications.
get_SOM_object Method Purpose Get the SOM object associated with a simple DSOM reference. IDL Syntax SOMObject get_SOM_object ( in SOMDObject somref); Description The get_SOM_object method returns the SOM object associated with a reference created by the create_SOM_ref method. Parameters receiver A pointer to the SOMOA object managing the implementation. env A pointer to the Environment structure for the method caller. somref A pointer to a SOMDObject created by the create_SOM_ref method.
Chapter 3.
AttributeDef Class Description The AttributeDef class provides the interface for attribute definitions in the Interface Repository.
New Methods None.
ConstantDef Class Description The ConstantDef class provides the interface for constant definitions in the Interface Repository.
New Methods None.
Contained Class Description The Contained class is the most generic form of interface for objects in SOM’s CORBA-compliant Interface Repository (IR). All objects contained in the IR inherit this interface. File Stem containd Base SOMObject Metaclass SOMClass Ancestor Classes SOMObject Types typedef string RepositoryId; struct Description { Identifier name; any value; }; Attributes All attributes of the Contained class provide access to information kept within the receiving object.
somModifiers (sequence) The somModifiers attribute is a sequence containing all modifiers associated with the object in the “implementation” section of the SOM IDL file where the receiving object is defined. Note: This attribute is a SOM-unique extension of the Interface Repository; it is not stipulated by the CORBA specification.
describe Method Purpose Returns a structure containing information defined in the IDL specification that corresponds to a specified Contained object in the Interface Repository. IDL Syntax Description describe ( ); Description The describe method returns a structure containing information defined in the IDL specification of a Contained object. The specified object represents a component of an IDL interface (class) definition maintained within the Interface Repository.
Example Here is a code fragment written in C that uses the describe method: #include #include #include . . . AttributeDef attr; /* An AttributeDef object (also a Contained) */ Description desc; /* .value field will be an AttributeDescription */ AttributeDescription *ad; Environment *ev; . . . desc = Contained_describe (attr, ev); ad = (AttributeDescription *) desc.value.
within Method Purpose Returns a list of objects (in the Interface Repository) that contain a specified Contained object. IDL Syntax sequence within ( ); Description The within method returns a sequence of objects within the Interface Repository that contain the specified Contained object. If the receiving object is an InterfaceDef or ModuleDef, it can only be contained by the object that defines it. Other objects can be contained by objects that define or inherit them.
Example Here is a code fragment written in C that uses the within method: #include #include . . . Contained anObj; Environment *ev; sequence(Container) sc; long i; . . . sc = Contained_within (anObj, ev); printf (”%s is contained in (or inherited by):\n”, Contained__get_name (anObj, ev)); for (i=0; i
Container Class Description The Container class is a generic interface that is common to all of the SOM CORBA-compliant Interface Repository (IR) objects that can hold or contain other objects. A Container object can be one of three types: ModuleDef, InterfaceDef, or OperationDef.
contents Method Purpose Returns a sequence indicating the objects contained within a specified Container object of the Interface Repository. IDL Syntax sequence contents ( in InterfaceName limit_type, in boolean exclude_inherited); Description The contents method returns a list of objects contained by the specified Container object. Each object represents a component of an IDL interface (class) definition maintained within the Interface Repository.
Return Value The contents method returns a sequence of pointers to objects contained within the specified Container object. Example Here is a code fragment written in C that uses the contents method: #include ... Container anObj; Environment *ev; sequence(Contained) sc; long i; ...
describe_contents Method Purpose Returns a sequence of descriptions of the objects contained within a specified Container object of the Interface Repository. IDL Syntax sequence describe_contents ( in InterfaceName limit_type, in boolean exclude_inherited, in long max_returned_objs); Description The describe_contents method combines the operations of the contents method and the describe method.
exclude_inherited A boolean value: TRUE to exclude any inherited objects, or FALSE to include all objects. max_returned_objs A long integer indicating the maximum number of objects to be returned by the method, or –1 to indicate no limit is set. Return Value The describe_contents method returns a sequence of ContainerDescription structures, one for each object contained within the specified Container object.
lookup_name Method Purpose Locates an object by name within a specified Container object of the Interface Repository, or within objects contained in the Container object. IDL Syntax sequence lookup_name ( in Identifier search_name, in long levels_to_search, in InterfaceName limit_type, in boolean exclude_inherited); Description The lookup_name method locates an object by name within a specified Container object, or within objects contained in the Container object.
Return Value The lookup_name method returns a sequence of pointers to objects of the given name contained within the specified Container object, or within objects contained in the Container object. Example Here is a code fragment written in C that uses the lookup_name method: #include #include #include ... Container repo; Environment *ev; sequence(Contained) sc; long i; Identifier nameToFind; ...
ExceptionDef Class Description The ExceptionDef class provides the interface for exception definitions in the Interface Repository. File Stem excptdef Base Contained Metaclass SOMClass Ancestor Classes Contained SOMObject Types struct ExceptionDescription { Identifier name; RepositoryId id; RepositoryId defined_in; TypeCode type; }; The describe method, inherited from Contained, returns an ExceptionDescription structure in the value member of the Description structure (defined in the Contained class).
New Methods None.
InterfaceDef Class Description The InterfaceDef class provides the interface for interface definitions in the Interface Repository.
Attributes All attributes of the InterfaceDef class provide access to information kept within the receiving InterfaceDef object. The “_get_” form of the attribute returns a memory reference that is only valid as long as the receiving object has not been freed (using _somFree). The “_set_” form of the attribute makes a (deep) copy of your data and places it in the receiving InterfaceDef object. You retain ownership of all memory references passed using the “_set_” attribute forms.
describe_interface Method Purpose Returns (from the Interface Repository) a description of all the methods and attributes of an interface definition. IDL Syntax FullInterfaceDescription describe_interface ( ); Description The describe_interface method returns a description of all the methods and attributes of an interface definition that are held in the Interface Repository.
Example Here is a code fragment written in C that uses the describe_interface method: #include ... InterfaceDef idef; Environment *ev; FullInterfaceDescription fid; long i; ... fid = InterfaceDef_describe_interface (idef, ev); printf (”The %s interface has the following attributes:\n”, Contained__get_name ((Contained) idef, ev)); if (!fid.attributes._length) printf (”\t[none]\n”); else { for (i=0; i
ModuleDef Class Description The ModuleDef class provides the interface for module definitions in the Interface Repository. File Stem moduledf Base Contained, Container Metaclass SOMClass Ancestor Classes Contained Container SOMObject Types struct ModuleDescription { Identifier RepositoryId RepositoryId }; name; id; defined_in; The describe method, inherited from Contained, returns a ModuleDescription structure in the value member of the Description structure (defined in the Contained class).
OperationDef Class Description The OperationDef class provides the interface for operation (method) definitions in the Interface Repository.
Attributes Following is a list of each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: result (TypeCode) The TypeCode that represents the type of the operation (method). The TypeCode returned by the “_get_” form of the type attribute is contained in the receiving OperationDef object, which retains ownership. Thus the returned TypeCode should not be freed. To obtain a separate copy, use the TypeCode_copy operation.
ParameterDef Class Description The ParameterDef class provides the interface for parameter definitions in the Interface Repository.
Overriding Methods somInit somUninit somDumpSelf somDumpSelfInt describe Interface Repository Framework Reference 3-29
Repository Class Description The Repository class provides global access to SOM’s CORBA-compliant Interface Repository (IR), which is discussed in Chapter 7, “The Interface Repository Framework,” of the SOM Toolkit User’s Guide.
lookup_id Method Purpose Returns the object having a specified RepositoryId. IDL Syntax Contained lookup_id ( in RepositoryId search_id); Description The lookup_id method returns the object having a RepositoryId given by the specified search_id argument. The returned object represents a component of an IDL interface (class) definition maintained within the Interface Repository.
Original Class Repository Related Information Methods: lookup_modifier, lookup_name, contents, within 3-32 SOMobjects Base Toolkit Programmer’s Reference Manual
lookup_modifier Method Purpose Returns the value of a given SOM modifier for a specified object [that is, for an object that is a component of an IDL interface (class) definition maintained within the Interface Repository]. IDL Syntax string lookup_modifier ( in RepositoryId id, in string modifier); Description The lookup_modifier method returns the string value of the given SOM modifier for an object with the specified RepositoryId within the Interface Repository.
Example Here is a code fragment written in C that uses the lookup_modifier method: #include ... Repository repo; Environment *ev; RepositoryId objectId; string filestem;i ...
release_cache Method Purpose Permits the Repository object to release the memory occupied by Interface Repository objects that have been implicitly referenced. Syntax void release_cache ( ); Description This method allows the Repository object to release the memory occupied by implicitly referenced Interface Repository objects.
TypeDef Class Description The TypeDef class provides the interface for typedef definitions in the Interface Repository. File Stem typedef Base Contained Metaclass SOMClass Ancestor Classes Contained SOMObject Types struct TypeDescription { Identifier RepositoryId RepositoryId TypeCode }; name; id; defined_in; type; The describe method, inherited from Contained, returns a TypeDescription structure in the value member of the Description structure (defined in the Contained class).
TypeCode_alignment Function Purpose Supplies the alignment value for a given TypeCode. IDL Syntax short TypeCode_alignment ( ); Description This function returns the alignment information associated with the given TypeCode. The alignment value is a short integer that should evenly divide any memory address where an instance of the type described by the TypeCode will occur. Parameters tc The TypeCode whose alignment information is desired. ev A pointer to an Environment structure.
TypeCode_copy Function Purpose Creates a new copy of a given TypeCode. IDL Syntax TypeCode TypeCode_copy ( ); Description The TypeCode_copy function creates a new copy of a given TypeCode. TypeCodes are complex data structures whose actual representation is hidden, and may contain internal references to strings and other TypeCodes.
TypeCode_equal Function Purpose Compares two TypeCodes for equality. IDL Syntax boolean TypeCode_equal ( TypeCode tc2); Description The TypeCode_equal function can be used to determine if two distinct TypeCodes describe the same underlying abstract data type. Parameters tc One of the TypeCodes to be compared. ev A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return exception information when an error condition is detected.
TypeCode_free Function Purpose Destroys a given TypeCode by freeing all of the memory used to represent it. IDL Syntax void TypeCode_free ( ); Description The TypeCode_free function destroys a given TypeCode by freeing all of the memory used to represent it. TypeCodes obtained from the TypeCode_copy or TypeCodeNew functions should be freed using TypeCode_free. TypeCodes contained in Interface Repository objects should never be freed.
TypeCode_kind Function Purpose Categorizes the abstract data type described by a TypeCode.
TypeCode Information per TCKind Category TCKind Parameters Type Function tk_objref 1 string The ID of the corresponding InterfaceDef in the Interface Repository. tk_struct 2N+1 string The name of the struct. ––next 2 repeat for each member–– tk_union 3N+2 string The name of the struct member. TypeCode The type of the struct member. string The name of the union. TypeCode The type of the discriminator. ––next 3 repeats for each enumerator–– tk_enum N+1 long The label value.
The tk_pointer TypeCode contains only one parameter—a TypeCode which describes the data type that the pointer references. The tk_self TypeCode is used to describe a “self-referential” structure or union without introducing unbounded recursion in the TypeCode.
TypeCodeNew Function Purpose Creates a new TypeCode instance. Syntax TypeCode TypeCodeNew (TCKind tag, ...); [The actual parameters indicated by “...” are variable in number and type, depending on the value of the tag parameter.] There are no implicit parameters to this function.
structOrUnionName A string that gives the name of a struct or union that has been previously named in the current TypeCode and is the subject of a self-referential pointer type. See the footnote on tk_self in the table given in the TypeCode_kind function description for an example of what this means and how it is applied. maxLength The maximum permitted length of a string or a sequence. The value 0 (zero) means that the string or sequence is considered unbounded.
TypeCode_param_count Function Purpose Obtains the number of parameters available in a given TypeCode. IDL Syntax long TypeCode_param_count ( ); Description The TypeCode_param_count function can be used to obtain the actual number of parameters contained in a specified TypeCode. Each TypeCode contains sufficient parameters to fully describe its underlying abstract data type. Refer to the table given in the description of the TypeCode_kind function.
TypeCode_parameter Function Purpose Obtains a specified parameter from a given TypeCode. IDL Syntax any TypeCode_parameter ( long index); Description The TypeCode_parameter function can be used to obtain any of the parameters contained in a given TypeCode. Refer to the table shown in the description of the TypeCode_kind function for a list of the number and type of parameters associated with each category of TypeCode. Parameters tc The TypeCode whose parameter is desired.
Since all TypeCode parameters have one of only three types (string, TypeCode, or long), the _type member will always be set to TC_string, TC_TypeCode, or TC_long, as appropriate. The _value member always points to the actual parameter datum. For example, the following code can be used to extract the name of a structure from a TypeCode of kind tk_struct in C: #include /* Interface Repository class */ #include /* Interface Repository TypeDef class */ #include
TypeCode_print Function Purpose Writes all of the information contained in a given TypeCode to stdout. IDL Syntax void TypeCode_print ( ); Description The TypeCode_print function can be used during program debugging to inspect the contents of a TypeCode. It prints (in a human-readable format) all of the information contained in the TypeCode.
TypeCode_setAlignment Function Purpose Overrides the default alignment value associated with a given TypeCode. IDL Syntax void TypeCode_setAlignment (short alignment); Description The TypeCode_setAlignment function overrides the default alignment value associated with a given TypeCode. Parameters tc The TypeCode to receive the new alignment value. ev A pointer to an Environment structure. alignment A short integer that specifies the alignment value.
TypeCode_size Function Purpose Provides the minimum size of an instance of the abstract data type described by a given TypeCode. IDL Syntax long TypeCode_size ( ); Description The TypeCode_size function is used to obtain the minimum size of an instance of the abstract data type described by a given TypeCode. This function is a SOM-unique extension to the CORBA standard. Parameters tc The TypeCode whose instance size is desired. ev A pointer to an Environment structure.
3-52 SOMobjects Base Toolkit Programmer’s Reference Manual
Chapter 4.
SOMMBeforeAfter Metaclass Description SOMMBeforeAfter is a metaclass that defines two methods (sommBeforeMethod and sommAfterMethod), which are invoked before and after each invocation of every instance method. SOMMBeforeAfter is designed to be subclassed. Within the subclass, each of the two methods should be overridden with a method procedure appropriate to the particular application.
sommAfterMethod Method Purpose Specifies a method that is automatically called after execution of each client method. IDL Syntax void sommAfterMethod ( in SOMObject object, in somId methodID, in void *returnedvalue, in va_list ap); Description The sommAfterMethod specifies a method that is automatically called after execution of each client method. The sommAfterMethod method is introduced in the SOMMBeforeAfter metaclass. The default implementation does nothing until it is overridden.
Example The following figure shows an invocation of “myMethod” on “myObject”. Because “myObject” is an instance of a class whose metaclass is a subclass of SOMMBeforeAfter, “myMethod” is followed by an invocation of sommAfterMethod (note the user does not actually code the method). The adjacent figure illustrates the meaning of the parameters to sommAfterMethod. SOMMBeforeAfter . . . myMethod(myObject,...) aMetaclass sommAfterMethod(receiver, ev, myObject, ...) . . .
sommBeforeMethod Method Purpose Specifies a method that is automatically called before execution of each client method. IDL Syntax boolean sommBeforeMethod ( in SOMObject object, in somId methodID, in va_list ap); Description The sommBeforeMethod specifies a method that is automatically called before execution of each client method. The sommBeforeMethod method is not called directly by the user.
Example The following figure shows an invocation of “myMethod” on “myObject”. Because “myObject” is an instance of a class whose metaclass is a subclass of SOMMBeforeAfter, “myMethod” is preceded by an invocation of sommBeforeMethod (note the user does not actually code the method). The adjacent figure illustrates the meaning of the parameters to sommBeforeMethod. SOMMBeforeAfter . . . sommBeforeMethod(receiver, ev, myObject, ...) aMetaclass myMethod(myObject,...) . . .
SOMMSingleInstance Metaclass Description SOMMSingleInstance can be specified as the metaclass when a class implementor is defining a class for which only one instance can ever be created. The first call to New in C, the new operator in C++, or the somNew method creates the one possible instance of the class. Thereafter, any subsequent “new” calls return the first (and only) instance. Alternatively, the method sommGetSingleInstance can be used to accomplish the same purpose.
sommGetSingleInstance Method Purpose Gets the one instance of a specified class for which only a single instance can exist. IDL Syntax SOMObject sommGetSingleInstance ( ); Description The sommGetSingleInstance method gets a pointer to the one instance of a class for which only a single instance can exist. A class can have only a single instance when its metaclass is the SOMMSingleInstance metaclass (or is a subclass of it).
SOMMTraced Metaclass Description SOMMTraced is a metaclass that facilitates tracing of method invocations. Whenever a method (inherited or introduced) is invoked on an instance (simple object) of a class whose metaclass is SOMMTraced, a message prints to standard output giving the method parameters; then, after completion, a second message prints giving the returned value. There is one more step for using SOMMTraced: nothing prints unless the environment variable SOMM_TRACED is set.
4-10 SOMobjects Base Toolkit Programmer’s ReferenceManual
Chapter 5.
SOMEClientEvent Class Description This class describes generic client events within the Event Manager (EMan). Client Events are defined, created, processed and destroyed entirely by the application. The application can queue several types of client events with EMan. When a client event occurs, EMan passes an instance of this class to the callback routine. The callback can query this object about its type and obtain any event-specific information.
somevGetEventClientData Method Purpose Returns the user-defined data associated with a client event. IDL Syntax void* somevGetEventClientData ( ); Description This method returns the user-defined data (if any) associated with the Client Event object. This associated data for a given client event type is passed to EMan at the time of registration. Parameters receiver A pointer to an object of class SOMEClientEvent. ev A pointer to the Environment structure for the calling method.
somevGetEventClientType Method Purpose Returns the type name of a client event. IDL Syntax string somevGetEventClientType ( ); Description This method returns the client event type of the Client Event object. Client event type is a string name assigned to the event by the application at the time of registering the event. Parameters receiver A pointer to an object of class SOMEClientEvent. ev A pointer to the Environment structure for the calling method.
somevSetEventClientData Method Purpose Sets the user-defined data of a client event. IDL Syntax void somevSetEventClientData ( in void* clientData); Description This method sets the user-defined event data (if any) of the Client Event object. This associated data for a given client event type is passed to EMan at the time of registration. Parameters receiver A pointer to an object of class SOMEClientEvent. ev A pointer to the Environment structure for the calling method.
somevSetEventClientType Method Purpose Sets the type name of a client event. IDL Syntax void somevSetEventClientType ( in string clientType); Description This method sets the client event type field of the Client Event object. Client event type is a string name assigned to the event by the application at the time of registering the event. Parameters receiver A pointer to an object of class SOMEClientEvent. ev A pointer to the Environment structure for the calling method.
SOMEEMan Class Description The Event Manager class (EMan) is used to handle several input events. The main purpose of this class is to provide a service that can do a blocked (or timed) wait on several event sources concurrently. Typically, in a main program, one registers an interest in an event type with EMan and specifies a callback (a procedure or a method) to be invoked when the event of interest occurs.
New Methods someGetEManSem someChangeRegData someProcessEvent someProcessEvents someQueueEvent someRegister someRegisterEv someRegisterProc someReleaseEManSem someShutdown someUnRegister Overriding Methods somInit somUninit 5-8 SOMobjects Base Toolkit Programmer’s Reference Manual
someChangeRegData Method Purpose Changes the registration data associated with a specified registration ID. IDL Syntax void someChangeRegData ( in long registrationId, in SOMEEMRegisterData registerData); Description This method is called to change the registration data associated with an existing registration of EMan. The existing registration is identified by the registrationId parameter. This ID must be the one returned by EMan when the event interest was originally registered with EMan.
someGetEManSem Method Purpose Acquires EMan semaphores to achieve mutual exclusion with EMan’s activity. IDL Syntax void someGetEManSem ( ); Description When EMan is used on OS/2, multiple threads can invoke methods on EMan concurrently. EMan protects its internal data by acquiring SOM toolkit semaphores. The same semaphores are made available to users of EMan through the methods someGetEManSem and someReleaseEManSem.
someProcessEvent Method Purpose Processes one event. IDL Syntax void someProcessEvent ( in unsigned long mask); Description Processes one event. This call is non-blocking. If there are no events to process it returns immediately. The mask specifies which events to process. The mask is formed by OR’ing the bit constants specified in the eventmsk.h file. Parameters receiver A pointer to an object of class SOMEEMan. ev A pointer to the Environment structure for the calling method.
someProcessEvents Method Purpose Processes infinite events. IDL Syntax void someProcessEvents ( ); Description This call loops forever waiting for events and dispatching them. The only way this can be broken is by calling someShutdown in a callback routine. It is a programming error to call this method without having registered interest in any events with EMan. Typically, a call to this method is the last statement in the main program of an application.
someQueueEvent Method Purpose Enqueues the specified client event. IDL Syntax void someQueueEvent ( in SOMEClientEvent event); Description Client events are defined, created, processed and destroyed by the application. EMan simply provides a means to enqueue and dequeue client events. Client events can be used in several ways.
someRegister Method Purpose Registers an object/method pair with EMan, given a specified registerData object. IDL Syntax long someRegister ( in SOMEEMRegisterData registerData, in SOMObject targetObject, in string targetMethod, in void *targetData); Description This method allows for registering an event of interest with EMan, with an object method as the callback. It is assumed that the target method has been declared as using OIDL callstyle.
Original Class SOMEEMan Related Information Methods: someRegisterEv, someRegisterProc, someUnRegister Also see the callstyle modifier of the SOM Interface Definition Language described in Chapter 4, “Implementing SOM Classes” of the SOM Toolkit User’s Guide.
someRegisterEv Method Purpose Registers the (object, method, Environment parameter) combination of a callback with EMan, given a specified registerData object. IDL Syntax long someRegisterEv ( in SOMEEMRegisterData registerData, in SOMObject targetObject, inout Environment callbackEv, in string targetMethod, in void *targetData); Description This method allows for registering an event interest with EMan with an object method as callback.
Example #include #include
someRegisterProc Method Purpose Register the procedure with EMan given the specified registerData. IDL Syntax long someRegisterProc ( in SOMEEMRegisterData registerData, in EMRegProc *targetProcedure, in void *targetData); Description The someRegisterProc method allows for registering an event of interest with EMan, with a specified procedure as the callback. The event of interest and its details are provided through a registration data object registerData.
Original Class SOMEEMan Related Information Methods: someRegister, someRegisterEv, someUnRegister Event Management Framework Reference 5-19
someReleaseEManSem Method Purpose Releases the semaphore obtained by the someGetEManSem method. IDL Syntax void someReleaseEManSem ( ); Description When EMan is used on OS/2, multiple threads can invoke methods on EMan concurrently. EMan protects its internal data by acquiring SOM toolkit semaphores. The same semaphores are made available to users of EMan through the methods someGetEManSem and someReleaseEManSem.
someShutdown Method Purpose Shuts down an EMan event loop. (That is, this makes the someProcessEvents return!) IDL Syntax void someShutdown ( ); Description This can be called from a callback routine to break the someProcessEvents loop. Parameters receiver A pointer to an object of class SOMEEMan. ev A pointer to the Environment structure for the calling method. Example #include SOMEEMan *some_gEMan; void MyCallBack(SOMEEvent *event, void *somedata){ ...
someUnRegister Method Purpose Unregisters the event interest associated with a specified registrationId within EMan. IDL Syntax void someUnRegister ( in long registrationId); Description When an application is no longer interested in a given event, it can unregister the event interest from EMan. EMan will stop making callbacks on this event, even if the event source continues to be active and generates events. Parameters receiver A pointer to an object of class SOMEEMan.
SOMEEMRegisterData Class Description This class is used for holding registration information for event types to be registered with EMan. EMan extracts all needed information from this object and saves the information in its internal data structures. An instance of this class must be created, properly initialized, and passed to the registration methods of EMan for registering interest in any kind of event.
someClearRegData Method Purpose Clears the registration data. IDL Syntax void someClearRegData ( ); Description This method initializes all fields of a RegData object to their default values. Parameters receiver A pointer to an object of class SOMEEMRegisterData. ev A pointer to the Environment structure for the calling method.
someSetRegDataClientType Method Purpose Sets the type name for a client event. IDL Syntax void someSetRegDataClientType ( in string clientType); Description Client events are defined, created, processed, and destroyed entirely by the application. The application can queue several types of client events with EMan. This method sets the client event type field of the registration data object.
someSetRegDataEventMask Method Purpose Sets the generic event mask within the registration data using NULL terminated event type list. IDL Syntax void someSetRegDataEventMask ( in long eventType, in va_list ap); Description This allows setting the event mask within the registration data object. Essentially, this tells EMan what kind of event is being registered with it. The event type list is a series of constants defined in the eventmsk.h file.
someSetRegDataSink Method Purpose Sets the file descriptor (or socket ID, or message queue ID) for the sink event. IDL Syntax void someSetRegDataSink ( in long sink); Description This method enables setting the true type of an event object. Typically, a subclass of Event calls this method (or overrides this method) to set the event type to indicate its true class(type). Parameters receiver A pointer to an object of class SOMEEMRegisterData.
someSetRegDataSinkMask Method Purpose Sets the sink mask within the registration data object. IDL Syntax void someSetRegDataSinkMask ( in unsigned long sinkmask); Description The sink mask within the registration data allows one to express interest in different events of the same event source. For example, using this mask one can express interest in being notified when there is input for reading, when the resource is ready for writing output, or just when exceptions occur.
someSetRegDataTimerCount Method Purpose Sets the number of times the timer will trigger, within the registration data. IDL Syntax void someSetRegDataTimerCount ( in long count); Description The someSetRegDataTimerCount method sets the number of times the timer will trigger, within the registration data. The default behavior is for the timer to trigger indefinitely. Parameters receiver A pointer to an object of class SOMEEMRegisterData. ev A pointer to the Environment structure for the calling method.
someSetRegDataTimerInterval Method Purpose Sets the timer interval within the registration data. IDL Syntax void someSetRegDataTimerInterval ( in long interval); Description This call allows setting the timer interval (in milliseconds) within the registration data object. Parameters receiver A pointer to an object of class SOMEEMRegisterData. ev A pointer to the Environment structure for the calling method. interval An integer indicating the timer interval in milliseconds. Example #include
SOMEEvent Class Description This is the base class for all generic events within the Event Manager (EMan). It simply timestamps an event before it is passed to a callback routine. The event type is set to the true type by a subclass. The types currently used by the Event Management Framework are defined in the eventmsk.h file. Any subclass of this class must avoid name and value collisions with the eventmsk.h file.
somevGetEventTime Method Purpose Returns the time of the generic event in milliseconds. IDL Syntax unsigned long somevGetEventTime ( ); Description EMan timestamps every event before dispatching it. The current time is obtained from the operating system (for example, using a gettimeofday call), is converted to milliseconds, and is given as the value of the timestamp. When this function is called, the event timestamp is returned. Parameters receiver A pointer to an object of class SOMEEvent.
somevGetEventType Method Purpose Returns the type of the generic event. IDL Syntax unsigned longsomevGetEventType ( ); Description This method returns the true type of a given event object (for example, to identify the particular subclass of the event object). The type is an integer valued constant defined in the eventmsk.h file. Parameters receiver A pointer to an object of class SOMEEvent. ev A pointer to the Environment structure for the calling method.
somevSetEventTime Method Purpose Sets the time of the generic event (time is in milliseconds). IDL Syntax void somevSetEventTime ( in unsigned long time); Description EMan timestamps every event before dispatching it. The current time is obtained from the operating system (for example, using a gettimeofday call), converted to milliseconds, and is given as the value of the timestamp. When an event occurs, EMan sets the timestamp of the event by calling this method.
somevSetEventType Method Purpose Sets the type of the generic event. IDL Syntax void somevSetEventType ( in unsigned long type); Description This method enables setting the true type of an event object. Typically, a subclass of SOMEEvent calls this method (or overrides this method) to set the event type to indicate its true type. Parameters receiver A pointer to an object of class SOMEEvent. ev A pointer to the Environment structure for the calling method.
SOMESinkEvent Class Description This class describes a sink event that is generated by EMan when it notices activity on a registered sink. On AIX, a sink refers to any file descriptor ( file open for reading or writing), any pipe descriptor, a socket ID or a message queue ID. On OS/2 or Windows, a sink refers to a socket ID. One can register for three types of interest in a sink: Read interest, Write interest, and Exception interest. (See the eventmsk.
somevGetEventSink Method Purpose Returns the sink, or source of I/O, of the generic sink event. IDL Syntax long somevGetEventSink ( ); Description The sink ID in the SinkEvent is returned. For message queues it is the queue ID, for files it is the file descriptor, for sockets it is the socket ID, and for pipes it is the pipe descriptor. Parameters receiver A pointer to an object of class SOMESinkEvent. ev A pointer to the Environment structure for the calling method.
somevSetEventSink Method Purpose Sets the sink, or source of I/O, of the generic sink event. IDL Syntax void somevSetEventSink ( in long sink); Description The sink ID in the SinkEvent is set. For message queues, it is the queue ID; for files it is the file descriptor; for sockets it is the socket ID; and for pipes it is the pipe descriptor. Parameters receiver A pointer to an object of class SOMESinkEvent. ev A pointer to the Environment structure for the calling method.
SOMETimerEvent Class Description This class describes a timer event that is generated by EMan when any of its registered timers pops. EMan passes an instance of this class as a parameter to the callbacks registered for Timer Events. The callback can query the instance for information on the timer interval and on any generic event properties.
somevGetEventInterval Method Purpose Returns the interval of the generic timer event (time in milliseconds). IDL Syntax void somevGetEventInterval ( ); Description The somevGetEventInterval method returns the interval of the generic timer event (time in milliseconds). Parameters receiver A pointer to an object of class SOMETimerEvent. ev A pointer to the Environment structure for the calling method. Return Value The interval time in milliseconds.
somevSetEventInterval Method Purpose Sets the interval of the generic timer event (in milliseconds). IDL Syntax void somevSetEventInterval ( in long interval); Description The somevSetEventInterval method sets the interval of the generic timer event (in milliseconds). Parameters receiver A pointer to an object of class SOMETimerEvent. ev A pointer to the Environment structure for the calling method. interval The timer interval in milliseconds.
SOMEWorkProcEvent Class Description This class describes a work procedure event object. It currently has no methods of its own. However, it sets the event type in its super class to say “EMWorkProcEvent” to help identify itself. These events are created and dispatched by EMan when a work procedure (something that the application wants to run when no other events are happening) is registered with EMan. EMan passes an instance of this class as a parameter to the callback registered for WorkProc Events.
Index A activate_impl_failed method, 2-130 add_arg method, 2-75 add_class_to_impldef method, 2-39 add_impldef method, 2-40 add_item method, 2-51 AttributeDef class, 3-2 See also “Interface Repository Framework” B Before/After methods.
create_operation_list method, 2-69 get_default_context method, 2-70 object_to_string method, 2-71 string_to_object method, 2-72 Principal class, 2-73 hostName attribute, 2-73 userName attribute, 2-73 Request class, 2-74 add_arg method, 2-75 destroy method (Request object), 2-77 get_response method, 2-79 invoke method, 2-81 send method, 2-83 SOMDClientProxy class, 2-85 somdProxyFree method, 2-87 somdProxyGetClass method, 2-88 somdProxyGetClassName method, 2-89 somdReleaseResources method, 2-90 somdTargetFree
get_implementation method, 2-101 get_interface method, 2-102 get_item method, 2-57 get_next_response function, 2-3 get_principal method, 2-24 get_response method, 2-79 get_SOM_object method, 2-138 get_values method, 2-32 invoke method, 2-81 is_constant method, 2-103 is_nil method, 2-104 is_proxy method, 2-105 is_SOM_ref method, 2-106 L H lookup_id method, 3-31 lookup_modifier method, 3-33 lookup_name method, 3-17 hostName attribute, 2-73 M I impl_alias attribute, 2-36 impl_flags attribute, 2-36 impl_
set_values method, 2-35 SOM kernel, 1-1 Functions somApply function, 1-2 somBeginPersistentIds function, 1-4 somBuiIdClass function, 1-5 SOMCalloc function, 1-39 somCheckId function, 1-6 SOMClassInitFuncName function, 1-40 somClassResolve function, 1-7 somCompareIds function, 1-9 somDataResolve function, 1-10 SOMDeleteModule function, 1-41 somEndPersistentIds function, 1-11 somEnvironmentEnd function, 1-12 somEnvironmentNew function, 1-13 SOMError function, 1-42 somExceptionFree function, 1-14 somExceptionI
somRespondsTo method, 1-154 somUninit method, 1-155 SOM metaclass classes/methods.
somevSetEventType method, 5-35 SOMEWorkProcEvent class, 5-42 See also “Event Management Framework” somExceptionFree function, 1-14 somExceptionId function, 1-15 somExceptionValue function, 1-16 SOM_Expect macro, 1-55 somFindClass method, 1-108 somFindClsInFile method, 1-110 somFindMethod(OK) methods, 1-80 somFindSMethod(OK) methods, 1-82 SOMFree function, 1-43 somFree method, 1-142 SOM_GetClass macro, 1-56 somGetClass method, 1-143 somGetClassName method, 1-144 somGetGlobalEnvironment function, 1-17 somGetI
Utility metaclasses.
X-8 SOMobjects Base Toolkit Programmer’s Reference Manual
Vos remarques sur ce document / Technical publication remark form Titre / Title : Bull DPX/20 SOMobjects Base Toolkit Programmer’s Reference Manual Nº Reférence / Reference Nº : 86 A2 28AQ 01 Daté / Dated : June 1995 ERREURS DETECTEES / ERRORS IN PUBLICATION AMELIORATIONS SUGGEREES / SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION Vos remarques et suggestions seront examinées attentivement Si vous désirez une réponse écrite, veuillez indiquer ci-après votre adresse postale complète.
ORDER REFERENCE 86 A2 28AQ 01 PLACE BAR CODE IN LOWER LEFT CORNER BULL S.A.
Utiliser les marques de découpe pour obtenir les étiquettes. Use the cut marks to get the labels.
