--- /dev/null
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">\r
+<html>\r
+<head>\r
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">\r
+ <meta name="GENERATOR" content="Mozilla/4.73 [en] (WinNT; I) [Netscape]">\r
+ <title>Main Page</title>\r
+<link href="doxygen.css" rel="stylesheet" type="text/css">\r
+</head>\r
+<body>\r
+ \r
+<center><table WIDTH="96%" >\r
+<tr>\r
+<td><a href="http://www.opencascade.com"><img SRC="sources/logocorp.gif" BORDER=0 height=46 width=122></a></td>\r
+\r
+<td>\r
+<div align=right><a href="http://www.opencascade.org/SALOME/"><img SRC="sources/application.gif" BORDER=0 height=46 width=108></a></div>\r
+</td>\r
+</tr>\r
+</table></center>\r
+<a NAME="page1"></a>\r
+<h2>\r
+Mapping of IDL definitions to Python language.</h2>\r
+<a NAME="Intro"></a>\r
+<h2>\r
+Introduction</h2>\r
+SALOME is a distributed client/server application using the Common\r
+Object Request Broker Architecture (CORBA). CORBA architecture uses the\r
+Interface Definition Language (IDL), which specifies interfaces between\r
+CORBA objects. So with help of IDL CORBA's language independence is ensured\r
+. Because interfaces described in IDL can be mapped to the most of currently\r
+used programming languages, CORBA applications and components are thus\r
+independent of the language(s) used to implement them. In other words,\r
+a client written in C++ can communicate with a server written in Java,\r
+which in turn can communicate with another server written in COBOL, and\r
+so forth.\r
+<p>One important thing to remember about IDL is that it is not an implementation\r
+language. That is, applications can't be written in IDL. The sole purpose\r
+of IDL is to define interfaces; providing implementations for these interfaces\r
+is performed using some other language.\r
+<p>This page contains an abridged reference manual for mapping of IDL definitions\r
+to Python language. It will be useful for Python programmers who are not\r
+familiar with IDL language. All examples are taken from SALOME source\r
+files. The complete version of Python Language Mapping Specification can\r
+be found <a href="http://www.omg.org" target="top">here.</a>\r
+<br> \r
+<p><a NAME="contents"></a><b>CONTENTS:</b>\r
+<ul> \r
+<li>\r
+<a href="#subsection1">Using Scoped Names</a></li>\r
+\r
+<li>\r
+<a href="#subsection2">Mapping for Template and Array Types</a></li>\r
+\r
+<li>\r
+<a href="#subsection3">Mapping for Objects and Operations</a></li>\r
+\r
+<li>\r
+<a href="#subsection4">Narrowing Object References</a></li>\r
+\r
+<li>\r
+<a href="#subsection5">Mapping for Exceptions</a></li>\r
+\r
+<li>\r
+<a href="#subsection6">Mapping for Enumeration Types</a></li>\r
+\r
+<li>\r
+<a href="#subsection7">Mapping for Structured Types</a></li>\r
+</ul>\r
+<br>\r
+<a NAME="subsection1"></a>\r
+<h3>\r
+Using Scoped Names</h3>\r
+Python implements a module concept that is similar to the IDL scoping mechanisms,\r
+except that it does not allow for nested modules. In addition, Python requires\r
+each object to be implemented in a module; globally visible objects are\r
+not supported.\r
+<p>Because of these constraints, scoped names are translated into Python\r
+using the following rules:\r
+<p>\95 An IDL module mapped into a Python module. Modules containing modules\r
+are mapped to packages (i.e., directories with an <b>__init__</b> module\r
+containing all definitions excluding the nested modules). An implementation\r
+can chose to map toplevel definitions (including the module CORBA) to modules\r
+in an implementationdefined package, to allow concurrent installations\r
+of different CORBA runtime libraries. In that case, the implementation\r
+must provide additional modules so that toplevel modules can be used without\r
+importing them from a package.\r
+<p>\95 For all other scopes, a Python class is introduced that contains all\r
+the definitions inside this scope.\r
+<p>\95 Other global definitions (except modules) appear in a module whose\r
+name is implementation dependent. Implementations are encouraged to use\r
+the name of the IDL file when defining the name of that module.\r
+<p>For instance,\r
+<div class="fragment">\r
+<pre>module SALOMEDS {\r
+ interface StudyManager {\r
+ void Close(in Study aStudy);\r
+ };\r
+};</pre>\r
+</div>\r
+would introduce a module SALOMEDS.py, which contains the following definitions:\r
+<div class="fragment">\r
+<pre># module SALOMEDS.py\r
+class StudyManager:\r
+ def _Close(self,aStudy):\r
+ pass #interfaces are discussed later</pre>\r
+</div>\r
+To avoid conflicts, IDL names that are also Python identifiers are prefixed\r
+with an underscore (\91_\92).\r
+<p><b><i><a href="#contents">Back to the contents</a></i></b><b><i></i></b>\r
+<p><a NAME="subsection2"></a>\r
+<h3>\r
+Mapping for Template and Array Types</h3>\r
+Both the bounded and the unbounded string type of IDL are mapped to the\r
+Python string type. Wide strings are represented by an implementation-defined\r
+type with the following properties:\r
+<p>\95 For the wide string X and the integer n, X[n] returns the nth character,\r
+which is a wide string of length 1.\r
+<p>\95 len(X) returns the number of characters of wide string X.\r
+<p>\95 CORBA.wstr(c) returns a wide character with the code point c in an\r
+implementation-defined encoding.\r
+<p>\95 X+Y returns the concatenation of wide strings X and Y.\r
+<p>\95 CORBA.word(CORBA.wstr(c)) == c\r
+<p>The sequence template is mapped to sequence objects (e.g., tuples or\r
+lists). Applications should not assume that values of a sequence type are\r
+mutable. Sequences and arrays of octets and characters are mapped to the\r
+string type for efficiency reasons.\r
+<p>For example, given the IDL definitions\r
+<div class="fragment">\r
+<pre>module SALOMEDS {\r
+ typedef sequence <string> StringSeq;\r
+ \r
+ interface AttributeTableOfInteger : GenericAttribute {\r
+\r
+ void SetRowTitles(in StringSeq theTitles) raises(IncorrectArgumentLength);\r
+ };\r
+};</pre>\r
+</div>\r
+a client could invoke the operation\r
+<div class="fragment">\r
+<pre>print My_AttributeTableOfInteger.SetRowTitles(["X","F"])</pre>\r
+</div>\r
+Array types are mapped like sequence templates. The application in this\r
+example also expects an IncorrectArgumentLength exception if it passes\r
+sequences that violate the bounds constraint or arrays of wrong size.\r
+<p>Another example with arrays. The following IDL definition\r
+<div class="fragment">\r
+<pre>module SALOMEDS {\r
+ typedef sequence<GenericAttribute> ListOfAttributes;\r
+ interface SObject {\r
+ ListOfAttributes GetAllAttributes();\r
+ };\r
+};</pre>\r
+</div>\r
+is equal to\r
+<div class="fragment">\r
+<pre>import SALOMEDS\r
+\r
+attributes=[]\r
+ \r
+attributes = My_SObject.GetAllAttributes()\r
+\r
+length = len(attributes)\r
+\r
+print "Attributes number = ", length\r
+print attributes</pre>\r
+</div>\r
+<b><i><a href="#contents">Back to the contents</a></i></b>\r
+<p><a NAME="subsection3"></a>\r
+<h3>\r
+Mapping for Objects and Operations</h3>\r
+A CORBA object reference is represented as a Python object at run-time.\r
+This object provides all the operations that are available on the interface\r
+of the object. Although this specification does not mandate the use of\r
+classes for stub objects, the following discussion uses classes to indicate\r
+the interface.\r
+<p>The nil object is represented by <b>None</b>.\r
+<p>If an operation expects parameters of the IDL Object type, any Python\r
+object representing an object reference might be passed as actual argument.\r
+<p>If an operation expects a parameter of an abstract interface, either\r
+an object implementing that interface, or a value supporting this interface\r
+may be passed as actual argument. The semantics of abstract values then\r
+define whether the argument is passed by value or by reference.\r
+<p>Operations of an interface map to methods available on the object references.\r
+Parameters with a parameter attribute of <b>in</b> or <b>inout</b> are\r
+passed from left to right tothe method, skipping <b>out</b> parameters.\r
+The return value of a method depends on the number of <b>out</b> parameters\r
+and the return type. If the operation returns a value, this value forms\r
+the first <i>result value</i>. All <b>inout</b> or <b>out</b> parameters\r
+form consecutive <i>result values</i>. The method result depends then on\r
+the number of <i>result values</i>:\r
+<p>\95 If there is no <i>result value</i>, the method returns None.\r
+<p>\95 If there is exactly one <i>result value</i>, it is returned as a single\r
+value.\r
+<p>\95 If there is more than one <i>result value</i>, all of them are packed\r
+into a tuple, and this tuple is returned.\r
+<p>Assuming the IDL definition\r
+<div class="fragment">\r
+<pre>module SALOMEDS{\r
+ interface StudyBuilder{\r
+ boolean FindAttribute ( in SObject anObject, \r
+ out GenericAttribute anAttribute, \r
+ in string aTypeOfAttribute );\r
+ };\r
+};</pre>\r
+</div>\r
+a client could write\r
+<div class="fragment">\r
+<pre>from SALOMEDS import StudyBuilder;\r
+my_StudyBuilder=...\r
+ \r
+ res,A=my_StudyBuilder.FindAttribute(Sobj, "AttributeSequenceOfReal")</pre>\r
+</div>\r
+In this example <b>A</b> corresponds to the return value <b>anAttribute</b>\r
+and <b>res</b> to the <b>boolean</b> return value.\r
+<p>If an interface defines an <b>attribute name</b>, for example, the attribute\r
+is mapped into an operation <b>_get_name</b>. If the attribute is not <b>readonly</b>,\r
+there is an additional operation <b>_set_name</b>.\r
+<p>The IDL definition\r
+<div class="fragment">\r
+<pre>module SALOMEDS{\r
+ interface Study{\r
+ attribute string Name;\r
+ };\r
+};</pre>\r
+</div>\r
+is equal to the following\r
+<div class="fragment">\r
+<pre>from SALOMEDS import Study\r
+My_Study=...\r
+ Name=My_Study._get_name();\r
+ Name=My_Study._set_name();</pre>\r
+</div>\r
+<b><i><a href="#contents">Back to the contents</a></i></b><b><i><a href="#contents"></a></i></b>\r
+<p><a NAME="subsection4"></a>\r
+<h3>\r
+Narrowing Object References</h3>\r
+Python objects returned from CORBA operations or pseudo-operations (such\r
+as string_to_object) might have a dynamic type, which is more specific\r
+than the static type as defined in the operation signature.\r
+<p>Since there is no efficient and reliable way of automatically creating\r
+the most specific type, explicit narrowing is necessary. To narrow an object\r
+reference <b>A</b> to an interface class <b>AttributeSequenceOfReal</b>,\r
+the client can use the following operation\r
+<div class="fragment">\r
+<pre>A = A._narrow(SALOMEDS.AttributeSequenceOfReal)</pre>\r
+</div>\r
+<b><i><a href="#contents">Back to the contents</a></i></b><b><i><a href="#contents"></a></i></b>\r
+<p><a NAME="subsection5"></a>\r
+<h3>\r
+Mapping for Exceptions</h3>\r
+An IDL exception is translated into a Python class derived from CORBA.UserException.\r
+System exceptions are derived from CORBA.SystemException. Both base classes\r
+are derived from CORBA.Exception. The parameters of the exception are mapped\r
+in the same way as the fields of a struct definition. When raising an exception,\r
+a new instance of the class is created; the constructor expects the exception\r
+parameters. For example, the definition\r
+<div class="fragment">\r
+<pre>module SALOMEDS{\r
+ interface StudyBuilder{\r
+ exception LockProtection {};\r
+ void CommitCommand() raises(LockProtection);\r
+ };\r
+};</pre>\r
+</div>\r
+could be used caught as\r
+<div class="fragment">\r
+<pre>from SALOMEDS import StudyBuilder;\r
+my_StudyBuilder=...\r
+try:\r
+ my_StudyBuilder.CommitCommand();\r
+except StudyBuilder.LockProtection,value:\r
+ print "Error! Study is locked for modifications"</pre>\r
+</div>\r
+\r
+<p><br><b><i><a href="#contents">Back to the contents</a></i></b><b><i><a href="#contents"></a></i></b>\r
+<p><a NAME="subsection6"></a>\r
+<h3>\r
+Mapping for Enumeration Types</h3>\r
+An enumeration is mapped into a number of constant objects in the name\r
+space where the enumeration is defined. An application may only test for\r
+equivalence of two enumeration values, and not assume that they behave\r
+like numbers. For example, the definition\r
+<div class="fragment">\r
+<pre>module VISU {\r
+ interface PrsObject{\r
+ \r
+ enum PrsObjType{ TCURVE, TTABLE, TMESH, TCONTAINER,\r
+ TSCALARMAP, TISOSURFACE, TDEFORMEDSHAPE,\r
+ TCUTPLANES, TVECTORS };\r
+ };\r
+};</pre>\r
+</div>\r
+introduces the objects\r
+<div class="fragment">\r
+<pre>from VISU import PrsObject\r
+VISU.PrsObjType.TCURVE,VISU.PrsObjType.TTABLE,VISU.PrsObjType.TMESH,VISU.PrsObjType.TCONTAINER,\r
+VISU.PrsObjType.TSCALARMAP,VISU.PrsObjType.TISOSURFACE,VISU.PrsObjType.TDEFORMEDSHAPE,VISU.PrsObjType.TCUTPLANES,\r
+VISU.PrsObjType.TVECTORS</pre>\r
+</div>\r
+<b><i><a href="#contents">Back to the contents</a></i></b>\r
+<p><a NAME="subsection7"></a>\r
+<h3>\r
+Mapping for Structured Types</h3>\r
+An IDL struct definition is mapped into a Python class or type. For each\r
+field in the struct, there is a corresponding attribute in the class with\r
+the same name as the field. The constructor of the class expects the field\r
+values, from left to right. For example, the IDL definition\r
+<div class="fragment">\r
+<pre>struct SDate {\r
+ short Second;\r
+ short Minute;\r
+ short Hour;\r
+ short Day;\r
+ short Month;\r
+ short Year;\r
+ };</pre>\r
+</div>\r
+could be used in the Python statements\r
+<div class="fragment">\r
+<pre>Date=SDate(30, 12, 15, 26, 1, 79)\r
+print Date.Second,Date.Minute,Date.Hour,Date.Day,Date.Month,Date.Year</pre>\r
+</div>\r
+\r
+<address>\r
+<b><i><a href="#contents">Back to the contents</a></i></b></address>\r
+\r
+</body>\r
+<!-- Generated by Doxygen 1.2.14 -->\r
+</html>\r
