View source for COM Integration/Writing your own COM component using VC++

[[Category: COM integration]]

''Requires [[Analytica 4.6]] Enterprise or better', and Microsoft Visual Studio''

== Introduction ==

This article leads you through the steps to create your own COM component in VC++ that can be called from your Analytica model. This provides a mechanism to call your own C++ code from Analytica. You may want to do this when you have an algorithm that you want to make really fast, have pre-existing and complex C++ code that you want to call, or want to create a wrapper to integrate with some other existing component, service or program.

The instructions here use Visual Studio 2013 Update 5. The steps may vary slightly in different Visual Studio releases.

In this introduction, I create a component named <code>Rainfall.Counter</code>. Your own component name will differ, so make the substitution with your own component name where appropriate. Once completed, the component is used from Analytica by first instantiating the object in an Analytica variable using.

:<code>COMCreateObject("Rainfall.Counter")</code>

And then calling its methods from other within the Definition of other variables. The methods of this class accept a one-dimensional array as input and return a one-dimensional array as a result.

== Create the Project ==

Start by creating a Visual Studio project. Launch VS and select '''File / New / Project&#x2026; / Templates / Visual C++ / ATL / ATL Project'''.

:[[image:COM_cpp_new_project.png]]

Enter a name for your project -- my project is named <code>Rainfall</code>.  Press '''OK'''.  On the next screen, set the application type to '''Executable (EXE)''' and check '''Allow merging of proxy/stub code'''.

:[[image:COM_cpp_app_settings.png]]

The proxy/stub is for convenience, eliminating an extra DLL that would otherwise have to be distributed with your final solution. The other Application types can also be used, but if you aren't sure why you'd want them, stick with EXE.

Once you press '''Finish''', your initial project is created.

=== Configuring to be 64-bit ===

You may optionally configure your component to be 64-bit. A few factors come into play in making this decision. If you are using C++ for pure algorithmic speed, then I recommend building a 64-bit component, since 64-bit applications tend to run about 50% faster than 32-bit ones. In addition, your component will be able to access large amounts of memory, should that be needed. However, your 64-bit component will not be usable by someone with a 32-bit Windows operating system. If your component is a wrapper for another application, or if you are wrapping an existing third-party library, then you may need to match the bitness of your available database drivers, application drivers and libraries.

To configure to be 64-bit, select '''Build / Configuration Manager&#2026;'''. In the pulldown for '''Platform''', select <code><New&#2026;></code>. Set New platform=x64, copy settings from=Win32 and press OK. It should now look like this.

:[[image:COM_app_configuration_manager.png]]

== Creating the Object Class ==

Next, create the class that will get instantiated when you call [[COMCreateObject]] from Analytica. It is usually most convenient at this point to go to the '''Class View''' pane in Visual Studio.

Select '''Project / Add Class&#x2026; / ATL Simple Object''' and press '''Add'''.

(Note: In Visual Studio 2017 version 15.3.2, you have to select '''Add New Item... / Visual C++ / ATL / ATL Simple Object''' to get to the dialog)

:[[image:COM_cpp_add_class.png]]

Enter a ''short name'' for your class -- here I've named it <code>Counter</code>. Then fill in the ProgID. The ProgID will be the text you'll use when calling [[COMCreateObject]] from Analytica.

:[[image:COM_cpp_add_class1.png]]

Note: If at some point in the future you change your mind about what the ProgID should be, after you've created the class and implemented something so that you don't want to start over with the Wizard, you can change it by editing <code>IDR_«classname»</code> in the <code>"REGISTRY"</code> folder in your project resources. For example, in this case it is <code>IDR_COUNTER</code>.

On the next screen, select the threading model. In most cases you will probably want to use <code>Apartment</code>, especially if you don't understand the differences between these. In my case, I'll be using the Free threading model, which is the most challenging to program for. I am using the free threading model so that I can call a method multiple times concurrently on separate data sets.

:[[image:COM_cpp_add_class2.png]]

For use by Analytica, you must have Interface=Dual or Interface=Custom with automation compatible checked.  Press '''Finish''' to finalize the creating of the object class.

=== Setting the printable name ===

Next, set the printed representation that you'll see in the Analytica interface when it displays an instance of your object. This step is optional, but if you don't do it, your object will simply be shown as <code>«COM object»</code>. 

From the class view, right click on the interface class, <code>ICounter</code> in my case, and select '''Add / Add Method&#x2026;'''. Create a method that returns an <code>[out, retval]  BSTR*</code> result as shown here.

:[[image:COM_cpp_add_className_method1.png]]

The method name can be anything, I have used <code>ToText</code> here, you may prefer <code>ToString</code>. Make sure you press the '''Add''' button before pressing '''Next>'''. Set the <code>id</code> to 0. Analytica looks for a method with id=0 to see if the object can print itself. You may optionally select '''hidden''' when people are using tools to browse the methods of your class. Press '''Finish'''.

