This document will help with creating the COM-NAM component (server) for Paws RTS (client).

TYX PAWS Studio version used: 1.26.0

MSVC++ version used: 6.0

Requirements: Studio 1.10.x or above. Backward and forward compatibility between the COM build with one version of the Studio library and other Studio versions is not guarantied.

Introduction: This document describes how to create a Non-ATLAS Module (NAM) as a Common Object Component (COM-NAM). We use Active Template Library (ATL) to produce a COM component also called a server. The application that uses COM is Paws RTS – a client. In this scenario COM component is stored in a .dll file as opposed to .exe, which will be covered in another document. The last part of the document is dedicated to the TYX PAWS Studio environment and Atlas example in particular.

Dll versus Exe:

1. Advantage of Dlls versus Exe:

· The Dll uses fewer resources than the Exe.

· The Dll can easily remain on top of the Wrts.

· The accelerators are directly passed on to the Wrts without additional code. When the Exe has the focus, it will need some code in order to pass on the accelerator destined for the Wrts.

· The message loop for painting the GUI is taken care of by the Wrts. For the Exe, the code needs to be placed into the Exe which may be done by the wizard to some extent.

· The Dll will be slightly faster than the Exe. This will however only make a difference for repeated transfer of a large amount of data.

2. Advantage of the Exe versus Dll:

· The Exe is more isolated than the Dll and if it crashes, it will not affect the Wrts. This may be an issue if the Exe links to code that is not stable.

· The Exe can be moved in front or behind the Wrts at will.

· The Exe can be run remotely.

1 Generating a dll with MSVC++ 6.0

1.1 Starting a simple ATL COM Application:

· From File | New…, select an ATL COM Application and select a project name NamSvr as seen below:

· Click on OK

· Select Dynamic Link Library (DLL) in the following window.

· Click on Finish.

· Click OK on the following window:

· Image below shows, how the project should look like.

· Select the ‘+’ sign next to the NamSvr classes and Globals folders to see all the methods generated automatically by the Wizard.

1.2 Adding the ATL object

· Go to the Insert on the Menu Bar and select New ATL Object…

· You should see the following window:

· Select Simple Object and click on Next.

· You will then see the following window. In the Short name: box, enter the name of the ATL object that you wish to create. The other boxes will fill in by themselves. In this case, we chose the name Sample.

Also, take note of the name in Prog ID: In this case NamSvr.Sample (dll name followed by the short name). This will be used as an entry in the Wrts options.

· In the list of attributes, as shown below, all defaults can be acceptable. You may want to add the option of Support IsupportErrorInfo and Custom for Interface as seen below. Custom option checked causes the COM interface to support only the IUnknown capability, which is sufficient for this project..

· Click on OK.

· If you get the following window:

· Click on Yes. If not, just proceed.

· Now we are back to the MS Studio.

· You need to repeat the previous steps to add another ATL object. As a short name use ArraySmpl.

· At this point you should get the following classes and method under ClassView:

1.3 Implementing COM-NAM interface

· For Wrts to instantiate successfully the COM-NAM object the object must implement the proper interface. That is why the project needs to link to an interface, which is what will be described in the next steps.

· In the workspace, you should right-click on the CArraySmpl Class

· After right clicking on CArraySmpl, Select Implement Interface… from the drop-down list.

· You will get the following message and then click on OK.

· In the event that you see the following image instead of the previous one, press AddTypelib…

· Select the ComNam type library and then click on OK. If you do not see ComNam, it is because you are using a version of the TYX Paws Studio that is older than 1.10.x.

· In the following window, you need to check INam interface and then click on OK.

· Repeat the previous steps for implementing the same INam interface for the CSample Class.

· Once completed, you should get the following display under ClassView:

· As shown on the above capture both classes CArraySmpl and CSample received two additional methods: Abort() and Run() after implementing the INam interface.

1.4 Developing the project

· You reached the point when all the procedures related to the automatic code generation were accomplished. From now on you need to adjust and develop the code manually.

· In the Resource.h file add the additional directive as shown in the code in bold below:

//{{NO_DEPENDENCIES}}

// Microsoft Developer Studio generated include file.

// Used by NamSvr.rc

#define IDS_PROJNAME 100

#define IDR_SAMPLE 101

#define IDR_ARRAYSMPL 102

#define IDS_E_UNEXPECTEDPARAM 0x201 //added directive

// Next default values for new objects

#ifdef APSTUDIO_INVOKED

#ifndef APSTUDIO_READONLY_SYMBOLS

#define _APS_NEXT_RESOURCE_VALUE 201

#define _APS_NEXT_COMMAND_VALUE 32768

