SOM - Perl extension for access to SOM and DSOM objects.
use SOM; blah blah blah
(exported with the tag :types):
:types
tk_short tk_ushort tk_long tk_ulong tk_float tk_double tk_char tk_boolean tk_octet tk_enum tk_string tk_objref tk_pointer # Not yet? tk_void # Output only
$class = Find_Class($classname, $major, $minor)
Returns SOM Class object. Use $major = $minor = 0 if you do not need a version check.
$major = $minor = 0
$obj = $class->NewObject()
Creates a new instance of an object of the given class.
$repo = RepositoryNew()
Returns an object for access to Repository.
SOMClass()
Returns the SOM (meta)class SOMClass.
SOMClass
SOMObject()
Returns the SOM class SOMObject.
SOMObject
SOMClassMgr()
Returns the SOM class SOMClassMgr.
SOMClassMgr
SOMClassMgrObject()
Returns the standard SOMClassMgrObject object.
SOMClassMgrObject
$obj->Dispatch0($method_name)
Dispatches a method with void return and no arguments (not supported, fatal error if $method_name cannot be resolved).
$obj->Dispatch_templ($method_name, $template, ...)
Dispatches a method with return type and arguments described by a $template. See t/animal.t how to build a template.
$obj->GetClass()
Return the class of the object (as a SOM object).
Some SOM methods are hardwired into the module, they operate on Perl objects with names ending on Ptr. (Other SOM methods are currently supported with Dispatch_templ() method only.)
Ptr
Note that support of Repository classes is much more complete than for other classes, since support on auto-import of methods is impossible without this.
DSOM-related primitive classes are listed in "Working with DSOM".
GetClass
Returns the class object.
GetClassName
Returns the class name.
Additionally, two non-SOM methods are made available: Dispatch0() and Dispatch_templ().
NewObject
Returns a new object of the given class.
All the methods take environment as an argument:
$name = $obj->name($env)
name
String name of the element (unique inside the immediate parent).
id
String id of the element (unique in the repository).
defined_in
String id of the immediate parent.
within
Returns a list of containers with definitions of this object.
describe
Returns information defined in the IDL specification of this object. Memory management for this???. Return type is AttributeDescriptionPtr.
AttributeDescriptionPtr
lookup_name
Returns a list of objects with the given name within a specified Container object, or within objects contained in the Container object.
$obj->lookup_name($env, $name, $levels, $type, $noinherited)
$levels should be -1 to search all the kids-containers as well, otherwise should be 1. $type should be one of
AttributeDef ConstantDef ExceptionDef InterfaceDef ModuleDef ParameterDef OperationDef TypeDef all
If $noinherited, any inherited objects will not be returned.
contents
Returns the list of contained elements.
$obj->contents($env, $type, $noinherited)
Parameters have the same sense as for the lookup_name method.
Should be scraped: AttributeDescriptionPtr should be substituted by proper subclass of Contained!
The methods do not take environment as an argument:
$typecode = $attr->type()
In addition to methods name(), id(), defined_in() similar to ones in Contained, has two additional methods:
Contained
TypeCodePtr object which describes the type of the attribute.
TypeCodePtr
whether the attribute is readonly.
Currently there is no value() method.
$name = $op->result($env)
result
TypeCode of the return value.
TypeCode
$name = $argN->type($env)
type
TypeCode of this argument.
mode
One of the strings INOUT, OUT, IN.
INOUT
OUT
IN
$kind = $tc->kind($env)
kind
Returns the type of the TypeCode. Types are the same as "Supported types".
param_count
Returns the number of parameters encoded in the TypeCode.
parameter
Returns the nth parameter encoded in the TypeCode as any. n changes from 0 to param_count - 1.
any
- 1
$p = $tc->parameter($env, 2);
$type = $any->type($env)
Returns the TypeCode of the value stored in the any.
value
Returns the value stored in the any. Only elementary types are supported now.
Since Container/Contained are completely supported by primitive classes, one can walk the Repository tree any way one is pleased. We use only the following subtree of the Repository: inside toplevel we find InterfaceDef elements (which carry information about SOM classes), inside an InterfaceDef we look for OperationDef elements (which correspond to methods in the class), and inside an OperationDef we look for ParameterDef elements (which correspond to arguments of a method).
Container
InterfaceDef
OperationDef
ParameterDef
We consider ContainedContainerPtr as being both a ContainerPtr and ContainedPtr. But not all of them are. This is bad, since calling C SOM bindings on an object of unappropriate type is not catchable.
ContainedContainerPtr
ContainerPtr
ContainedPtr
After any call which includes $ev, one should $ev-Clear> to avoid memory leaks. Before this call $ev can be expected for error info. Package SOM contains following major codes of exceptions: SYSTEM_EXCEPTION, USER_EXCEPTION, NO_EXCEPTION (exportable with tag :environment).
$ev-
:environment
This API is very experimental. Read DSOM reference to know what these calls are doing.
DSOM to WPS requires two servers: one is a SOMD server (a separate process), another is WPSD server (extra thread(s) in WPS shell process). To check existence: SOM::IsSOMDDReady(), SOM::IsWPDServerReady(). Possible error codes in $^E: PMERR_WPDSERVER_IS_ACTIVE(), PMERR_WPDSERVER_NOT_STARTED(), PMERR_SOMDD_IS_ACTIVE(), PMERR_SOMDD_NOT_STARTED() (all in package SOM, exportable on :dsom).
:dsom
To create: SOM::RestartSOMDD(1), SOM::RestartWPDServer(1).
SOM::RestartSOMDD(1)
SOM::RestartWPDServer(1)
To stop: SOM::RestartSOMDD(0), SOM::RestartWPDServer(0).
SOM::RestartSOMDD(0)
SOM::RestartWPDServer(0)
Keep in mind that servers are not refcounted, so it maybe not a very good idea to shut them down even if did not run when you started (since somebody else could have started to use them in between).
Additionally, stopping servers when they did not completely started could lead to problems.
A convenience function SOM::Ensure_Servers($shutdown_dsom, $shutdown_wpsd) is provided. If the arguments are given, servers will be shutdown at end of run if they were not running when this function was called. (Exportable with :dsom)
SOM::Ensure_Servers($shutdown_dsom, $shutdown_wpsd)
EnvironmentPtr
To create:
$ev = SOM::CreateLocalEnvironment();
(exportable with tag :environment).
Methods:
$major = $ev->major; $stringID = $ev->id; $minor = $ev->id; # 0 if $ev->major != SYSTEM_EXCEPTION $state = $ev->completed; # undef if $ev->major != SYSTEM_EXCEPTION # or state is not YES or NO, otherwise 0 or 1 $ev->Clear; # Free() data if $ev->major == SYSTEM_EXCEPTION
A simpleminded error reporter is made available as method Check:
Check
$err = $ev->Check and warn "Got exception $err";
$err is formatted as MAJOR=2 ID='OPSYS' MINOR=343 COMPLETED=NO.
MAJOR=2 ID='OPSYS' MINOR=343 COMPLETED=NO
SOM::SOMDeamon
Functions:
Init($ev); Uninit($ev); ClassMgrObject(); # Default SOMD class manager ObjectMgr(); # Default SOMD object manager WPClassManagerNew(); # One can Merge the result with ObjectMgr()
SOMClassManagerPtr
$oldmgr->MergeInto($newmgr);
ObjectMgrPtr
$mgr->ReleaseObject($ev, $servername);
SOMDObjectMgrPtr
ISA ObjectMgrPtr.
$server = $mgr->FindServerByName($ev, $servername);
SOMDServerPtr
$server->GetClassObj($ev, $classname);
Initialize:
use SOM ':class', ':dsom', ':environment'; Ensure_Servers(); $ev = SOM::CreateLocalEnvironment(); sub EnvironmentPtr::CheckAndWarn { my $err; $err = $ev->Check and warn "Got exception $err"; }
Start class dispatchers:
SOM::SOMDeamon::Init($ev); $ev->CheckAndWarn; $SOM_ClassMgr = SOM::SOMDeamon::ClassMgrObject or die; $WPS_ClassMgr = SOM::SOMDeamon::WPClassManagerNew or die; $SOM_ClassMgr->MergeInto($WPS_ClassMgr); # In fact MergeFrom Init_WP_Classes(); # Otherwise cannot GetClassObj('WPFolder') $server = SOM::SOMDeamon::ObjectMgr->FindServerByName($ev, "wpdServer") or die; $ev->CheckAndWarn;
Get a class object of requested type:
$classFolder = $server->GetClassObj($ev, "WPFolder") or die; $ev->CheckAndWarn; ## ... Do some work with $folderClass
Shut down dispatchers:
SOM::SOMDeamon::ObjectMgr->ReleaseObject($ev, $server); $ev->CheckAndWarn; SOM::SOMDeamon::Uninit($ev); $ev->CheckAndWarn;
None by default. Tags :types, :class, :dsom, :environment.
:class
A. U. Thor, a.u.thor@a.galaxy.far.far.away
Only primitive types of parameters and return value are supported.
Only in-parameters are supported.
No memory management is done at all.
Exception is not analysed.
SOM Objects have type SOMObjectPtr, SOM Classes have type SOMClassPtr etc.
Methods may be dispatched only when a signature is explicitely described.
perl(1).
To install SOM, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SOM
CPAN shell
perl -MCPAN -e shell install SOM
For more information on module installation, please visit the detailed CPAN module installation guide.