:[[image:COM_cpp_add_className_method2.png]]

Now, edit the <code>*.cpp</code> file for your class, <code>Counter.cpp</code> in my case.  You'll find the Add Method Wizard created an empty stub for your method, which you should now fill in to return the printed name of your object.

:[[image:COM_cpp_add_className_method4.png]]

== Register and test ==
Now that you have a class, you can run a test to verify that you can register (install) your component and instantiate it from Analytica.

Compile your project by selecting '''Build / Build solution'''. It should compile with no errors. 

Next, to register (install) the component, open a CMD window and CD to your project directory, and then CD into the <code>x64\Debug</code> directory where your project was just built. Type <code>YourProgram.exe /RegServerPerUser</code>.

:[[image:COM_cpp_regserver.png]]

This inserts entries into your system registry telling Windows (and thus Analytica) how to instantiate your component. To uninstall, run it with <code>/UnRegServerPerUser</code>.  The <code>/RegServerPerUser</code> installs the component for your user account only, and does not require system administration privileges. To install the component for all users on your computer, use <code>/RegServer</code>, but this only works if you run CMD and Administrator.

Finally, to test that you can create an instance, start Analytica and created a variable to hold the instance and define it as a call to <code>[[COMCreateObject]]</code> as seen here, replacing <code>"Rainfall.Counter"</code> with the ProgID of your own class.

:[[image:COM_cpp_test_instantiation.png]]

Evaluate. If you see an instance appear as in the preceding screenshot, you have a working class and are ready to start implementing methods.

Before you can compile anew, you'll need to have Analytica release the object. To do this, insert a space into the definition with [[COMCreateObject]] to cause the computed result to invalidate.

== Creating a method with scalar parameters and result ==

Here I demonstrate how to create a method that accepts scalar parameters and returns a scalar result. Suppose we want a method that accepts and integer, «base», and a double, «x», and returns the base «base» logarithm of «x».  To do this, right click on the interface name in the Class View panel (ICounter in my case) and select '''Add / Add Method&#x2026;'''. Sometimes the Class View pane in Visual Studio lists the interface multiple times (possible a bug?), in which use the one that has a sub-folder '''Base Type'''.

In the '''Add Method Wizard''', fill in the data types and names, as follows for the LogBase example.

:[[image:COM_cpp_logbase.png]]

As of [[Analytica 4.6]], pure <code>[out]</code> parameters are not supported in Analytica, so you should use only <code>[in]</code> parameters, with the very last parameter being a <code>[out,retval]</code> parameter if your method has a return value. The <code>[out,retval]</code> parameter needs to be a pointer parameter like <code>DOUBLE*</code>.

The second screen of the wizard selects an id for this method automatically and you don't need to make any changes on that screen. When the Wizard completes, open the <code>*.cpp</code> for your class, where you'll find the Wizard has added a method stub for you to fill in.

:[[image:COM_cpp_logbase_code.png]]

From Analytica, test this by creating a new variable that calls the method.
:<code>counter->LogBase(2,Pi)</code>
which evaluates to 1.651.  Note that <code>counter</code> is the variable defined previously which holds an instance of your COM component. You should insert a space in its definition to invalidate the result so that it lets go of the object, allowing you to recompile as you continue with your component development.

== Creating a method with Array parameter and result ==

I now add an method that accepts a 1-D array as input and computes a 1-D array as a result. This method is called <code>PeaksAndValleys</code> and filters out all points in the input array that are not a peak or valley. 

This parameter will be of type <code>SAFEARRAY<VARIANT></code>, and the result will be of type <code>SAFEARRAY<DOUBLE></code>. Although I really want a <code>SAFEARRAY<DOUBLE></code> for the input parameter, Analytica will pass arrays as a <code>SAFEARRAY<VARIANT></code>, you should always use a VARIANT element type on input parameters. 

Right-click on the interface name (<code>ICounter</code>) and select '''Add / Add Method&#x2026;'''. We are immediately faced with a problem -- SAFEARRAY does not appear as a data type option in the Visual Studio Wizard. Apparently they just forgot to include the array options, so just enter placeholder types for now.

:[[image:COM_cpp_AddMethod_PeaksAndValleys.png]]

Proceed through the second screen without making any changes. Next, open the <code>*.idl</code> file from the Solution Explorer pane. The Wizard has added this line to the IDL:

:<code>[id(2)] HRESULT PeaksAndValleys([in] VARIANT timeSeries, [out, retval] DOUBLE* result);</code>

Modify it by adding the SAFEARRAY type declaration so that it reads

:<code>[id(2)] HRESULT PeaksAndValleys([in] SAFEARRAY(VARIANT) timeSeries, [out, retval] SAFEARRAY(DOUBLE)* result);</code>