#define _APS_NEXT_CONTROL_VALUE 201

#define _APS_NEXT_SYMED_VALUE 103

#endif

· Add an extra member function ChangeData() to the CSample class by adding the following declaration in Sample.h file as presented in the code below:

// Sample.h : Declaration of the CSample

#ifndef __SAMPLE_H_

#define __SAMPLE_H_

#include "resource.h" // main symbols

#import "c:\usr\tyx\com\ComNam.dll" raw_interfaces_only, raw_native_types, no_namespace, named_guids

/////////////////////////////////////////////////////////////////////////////

// CSample

class ATL_NO_VTABLE CSample :

public CComObjectRootEx<CComSingleThreadModel>,

public CComCoClass<CSample, &CLSID_Sample>,

public ISupportErrorInfo,

public ISample,

public INam

{

public:

CSample()

{

}

DECLARE_REGISTRY_RESOURCEID(IDR_SAMPLE)

DECLARE_PROTECT_FINAL_CONSTRUCT()

BEGIN_COM_MAP(CSample)

COM_INTERFACE_ENTRY(ISample)

COM_INTERFACE_ENTRY(ISupportErrorInfo)

COM_INTERFACE_ENTRY(INam)

END_COM_MAP()

// ISupportsErrorInfo

STDMETHOD(InterfaceSupportsErrorInfo)(REFIID riid);

// ISample

public:

// INam

STDMETHOD(Run)(VARIANT varArgs, LONG lNamOptions, INamServices * pNamServices, VARIANT varReserved)

{

return E_NOTIMPL;

}

STDMETHOD(Abort)()

{

return E_NOTIMPL;

}

// utility functions

HRESULT ChangeData(long lVad, INamServices* pNamServices); // added

};

#endif //__SAMPLE_H_

· In the Sample.cpp make the following changes:

Add an ID &IID_INam for proper error reporting (and add a comma to the end of the previous line).
Implement the code for Run() method
Implement the code for Abort() method
Implement the code for ChangeData() method

Those changes are shown below in bold:

// Sample.cpp : Implementation of CSample

#include "stdafx.h"

#include "NamSvr.h"

#include "Sample.h"

/////////////////////////////////////////////////////////////////////////////

// CSample

STDMETHODIMP CSample::InterfaceSupportsErrorInfo(REFIID riid)

{

static const IID* arr[] =

{

&IID_ISample,

&IID_INam

};

for (int i=0; i < sizeof(arr) / sizeof(arr[0]); i++)

{

if (InlineIsEqualGUID(*arr[i],riid))

return S_OK;

}

return S_FALSE;

}

STDMETHODIMP CSample::Run(VARIANT varArgs, LONG lNamOptions, INamServices * pNamServices, VARIANT varReserved)

{

if (varArgs.vt != (VT_ARRAY | VT_I4))

return Error(IDS_E_UNEXPECTEDPARAM);

SAFEARRAY* pSafeArray = varArgs.parray;

long lArgsIdxMax; //get the maxim index for this safearray

HRESULT hr = ::SafeArrayGetUBound(pSafeArray, 1, &lArgsIdxMax);

if (FAILED(hr)) return hr;

if (lArgsIdxMax != 4)

return Error(IDS_E_UNEXPECTEDPARAM);

// arguments

long lVad;

long lArgsIdx[1];

for (int nArgsIdx = 0; nArgsIdx <= lArgsIdxMax; nArgsIdx++)

{

lArgsIdx[0] = nArgsIdx;

hr = ::SafeArrayGetElement(pSafeArray, lArgsIdx, &lVad);

if (FAILED(hr)) return hr;

hr = ChangeData(lVad, pNamServices);

if (FAILED(hr)) return hr;

}

return S_OK;

}

STDMETHODIMP CSample::Abort()

{

return E_NOTIMPL;

}

HRESULT CSample::ChangeData(long lVad, INamServices* pNamServices)

