next up previous contents index
Next: V.1 CLA classes Up: V. FeResPost as COM Previous: V. FeResPost as COM   Contents   Index

Subsections


V.0 Introduction

On Windows OS, FeResPost is distributed at the same time as a ruby extension, and as a COM component. One describes in this Part several characteristics of FeResPost as a COM component.

In general, the class names, their methods and attributes (properties), the parameters of these methods and attributes are the same as those available in the FeResPost ruby extension. (At least, this will be the case when programming of all the classes and modules is finished.) When necessary, modifications have been done in the ruby extension in order to maintain as much as possible the compatibility between the ruby extension and the COM component. Therefore, the user is referred to Parts I, II, III and IV to find information on the use of the different classes and methods. In most cases, the information given there is sufficient to use the COM component.

However, an exact match between the ruby extension and COM component is not possible. One details below the conventions that have been adopted when incompatibility problems were not solved. More generally, one explains here the specific aspects of the use of FeResPost as a COM component.

This Part of the document is organized as follows:

The present Chapter discusses the following points: The installation (registration) of the COM component is described in section IX.A.3.4).


V.0.1 Accessing the COM component

One makes the distinction between the different programming languages and programming environments. The access to the component is always done by a request of the kind

   ``create object'' FeResPost_3_4_4.Application
in which the three integers correspond to the version of FeResPost. (Several versions of FeResPost can be installed simultaneously on a computer.) One intends to maintain the same conventions for the naming of the FeResPost COM component.

When the application is started, the corresponding window appears. This window can be made visible or invisible by setting the ``Visible'' property of the application object to True or False respectively. The window presents for each class a count of the number of objects available in the memory, and of the number of references to these objects. Note that when the property is set to True, the execution of the program might slow down significantly. Therefore, the property should be set to True for debugging only.


V.0.1.1 Accessing the COM component in ruby

Even though FeResPost is first programmed as a ruby extension, the COM component can also be accessed from ruby language. For this, one first requires the ``win32ole'' ruby extension that allows the access to all the COM components installed on the computer. Then the FeResPost component can be accesses by requiring the corresponding application:

   require 'win32ole'
   
   ...
   
   frpApp = WIN32OLE.new("FeResPost_3_4_4.Application")
In the example, above one required the 3.4.4 version of the FeResPost COM component, and stores a reference to this application in ``frpApp'' variable.

Note that memory leakage has been observed in win32ole extension of ruby language. This can result in COM objects not being released when they should be. This bug, not related to FeResPost, is currently under investigation, and should be fixed in version 1.8.7 of ruby.


V.0.1.2 Accessing the COM component in python

The access to the FeResPost COM component from python is similar to the access from ruby. A win32con extension must first be imported, then the component can be accessed:

	import win32con

	from win32com.client import Dispatch, constants

   ...

   frpApp = Dispatch("FeResPost_3_4_4.Application")


V.0.1.3 Accessing the COM component in VBscript

In this case, no special extension is required because the OLE support is ``build-in'' the language. The application is simply accessed with the following statement:

   set frpApp= CreateObject("FeResPost_3_4_4.Application")


V.0.1.4 Accessing the COM component in VBA

When programming in VBA, for example in excel, the component must first be referenced in the excel workbook. For this:

  1. Open the VBA editor from an excel workbook.
  2. Go to the ``Tools'' menu and select the ``References'' menu.
  3. There, you select the (or one of the) available FeResPost library. For example, for version 3.1.7, the library is referred to as ``FeResPost 3.1.7 COM server''.
  4. Quit the ``Tools/References'' menu.
  5. Then, the server can be accessed from excel VBA code with a statement like:
            set frpApp= CreateObject("FeResPost_3_1_7.Application")
    
Once the FeResPost component library is activated, the different classes and the corresponding methods can be viewed in the object explorer. During the VBA program execution, the behavior of the different classes and methods can also be watched.

If you want to change the version of VBA used in an existing excel VBA project, proceed as follows:

  1. It may be practical to un-activate the execution of excel VBA macros before doing the following operations.
  2. Make sure that the new version of FeResPost is properly registered.
  3. Open the VBA editor from an excel workbook.
  4. Go to the ``Tools'' menu and select the ``References'' menu.
  5. Un-select the old version of FeResPost COM server. (The one you no longer want to use.)
  6. Quit the ``Tools/References'' menu.
  7. Re-enter into the ``Tools'' menu and select the ``References'' menu.
  8. Select the new version of FeResPost COM server you want to use in the workbook.
  9. Quit the ``Tools/References'' menu.
  10. Do not forget to modify the version of the server requested by ``CreateObject'' method in excel VBA code.
If you no longer need the old version of FeResPost COM server, you can un-register it and delete the corresponding files from your computer.


V.0.1.5 Accessing the COM component in compiled languages

Section VI.1.1.4 shows an example of C++ program in which the component is accessed. This object shows that the use of COM component from compiled languages is significantly more difficult than from interpreted languages. This is related to the fact that the management of many operations has to be done by the programmer and is no longer dealt with by the interpreted language.

This example also shows that additional information should be added to the documentation to allow an easy access to the different methods and classes of the component by the compiled languages programmers. This documentation is still under development.

Actually, the example shows even more that the component that is being developed is adapted to the use with languages that support the Microsoft IDispatch interface. However, a library adapted to the use with C++ language should also be developed. Consequently we do not advise to use the component from C++ or C language.


