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

TYX PAWS Studio version used: 1.26.8

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 an exe file as opposed to dll, which is 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 an exe with MSVC++ 6.0

1.1 Starting a simple ATL COM Application:

· Open the Visual Studio 6.0.

· From File | New…, select an ATL COM AppWizard, then select:

A project name NamSvr as seen below.
The location for the project. In this case C:\usr\NamSvr.

· Click on OK

· Select Executable (EXE) in the following window.

· Click on Finish.

· Click OK on the following window:

· The image below shows how the project should look like.

· Select the ‘+’ sign next to the NamSvr classes 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 Sample1.

Also, take note of the name in Prog ID: In this case NamSvr.Sample1 (exe 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 Support IsupportErrorInfo option.
The Custom for Interface as opposed to Dual. The 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 ArraySmp1 (Smp one and not the letter L).

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

1.3 Implementing COM-NAM interface

· For the WRTS to instantiate the COM-NAM object successfully, 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 CArraySmp1 Class

· After right clicking on CArraySmp1, 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 CSample1 Class.

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

· As shown on the above capture both classes CArraySmp1 and CSample1 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. The new lines of code are in bold:

· 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_SAMPLE1 101

#define IDR_ARRAYSMP1 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 CSample1 class by adding the following declaration in Sample1.h file as presented in the code below:

// Sample1.h : Declaration of the CSample1

#ifndef __SAMPLE1_H_

#define __SAMPLE1_H_

#include "resource.h" // main symbols

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

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

// CSample1

class ATL_NO_VTABLE CSample1 :

public CComObjectRootEx<CComSingleThreadModel>,

public CComCoClass<CSample1, &CLSID_Sample1>,

public ISupportErrorInfo,

public ISample1,

public INam

{

public:

CSample1()

{

}

DECLARE_REGISTRY_RESOURCEID(IDR_SAMPLE1)

DECLARE_PROTECT_FINAL_CONSTRUCT()

BEGIN_COM_MAP(CSample1)

COM_INTERFACE_ENTRY(ISample1)

COM_INTERFACE_ENTRY(ISupportErrorInfo)

COM_INTERFACE_ENTRY(INam)

END_COM_MAP()

// ISupportsErrorInfo

STDMETHOD(InterfaceSupportsErrorInfo)(REFIID riid);

// ISample1

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 //__SAMPLE1_H_

· In the Sample1.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:

// Sample1.cpp : Implementation of CSample1

#include "stdafx.h"

#include "NamSvr.h"

#include "Sample1.h"

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

// CSample1

STDMETHODIMP CSample1::InterfaceSupportsErrorInfo(REFIID riid)

{

static const IID* arr[] =

{

&IID_ISample1,

&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 CSample1::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 CSample1::Abort()

{

return E_NOTIMPL;

}

HRESULT CSample1::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 Sample1.h file remove the body for Run() and Abort() methods in order to avoid compiling errors. Leave clean methods declarations. Change the following lines:

// ISample1

public:

// INam

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

{

return E_NOTIMPL;

}

STDMETHOD(Abort)()

{

return E_NOTIMPL;

}

into:

// ISample1

public:

// INam

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

STDMETHOD(Abort)();

· In ArraySmp1.cpp file do the following changes:

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

// ArraySmp1.cpp : Implementation of CArraySmp1

#include "stdafx.h"

#include "NamSvr.h"

#include "ArraySmp1.h"

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

// CArraySmp1

STDMETHODIMP CArraySmp1::InterfaceSupportsErrorInfo(REFIID riid)

{

static const IID* arr[] =

{

&IID_IArraySmp1,

&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 CArraySmp1::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;