Next, edit the *.h file for your class (Counter.h in my case). Here the Wizard has added the line
:<code>STDMETHOD(PeaksAndValleys)(DOUBLE  /*in*/ timeSeries, DOUBLE* /*out,retval*/ result);</code>

which you need to modify to be
:<code>STDMETHOD(PeaksAndValleys)(SAFEARRAY* /*in*/ timeSeries, SAFEARRAY** /*out,retval*/ result) override;</code>

And in the <code>*.cpp</code> file (<code>Counter.cpp</code> in my case), change the parameter declarations in the same way.  To allow the method to be tested, you can also add one line of code copy the input into the result.

<pre style="background:white; border:white; margin-left: 1em;">
STDMETHODIMP CCounter::PeaksAndValleys(SAFEARRAY* /*in*/ timeSeries, SAFEARRAY** /*out,retval*/ result)
{
	SafeArrayCopy(timeSeries,result);
	return S_OK;
}
</pre>

You can test this from Analytica using 
:<code>counter->PeaksAndValleys(COMArray(Time^2,Time))</code>
In this expression, [[COMArray]] is used to pass a COM array in.  The result is a list.

=== Implementing the function ===

From here, the implementation of the logic is just a matter of writing C++ code. 

<pre style="background:white; border:white; margin-left: 1em;">
// Removes all points except those where the slope changes sign (the peaks and valleys).
void FilterNonPeaksAndValleys( vector<double>& x )
{	
	int prevSlope=0, nextSlope=0;					// sign of preceding slope
	size_t iDst=0, n=x.size();

	for (size_t iSrc=0 ; iSrc+1<n ; ++iSrc, prevSlope=nextSlope) {				// All but last point
		nextSlope = sign(x[iSrc+1] - x[iSrc]);
		bool bSignChange = iSrc==0 || (prevSlope!=0) && (prevSlope!=nextSlope);		// first point or sign change
		if (bSignChange) x[iDst++] = x[iSrc];
	}
	if (n>=2) x[iDst++] = x[n-1];				 // keep last point
	x.resize(iDst);
}

STDMETHODIMP CCounter::PeaksAndValleys(SAFEARRAY* /*in*/ timeSeries, SAFEARRAY** /*out,retval*/ result)
{
	vector<double> data;
	if (!SafeArray1DToVector(timeSeries,data))
		return E_INVALIDARG;

	FilterNonPeaksAndValleys(data);

	*result = VectorToSafeArray(data);

	return S_OK;
}
</pre>

Several helper functions are used in the above code. You may find the functions for converting from a SAFEARRAY to a C++ <code>std::vector</code> to be convenient.

<pre style="background:white; border:white; margin-left: 1em;">
class AlwaysFinalize {
	std::function<void()> fn_;
public: 
	AlwaysFinalize(std::function<void()> fn) : fn_(fn) {}

	~AlwaysFinalize() 
	{
		fn_();
	}
};

inline bool SafeArray1DToVector( SAFEARRAY* /*in*/ psa, vector<double>& /*out*/ vec)
{
	if (SafeArrayGetDim(psa) != 1) return false;

	VARIANT* pdata=nullptr;
	if (SafeArrayAccessData(psa,(void**)&pdata) != S_OK) return false;
	AlwaysFinalize rememberToUnaccess( [&](){ SafeArrayUnaccessData(psa); } );

	unsigned n = psa->rgsabound[0].cElements;
	vec.resize( n );

	for (unsigned i=0 ; i <n ; ++i) {
		_variant_t xi;
		if (VariantChangeType(/*dst*/ &xi,/*src*/ &pdata[i],0,VT_R8) != S_OK) return false;
		vec[i] = V_R8(&xi);
	}

	return true;
}
inline SAFEARRAY* VectorToSafeArray( const std::vector<double>& vec )
{
	unsigned n = (unsigned)vec.size();
	SAFEARRAYBOUND bounds;
	bounds.cElements = n;
	bounds.lLbound = 0;

	SAFEARRAY* psa = SafeArrayCreate(VT_R8,1,&bounds);
	double* pdata = nullptr;
	if (SafeArrayAccessData(psa,(void**)&pdata) == S_OK) {
		AlwaysFinalize rememberToUnaccess( [&](){ SafeArrayUnaccessData(psa); } );

		for (unsigned i=0 ; i<n ; ++i) {
			pdata[i] = vec[i];
		}
	}
	
	return psa;
}

template <typename T> int sign(T val) {
    return (T(0) < val) - (val < T(0));
}
</pre>

== Summary ==

This article has shown how to set up a Visual Studio project to build your own COM component that can be called from an Analytica model. 

== See Also ==
* [[COMCreateObject]]
* [[COM Integration]]
* [[RunConsoleProcess]]
* [[Writing your own COM component using VB.NET]]