README.TXT

Multilingual Simple and Power Samples 
                ===================================== 
 
 
Table of Contents 
================= 
 
    Overview 
    Developing Components 
    C++ 
    ATL 
    Installation 
    Directory List 
    Usage 
    Sample ASP scripts 
    Support 
    Change Notes 
 
 
Overview 
======== 
 
Here, for your edification, are two Active Server Pages components, 
each implemented in two different environments: C++/ATL (Microsoft 
ActiveX Template Library) and Microsoft Visual Basic 5. 
 
The implementations are functionally equivalent.  Each implementation 
should behave in exactly the same way.  Each implementation is written 
in an idiomatic style to demonstrate the best way to implement the 
component in that environment. 
 
The Simple component has one method (myMethod) and one property 
(myProperty), which can be both retrieved (get) and modified (set). 
MyMethod converts a string to uppercase; myProperty is a string in the 
object that can be get or set.  There is nothing ASP-specific about 
the Simple component and, if desired, it could be used from any OLE 
container. 
 
The Power component (found in the \intermediate folder) is a superset 
of the Simple component.  In addition to myMethod and myProperty, it  
has myPowerMethod and myPowerProperty (gettable but not settable),  
which demonstrate some ASP-specific features.  Two other standard but 
optional ASP methods are also provided: OnStartPage and OnEndPage.   
These methods bracket the lifetime of a page.  OnStartPage is needed  
to gain access to the intrinsic ASP objects: Request, Response,  
Server, Application, and Session. 
 
