// output some starting information<BR>
fprintf(m_fileLog, _T(&quot;************************\n&quot;));<BR>
fprintf(m_fileLog, _T(&quot;Start %s\n&quot;), (LPCTSTR) oTimeStamp.Format (&quot;%B
%#d, %Y, %I:%M %p&quot;));<BR>
fprintf(m_fileLog, _T(&quot;\n&quot;));<BR>
}<BR>
}<BR>
CTracker::~CTracker()<BR>
{<BR>
// if we have a file handle<BR>
if(m_fileLog)<BR>
{<BR>
// output some closing information<BR>
CTime oTimeStamp = CTime::GetCurrentTime();<BR>
fprintf(m_fileLog, _T(&quot;\n&quot;));<BR>
fprintf(m_fileLog, _T(&quot;End %s\n&quot;), oTimeStamp.Format <BR>
(&quot;%B %#d, %Y, %I:%M %p&quot;));<BR>
fprintf(m_fileLog, _T(&quot;************************\n&quot;));<BR>
// close the file<BR>
fclose(m_fileLog);<BR>
}<BR>
<BR>
// if we have valid timer services<BR>
if(m_lTimeBegin == TIMERR_NOERROR)<BR>
// reset the timer to its original state<BR>
timeEndPeriod(1);<BR>
// make sure that the application can unloaded<BR>
::AfxOleUnlockApp();<BR>
}<BR>
. . .</TT></FONT></P>
<P>Finally you update the build settings for the project. Since the sample implementation
is using some timer functions defined in mmsystem.h, you also need to be linked with
the appropriate library file that contains their implementation. Under the <U>P</U>roject
menu, select the <U>S</U>ettings menu item. In the Project Settings dialog, from
the <U>S</U>ettings For drop-down list box, select the All Configurations entry.
Select the Link tab, and add the file winmm.lib to the Object/<U>l</U>ibrary modules
edit field. Click OK to close the dialog.</P>
<P>The basic support code needed for the sample implementation is now added. The
server will open a file in its constructor and leave the file open during its entire
lifetime. When the server is destroyed, the destructor will be called, and the file
will be closed.</P>
<P>The next step is to make the sample more meaningful by adding methods and properties,
which are used to output data to the open file.
<H2><A NAME="Heading13"></A>Adding Methods</H2>
<P>An <I>automation method</I> consists of zero to <I>n </I>parameters and may or
may not have a return value. The term <I>method</I> is synonymous with function or
subroutine, depending on the particular language you are familiar with. Since your
server is <TT>IDispatch</TT>-based, you are limited to a specific set of data types.
Only those data types that are valid <TT>VARIANT</TT> data types can be passed or
returned via a method.</P>
<P>The rules for declaring parameters and how they are used is very much like C++
and VB. Methods can pass parameters by value or by reference and may also declare
them as optional, meaning that the parameter does not have to be supplied.</P>
<P>When passing a parameter by value, a copy of the data is sent to the method, and
when passing by reference, the address of the parameter is passed, allowing the method
to change the data.</P>
<P>Optional parameters are handled a little differently than C++, however, since
you can't specify a default value in the traditional C++ sense. Optional parameters
must be passed as <TT>VARIANT</TT> data types and not the actual data type they represent.</P>
<P>For developers using VB to access a method with optional parameters, VB will supply
the parameter for you if one has not been provided. With C++, you are still required
to supply a <TT>VARIANT</TT> parameter even though it may not contain any data.</P>
<P>As we stated at the beginning of the chapter, the sample Automation Server will
be used to log strings of data to a file. The server will define the method <TT>OutputLines</TT>,
which is used by the user of the server to supply the string data that is written
to the file. The method will accept an array of strings and an optional indentation
parameter and will output the strings to the file. The indentation parameter is used
to offset the strings by <I>n </I>number of tab characters to provide simple, yet
effective, formatting to the data as it is output to the file.</P>
<P>From the <U>V</U>iew menu, select the Class<U>W</U>izard menu item. Select the
Automation tab, and click the <U>A</U>dd Method button. In the Add Method dialog
enter an <U>E</U>xternal name of <TT>OutputLines</TT> and a Return <U>t</U>ype of
<TT>BOOL</TT> (see fig. 3.5). <B><BR>
<BR>
</B><A HREF="Art/03/cfig5r.jpg"><B>FIG. 3.5</B></A> <I><BR>
Add the <TT>OutputLines</TT> method with the ClassWizard.</I></P>
<P><IMG SRC="bar.gif" WIDTH="480" HEIGHT="6" ALIGN="BOTTOM" BORDER="0"></P>


<BLOCKQUOTE>
	<P><B>Boolean Data Type Differences Between VC++ and VB</B><BR>
	It is important to note a fundamental difference between VC++ and VB when using Boolean
	data types. The Boolean data type is defined by C++ as being of type integer that
	is a 32-bit value. For VB, however, an integer is 16-bit. For simple MFC-based Automation
	Servers, the difference in sizes between a VB integer and VC++ integer is not a problem
	since MFC hides the details involving the conversion of the 32-bit value to a 16-bit
	value, and vice versa. For dual-interface applications, though, the size difference
	poses a significant problem. When accessing the custom interface of a dual-interface
	server, the functions are called in the same fashion as any other function in an
	application. Basically, the parameters of the function are pushed on to a stack,
	and the function is called. When the function executes, the parameters are then popped
	off the stack. If VB calls a function in VC++, the stack will become corrupt because
	of the different sizes that each language uses for the Boolean data type. To be safe,
	VC++ applications should define all Boolean data types as type <TT>VARIANT_BOOL</TT>,
	which is defined by OLE as a 16-bit value and which is guaranteed to be the same
	size regardless of the language or tool being used. The actual Boolean data value
	is different between VB and VC++ also. VB developers are used to Boolean values of
	0 indicating <TT>FALSE</TT> and -1 indicating <TT>TRUE</TT>. For those of you who
	may be wondering why, the binary values for each is 00000000 and 11111111, respectively.
	For C++ programmers, Boolean data values are usually defined as 0 for <TT>FALSE</TT>
	and 1 or non-zero for <TT>TRUE</TT>.

</BLOCKQUOTE>

<P><IMG SRC="bar.gif" WIDTH="480" HEIGHT="6" ALIGN="BOTTOM" BORDER="0">

<DL>
	<DT>The differences in Boolean data values can cause considerable problems when integrating
	VB and VC++ applications. In addition, VB 4 has some behavioral differences in its
	language, depending on the value being tested. Some VB functions do not test for
	0 or non-zero and will test for the absolute value of 0 or -1, and vice versa, depending
	on the data type and function. When using Boolean data types, it is wise to also
	use the <TT>VARIANT_FALSE</TT> and <TT>VARIANT_TRUE</TT> constants to define the
	value of the variable.</DT>
</DL>

<P><TT>OutputLines</TT> is defined as having two parameters: <TT>varOutputArray</TT>
as a <TT>VARIANT</TT> passed by reference, which will contain a string array of data
to output to the file, and <TT>varIndent</TT> as a <TT>VARIANT</TT> passed by value,
which is also an optional parameter indicating the amount of indentation when writing
the string data to the file. To add the method parameters, double-click the line
in the <U>P</U>arameter list that is directly below the Name column, and type varOutputArray.
Click directly under the Type column to activate the Type drop-down list box. Select
<TT>VARIANT *</TT> from the list. Repeat the same process for <TT>varIndent</TT>,
but set the data type to <TT>VARIANT</TT>.</P>
<P>Due to data type restrictions imposed by Automation, you cannot pass arrays as
parameters of methods. You can, however, pass <TT>VARIANT</TT> data types that can
contain arrays, thus the reason for defining <TT>varOutputArray</TT> as a <TT>VARIANT</TT>.
You are also required to pass <TT>varOutputArray</TT> by reference because the array
stored in the <TT>VARIANT</TT> does not get copied over when it is passed by value.</P>
<P>Optional parameters must fall at the end of the parameter list and must be of
type <TT>VARIANT</TT> (see Listing 3.6). <TT>varIndent</TT> is an optional parameter
that indents the text output as an added formatting feature.</P>
<P>Click OK to add the method.</P>
<P>Click OK in the MFC ClassWizard dialog to close the ClassWizard. Remember that
the ClassWizard also added an entry to the ODL file as well as the header and source
files.</P>
<P>It is a function of the ODL file to declare a parameter of a method as being optional.
To be optional, a parameter must be declared with the optional parameter attribute
(see Listing 3.6), which you are required to add by hand since the ClassWizard will
not add it for you.
<H3><A NAME="Heading14"></A>Listing 3.6 MFCSERVER.ODL--Updated ODL Entry for OutputLines
Method</H3>
<P><FONT COLOR="#0066FF"><TT>// NOTE - ClassWizard will maintain method information
here. <BR>
// Use extreme caution when editing this section. <BR>
//{{AFX_ODL_METHOD(CTracker) <BR>
[id(1)] boolean OutputLines(VARIANT* varOutputArray, <BR>
[optional] VARIANT varIndent); <BR>
<BR>
//}}AFX_ODL_METHOD </TT></FONT></P>
<P>Before you add the implementation of the <TT>OutputLines</TT> method, you need
to add a member variable to the class definition (see Listing 3.7). The new member,
<TT>m_lIndent</TT>, is used to store the current indentation level between calls
to the method <TT>OutputLines</TT>.
<H3><A NAME="Heading15"></A>Listing 3.7 TRACKER.H--New Member Variable Added to the
Tracker Class</H3>
<P><FONT COLOR="#0066FF"><TT>protected: <BR>
FILE * m_fileLog; <BR>
long m_lTimeBegin; <BR>
long m_lHiResTime; <BR>
long m_lLastHiResTime; <BR>
long m_lIndent; <BR>
<BR>
}; </TT></FONT></P>
<P>You also need to update the constructor to initialize the member to a valid starting
value (see Listing 3.8).
<H3><A NAME="Heading16"></A>Listing 3.8 TRACKER.CPP--Member Initialization in the
Constructor</H3>
<P><FONT COLOR="#0066FF"><TT>CTracker::CTracker() <BR>
{<BR>
. . .<BR>
m_lIndent = 0;<BR>
}</TT></FONT></P>
<P>Listing 3.9 shows the implementation of the <TT>OutputLines</TT> method. First
you check to see if you have a valid file handle and array of string data. The next
step is to lock down the array so that you can perform operations on it. This step
is required for all functions that manipulate safe arrays. The next function determines
the starting point of the array, which can be either 0 or 1. This procedure is very
important to implement since programming languages such as C++ define a base of 0
for arrays, and languages such as VB can define a base of 0 or 1. Next you retrieve
the number of dimensions in the array. Note that this value represents the number
of dimensions and not the last dimension relative to the lower bound value.</P>
<P>After establishing the boundaries of the array, you check to see if you have received
an indentation value also. You want to receive a long, <TT>VT_I4</TT>, but if you
don't receive it, you try to convert the data that was given to you to a usable value.
If you can't convert the data, you simply use the value that the variable already
contains. To indent the text, concatenate from 1 to <I>n </I>tab characters into
a string.</P>
<P>For each of the elements in the array of strings, get the current time and the
data associated with each element, and output them along with the indentation string
to the open file--and don't forget to free the string element when you finish with
it.</P>
<P>The last step is to unlock the array and exit the method with the proper return
value.
<H3><A NAME="Heading17"></A>Listing 3.9 TRACKER.CPP--OutputLines Method Implementation</H3>
<P><FONT COLOR="#0066FF"><TT>. . . <BR>
///////////////////////////////////////////////////////////////////////////// <BR>
// CTracker message handlers <BR>
BOOL CTracker::OutputLines(VARIANT FAR* varOutputArray, const VARIANT FAR&amp; varIndent)
<BR>
{ <BR>
BOOL bResult = VARIANT_TRUE; <BR>
// if we have a file a if the variant contains a string array <BR>
if(m_fileLog &amp;&amp; varOutputArray-&gt;vt == (VT_ARRAY | VT_BSTR)) <BR>
{ <BR>
// lock the array so we can use it <BR>
if(::SafeArrayLock(varOutputArray-&gt;parray) == S_OK) <BR>
{ <BR>
LONG lLBound; <BR>
// get the lower bound of the array <BR>
if(::SafeArrayGetLBound(varOutputArray-&gt;parray, 1, &amp;lLBound) == S_OK) <BR>
{ <BR>
LONG lUBound; <BR>
// get the number of elements in the array <BR>
if(::SafeArrayGetUBound(varOutputArray-&gt;parray, 1, &amp;lUBound) == S_OK) <BR>
{ <BR>
CString cstrIndent; <BR>
CTime oTimeStamp; <BR>
BSTR bstrTemp; <BR>
// if we have an indent parameter <BR>
if(varIndent.vt != VT_I4) <BR>
{ <BR>
// get a variant that we can use for conversion purposes <BR>
VARIANT varConvertedValue; <BR>
// initialize the variant <BR>
::VariantInit(&amp;varConvertedValue); <BR>
// see if we can convert the data type to something useful - VariantChangeTypeEx()
could also be used <BR>
if(S_OK == ::VariantChangeType(&amp;varConvertedValue, (VARIANT *) &amp;varIndent,
0, VT_I4)) <BR>
// assign the value to our member variable <BR>
m_lIndent = varConvertedValue.lVal; <BR>
} <BR>
else <BR>
// assign the value to our member variable <BR>
m_lIndent = varIndent.lVal; <BR>
// if we have to indent the text <BR>
for(long lIndentCount = 0; lIndentCount &lt; m_lIndent; lIndentCount++) <BR>
// add a tab to the string <BR>
cstrIndent += _T(&quot;\t&quot;); <BR>
// for each of the elements in the array <BR>
for(long lArrayCount = lLBound; lArrayCount &lt; (lUBound + lLBound); lArrayCount++)
<BR>
{ <BR>
// update the time <BR>
oTimeStamp = CTime::GetCurrentTime(); <BR>
m_lHiResTime = timeGetTime(); <BR>
// get the data from the array <BR>