windows-xp/Source/XPSP1/NT/inetsrv/iis/svcs/cmp/devsmpl/controt

                      Content Rotator Component
                      =========================


Table of Contents
=================

    Overview
    Installation
    File List
    Sample ASP
    Build Notes
    Support
    Data Format
    Discussion of the Design
    Change Notes


Overview
========

The Content Rotator Component is an Active Server Pages component that
yields random selections of HTML from a data file.  It can be used for
such diverse applications as:
    * a tip-of-the-day generator
    * a random advertisement billboard
    * a poor man's load-balancing scheme for selecting email names of
      Tech Support people.


Installation
============

In order to use this component you must register it.  This will allow Active
Server Pages (ASP) Scripting Languages and other languages to make use of
the component.  ASP uses either the Server.CreateObject("ObjectName") syntax
or the <object id="myName" progid="ObjectName" runat="server"> syntax to
gain access to an object.  New objects can be made ready for use by
installing a new component.  Note: One component may contain more than one
object definition.

The following directions are to help you register the component for use:
 1. Use the Start menu, Programs option to start a Command Prompt
 2. Type the following:
	cd \InetPub\ASPSamp\Components\ContRot\DLL\i386
 3. Type:
	regsvr32 ContRot.dll
Note: you must register the component on each IIS server where you intend
to use it.

If you have trouble registering components, you may be using the wrong
version of RegSvr32.exe.  Please use the version installed by default in
the directory <InstallDir>\ASP\Cmpnts.  On Windows NT, the default
installation directory is \winnt\System32\Inetsrv.  On Windows 95, it is
\Program Files\WebSvr\System.

(If you rebuild the source code, the makefile will automatically reregister
the component for you.)

The following directions are to help you test the registered component:
 1. Use the Windows Explorer to copy all of the Sample files except
    global.asa from \InetPub\ASPSamp\Components\ContRot\Samples
    to \InetPub\ASPSamp\Samples.
 2. Copy global.asa to \InetPub\ASPSamp.  (Note: global.asa *must* be in a
    virtual root directory; the other files need not be.)
 3. In your browser, open http://localhost/ASPSamp/Samples/ContRot.htm
You must copy the sample files to a virtual directory; if you attempt to
examine them with a browser in the ContRot\Samples directory, ASP will not
execute the script.


File List
=========

File             Description
----             -----------

.\Source

 RotObj.cpp      the C++ source code for the content rotator component
 RotObj.h        declarations for CContentRotator
 ContRot.idl     declaration of IContentRotator, the IDispatch-based interface
 Makefile        a makefile that can be used with nmake
 ContRot.mak     the Developer Studio makefile
 debug.cpp       useful debugging stubs
 debug.h         useful debugging macros and declarations for debug.cpp
 ContRot.cpp     )
 ContRot.def     )
 ContRot.mdp     )
 ContRot.rc      )
 ContRtPS.def    } Generated by the ATL COM AppWizard
 ContRtPS.mak    )
 Resource.h      )
 StdAfx.cpp      )
 StdAfx.h        )

.\Samples

 ContRot.htm     Explains how to use the Content Rotator
 global.asa      session object setup
 fortunes.asp    session-level object demonstration; refreshes automatically
 fortunes.txt    sample Content Schedule File for fortunes.asp
 ufortune.txt    Unicode version of fortunes.txt
 techsupp.asp    page-level object ChooseContent demonstration
 techsupp.txt    another sample Content Schedule File
 cr-proof.asp    demonstration of GetAllContent for proof-reading


Samples
=======

You will need to copy the sample files to a virtual directory on an
IIS Server.  Note that global.asa (and hence fortunes.asp and
techsupp.asp) will not work unless global.asa is in a virtual root.

There are two examples of using ChooseContent: one as a page-level
object (techsupp.asp) and one as a session-level object
(fortunes.asp).  Note that if you repeatedly refresh techsupp.asp, the
distribution of content that you will see will almost certainly not
match the weights specified in techsupp.txt.  If you look at
fortunes.asp, you will see that the distributions of fortunes is
correct.  See the Discussion of the Design section below for why this
is so.