MyPowerMethod and myPowerProperty make use of the Request and Response 
objects: Request to gain access to the ServerVariables collection and 
thereby the ScriptName and the HttpUserAgent (user's browser) 
variables; Response to write directly back to the user's browser. 
MyPowerProperty returns the name of the ASP script from which it was 
called.  MyPowerMethod writes a browser-dependent message back to the 
user's browser; one for Microsoft Internet Explorer, a different one 
for anything else. 
 
 
Developing Components 
===================== 
 
You can develop ASP components in Visual C++, Visual J++, Visual 
Basic, or any other language that builds ActiveX COM objects. 
 
These samples are written for IIS 4.0.  You must have the latest 
version of IIS to compile and use these components.  You must 
also have installed Microsoft Transaction Server (part of the Windows 
NT 4.0 Option Pack). 
 
 
C++ 
=== 
 
The C++ samples require Microsoft Visual C++ 5.0 or newer along with 
ATL (which comes with VC5). 
 
If you get an error about "don't know how to make asptlb.h" for the 
power samples, you will need to copy 
 
<InstallDir>\iissamples\sdk\include 
 
to your include directory, \Program Files\DevStudio\VC\include.   
The default installation directory is C:\Inetpub. 
 
Finally you must have the lastest version of MS Transaction Server 
installed (part of Windows NT 4.0 Option Pack).  Add the include path  
and library path of MTX before any system directories under 
Tools:Options....  So your include path might look like this: 
c:\program files\mts\include;c:program files\devstudio\vc\include;... 
(depending on where you have installed MTX). 
 
If you intend to build from the command line, you must edit  
vcvars32.bat accordingly as well. 
 
 
ATL 
=== 
 
The ATL samples also requires the latest version of ATL (Microsoft 
Active Template Library).  ATL ships with Visual C++ 5.0. 
 
ATL is the recommended library for writing ASP and other ActiveX 
components in C++: 
    * produces small, fast, industrial-strength components ("lean and mean") 
    * supports all COM threading models (single, apartment, free) 
    * supports IDispatch interfaces 
    * dual interfaces are easy 
    * supports the OLE error mechanism 
    * methods are called very quickly 
    * fine control over COM features ("closer to the metal") 
    * many other features 
 
For ATL 2.0, in order to add a method or a property to a component, it 
is necessary to modify the .idl, .h, and .cpp files by hand.  With ATL 
2.1, the wizards in Visual C++ 5.0 automates much of this for you. 
 
To create a new component with ATL: 
    * Start a New Project Workspace in Developer Studio 
    * Select ATL COM AppWizard 
    * Enter the name and location of the project 
    * Hit Create. 
    * Accept the defaults and hit Finish. 
 
Now that you've created the project, it's time to create a COM object 
within the project.  In Visual C++ 5.0, you can go to the Insert menu 
where you'll see New ATL Object... or you can right-click on the classes 
in the ClassView pane, where you'll also see New ATL Object.... 
 
When the ATL Object Wizard pops up, you'll see two panes.  In the left 
pane, click on Objects.  In the right pane, double-click on Simple Object. 
If you have VC 5.0, you'll see a number of additional objects; click on 
ActiveX Server Component instead. 
 
The ATL Object Wizard Properties dialog will appear.  On the Names tab, 
type in the short name of your object.  The other names will be filled in 
automatically.  You can edit them if you wish.  It's quite likely that 
you'll want to edit the Prog ID. 
 
On the Attributes tab, you may want to change the Threading Model to Both. 
You probably don't need to support Aggregation.  You ought to Support 
ISupportErrorInfo.  The other attributes should not need to be changed. 
 
On the ASP tab, you can enable OnStartPage and OnEndPage methods and select 
which of the ASP intrinsic objects you want to use.  However, it is now 
recommended that you use the Object Context (which doesn't require the 
OnStartPage and OnEndPage methods) rather than the Scripting Context (which 
is what OnStartPage supplies you with).  This allows you to create more 
powerful application state objects.  All the samples that need it use the 
Object Context rather than the scripting context. 
 
Note the use of the ATL wrapper classes CComBSTR, CComVariant, 
CComPtr, and CComQIPtr in the ATL samples to simplify management of 
COM data types. 
 
 
Installation 
============ 
 
To install these sample components, you must first compile them with 
Microsoft Visual C++.  Load the individual project files into VC++  
and build the DLLs.  You can also build the DLLs by just typing  
"nmake" in the command line.  Running nmake in the top level directory 
(the directory this file is in) will build both the simple and power 
DLLs. 
 
These components may not compile correctly unless you have the correct 
header and library files.  You may need to copy all the header files 
in ...\iissamples\sdk\include (default is C:\Inetpub\...) to your VC++  
include directory.  In addition, you may need to copy the MTS header  
and library files to the VC++ include and library directory.  The MTS  
header files are located in ...\MTS\include (default is C:\Program  
Files\...) while the MTS library files are located in ...\MTS\lib. 
 
*** NOTE: The MTS header and library files are not installed by  
default.  In most cases, you will need to install this using the  
Windows NT 4.0 Option Pack setup. 
 
If you intend to run these components on a machine other than the one  
on which they are compiled, you will need to copy the DLLs to the  
target machine and 
    regsvr32 /s /c SAMPLE.dll 
(the samples will be registered automatically on the machine they're 
built on). 
 
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 \<winnt-directory>\system32\inetsrv. 
 
 
Directory List 
============== 
 
Directory        Description 
---------        ----------- 
 
 Simple          C++ ATL Simple Sample 
 Intermediate    C++ ATL Power Sample 
 
 
Usage 
===== 
 
To use the samples, simply call Server.CreateObject("IISSample.XXX") 
to create the object, where "XXX" is one of 
    C++ATLSimple     C++ATLPower 
Then you may access the object's methods and properties from your ASP 
script.  Read any of the sample ASP scripts to discover how to use the 
objects. 
 
 
Sample ASP scripts 
================== 
 
You must copy the sample ASP scripts to a virtual directory (it need 
not be a virtual root) on the IIS Server where you have installed the 
sample components before they will work. 
 
 
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 
listserv@listserv.msn.com with 
 
subscribe ActiveServerPages [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. 
 
 
Change Notes 
============ 
 
Version 1.0 Beta 1: February 1997 
--------------------------------- 
 
First release. 
 
 
Version 1.0 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). 
* Better comments in Power components. 
 
 
Version 2.0 Beta 3: September 1997 
---------------------------------- 
 
* Updated for IIS4.0 
* Using IObjectContext instead of IScriptingContext. 
 
 
Version 2.1: October 1997 
------------------------- 
 
* Modified for the IIS4.0 SDK release