V.0.2 COM component versus ruby extension

One highlights below some differences between COM component and ruby extension that are related to specific programmatic aspects of the two different systems.


V.0.2.1 Creating class instances

New instances of the FeResPost classes are obtained by calling the ``newObject'' method of FeResPost application. The argument of this method is a String containing the name of the class of which a new object is requested. For example, in ruby, the creation of new instances is done with statements like:

   ...
   frpApp = WIN32OLE.new("FeResPost_3_4_4.Application")
   ...
   db=frpApp.newObject("ClaDb")
   ...
   mat=frpApp.newObject("ClaMat")
   ...
The corresponding VBscript lines of code follow:
   ...
   set frpApp= CreateObject("FeResPost_3_4_4.Application")
   ...
   set db=frpApp.newObject("ClaDb")
   ...
   set mat=frpApp.newObject("ClaMat")
   ...


V.0.2.2 Associative containers and Arrays

By default, COM does not define associative containers (i.e. containers that associate keys and values, like the ``Hash'' class of ruby language.) As in FeResPost ruby extension, Hash objects are often used as method arguments, or values returned by these methods, A convention must be agreed upon to determine the type of arguments that are to be used to replace these Hashes.

The convention that has been adopted is that each Hash is replaced by a 2D Array:

One notes that the indices used to access the elements of an Array start with 0 corresponding to the first element. This is a convention that has systematically been used for all the Array produced by FeResPost COM component. This convention is that same as the one of FeResPost ruby extension, and is consistent with C, C++, ruby and many other programming languages.


V.0.2.3 Iterators

COM provides a standard interface that allows the writing of iterators on collections of different types. In FeResPost, the iteration is based on the IEnumVARIANT interface. One notes however, that it does not seem possible to implement a class that defines several enumerators. This is why, an additional class corresponding to the iteration has been created in FeResPost: the ``Iterator'' class.

The ``Iterator'' class is common to all the iterators of all the FeResPost classes. But an Iterator object behaves differently depending on the class that produces it and/or the method of the class that is used to produce it.

Let us illustrate it by an example... Consider the ``each_ply'' iterator defined in ClaLam class of FeResPost ruby extension. With the ruby extension, the iteration on the plies of a laminate may be performed as follows:

   ...
   lam.each_ply do |plyDescr|
      ...
   end
   ...
With FeResPost COM component, an Iterator must first be produced before iterating on the elements of the corresponding collection. This can be done as follows:
   ...
   plyIt = lam.iter_ply
   plyIt.each do |plyDescr|
      ...
   end
   ...
This examples illustrates the conventions that have been used when programming the FeResPost COM component to transpose the iterators proposed in the ruby extension:
  1. As in the FeResPost ruby extension, each iterator method name starts with ``each_'', correspondingly, the COM component methods returning an Iterator object have a name that starts with ``iter_''. The correspondence between ruby extension methods and COM component methods is obvious: ``each_ply'' becomes ``iter_ply'', ``each_material'' becomes ``iter_material'',...
  2. When the COM iteration method has no argument, it is a property ``getter'' that is used instead of a method. Otherwise, a method with argument is defined.
  3. In ruby using the COM component, the iteration on the Iterator object is done using ``each'' iteration method.
Note that to the ruby lines given as example above, one prefers the shorter notation:
   ...
   lam.iter_ply.each do |plyDescr|
      ...
   end
   ...
The corresponding code in python may be:
   ...
   for plyDescr in lam.iter_ply:
      ...
   ...
and in VBscript, one shall have:
   ...
   for each plyDescr in lam.iter_ply
      ...
   Next
   ...


V.0.2.4 Operators

Operators are not supported in COM. Therefore, the operators that are defined by ruby classes are replaced by methods in COM component:

For example, the following ruby statement:
   z=x+y
becomes, with COM component:
   z=x.opAdd(y)
Note that the different ``operator'' methods defined in ruby ``Post'' module are also defined in the ``Application'' class of COM component (section V.2.1).


V.0.2.5 Singleton methods

In ruby language, classes may define singleton methods that can be called directly from the class, and not from an instance of the class. Apparently, this capability is not supported by COM classes.

Therefore, all the singleton methods defined in ruby extension are defined as instance methods in COM component. This means that before using such a method, an instance of the corresponding class must be defined first.


V.0.2.6 ``Clone'' methods

When one class of the ruby extension defines a ``clone'' method, the corresponding method of the COM component defines a ``makeCopy'' method. This has been done to avoid method name conflicts when the COM component is used with ruby language.


V.0.2.7 ``Post'' Module

In ruby extension, several methods are defined in ``Post'' Module. In COM component, these methods are defined in ``Application'' class.


V.0.2.8 Complex arguments

In ruby extension, several methods have complex arguments. No standard ``Complex'' class exists in COM, even though the ``Complex'' class is available in most programming languages. In FeResPost COM component one decided that the convention is to represent Complex numbers by Arrays of two real numbers corresponding to the real and imaginary parts of the number.


V.0.2.9 ``nil'' arguments

With FeResPost ruby extension, an optional argument can be set to ``nil'' when not provided. The ``nil'' argument also works when the COM component is used with ruby language. in VBA, the ``nil'' argument can be replaced by an unitialized Variant object (VT_EMPTY variant type).


next up previous contents index
Next: V.1 CLA classes Up: V. FeResPost as COM Previous: V. FeResPost as COM   Contents   Index
FeResPost 2017-05-28