If a user is likely to visit a page with a content rotator only once,
then it doesn't really matter whether it's a session-level object or
not.  If a user revisits a page several times within a few minutes,
which is quite likely if it's a key page they have to keep navigating
through, or if the same content rotator is used on multiple pages,
then it should be a session-level object.

Ufortune.txt is included only to demonstrate that the Content Rotator
really does work when it's built as a Unicode DLL and is of little
practical use.  You can use NT's notepad.exe to write files in Unicode
format: check "Save as Unicode" on the Save As dialog box.


Build Notes
===========

This sample requires Microsoft Visual C++ 4.2b or newer.  If you are using
VC 4.2, it is necessary that you upgrade to VC 4.2b, using the patch which
can be found at http://www.microsoft.com/visualc/patches/v4.2b/vc42b.htm
Note that this patch will not work with earlier or later versions of
Visual C++, only with VC 4.2.

This sample also requires ATL (Microsoft Active Template Library)
version 2.0 or newer.  ATL 2.1 ships with Visual C++ 5.0.  ATL 2.0 for
VC 4.2b can be downloaded from: http://www.microsoft.com/visualc/prodinfo/
You do not need the ATL Docs or Object Wizard Technology Preview to build
the registry access component, but you will probably find them useful.

If you get an error about "don't know how to make asptlb.h", you will
need to copy <InstallDir>\ASP\Cmpnts\AspTlb.h to your include
directory.

You can build this component with nmake at the command line.  Read
Makefile for more details.  You can also build it in Microsoft
Developer Studio, using the ContRot.mdp project.

The component can be built as ANSI or Unicode.  If you intend to
run it on Windows 95, build it as ANSI.  If you build it as a
Unicode DLL, all data files will need to be in Unicode format.


Support
=======

This component is not officially supported by Microsoft Corporation.
Peer support is available on the Active Server Pages mailing list or on
the microsoft.public.inetserver.iis.activeserverpages newsgroup.

To subscribe to the Active Server Pages mailing list, send mail to
[email protected] with

subscribe Denali [firstname lastname]

in the body of the message, and then follow the directions carefully.
(firstname and lastname are optional.)

You can reach the newsgroup through msnews.microsoft.com and other NNTP
servers.


Data Format
===========

You can find examples of Content Schedule files in the Samples directory.


Discussion of the Design
========================

The Content Rotator is best used as a session-level object, rather
than a page-level object.  It caches the contents of the data file,
which gives you two benefits at the cost of using some more memory:
it's faster on second and subsequent invocations and you get much
better random distribution of the data, as it takes some care to
ensure that each entry is served up no more than its fair share of
times.

When it's used as a page-level object, you do not benefit from its
caching of the data.  More importantly, you are much more likely to
perceive a less random permutation of the data if you repeatedly
refresh the page.  This is because there is no way to ensure a
properly random distribution of the data if the Content Rotator object
is created afresh each time the page is visited.  See the Samples
directory for an example of how to use the Content Rotator as a
session-level object.

It is technically impossible to use the Content Rotator as an
application-level object (because application-level objects do not
receive the OnStartPage call which is needed to get a pointer to the
Server object so that its MapPath method can be called to translate
the virtual path of the data filename into a physical filesystem
path), or that would be the recommended way to use it.  It would be
very easy for you to change the ChooseContent and GetAllContent
methods to work with a physical data path.

The Page Counter sample component demonstrates an alternative method
of caching data between invocations.  The Page Counter DLL has a
global object (the Central Counter Manager) which tracks hits across
all pages and takes care of writing the data to persistent storage
periodically.  When a Page Counter object is created, it modifies the
global CCM as necessary.  Creating a global cache for the Content
Rotator would be more complicated because it would have to cache
multiple data files simultaneously.

Note that if you create a single content rotator object and you have
it use several data files on different pages, then the benefits of
caching the data are nullified.  Far better to create one object for
each datafile, especially if the datafile is used in more than one
place.

The discussion of critical sections in RotObj.cpp may also be of
interest.


Change Notes
============

Beta 1: February 1997
---------------------

First release.


Beta 2: March 1997
------------------

* Fixed Developer Studio makefile problems in C++ components.
* Upgraded to build cleanly with ATL 2.0 (Visual C++ 4.2b) and ATL 2.0 (VC5).
* Type Library name changes
* Check for new returning NULL a la ATL itself