{

CComVariant varVal;

HRESULT hr = pNamServices->GetData(lVad, &varVal);

if (FAILED(hr)) return hr;

long lTypeInfo;

hr = pNamServices->GetType(lVad, &lTypeInfo);

if (FAILED(hr)) return hr;

long lType = lTypeInfo & 0xf;

if (varVal.vt == VT_BOOL)

// BOOL

varVal.boolVal = !varVal.boolVal;

else if (varVal.vt == VT_I4)

// INTEGER

varVal.lVal++;

else if (varVal.vt == VT_R8)

// DECIMAL(REAL)

varVal.dblVal += 1.234;

else if (varVal.vt == VT_BSTR && lType == NAM_TYPE_TEXT)

{

// TEXT (STRING OF CHAR)

hr = varVal.Clear();

if (FAILED(hr)) return hr;

varVal = CComBSTR("Modified Text");

}

else if (varVal.vt == (VT_ARRAY | VT_UI2))

{

// DIGITAL

// check the size for digital

long lDigIdxMax; //get the maxim index for this safearray

HRESULT hr = ::SafeArrayGetUBound(varVal.parray, 1, &lDigIdxMax);

if (FAILED(hr)) return hr;

if (lDigIdxMax != 0)

return Error(IDS_E_UNEXPECTEDPARAM);

// check the excess for digital

if (((lTypeInfo & NAM_EXCESSMASK) >> 4) != 0)

return Error(IDS_E_UNEXPECTEDPARAM);

// modify the only digital word

long lWordIndex[1];

lWordIndex[0] = 0;

unsigned short* pWord;

hr = ::SafeArrayPtrOfIndex(varVal.parray, lWordIndex, (void**)&pWord);

if (FAILED(hr)) return hr;

*pWord ^= 0xffff;

}

else

return Error(IDS_E_UNEXPECTEDPARAM);

return pNamServices->PutData(lVad, varVal);

}

· In the Sample.h file remove the body for Run() and Abort() methods in order to avoid compiling errors. Leave clean methods declarations. Change the following lines:

// ISample

public:

// INam

STDMETHOD(Run)(VARIANT varArgs, LONG lNamOptions, INamServices * pNamServices, VARIANT varReserved)

{

return E_NOTIMPL;

}

STDMETHOD(Abort)()

{

return E_NOTIMPL;

}

into:

// ISample

public:

// INam

STDMETHOD(Run)( VARIANT varArgs, LONG lNamOptions, INamServices * pNamServices, VARIANT varReserved);

STDMETHOD(Abort)();

· In ArraySmpl.cpp file do the following changes:

add an ID &IID_INam
implement the code for Run() method
implement the code for Abort() method

// ArraySmpl.cpp : Implementation of CArraySmpl

#include "stdafx.h"

#include "NamSvr.h"

#include "ArraySmpl.h"

/////////////////////////////////////////////////////////////////////////////

// CArraySmpl

STDMETHODIMP CArraySmpl::InterfaceSupportsErrorInfo(REFIID riid)

{

static const IID* arr[] =

{

&IID_IArraySmpl,

&IID_INam

};

for (int i=0; i < sizeof(arr) / sizeof(arr[0]); i++)

{

if (InlineIsEqualGUID(*arr[i],riid))

return S_OK;

}

return S_FALSE;

}

STDMETHODIMP CArraySmpl::Run(VARIANT varArgs, LONG lNamOptions, INamServices * pNamServices, VARIANT varReserved)

{

if (varArgs.vt != (VT_ARRAY | VT_I4))

return Error(IDS_E_UNEXPECTEDPARAM);

SAFEARRAY* pSafeArray = varArgs.parray;

long lArgsIdxMax; //get the maxim index for this safearray

HRESULT hr = ::SafeArrayGetUBound(pSafeArray, 1, &lArgsIdxMax);

if (FAILED(hr)) return hr;

if (lArgsIdxMax != 1) // 1 is for two arguments(arg number 0 and arg number 1)

return Error(IDS_E_UNEXPECTEDPARAM);

// get the vad for the integer array(which is the vad of its first element)

long lArgsIdx[] = {0};

long vadInts;

hr = ::SafeArrayGetElement(pSafeArray, lArgsIdx, &vadInts);

if (FAILED(hr)) return hr;

// get the vad for the array size

lArgsIdx[0] = 1;

long vadArraySize;

hr = ::SafeArrayGetElement(pSafeArray, lArgsIdx, &vadArraySize);

if (FAILED(hr)) return hr;

// get the size of the size array

CComVariant varArraySize;

hr = pNamServices->GetData(vadArraySize, &varArraySize);

if (FAILED(hr)) return hr;

if (varArraySize.vt != VT_I4)

return Error(IDS_E_UNEXPECTEDPARAM);

// increment all elements of the integer array

for (int i = 0; i < varArraySize.lVal; i++)

{

// get the array element whose vad is vadInts

CComVariant varInt;

hr = pNamServices->GetData(vadInts, &varInt);

if (FAILED(hr))

return hr;

if (varInt.vt != VT_I4)

return Error(IDS_E_UNEXPECTEDPARAM);

// increment its value

varInt.lVal++;

// put the incremented value back in the array

hr = pNamServices->PutData(vadInts, varInt);

if (FAILED(hr))

return hr;

// Steps for passing to the next element of the array:

// Step one: get the type of the current element

long nTypeInfo;