Setting up an Ftp Site

User Isolation

LocalUser

public

CACLS "%SystemDrive%\inetpub\ftproot" /G "Network Service":C /T /E
Next the user NetworkService needs to be given permission to the config folder and two config files
CACLS "%SystemDrive%\Windows\System32\inetsrv\config" /G "Network Service":R /E
CACLS "%SystemDrive%\Windows\System32\inetsrv\config\administration.config" /G "Network Service":R /E
CACLS "%SystemDrive%\Windows\System32\inetsrv\config\redirection.config" /G "Network Service":R /E

IIS Manager Authentication

private void CreateFtpUser(string configurationPath, string username, string password)
{
   /* First Create the User for the ftp site */
   ManagementUserInfo userInfo = ManagementAuthentication.CreateUser(username, password);
   ManagementAuthorization.Grant(userInfo.Name, configurationPath, false);
   /* Next set up the permissions for this user (Read/Write) */
   using (ServerManager serverManager = new ServerManager())
   {
      Configuration config = serverManager.GetApplicationHostConfiguration();
      ConfigurationSection authorizationSection =
         config.GetSection("system.ftpServer/security/authorization", configurationPath);
      ConfigurationElementCollection authorizationCollection =
         authorizationSection.GetCollection();
      ConfigurationElement newElement =
         authorizationCollection.CreateElement("add");
      newElement["accessType"] = @"Allow";
      newElement["users"] = username;
      newElement["permissions"] = @"Read, Write";
      authorizationCollection.Add(newElement);
      serverManager.CommitChanges();
   }
}

Be sure to create a sub folder under the LocalUser folder (under your ftp site's root folder)for the users you create using the code above. The username of the user and the folder name should be the same.

Building the WebService Client

So lets start by building a WebService client for an existing Webservice. Just to get our feet wet as it were. If you go to Xmethods.com you'll see there are a number of WebServices people have posted links for. We'll use one of these services for starters.

You might notice that I'm being partial here. I've chosen the Send an Email WebService. We'll write a simple client for this WebService. Before we can begin to use any WebService, we need to have the WSDL file. With Delphi, you simply need the URL to a WSDL file. You could use a physical WSDL file as well, but the Expert available to us, allows us to supply the URL to a WSDL file so we'll use this capability. The expert will generate the Interface files for us.

WSDL File

Let's take a brief look at the WSDL file. The URL for the WSDL file is http://webservices.matlus.com/scripts/emailwebservice.dll/wsdl/IemailService. If you're using I.E, you can click on this link to see the WSDL file inside your browser. Without going into too many details (the WSDL spec. can be quite complex for the faint hearted), lets take a look at some of the elements you should be aware of.

1. The <message> element. The name attribute contains the name of the method with the word Request added to it. This is part of the spec. This is not the element that really tells you the name of the method however. That comes later
2. the <part> element's name attribute tells you the name of the parameters while the type attribute tells you the type of the parameters.
3. Next, take a look at the next <message> element. The name attribute has the name of the method with the word Response at the end of it. Once again, this is as per spec.
4. Under this element the <part> element's name attribute tells you what is being returned and the type attribute tells you the type of this return value.
5. The next important element is the <operation> element. This is the element that really gives you the remote method name. In this case SendMail.
6. The <soap:operation> element has an attribute called soapAction. You'll see this mentioned once again later in this tutorial. The value of this attribute is generated for you automatically by the Delphi 6 SOAP framework. In particular by the TWSDLHTMLPublish component at the server end. This is the component that actually generated this WSDL file in the first place.(if you examine the URL for this WSDL file, you'll notice that it points to an action in the ISAPI.)
7. The <service> element and it's name attribute are the next elements to look at. We'll see these again when building the client later. In particular, when populating the THTTPRIO component's Service and Port properties.

That's probably some of the more important things to look for in a WSDL file when building a Webservice client. Of course, things can get a bit funky when you run into problems with namespaces etc. when dealing with services that were either built according to an older or newer SOAP specification, or different development tool. These are some of the issues you're going to have to live with when living on the bleeding edge of technology.

I'd also like to take this opportunity to highlight another aspect that relates to XML. Now you don't need to get too involved with this at this point in time. It'll all come together soon enough. So if you don't understand it now, it's ok. For the moment there is no real need to have to understand it. I'm talking about Namespaces. Any good book on XML will give you a more detailed explanation. However, I'll explain things as they relate to SOAP and in particular the WSDL file in question. Right at the start of this WSDL file, you'll see some namespaces being declared. In I.E. they will be highlighted in red (You must have wondered about this when you first show the WSDL file right?). Namespaces are declared as attributes of an element. In this case the <definitions> element like

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 

This declaration now gives us a namespace called soap. Further down in the WSDL file there are a few elements that start with the word soap. For example, <soap:operation>. This is really the <operation> element in the soap namespace. You can tell this by the virtue of the fact that there is a : (colon) between the word soap and operation. Hope that makes some sense at this point.

WebService Client Project

1. Start a new project
2. Then File | New | Other
3. In the New Items dialog, choose the WebServices tab
4. Choose the WebServices Importer
5. Click OK

Figure 1: Selecting the WebServices Importer

This should show you the Wizard.

Figure 2: Showing the WebService Importer Wizard

In the WSDL Location field, type in the URL for the WSDL File for the Send an Email WebService. This should be http://webservices.matlus.com/scripts/emailwebservice.dll/wsdl/IEmailService. Once you've done that (make sure the URL you type in is exactly as shown), click on the Generate button. Delphi will now create a new unit for you and the Interface declaration for the Send an Email WebService. This unit will look like this:

Unit Unit2;

interface

uses Types, XSBuiltIns;
type

  IEmailService = interface(IInvokable)
    ['{C355CCC3-4CD4-4577-A0D2-88FBB9B2801E}']
    function SendMail(const ToAddress: WideString; const FromAddress: WideString; const ASubject: WideString; const MsgBody: WideString): Integer;  stdcall;
  end;


implementation

uses InvokeRegistry;

initialization
  InvRegistry.RegisterInterface(TypeInfo(IEmailService), 'urn:EmailIPortTypeInft-IEmailService', '');

end.

From the code listing above, you should see that the interface is called IEmailService and that is has one method (a function in this case) called SendMail. This method, expects to see the parameters required to send an email. What is interesting to note is that this Interface is derived from an interface called IInvokable. This is new to Delphi 6. IInvokable is almost exactly the same as IInterface (or IUnknown) which is the base type for all Delphi Interfaces. The key difference is that it is compiled with Run time Type information using the {$M } compiler directive. I mentioned in the previous articles, the Delphi SOAP implementation uses RTTI and Interfaces. This is one part of that equation.

The next thing to note is the initialization section of the unit that was generated. The invocation registry is again new to Delphi 6. The Delphi 6 SOAP framework uses this "registry" to be able to automatically instantiate instances of Invokable classes (classes that implement interfaces derived from IInvokable) and Remoteable classes (we'll get to these in a later tutorial). Needless to say, that if you don't register things that need to be registered, your WebServices will not work. The Online help has a decent explanation of the RegisterInterface method and the parameters expected (most of them are optional). Also notice the stdcall directive. Currently, the Delphi default calling convention (register) is not yet supported. You could use any other calling convention that Delphi supports, such as cdecl, pascal, or safecall. It is not recommended that you use safecall since safecall calls are wrapped with an exception handler by the compiler and this may swallow more exceptions than you'd want to. The default is to use stdcall so I suggest you stick with this.

Lets switch to the main form of the application and drop down a THTTPRIO component on the form. You'll find this component in the WebServices palette. This component has 4 key properties.

1. WSDLLocation
2. Service
3. Port
4. URL

You either use the WSDLLocation, Service and Port properties or just the URL property.

Given a WSDLLocation (URL) the THTTPRIO component is capable of parsing out the WSDL file and populating the Service and Port property dropdown lists. So lets fill in the WSDLLocation with the same URL we used earlier. Now drop down the Service property's combo box and select IEmailServiceservice. Do the same for the Port property and select IEmailServicePort.

Figure 3: Showing the Object Inspector with the THTTPRIO component's properties populated.

Looking at the parameters required by the SendMail method of the IEmailService, I've built a simple GUI with the required fields as show in Figure 3 below.

Figure 4: Showing the simple GUI for the Send an Email WebService

The Code

I've named the unit that Delphi created as EmailIPortTypeInft. You don't need to name it the same, but you do need to add this unit to the uses clause of the implementation section of your form's unit. Once you do this, in the OnClick event of the Send button you need to write some code.

unit uClientMain;

interface

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, StdCtrls, Rio, SoapHTTPClient, ComCtrls;

type
  TForm1 = class(TForm)
    HTTPRIO1: THTTPRIO;
    Label1: TLabel;
    Button1: TButton;
    txtToAddress: TEdit;
    Label2: TLabel;
    txtFromAddress: TEdit;
    Label3: TLabel;
    txtSubject: TEdit;
    MemMessageBody: TMemo;
    Label4: TLabel;
    StatusBar1: TStatusBar;
    procedure Button1Click(Sender: TObject);
  private
    { Private declarations }
  public
    { Public declarations }
  end;

var
  Form1: TForm1;

implementation

{$R *.dfm}

uses
 EmailIPortTypeInft;

procedure TForm1.Button1Click(Sender: TObject);
begin
  Screen.Cursor := crHourGlass;
  StatusBar1.SimpleText := 'Sending Email....';
  StatusBar1.Refresh;
  try
    if (HTTPRIO1 as IEmailService).SendMail(txtToAddress.Text, txtFromAddress.Text,
      txtSubject.Text, MemMessageBody.Lines.Text) <> 0 then
      StatusBar1.SimpleText := 'Error Sending Email.'
    else
      StatusBar1.SimpleText := 'Email Sent.';
    StatusBar1.Refresh;
  finally
    Screen.Cursor := crDefault;
  end;
end;


end.

Basically, you really need just one line of code. Most of the code you see in the OnClick event is really related to GUI frills. The one line of code that really does the work is:

    if (HTTPRIO1 as IEmailService).SendMail(txtToAddress.Text, txtFromAddress.Text,
      txtSubject.Text, MemMessageBody.Lines.Text) <> 0 then

If you run this application and fill in the values to send yourself an email and hit the send button, you'll receive and email if all goes well.

Behind the Scenes

Behind the scenes, the THTTPRIO component has built a SOAP envelope for you and sent it over to the WebService server. The server knows what to do with this SOAP envelop. This SOAP envelope (for those interested) looks like this:

POST http://matlus.matlus.com/scripts/emailwebservice.dll/soap/IEmailservice HTTP/1.0
Accept: application/octet-stream, text/xml
SOAPAction: "urn:EmailIPortTypeInft-IEmailService"
Content-Type: text/xml
User-Agent: Borland SOAP 1.1
Host: matlus.matlus.com
Content-Length: 759
Proxy-Connection: Keep-Alive
Pragma: no-cache

<?xml version="1.0" encoding='UTF-8'?>
  <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/1999/XMLSchema"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"> 
    <SOAP-ENV:Body> 
      <NS1:SendMail xmlns:NS1="urn:EmailIPortTypeInft-IEmailService" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 
        <NS1:ToAddress xsi:type="xsd:string">shivk@erols.com</NS1:ToAddress> 
        <NS1:FromAddress xsi:type="xsd:string">Shiv Kumar<shiv@matlus.com></NS1:FromAddress> 
        <NS1:ASubject xsi:type="xsd:string"> Testing</NS1:ASubject> 
        <NS1:MsgBody xsi:type="xsd:string">This is a TEST MESSAGE</NS1:MsgBody> 
      </NS1:SendMail> 
    </SOAP-ENV:Body> 
  </SOAP-ENV:Envelope>

1. In the HTTP header take a look at the URL that was constructed - http://matlus.matlus.com/scripts/emailwebservice.dll/soap/Iemailservice. What is key here is the part after the emailwebservice.dll. On the server side, when the Service receives this Request a component called THTTPSOAPDispatcher fields this request (because it has PathInfo /soap). It then hands it over to another component called THTTPPascalInvoker. This component looks up the Invocation Registry and tries to match the name of the interface (IEmailService). If it finds a match, it instantiates an instance of the class that implements this interface. We'll get to this when we build the server side. But you should know, that this is done for you automatically by the Delphi 6 SOAP framework.
2. The SOAPAction HTTP header. This is a new HTTP header required for SOAP calls. This is one of the headers that a firewall/proxy can look for to either allow/disallow SOAP calls past it for security reasons. Of course, the SOAP spec. does not make this mandatory. I would guess that in time this header will be mandatory.
3. Next, within the XML Document (SOAP envelope) you should see the name of the method.
4. You should also see the parameters and values to these parameters that are being sent to the server.

The server processed this packet and responded with another SOAP packet that looks like this

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Sat, 14 Jul 2001 07:35:44 GMT
Content-Type: text/xml
Content-Length: 531
Content:

<?xml version="1.0" encoding='UTF-8'?>
  <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/1999/XMLSchema"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/>
    <SOAP-ENV:Body>
      <NS1:SendMailResponse xmlns:NS1="urn:EmailIPortTypeInft-IEmailService" SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/>
        <NS1:return xsi:type="xsd:int">0</NS1:return>
      </NS1:SendMailResponse>
    </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

If you really want to know what all the XML stuff is you'll need to go deeper into the SOAP spec and XML. If you want to be a good SOAP programmer you can't avoid this. For now however, we don't need to know.

What if this WebService was written in Java or C ? How would they know what to do with such as request? In particular, how do they treat IEmailService? As I mentioned in the previous articles, Delphi 6's SOAP implementation uses Interfaces. Other SOAP tool kits don't have to. So they will understand this request the way They need to. SOAP is an implementation and platform agnostic protocol. With WebServices it doesn't matter what tool the service is written in or what platform its running on. Well, this is the ideal scenario. Currently, there are interoperability issues, but we'll get there one day I'm sure. For the most part, things should work just fine.

With the knowledge you've gained so far, you should be able to experiment with other WebServices listed on the XMethods web site. I suggest you do this and then come back here to learn how to build the server for this WebService.

THTTPRIO Explained

Figure 5: Showing the Properties of THTTPRIO

We've used the WSDLLocation property, the Service property and the Port. Keep in mind, that for you to be able to use the WSDLLocation in design time (or run time) you need access to the Internet if your WSDLLocation is a URL. Also, you use the Service and Port properties only when using the WSDLLocation property. Instead of using the WSDLLocation property, you could use the URL property. When using the URL property, you don't need (and shouldn't) use the Service and Port properties. The value of the URL property will not be the same as the WSDLLocation. You need to use the proper value in this case. This is the SOAP Endpoint URL. When looking at SOAP services that listed at sites such as XMethods or SALCentral, you will see the SOAP Endpoint URL listed along with the WSDL file. The THTTPRIO component gets the WSDL file at run time, parses it out and finds the SOAP Endpoint URL in the WSDL File. So it goes without saying, that using the URL property will be slightly faster than using the WSDLLocation property since some round trips are saved. Keep this in mind, if you are making repeated calls to a certain WebService in your applications. Another interesting point to note is that the URL for the WSDL file and the SOAP Endpoint (only for Delphi 6 build WebServices) have a very small difference. The word wsdl is replaced with the word soap. Note that this is by default and that you have the option to change this.

What if you are behind a proxy/firewall either at home or work? Well, then you're going to have some issues that you'll need to circumvent. You won't be able to use the WebService Importer as I explained earlier. What you'll have to do is use your browser to get to the WSDL File. Save it locally, and then use this file (you can use the Browse button) to fill in the WSDLLocation field in the wizard. Once you've done this and the interface file(s) is created for you, your next issue will be when you attempt to fill in the properties of the THTTPRIO component. First, if you look at the properties shown in Figure 5, you'll see that the THTTPRIO component has a Proxy property as well as UserName and Password properties. You'll need to get the details from your Network administrator if you don't know what to fill in here. As an example, if you have a proxy server called MyProxy that uses port 8080, then the Proxy property needs to be filled in as MyProxy:8080. As explained earlier, I suggest you use the URL property instead of the WSDLLocation. If you do plan to use the WSDLLocation property, you need to use the file path and name instead of the URL to this file and most probably, when you deploy your client application, it's going to then need to find this WSDL file as well.

The Agent property is another interesting property. If you look at the HTTP header that was shown earlier, you'll see that the User-Agent HTTP header was Borland SOAP 1.1. Now you're free to change this to whatever else you'd like. I normally use the User-Agent HTTP header to distinguish my client applications from others. If you have to deal with security (proxies/firewalls), the User-Agent HTTP header can come in handy to allow for further filtering. For example, you can tell you network security guys, to allow HTTP requests that have a Content-Type of text/xml ONLY if the User-Agent is xyz and the SOAPAction header is abc. Etc.

The THTTPRIO component can be lifetime managed as a component or as an Interfaced object. It is managed, as a component when its owner is not nil. If you drop it on a form, its owner is the form and so it is managed as a component. This becomes important to know in the following case:

In the OnClick event of code listed above, you'll notice that we've not declared a variable of the type IEmailService. But what if we needed to do this? What if we needed a global variable of this type in our application? Well, we declare a variable of this type in the private section and use it in the OnClick event and elsewhere in our code. When we do this, we need to be sure to nil out this variable in the destructor of the form (or some other appropriate place). The code below shows and example of this.

type
  TForm1 = class(TForm)
    Button1: TButton;
    procedure Button1Click(Sender: TObject);
    procedure FormDestroy(Sender: TObject);
  private
    EmailService: IEmailService;
    { Private declarations }
  public
    { Public declarations }
  end;

var
  Form1: TForm1;

implementation

{$R *.dfm}

procedure TForm1.Button1Click(Sender: TObject);
begin
  EmailService := HTTPRIO1 as IEmailService;
end;

procedure TForm1.FormDestroy(Sender: TObject);
begin
  EmailService := nil;
end;

end.

Building the Send an EMail WebService Server

Before we begin with building the Send an Email Webservice, let me take you through the paces of what we will be doing.

We're going to start a new SOAP Server Application using the Wizard. This essentially produces a Web server extension (CGI, ISAPI etc.) that contains a Web Module and some components on it. This is really very similar to a Web Broker application. We'll choose the ISAPI option.

If you're not familiar with ISAPI applications, I suggest you look at the tutorials on my web site related to ISAPI applications. The WebServices you'll build with the help of tutorials on this web site will mostly be ISAPI applications. Your knowledge of ISAPI Applications/debuggin etc. will be leveraged here. If you don't have experience building ISAPI applications, debugging etc. I strongly suggest you read the tutorials on my web site for this before you attempt to build WebServices. This way you'll have a firmer grasp of what is going on and this will save you (and me ) endless hours of frustration.

I assume you know ISAPI application development and as a result, you will find that I do not explain ISAPI related concepts in any of the WebService tutorials.

The standard SOAP Server application has three components on it.

1. THTTPSOAPDispatcher
2. THTTPSOAPPascalInvoker
3. TWSDLHTMLPublish

The THTTPSOAPDispatcher dispatches all requests that have /soap in the PathInfo. It then hands the request over to THTTPSOAPPascalInvoker. This component really handles the bulk of the process. What is this process? Well, If you take a look at the HTTP request header from earlier, you see, that the full request looks like this:

http://matlus.matlus.com/scripts/emailwebservice.dll/soap/IEmailservice

The PathInfo part of this request is:

/soap/IEmailservice

You learned earlier, that the THTTPSOAPDispatcher handles all requests, with /soap in it and hands it over to the THTTPSOAPPascalInvoker. So the THTTPSOAPPascalInvoker has to do something with /IEMailservice. So what does it do? It looks up the Invocation Registry for any registered Interfaces that match the name IEMailservice. It also parses out the content of the web request (this is the SOAP Packet from earlier) and finds the name of the method and the parameters. Once it has done that, it instantiates an instance of the class that implements this interface and calls the required method handing it the parameters it received. Remember that it's able to do all this using RTTI for interfaces (new to Delphi 6) and some old RTTI magic. Since it receives all this information in the form of a string, it is converting these strings into method calls that instantiate an instance of a class and call the required methods (very much like a scripting engine). When you build a WebService, it is your job to:

1. Define an Interface.
2. Implement this interface in a class.
3. Register the interface and class with the invocation registry.

That's it. The Delphi 6 SOAP framework handles the rest of it for you. What's the rest of it you might ask?

1. Parsing the SOAP envelope.
2. Instantiating the required class.
3. Calling the required method and passing the received (parsed) parameters to it
4. Getting back a result from the method.
5. Putting the result back in a SOAP response envelope and sending it back out.
6. If there is an exception it constructs a SOAP Fault packet instead

To put it in really simple terms!

I hope this short explanation has cleared things up a bit. If it has, then we're ready to move on and start with building our first Delphi 6 WebService.

The SOAP Server Application

1. From the Delphi main menu, choose File | New | Other
2. Choose the WebServices tab and choose the SOAP server Application Expert
3. In the next dialog, leave the ISAPI/NSAPI (this is the default) Dynamic Link Library option selected and Click OK.

Figure 6: Showing the Steps involved in Creating a New SOAP Server Application

After doing these steps, you should see something like the last image in Figure 6. I suggest you save this project as EmailWebService and the WebModule unit as MainU.pas.

Note: I assume at this point that you know about building ISAPI Applications and debugging them etc. I keep stressing this because I don't want to be flooded with emails asking me questions about WebServices that really pertain to ISAPI applications. I believe the information available on my web site related to ISAPI is more than enough to help you get started with ISAPI applications and get to the point where you can now build WebServices.

Defining the Interface

If you've registered Delphi 6, you should then have access to some of the power toys that will be made available to you. At the time of this writing, I believe they are not yet available. Anyhow, I'll use (one of these toys) the Invokable Wizard that will help in building the WebService. Don't worry, if you don't have this wizard. What it does is it creates two new units for you, one that defines the Interface and the other that defines a class that implements this interface. I'll show you the full units, so you can create them by hand if required. Why have the interface defined in one unit and the implementation in another? Technically, there is obviously no need for this. But if you're building a client for the WebService as well (and 99% of the time you will, only if it's to test the WebService), you can include the unit that declares your interface in the client application's project as well. This will eliminate the need to import the WSDL file (one of the steps we went through while building the client). However, if you want to test your WebService completely, you're better off building the client as we did earlier. That is, treat the client as an independent part of your system, so you know that others attempting to use the WebService will be able to.

The Invokable Wizard can be found in the New Items dialog (File | New | Other | WebServices) as shown in Figure 7 below.

Figure 7: Showing the Invokable Wizard

As Shown in Figure 8 below, the Invokable Wizard presents you with another dialog.

Figure 8: Showing the dialog the Invokable Wizard presents you with.

I've filled in the values as shown there. You'll notice that the InvokableClass field has a combo box. I've chosen TInvokableClass. The other option is TInterfacedObject. There is a subtle difference between these two. TInvokableClass is derived from TInterfacedObject so it implements QueryInterface, AddRef and ReleaseRef. But it also has a virtual constructor. The fact that it has a virtual constructor allows the compiler to create an instance of the class using RTTI. If you need to derive from TInterfacedObject for some reason, you'll have to implement one extra step in your code (Ill show you that later) and register the class differently (I'll show you that too). All this, so the compiler can instantiate an instance of your class on the fly (That is THTTPSOAPPascalInvoker can instantiate an instance as was described earlier).

The two units thus created are shown below. The first one is the unit that declares the Interface - IEmailService and the next one declares the class that will implement this interface - TEmailService.

unit EMailServiceIntf;

interface

uses
  Types, XSBuiltIns;

type
  IEMailService = interface(IInvokable)
    ['{A987FE00-E596-4733-83BB-E75ACA5FF363}']
  end;

implementation

uses
  InvokeRegistry;

initialization
  InvRegistry.RegisterInterface(TypeInfo(IEMailService), '', '');

end.

unit EMailServiceImpl;

interface

uses
  EMailServiceIntf, InvokeRegistry;

type
  TEMailService = class(TInvokableClass, IEMailService)
  end;

implementation

initialization
  InvRegistry.RegisterInvokableClass(TEMailService);

end.

Make a note of the units in the uses clause of both these units and the initialization section as well. If you're building these units, by hand, I suggest you do so at this point looking at the above listings.

To understand the "Registration" need, I suggest you look at the on-line help for more information. Notice also, that the unit that declares the Interface is very similar to the one that was generated for us using the WebService Importer wizard back when we started with building the client application. Minus the SendMail method and GUID obviously.

Lets go ahead and define the SendMail method as shown in the listing below.

unit EMailServiceIntf;

interface
uses
  Types, XSBuiltIns;

type
  IEmailService = interface(IInvokable)
  ['{C56A3546-DA66-492F-9024-D78D960AB248}']
    function SendMail(ToAddress, FromAddress, ASubject, MsgBody: string): Integer; stdcall;
  end;

implementation

uses
  InvokeRegistry;

initialization
  InvRegistry.RegisterInterface(TypeInfo(IEmailService));


end.

Save these units using the names shown (these are the names generated for you by the Wizard if you used it). New to Delphi 6 is the ability to use Code Insight to fill in the methods of an interface in the class that implements the interface. You can even multi-select the methods shown to get Code Insight to write them all out for you as they were declared in the Interface. Note that the units need to be saved for this to work.

So switch to the unit that declares the class the implements the IEMailService, move you cursor under the "T" of TEMailService and hit CTRL Space. You should see the SendMail method listed in the code completion drop down. Select it and hit the Enter key and you'll see that Delphi does the rest for you. Now do the class completion (CTRL SHIFT C)

We're using Indy to do the sending of emails. You'll notice that Indy is now a part of Delphi 6. Those of you who have not used Indy yet, will obviously need to get to know how to use them. Our implementation of sending an email is nothing special, except for the fact that all objects are being created on the fly. You will also need to add the required units to the uses clause of your units. The listing below shows the full unit for the TEmailService class. Remember, this is the class that implements the interface IEmailService.

unit EMailServiceImpl;

interface

uses
  InvokeRegistry, XSBuiltIns, EmailIServiceInft, IdBaseComponent, IdComponent,
  IdTCPConnection, IdTCPClient, IdMessageClient, IdSMTP, IdMessage;

type
  TEmailService = class(TInvokableClass, IEmailService)
  public
    function SendMail(ToAddress: String; FromAddress: String;
      ASubject: String; MsgBody: String): Integer; stdcall;
  end;

implementation

{ TEmailService }

function TEmailService.SendMail(ToAddress, FromAddress, ASubject,
  MsgBody: String): Integer;
const
  SMTPServer = 'smtp-server'; { Change this to your SMTP server }
var
  IdSMTP: TIdSMTP;
  IdSendMsg: TIdMessage;
begin
  IdSMTP := TIdSMTP.Create(nil);
  IdSendMsg := TIdMessage.Create(IdSMTP);
  try
   Result := -1;
   with IdSendMsg do
   begin
     Body.Text := MsgBody;
     From.Text := FromAddress;
     Recipients.EMailAddresses := ToAddress;
     Subject := ASubject;
   end; { with IdSendMsg do }

   with IdSMTP do
   begin
     Host := SMTPServer;
     Connect;
     try
       Send(IdSendMsg);
       Result := 0;
     finally
       Disconnect;
     end;
   end; { with IdSMTP do }
  finally
    IdSendMsg.Free;
    IdSMTP.Free;
  end; { try }
end;

initialization
  InvRegistry.RegisterInvokableClass(TEmailService);

end.

Add these two units to your project and we're almost done now. Pretty simple so far huh? The last thing that's left is getting the service application to respond to SOAP calls and publish the WSDL file. Remember, without a WSDL file, your WebService is practically useless to anyone else.

TWSDLPublish

What we need to do is select the TWSDLPublish component on the WebModule and set its AdminEnabled property to true. Now run your application and using a browser, navigate to this URL http://matlus.matlus.com/scripts/EmailWebService.dll/wsdl. Change the domain and path according to your setup. Just be sure you put the /wsdl as a path of the final URL. You should see a screen similar to that shown in Figure 9.

Figure 9: Showing the WSDL Administration Page

If you had not set the AdminEnabled property to True, you wouldn't see the Administrator button. Click on the WSDL for IEmailService link. You should now see a WSDL file in your browser. Scroll to the end of the document. You should see that the <service> element is an empty tag (as per XML definition). If you look at the WSDL file at the URL specified at the start of this tutorial, you should notice that the <service> element had a child element called <port> and the <port> element had a <soap:address> element as a child like so:

<port name="IEmailServicePort" binding="IEmailServicebinding">
  <soap:address location="http://matlus.matlus.com/scripts/EmailWebservice.dll/soap/IEmailService" />

We need to define the Port for our service. We do that by clicking on the Administrator button and then on the WSDL for IEMailService link. You should see a screen that looks like that shown in Figure 10.

Figure 10: Showing the Admin Screen that allows for registering a Port for the WebService

In the PortName field enter IEmailServicePort and in the Address field enter http://matlus.matlus.com/scripts/EmailWebservice.dll/soap/IEMailservice. Change the domain name as per your set up. Click the Add button. You should see a screen that looks like that shown in Figure 11.

Figure 11: Showing the Admin Screen that allows for registering a Port for the WebService

Hit the back button of your browser twice. This should show the URL http://matlus.matlus.com/scripts/EmailWebService.dll/wsdl in your browser. Now if you click on the WSDL for IEMailService link and check the WSDL file thus generated, the <service> and <port> elements are as they should be. You should note also, that this operation has generated an .ini file in the /scripts folder (the same folder in which your DLL is installed. This .ini file will have the same name as your ISAPI dll with the words _WSDLADMIN.INI appended to it. The contents of this file should be something like this:

[IWSDLPublish]
IWSDLPublishPort=http://matlus.matlus.com/scripts/EmailWebservice.dll/soap/IWSDLPublish

[IEmailService]
IEmailServicePort=http://matlus.matlus.com /scripts/EmailWebservice.dll/soap/IEmailService

When you deploy your WebService to your production server, you either need to go through these steps again, or simply copy this .ini file over to the production server and change the domain name parts in both sections to match that of your production server. Do not forget this step. Without this step, your WebService will be quite un-usable.

TInvokableClass or TInterfacedObject

Earlier, I mentioned that if you decide to use TInterfacedObject as the class to derive your implementation class, you'll need to do things differently. Here are the differences and why you need to do them. TInterfacedObject does not have a virtual constructor declared. As a result, there is no way for your application to instantiate an instance of your class at run time when it gets a SOAP request to do so. As usual, there is always an option with Delphi. (These guys think of everything). What you need to do is implement a "Factory" method for your class. This method needs to return an instance of your class as an out parameter. Further, for the run time to figure it out, you need to register this method when registering the class with the invocation registry so that the application can call this method to get back an instance of your class. This is how you should implement this method and register it.

procedure EMailServiceFactory(out obj: TObject);
begin
  obj := TEmailService.Create;
end;

initialization
  InvRegistry.RegisterInvokableClass(TEMailService, EMailServiceFactory);

end.

Note the change in the call to the RegisterInvokableClass method in the initialization section as well.

Well, that pretty much does it. This tutorial contains more explanation than the actual work involved in building a WebService with Delphi 6. It's really very simple and I hope, after you've read this tutorial, you feel the same. Testing your WebService server is a simple task, now, since you already have a client. All you need to do is change the WSDLLocation property of the THTTPRIO component in your client application (or URL property as the case may be) to match that of your WebService (instead on mine). The projects are available for download as a project group containing the WebService Client project and WebService server project.

Actually doing the work gives you a far better understanding and also surfaces the "facts" and "half-truths" about a certain technology. Further, having actually done it by hand, gives you a better insight into the technology in question. So rub your hands together and get ready for the fun that lies ahead.

The WebService client that we are about to build is a generic SOAP Client. Currently, it can handle WebServices that have one method and expect none or one parameter. Examples of such WebServices are:

1. WhoIS
2. Shakespearean Insult Generator
3. Kazoo Training Classes
4. WordFind
5. FedEx Tracker
6. Delayed Stock Quote
7. Domain Name Checker

What will you need to build this project

1. Delphi 5 Pro/Enterprise or Delphi 6 Pro/Enterprise
2. Microsoft SOAP toolkit 2.0 Gold Release
3. Indy version 8.0

What will you have learnt by the end

1. You'll learn how to use the Microsoft DOM Parser, to build and parse XML Documents
2. You'll learn how to use the Indy TIdHTTP component
3. You'll learn about WSDL Files and how to "read" them
4. You'll learn about the SOAP protocol
5. You'll learn how to use the I.E. ActiveX Browser control

Importing the MSXML type library

Step 1	Step 2 - Select the Library and Click Create Unit	Step 3 - You should see the file in the Editor - Save it

Let the games begin

Image1 - The First Step - Get the URL to a WSDL File

Image2 - Enter the URL for the WSDL File

Image3 - Clicking on the Get WSDL Button retrieves the WSDL File, Parses it and populates the fields

Image4 - If the WebService Method Requires a Parameter, then Enter a Valid Value

Image5 - Clicking on the Make SOAP Request Button Executes the SOAP method

Image6 - The SOAP Request that was sent to the WebService

Image7 - The SOAP Response that came back from the WebService ]]>ProgrammingDelphiSOAPWebServicesMon, 21 Jan 2008 10:52:07 GMThttp://exposureroom.com/members/skumar/tutorials/post/3/http://exposureroom.com/members/skumar/tutorials/post/3/Sending back strings, integers etc. as a result of a WebService method is really simple. You didn't have to do anything special to accomplish this. In this tutorial, we'll see how we can:

1. Send back custom objects
2. Define and raise custom Exceptions

As soon as you read the things we're going to learn how to do in this tutorial, you must have thought to yourself:

• If we send back an Object how will clients written in tools other then Delphi deal with these objects?
• Riase an Exception? What, on a Remote Client? What if the client is not a Delphi client? How will it know what to do with a Delphi Exception?
• What if the Client is running on a platform other than Windows?

If you asked any or all of these questions, then you've been paying attention . That's good news. Read on, and you'll have the answers to questions you ask.

WebService Methods Returning Objects

type
  TFieldInfo = class(TRemotable)
  private
    FIsKeyField: Boolean;
    FFieldSize: Integer;
    FFieldName: string;
    FFieldType: string;
  published
    property FieldName: string read FFieldName write FFieldName;
    property FieldType: string read FFieldType write FFieldType;
    property FieldSize: Integer read FFieldSize write FFieldSize;
    property IsKeyField: Boolean read FIsKeyField write FIsKeyField;
  end;

  TFieldInfoArray =   array of TFieldInfo;

POST http://webservices.matlus.com/scripts/xmldatasetwebservice.dll/soap/IDatasetXML HTTP/1.0
Accept: application/octet-stream, text/xml
SOAPAction: "urn:DatasetXMLIntf-IDatasetXML#GetSchemaInfo"
Content-Type: text/xml
User-Agent: Borland SOAP 1.1
Host: webservices.matlus.com
Content-Length: 535
Proxy-Connection: Keep-Alive
Pragma: no-cache

<?xml version="1.0" encoding='UTF-8'?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/1999/XMLSchema"
  xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <NS1:GetSchemaInfo xmlns:NS1="urn:DatasetXMLIntf-IDatasetXML" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <NS1:TableName xsi:type="xsd:string">Customer</NS1:TableName>
    </NS1:GetSchemaInfo>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Fri, 20 Jul 2001 04:34:23 GMT
Content-Type: text/xml
Content-Length: 4676
Content:

<?xml version="1.0" encoding='UTF-8'?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/1999/XMLSchema"
  xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <NS1:GetSchemaInfoResponse
      xmlns:NS1="urn:DatasetXMLIntf-IDatasetXML"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
      xmlns:NS2="http://www.w3.org/2001/XMLSchema">
      <NS1:return xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="NS2:TFieldInfo[13]">
        <NS1:item href="#1"/>
        <NS1:item href="#2"/>
        <NS1:item href="#3"/>
        <NS1:item href="#4"/>
        <NS1:item href="#5"/>
        <NS1:item href="#6"/>
        <NS1:item href="#7"/>
        <NS1:item href="#8"/>
        <NS1:item href="#9"/>
        <NS1:item href="#10"/>
        <NS1:item href="#11"/>
        <NS1:item href="#12"/>
        <NS1:item href="#13"/>
      </NS1:return>
      <NS2:item id="1" xsi:type="NS2:TFieldInfo">
        <NS2:FieldName xsi:type="xsd:string">CustNo</NS2:FieldName>
        <NS2:FieldType xsi:type="xsd:string">ftFloat</NS2:FieldType>
        <NS2:FieldSize xsi:type="xsd:int">0</NS2:FieldSize>
        <NS2:IsKeyField xsi:type="xsd:boolean">False</NS2:IsKeyField>
      </NS2:item>
      <NS2:item id="2" xsi:type="NS2:TFieldInfo">
        <NS2:FieldName xsi:type="xsd:string">Company</NS2:FieldName>
        <NS2:FieldType xsi:type="xsd:string">ftWideString</NS2:FieldType>
        <NS2:FieldSize xsi:type="xsd:int">30</NS2:FieldSize>
        <NS2:IsKeyField xsi:type="xsd:boolean">False</NS2:IsKeyField>
      </NS2:item>
      <NS2:item id="3" xsi:type="NS2:TFieldInfo">
        <NS2:FieldName xsi:type="xsd:string">Addr1</NS2:FieldName>
        <NS2:FieldType xsi:type="xsd:string">ftWideString</NS2:FieldType>
        <NS2:FieldSize xsi:type="xsd:int">30</NS2:FieldSize>
        <NS2:IsKeyField xsi:type="xsd:boolean">False</NS2:IsKeyField>
      </NS2:item>
    </NS1:GetSchemaInfoResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Figure 1: Showing part of the WSDL file that defines the complexType

The SOAP request is a standard request (for this WebService) calling the GetSchemaInfo method and sending it the TableName, Customer. The response by the WebService is what we need to take a closer look at. As I mentioned earlier, this method returns an array of objects. In XML terms, as you can see from the WSDL file or Figure 1, this is a complexType that is defined as an array. So you see, that the object is really defined like a Delphi record or C/C struct. When a Delphi client receives this kind of data it gets converted into an object instance (more about this later). The Customer table in this case has 13 fields. You can see this from the HTTP response shown earlier. I've shown only the first 3 fields to save space, but the line:

<NS1:return xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="NS2:TFieldInfo[13]">

Figure 2: SOAP is just a Wire Protocol

Remember that SOAP is a wire protocol. What that means is that the actual communication between two end points is taking place using the SOAP protocol. What happens before the message leaves one end and what happens once the messages gets to the other end is left totally up the implementation specific details of the two end points. What is key is that everyone should be on the same page as far as their interpretation of the SOAP specification is concerned. Once the messages gets across the wire it's up to that end point how you deal with it. Even though SOAP has the word Object in it, is not necessary that there are any objects involved. When a Delphi built WebService server receives a SOAP Request, it instantiates an instance of an object. It doesn't matter what kind of client made a request or what platform the client is running on. Similarly, if a WebService responds with a SOAP Response as shown earlier, a Delphi WebService Client, will instantiate an instance of an array of objects with 13 elements in it. It doesn't matter what language the WebService was written in or what platform it is running on. That's just the way Delphi implements SOAP.

We saw in the - Building your First WebService tutorial (from here on in reffered to as "the previous tutorial), how Delphi built WebServices and clients figure out what these objects are and how to instantiate them and which objects to instanciate. In this case, the difference is that the WebService is returning an object. How the client figures out what this object is and how to instanciate which object, we'll see later in this tutorial (hint - the object needs to be registered with the Invocation Registry and needs to be derived from a specific class).

Building the Server

The first thing we're going to need is to define our Interface. You can use the Wizard (available to registered users) or code the unit by hand. The method GetDatasetAsXML expects to see and SQL SELECT statement as a parameter and it returns the result of the query in the form of an XML document. The second method, GetSchemaInfo expects to see the name of a table (in this case a table that exists in the dbdemos.mdb Access database) and returns the schema of the table in the form of an array of TFieldInfo objects (one element per field).

Returning an XML document as a result of a WebService method is not recommended. This is because the WSDL file indicates that this method will return a string. Someone building a client for this service simply looking at the WSDL file (which is really how WebServices are supposed to work.) will have no indication that this "string" is in fact going to be an XML document.

When designing WebServices it is important to keep the spirit of WebServices.

• WSDL - always think, "Will just the WSDL file be enough for anyone else to use my WebService?"
• Interoperability - People using other development tools and/or platforms should be able to access your WebService.

If you feel you don't need to comply with these two points. You probably don't need to use WebServices. That is, if you're building the client and server for personal consumption, as a result you can ignore the above "requirements", there are probably better solutions for your needs. Remember, XML is a very verbose protocol and as a result tends to be very slow. The number of bytes being transferred between client and server is very large and there is a fair amount of processing on both the client and server in constructing the XML document and parsing it. There are solutions (I'll present one of them soon if I haven't already by the time you read this) that are much lighter than XML and can use HTTP and so still gain the benefits that SOAP provides but require a lot less bandwidth and processing power and as a result are more scalable. If you need to expose and API to a system you're building, to the out side world then WebServices is a good choice. If you're using WebServices for a Client/Server or n-tier system then WebServices is not the answer. You might want to take a look at this article on ZDNet Fat protocols slow Web services.

unit DatasetXMLIntf;

interface

uses
  Types, XSBuiltIns, uFieldInfo;

type
  IDatasetXML = interface(IInvokable)
    ['{C7785514-F56F-40AD-B943-950A162296BE}']
    function GetDatasetAsXML(const SelectSQL: WideString): WideString; stdcall;
    function GetSchemaInfo(const TableName: WideString): TFieldInfoArray; stdcall;
  end;

implementation

uses
  InvokeRegistry;

initialization
  InvRegistry.RegisterInterface(TypeInfo(IDatasetXML), '', '');

end.

unit uFieldInfo;

interface

uses
  InvokeRegistry, XSBuiltIns;

type
  TFieldInfo = class(TRemotable)
  private
    FIsKeyField: Boolean;
    FFieldSize: Integer;
    FFieldName: string;
    FFieldType: string;
  published
    property FieldName: string read FFieldName write FFieldName;
    property FieldType: string read FFieldType write FFieldType;
    property FieldSize: Integer read FFieldSize write FFieldSize;
    property IsKeyField: Boolean read FIsKeyField write FIsKeyField;
  end;

  TFieldInfoArray =   array of TFieldInfo;


implementation

initialization
  RemClassRegistry.RegisterXSClass(TFieldInfo, '', 'TFieldInfo', '');
  RemTypeRegistry.RegisterXSInfo(TypeInfo(TFieldInfoArray), '', 'TFieldInfoArray');

finalization
  RemClassRegistry.UnRegisterXSClass(TFieldInfo);
  RemTypeRegistry.UnRegisterXSInfo(TypeInfo(TFieldInfoArray));
end.

For ComplexTypes to work, you need to apply a fix to the WebServExp.pas source code file. This is an unofficial fix that I have made and is not supported. So far I have not seen any repercussions to implementing this fix. When Borland releases a patch or fix for this, please be sure to implement their fix rather than this. The WSDL generated without this fix is not correct as it does not include the definition for the complexTypes.

function TWebServExp.FindSchema(const ObjectTypeInfo: PTypeinfo; const
TnsURI: string): Boolean;
var
  Index: Integer;
begin
  Result := False;
  //Do not register Empty TnsURI or tkSet or any predefined type from XMLSchema
{ TODO -oShiv Kumar -cBUG :
Complex Types are not generated if this code is NOT commented.
Don't know the implications of doing this, but so far have not had issues. }

{  if ((TnsURI = '') or (ObjectTypeInfo.Kind = tkSet) or (TnsURI =
SXMLSchemaURI_1999) or  (TnsURI = SXMLSchemaURI_2000_10) or
    (TnsURI = SXMLSchemaURI_2001))  then
  begin
    Result := True;
    Exit;
  end;
}
  for Index := 0 to Length(SchemaArray) -1 do
  begin
    if SchemaArray[Index].TypeInfo = ObjectTypeInfo then
    begin
      Result := True;
      Exit;
    end;
  end;

  //Add new type
  Index := Length(SchemaArray);
  SetLength(SchemaArray, Index 1);
  SchemaArray[Index].TypeName := ObjectTypeInfo.Name;
  SchemaArray[Index].NameSpace := TnsURI;
  SchemaArray[Index].TypeInfo := ObjectTypeInfo;
  SchemaArray[Index].XSGenerated := False;
end;

More on TRemotable

function GetSchemaInfo(const TableName: WideString): TFieldInfoArray; stdcall;

What if a TRemotable type is a parameter to a method instead of being returned as a result? On the Client end (Delphi Clients), the client is responsible for creating and instance of it before making the method call and freeing the instance after it is finished using it. On the server end, the instance is once again automatically created and freed. Of course, for all of this to work, both the client and server need to register the class with the Invocation Registry. This is very important. Take a look at the on-line help for the methods RegisterXSClass and RegisterXSInfo.

unit DatasetXMLImpl;

interface

uses
  Classes, DatasetXMLIntf, InvokeRegistry, uFieldInfo, DB, ADODB, msxmldom,
  xmldom, XMLIntf, XMLDoc;

type
  ENotSelectSQL = class(ERemotableException)
  private
    FSQLStatememnt: string;
    FNotes: string;
    FReason: string;
  public
    constructor Create(IllegalSQLStatement, AReason: string);
  published
    property SQLStatement: string read FSQLStatememnt write FSQLStatememnt;
    property Notes: string read FNotes write FNotes;
    property Reason: string read FReason write FReason;
  end;

  TDatasetXML = class(TInvokableClass, IDatasetXML)
  private
    XMLDocument1: TXMLDocument;
    ADOConnection1: TADOConnection;
    ADODataset1: TADODataset;
    DocumentElement: IXMLNode;
    procedure CreateDataAccessObjects;
    procedure FreeDataAccessObjects;
    procedure GenerateDataSection(Dataset: TDataSet);
    procedure GenerateSchemaSection(Dataset: TDataSet);
    function GenerateDataAsXML: string;
  public
    { IDatasetXML }
    function GetDatasetAsXML(const SelectSQL: WideString): WideString; stdcall;
    function GetSchemaInfo(const TableName: WideString): TFieldInfoArray; stdcall;
  end;

implementation

uses
  TypInfo, SysUtils;

{ TDatasetXML }

procedure TDatasetXML.CreateDataAccessObjects;
begin
  ADOConnection1 := TADOConnection.Create(nil);
  ADODataset1 := TADODataset.Create(nil);
  XMLDocument1 := TXMLDocument.Create(nil);
  ADOConnection1.Provider := 'Microsoft.Jet.OLEDB.4.0';
  ADOConnection1.ConnectionString := 'Provider=Microsoft.Jet.OLEDB.4.0;'  
    'Data Source=C:\Program Files\Common Files\Borland Shared\Data\dbdemos.mdb;'  
    'Persist Security Info=False';
  ADOConnection1.LoginPrompt := False;
  ADOConnection1.Connected := True;
  ADODataset1.Connection := ADOConnection1;
end;

procedure TDatasetXML.FreeDataAccessObjects;
begin
  ADODataset1.Free;
  ADOConnection1.Free;
  XMLDocument1.Free;
end;

function TDatasetXML.GetDatasetAsXML(const SelectSQL: WideString): WideString;
begin
  if AnsiCompareText(Copy(SelectSQL, 1, 6), 'SELECT') <> 0 then
  begin
    raise ENotSelectSQL.Create(SelectSQL, 'Only SELECT SQL Statements are Allowed');
  end;
  CreateDataAccessObjects;
  try
    ADODataset1.CommandText := SelectSQL;
    ADODataset1.Open;
    Result := GenerateDataAsXML;
  finally
    FreeDataAccessObjects;
  end;
end;

function TDatasetXML.GetSchemaInfo(
  const TableName: WideString): TFieldInfoArray;
var
  i: Integer;
begin
  CreateDataAccessObjects;
  try
    with ADODataset1 do
    begin
      CommandText := 'SELECT * FROM '   TableName;
      Open;
      FieldDefs.Update;
      SetLength(Result, FieldCount);
      for i := 0 to FieldCount -1 do
      begin
        Result[i] := TFieldInfo.Create;
        Result[i].FieldName := Fields[i].FieldName;
        Result[i].FieldType := GetEnumName(TypeInfo(TFieldType),Integer(Fields[i].DataType));
        Result[i].FieldSize := Fields[i].Size;
        Result[i].IsKeyField := Fields[i].IsIndexField;
      end; { for i := 0 to Dataset.FieldCount -1 do }
    end; { with Dataset do }
  finally
    FreeDataAccessObjects;
  end;
end;

function TDatasetXML.GenerateDataAsXML: string;
begin
  XMLDocument1.Active := True;
  DocumentElement := XMLDocument1.CreateElement('dataset', '');
  { Set this element as the Document Element }
  XMLDocument1.DocumentElement := DocumentElement;
  GenerateSchemaSection(ADODataSet1);
  GenerateDataSection(ADODataSet1);
  Result := XMLDocument1.XML.Text;
end;

procedure TDatasetXML.GenerateSchemaSection(Dataset: TDataSet);
var
  i: Integer;
  SchemaElement: IXMLNode;
  AttributeElement: IXMLNode;
begin
  SchemaElement := DocumentElement.AddChild('schema');
  with Dataset do
  begin
    FieldDefs.Update;
    for i := 0 to FieldCount -1 do
    begin
      AttributeElement := SchemaElement.AddChild('attributeType');
      AttributeElement.SetAttribute('fieldName', Fields[i].FieldName);
      AttributeElement.SetAttribute('fieldType', GetEnumName(TypeInfo(TFieldType),Integer(Fields[i].DataType)));
      AttributeElement.SetAttribute('fieldSize', IntToStr(Fields[i].Size));
    end; { for i := 0 to Dataset.FieldCount -1 do }
  end; { with Dataset do }
end;

procedure TDatasetXML.GenerateDataSection(Dataset: TDataSet);
var
  i: Integer;
  DataElement: IXMLNode;
  RowElement: IXMLNode;
begin
  DataElement := DocumentElement.AddChild('data');
  with Dataset do
  begin
    First;
    while not Eof do
    begin
      RowElement := DataElement.AddChild('row');
      for i := 0 to Dataset.FieldCount -1 do
      begin
         RowElement.SetAttribute(Dataset.Fields[i].FieldName, Dataset.Fields[i].AsString);
      end; { for i := 0 to Table1.FieldCount -1 do }
      Next;
    end; { while not Eof do }
  end; { with Table do }
end;


{ ENotSelectSQL }

constructor ENotSelectSQL.Create(IllegalSQLStatement, AReason: string);
begin
  FSQLStatememnt := IllegalSQLStatement;
  FNotes := 'Due to Security Reasons. Only SQL SELECT Statments are allowed.'   #13#10 
   'Further, the WebService can Access only the DBDEMOS.mdb database';
  FReason := AReason;
  inherited Create(Reason   #13#10 Notes);
end;

initialization
  InvRegistry.RegisterInvokableClass(TDatasetXML);
  RemClassRegistry.RegisterXSClass(ENotSelectSQL, '', 'ENotSelectSQL', '');
end.

The implementation of the IDataSetXML Interface is quite straightforward. We use the TXMLDocument component (New to Delphi 6 - read about it on the on-line help) to generate the XML being returned as a result of the GetDataSetXML method. Of course we could have just as easily used ADO and it's inherent capability to produce XML documents of the recordset it holds. But I did it this way for those that may not want to use ADO and secondly, since we have this new component in D6.

ERemotableException

The base class for Remotable Exceptions is ERemotableException. You need to derive your custom exceptions from this class and register them using the RegisterXSClass method. If the client of this WebService is a Delphi client, then your custom exceptions need to be register at the client side as well (this is automatically handled for you when you import the WSDL File using the expert.

The HTTP Header and content shown below is a sample SOAP Fault Packet of an exception of type ENotSelectSQL raised by the server.

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Fri, 20 Jul 2001 10:48:43 GMT
Content-Type: text/xml
Content-Length: 1066
Content:

<?xml version="1.0" encoding='UTF-8'?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/1999/XMLSchema"
  xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <SOAP-ENV:faultcode>SOAP-ENV:Server</SOAP-ENV:faultcode>
      <SOAP-ENV:faultstring>Only SELECT SQL Statements are Allowed Due to Security Reasons.
                            Only SQL SELECT Statments are allowed.
                            Further, the WebService can Access only the DBDEMOS.mdb database</SOAP-ENV:faultstring>
      <NS1:detail xmlns:NS1="http://www.w3.org/2001/XMLSchema" xsi:type="NS1:ENotSelectSQL">
        <NS1:SQLStatement xsi:type="xsd:string">SELEC * FROM CUSTOMER</NS1:SQLStatement>
        <NS1:Notes xsi:type="xsd:string">Due to Security Reasons. Only SQL SELECT Statments are allowed.
                                         Further, the WebService can Access only the DBDEMOS.mdb database</NS1:Notes>
        <NS1:Reason xsi:type="xsd:string">Only SELECT SQL Statements are Allowed</NS1:Reason>
      </NS1:detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This finishes the WebService Server. Next we'll tackle the WebService client.

The client is really very simple in this case and so I don't go into it here. But it is available for download with the rest of this project.

<HTML>
<HEAD>
  <LINK REL=STYLESHEET TYPE="text/css" href="/home-styles.css">
  <TITLE> Delphi ASP Object Demo</TITLE>
</HEAD>
<BODY>
<CENTER><H2>Vendors Table from DBEMOS</H2></CENTER>
<HR>
<% Set DelphiASPObj = Server.CreateObject("DelphiASP.Vendor")
   DelphiASPObj.GetVendors
%>
<HR>
</BODY>
</HTML>

procedure TVendor.GetVendors;
var
  sSQL : string;
begin
  sSQL := Request.Form['txtSQL'];
  Response.Write(DM.GetVendorInfoPage(sSQL));
end;

Building you first ASP object in Delphi

Also, COM DLLs compiled with Delphi, like most things Delphi does are self contained. Yes they need the COM run time, but they don't need other DLLs, like VB DLLs or even VC COM DLLs for that matter.

Data Access speeds in Delphi once again are far better than VB. All in all, a COM DLL built in Delphi will out perform a COM DLL built in VB or VC .

How many ASP programmers do you think use ASP objects? Hardly any. Yes, they use third party objects by way of reusability. But they don't go around building their own ASP objects. They are primarily ASP scripting people.

As a Delphi programmer, you can build ASP objects that these programmers can use or you can build a whole web site using ASP objects. I'd personally, just use ISAPI, but then there are those that get caught up with buzzwords. If it weren't for buzzwords, I wouldn't be writing this article now would I?

The ASP engine that comes with Win98/Win2000 (needs to be installed for Win95.) is nothing but an ISAPI DLL. The name of the file is ASP.DLL. This DLL is loaded into memory by IIS, which in turn does the interpreting of ASP scripts or loads the ASP DLL objects into memory (along with a TON of other junk). For an ISAPI programmer (building ASP objects), this adds an unnecessary layer and slows things down due to the COM overhead. Believe you me, this overhead is a lot. Your server can do far better without this overhead.

So what's better, ASP or ISAPI? As per Microsoft (read my article - ISAPI versus CGI for quotes from the M$ web site), for speed, scalability and resources, use ISAPI, for all other things use ASP. I'd say, if you are a programmer, use ISAPI, if you're a VBer, use ASP<G>

Enough slandering, lets get on with our project.

In this project, we're going to build an ASP object that connects to the VENDORS table in DBDEMOS. A very simple project, but none the less, get the picture (ASP) across.

What is needed for this project

1. I am personally using Firebird 1.0 for this project as well as my whole web site. You can download Interbase 6.0 for free from Here. I'm really impressed with its speed and light weight. I've upsized the DBDEMOS database to Interbase. Using the Interbase Express components that come with Delphi (Enterprise), I'm now free of the BDE as well. But you can use the standard DBDEMOS database (paradox) for this tutorial if you wish. The methods of the data access objects are the same. Some properties differ.
2. You'll need to have the ASP engine installed if you are using Win95. You should probably be able to download this from the Microsoft site.
3. Delphi Professional or Enterprise, since I believe these are the only versions that come with the ASP object (Wizard/Expert) option.

Before we really start building the project, lets see what exactly we're going to do. First we need to have an ActiveX library (COM DLL). To this library, we need to add an ASP object. We need to give this ASP objects a method, that will return the data from VENDORS table.

Getting ahead of ourselves a bit, lets examine the ASP file that will create our object and call its method. The ASP file looks like this:

<HTML>
<HEAD>
  <TITLE> Delphi ASP Object Demo</TITLE>
</HEAD>
<BODY>
<CENTER><H2>Vendors Table from DBEMOS</H2></CENTER>
<HR>
<% Set DelphiASPObj = Server.CreateObject("DelphiASP.Vendor")
   DelphiASPObj.GetVendors
%>
<HR>
</BODY>
</HTML>

Figure 1: Showing the Flow of a Request made by a web browser

As Shown in Figure 1 ASP works similar to ISAPI in that it receives a request, processes it, and sends back a response in the form of HTML. The <% and %> are the ASP script delimiters. The stuff between these delimiters is processed at the server end by the ASP engine. It will be replaced by HTML after processing. So imagine, if you will, that in the ASP file above, our method's output should result in HTML that will display data from the VENDORS table. The parts, before and after the ASP script delimiters are standard HTML.

In the ASP script

Looking at the ASP file above. More notably, the ASP script, you'll notice the VB syntax that creates a COM object.

  Set DelphiASPObject = Server.CreateObject("DelphiASP.Vendor")

DelphiASP is the name of our ASP DLL file. In the DLL, we have an ASP object called Vendor. The next line:

  DelphiASPObject.GetVendors

Once the object (DelphiASPObject, which is of the type DelphiASP) is created, we call its method - GetVendors. We create this method for our object and we have to implement this method. The result of this method returns a valid HTML string. And so, in this way, we've replaced the <% and %> with HTML that is then sent out through the (oh so sluggish) ASP/COM engine, then through the web server onto the (unsuspecting) client.

The Good news is that Delphi creates the .asp file for us.

Starting the Project

Lets get started with actually building the project.

1. Form Delphi's File menu, choose New
2. In the New Items Dialog, switch to the ActiveX Page.
3. Choose ActiveX Library and then click OK.
4. Form the File menu choose New
5. In the New Items Dialog, switch to the ActiveX Page.
6. This time Choose Active Server Object.
7. In the New Active Server Object dialog, type is Vendor in the CoClass Name field.
8. If you are using IIS 5.0 or later, Change the Active Server Type option to Object Context.
9. Click OK

If you're not familiar with the various options presented in the New Active Server Object dialog, I suggest you read the on-line help on those various options by hitting the F1 key while the dialog is active.

You should now see the Type Library Editor as shown in Figure 2.


Figure 2: Showing the Type Library Editor of the Active Server Object.

Lets save the project we've created thus far.

• Save Vendor.asp as Vendor.asp
• unit1.pas as uVendor_Impl.pas
• Project1.dpr as DelphiASP.dpr

The unit, DelphiASP_TLB is the type library for our Active Server Object. Hitting the F12 key when this unit is active will toggle between the type library editor and this unit. The unit uVendor_Impl is the implementation of our Active Server Object. This is the unit in which we will write code to implement the methods we give our ASP object. Vendor.asp is the ASP file that, when called will create an instance of our ASP object and call the required method.

<HTML>
<BODY>
<TITLE> Testing Delphi ASP </TITLE>
<CENTER>
<H3> You should see the results of your Delphi Active Server method below </H3>
</CENTER>
<HR>
<% Set DelphiASPObj = Server.CreateObject("Project1.Vendor") 
   DelphiASPObj.{Insert Method name here}
%>
<HR>
</BODY>
</HTML>

Notice, that the method name is unknown as this time and so we see{Insert Method name here} in its place. Once we create a method and implement it, it is our job to modify the .asp file such that is calls the right method of our object. Also notice the line

<% Set DelphiASPObj = Server.CreateObject("Project1.Vendor")

Since this file was created before we saved our project with a new name, we need to change Project1 to DelphiASP. Lets go ahead and do that now.

The uVendor_impl.pas unit looks like this:

unit uVendor_Impl;
interface
uses
  ComObj, ActiveX, AspTlb, DelphiASP_TLB, StdVcl;
type
  TVendor = class(TASPObject, IVendor)
  protected
    procedure OnEndPage; safecall;
    procedure OnStartPage(const AScriptingContext: IUnknown); safecall;
  end;
implementation
uses ComServ;
procedure TVendor.OnEndPage;
begin
  inherited OnEndPage;
end;
procedure TVendor.OnStartPage(const AScriptingContext: IUnknown);
begin
  inherited OnStartPage(AScriptingContext);
end;
initialization
  TAutoObjectFactory.Create(ComServer, TVendor, Class_Vendor,
    ciMultiInstance, tmApartment);
end.

Delphi has generated this unit for us. Notice that we have an object TVendor that is derived from TASPObject and implements the IVendor interface. So far, this is just a skeleton and it is this unit that we will write our implementation code in.

Some of you might have noticed that unlike an ISAPI/CGI project, we have no place to keep our components such as data access components. In other words, there is no web data module created for us. We could create all the components we want/need on the fly and use them that way. I prefer using a Data Module for this. So lets add new Data Module to our project.

1. From the File menu, choose New
2. Choose Data Module from the New Items dialog box.
3. Name the Data Module - DM1
4. Save the Project. When prompted, name the unit uDM

Creating the GetVendors Method

Since we're working with a COM object, we need to use the Type Library editor to give our object properties and methods. So lets get to the Type library Editor. If you don't see it, make the unit DelphiASP_TLB the active unit in the code editor and then hit the F12 key.

In the TreeView of the type library editor, you should notice our (COM DLL) library DelphiASP has an interface IVendor. Select IVendor in the TreeView and click on the New Method tool bar icon. When you see the new method, change the name to GetVendors.

Then click on the Refresh Implementation tool bar button in the type library editor. This action will create a skeleton of the implementation for us in the Delphi object that implements this interface. Namely, Tvendor in the unit uVendor_Impl.

Implementing the GetVendors Method

Most of this part is standard Delphi programming. One of the things that the base class for Delphi ASP objects (TASPObject) does is, it gives us access to the various ASP objects and methods, such as the Request and Response objects, the ASP Session object etc. So in any method within this unit, we have access to these objects.

In the implementation of the GetVendors method, we need to make sure, we generate valid HTML and hand it over to the Response object. The ASP Response object has a method called Write that declared as

  procedure Write(varText: OleVariant); safecall;

Before we go any further, lets examine the difference between the ISAPI response object and the ASP response object. If we had code in an ISAPI application that looked like this:

  Response.Content := 'Hello World';
In our ASP object it would be
  Response.Write('Hello World');
If on the other hand we had this in our ISAPI:
  Response.Content := 'Hello';
  Response.Content := Response.Content   'World';
In our ASP object it would be
  Response.Write('Hello');
  Response.Write('World');

You will notice that you won't find any documentation on the ASP objects in Delphi. They've left it to Microsoft to document. So you'll have to refer to the Microsoft web site for any documentation for the ASP objects. One place I've found such information is in MSDN

By way of good design, we're going to leave the Data Access methods to our DataModule. In our TVendor class, we'll call methods of the DataModule. This will keep our code cleaner. To use the Data Module from within our TVendor class, we need to add the Data Module's unit to the uses clause of the interface section (yes, the interface section and not the implementation section. We''l see why later). Once we've done that, we can call methods of our DataModule by referencing it.

We have only one line of code in the implementation of the GetVendors method of our TVendor class.

Response.Write(DM1.GetVendorInfoPage);

GetVendorInfoPage is a public method of our DataModule.

The unit of our TVendor class should now look like this:

<% Set DelphiASPObj = Server.CreateObject("Project1.Vendor")

Since this file was created before we saved our project with a new name, we need to change Project1 to DelphiASP. Lets go ahead and do that now.

The uVendor_impl.pas unit looks like this:

unit uVendor_Impl;
interface
uses
  ComObj, ActiveX, AspTlb, DelphiASP_TLB, StdVcl, uDM;
type
  TVendor = class(TASPObject, IVendor)
  protected
    procedure OnEndPage; safecall;
    procedure OnStartPage(const AScriptingContext: IUnknown); safecall;
    procedure GetVendors; safecall;
  end;
implementation
uses ComServ;
procedure TVendor.OnEndPage;
begin
  inherited OnEndPage;
end;
procedure TVendor.OnStartPage(const AScriptingContext: IUnknown);
begin
  inherited OnStartPage(AScriptingContext);
end;
procedure TVendor.GetVendors;
begin
  Response.Write(DM.GetVendorInfoPage);
end;
initialization
  TAutoObjectFactory.Create(ComServer, TVendor, Class_Vendor,
    ciMultiInstance, tmApartment);
end.

Working on the DataModule

We've done nothing so far with the DataModule, so lets get started.

1. Drop a TQuery on the DataModule
2. Set its DatabaseName property to DBDEMOS
3. Set its SQL property to SELECT * FROM VENDORS
4. Set the Active property to True
5. Drop a TSession component on the DataModule and set its AutoSessionName property to True
6. Drop a TDataSetTableProducer component on the DataModule and set its DataSet property to Query1
7. Declare a public method like so:

   function GetVendorInfoPage(sSQL : string) : string;
   

8. Complete the class (Ctrl SHIFT C) to create the implementation stub of this method

Figure 3 show what the Data Module should look like after having completed the steps outlined above.


Figure 3 Showing the Data Module with its components

The unit for the DataModule should be like this:

unit uDM;
interface
uses
  Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs;
type
  TDM1 = class (TDataModule)
    Query1: TQuery;
    Session1: TSession;
    DataSetTableProducer1: TDataSetTableProducer;
  private
    { Private declarations }
  public
    function GetVendorInfoPage : string;
    { Public declarations }
  end;
var
  DM1: TDM1;
implementation
{$R *.DFM}
{ TDM1 }
function TDM1.GetVendorInfoPage: string;
begin
end;
end.

The function GetVendorInfo has only one line of code

Result := DataSetTableProducer1.Content;

That's all there is to it! The output produced by this ASP object will be a simple HTML table as will be produced by the TDataSetTableProducer component. We can modify properties of this component to enhance the look of the HTML page produced. And we shall. But before we proceed .

One important thing you need to remember is that the DataModule is not going to be created automatically for us. We need to explicitly create and destroy the DataModule in our ActiveX Library projects. We'll create the DataModule in the OnStartPage method and Free it in the OnEndPage method of our TVendor class.

Also, notice the implementation of the GetVendors method of our TVendor class. We reference an object called DM and not DM1. DM has been declared as a read only property of our TVendor Class (hence the need to declare uDM in the interface section).

The uVendor_impl.pas unit now looks like this:

unit uVendor_Impl;
interface
uses
  ComObj, ActiveX, AspTlb, DelphiASP_TLB, StdVcl, uDM;
type
  TVendor = class(TASPObject, IVendor)
  protected
    FDM : TDM1;
    procedure OnEndPage; safecall;
    procedure OnStartPage(const AScriptingContext: IUnknown); safecall;
    procedure GetVendors; safecall;
    property DM : TDM1 read FDM;
  end;
var
  DM : TDM1;
implementation
uses ComServ;
procedure TVendor.OnEndPage;
begin
  FDM.Free;
  FDM := nil;
  inherited OnEndPage;
end;
procedure TVendor.OnStartPage(const AScriptingContext: IUnknown);
begin
  inherited OnStartPage(AScriptingContext);
  FDM := TDM1.Create(nil);
end;
procedure TVendor.GetVendors;
begin
  Response.Write(DM.GetVendorInfoPage);
end;
initialization
  TAutoObjectFactory.Create(ComServer, TVendor, Class_Vendor,
    ciMultiInstance, tmApartment);
end.

Compiling and Testing

A couple of things are different from an ISAPI project here. The reason being, you're dealing with ASP and COM and not native DLLs.

1. From the Project menu, choose Options and switch to the Directories/Conditionals page in the project options dialog.
2. Set the Output Directory to your web servers scripts folder (C:\inetpub\scrits)
3. Click the OK button

This will produce a DLL by the name DelphiASP in the scripts folder when we compile. We still can't use the DLL. All COM DLLs need to be registered with the system. We can use the Run|Register ActiveX Server menu option or from the Type Library editor we can click the Register Type Library tool bar button. When you do this, you should get a confirmation dialog stating that the registration was successful.

Now we're ready to use our ASP object. Remember that it is really the .asp file that will instantiate our ASP object and call its method. Lets make sure this ASP file is the way it should be.

<HTML>
<BODY>
<TITLE> Testing Delphi ASP </TITLE>
<CENTER>
<H3> You should see the results of your Delphi Active Server method below </H3>
</CENTER>
<HR>
<% Set DelphiASPObj = Server.CreateObject("Project1.Vendor") 
   DelphiASPObj.GetVendors
%>
<HR>
</BODY>
</HTML>

Notice the line : DelphiASPObject.GetVendors. Your Vendor.asp file should have that line as it is shown above. Lets also move this file (after saving the project. Saving the project, also saves the .asp file) to our web server's root folder (C:\inetpub\wwwroot). We can now call this .asp file using the following URL in a web browser:

  http://mydomain/vendor.asp

Where mydomain is the PC/Machine name of your PC or IP address (localhost or 127.0.0.1 will also do).

Figure 4 shows what the generated HTML page will look like if eveything goes well. Remember, if you need to re-compile this project after the ASP object has been created, you need to treat this DLL like an ISAPI DLL in that respect.


Figure 4 showing the output of Vendor.asp

Enhancing the output

The TDataSetTableProducer component can be used similar to the way one would use it in an ISAPI application. We can use it here to format the HTML Table produced. You have access to the Response Editor as well as the various events this component has. Using the Response Editor we can:

1. Set the HTML Table properties
2. Decide which fields we want to show in the generated output
3. Decide the order in which the fields are to be displayed

etc.

Using the Response Editor, lets set the Border attribute of the HTML Table to 1. Using the OnFormatCell event we can manipulate the HTML table even further. Here is what the OnFormatCell event of the TDataSetTableProducer should look like to produce an output similar to the demo you saw at the beginning of this article.

procedure TDM1.DataSetTableProducer1FormatCell(Sender: TObject; CellRow,
  CellColumn: Integer; var BgColor: THTMLBgColor; var Align: THTMLAlign;
  var VAlign: THTMLVAlign; var CustomAttrs, CellData: String);
begin
  { Color the First Column }
  if CellColumn = 0 then
    BgColor := 'Teal';
  { Color the Second Column }
  if CellColumn = 1 then
    BgColor := 'Olive';
  { Color the Second Row - excluding the Field Name Row }
  if CellRow = 2 then
    BgColor := 'Red';
  { Color all instances of the Field - Preferred where the Value = False }
  if CellColumn = 10 then
  begin
    if CellData = 'F' then
      BgColor := 'Yellow';
  end;
end;

Modifiing the ASP Object to Read Form Data

What if we wanted our ASP object to respond to Data sent to it via an HTML Form? Lets modify our object, such that it receives the SQL string to use in the Query from an HTML Form as you might have seen in the Demo at the start of this tutorial.

So we're going to need:

1. An HTML Page that allows us to define an SQL statement to be used by our ASP object, to generate an HTML output of the result set.
2. This .htm file needs to call our ASP object and pass on to it the SQL statement
3. Our ASP objects needs to be modified such that it looks for the SQL statement in the HTML Form's fields.

In an ISAPI application, we would "extract" an HTML Form's fields using code like this:

  sSQL := Request.ContentFields.Values['txtSQL'];

Where sSQL is defined as a string type and txtSQL is the name of the field in the HTML Form that contains the requested SQL Statement to be applied to a Query object. Assuming here that the method of the HTML Form is POST and not GET.

In ASP, the Request object is a bit different. It has a property called Form. The way you would access the fields of a Form in ASP is:

  sSQL := Request.Form['txtSQL'];

Once we get a hold of the SQL statement that was given to us via an HTML Form, we'd like to pass this on to our GetVendorInfo method of our Data Module, where we can assign the SQL string to our Query object and generate a result set.

Currently, our GetVendorInfoPage method does not expect any parameters, so we'll have to modify it such that it expects to see a string parameter and then use this parameter to assign it to our Query object and get a result set.

The GetVendors method of our ASP object will now look like this:

procedure TVendor.GetVendors;
var
  sSQL : string;
begin
  sSQL := Request.Form['txtSQL'];
  Response.Write(DM.GetVendorInfoPage(sSQL));
end;

and the GetVendorInfoPage method of our DataModule will look like this:

function TDM1.GetVendorInfoPage(sSQL : string) : string;
begin
  with Query1 do
  begin
    Close;
    SQL.Clear;
    SQL.Add(sSQL);
    Open;
  end;
  Result := DataSetTableProducer1.Content;
end;

Remember to change the declaration of this method in the interface section of the DataModule to match that shown above.

This concludes the changes we need to make to our ASP object such that it receives the SQL statement via an HTML form. We still need the HTML form however. The HTML form's source code looks like this:

<HTML>
<HEAD>
  <TITLE>Delphi ASP Demo</TITLE>
</HEAD>
<BODY>
  <FORM ACTION="http://www.matlus.com/Vendor.asp" METHOD="POST">
   The <B>ASP Object</B> is connected to the VENDORS Table in DBDEMOS. Feel Free to Change the SQL Statement below to a Valid SQL Statement for this Table.
   <P>
 <TEXTAREA NAME="txtSQL" COLS=40 ROWS=5>SELECT * FROM VENDORS</TEXTAREA>
   <BR>
   <INPUT TYPE="SUBMIT"> 
  </FORM>
</BODY>
</HTML>
</PRE>

Notice the Form's ACTION attribute. It calls the Vendor.asp page, which in turn creates an instance of our ASP object, and calls its method. The Memo field's (TEXTAREA) name is important here, as it needs to match the name of the form field we're using in our ASP object sSQL := Request.Form['txtSQL'];. Save this .htm file as Vendor.htm.

To test our work, we need to load the Vendor.htm in our browser, set the SQL statement if required (you should test this) and clicking on the SUBMIT button on the Form. Figure 5 shows what the output will look like with an SQL statement of: SELECT VendorNo, VendorName, City, State, Zip, Preferred FROM VENDORS

Figure 5 Showing the output generated by the ASP object

The flaw in our design here is that there is no column 10 and so even though the Preferred field is amongst the one we want displayed, it is not colored yellow where the value = False. We'll leave that as an exercise for those of you who would want to see this work.

Deploying the ASP Object

In most cases, you'd be developing your ASP objects on your development machine but later you'd want to deploy the ASP object on your production web server. What you need to do in this case is register your COM DLL on the production server. To do that you need to do the following:

1. Place the COM DLL (DelphiASP.DLL in this case) in your web server's scripts folder (C:\inetpub\scripts).
2. From the Start Menu, choose Run
3. In the dialog box presented type -regsvr32 C:\inetpub\scrits\DelphiASP.DLL
4. This action should register your COM DLL and give you a confirmation stating as such
5. You will of course need an ASP file that instantiates your ASP object and calls its methods as well (similar to the Vendor.asp file)

ISAPI versus ASP

Unlike the ISAPI implementation in Delphi, which is event driven using Actions, ASP objects are method driven. In VB, you could use WebClasses to compliment your ASP scripts written using Visual InterDev and ASP objects in VB to achieve a somewhat event driven paradigm to web applications. This method adds one more layer to web applications written in VB that is known to slow things down even further.

The Delphi ISAPI/CGI framework, gives you all of that in a single place at break neck speeds and minimal resource utilization with incomparable scalability. So why bother with ASP.

A quote from the Microsoft site:

While no benchmarks are really going to give you the complete story, these benchmarks can tell you something. If WebClasses are slower, they aren't really that much slower (30%). Most of the performance loss is simply due to creating and destroying WebClass instances, which is not a sufficient reason to avoid using WebClasses. Moreover, if you're not willing to give up a little performance to get some extra productivity, you shouldn't be using Visual Basic or the ASP framework-you should be writing custom ISAPI extension DLLs with C .

In Delphi, ISAPI gives us the productivity we need. Productivity is comparable to what you would get if you were using Visual InterDev (minus the HTML Page design, but then you're not limited to using any tool for that purpose. Using HTML templates in a Delphi ISAPI frees you to use any HTML page designer to accomplish this end), with the benefits of ISAPI over any other competing technology for web based applications, without the headaches associated with ISAPI that a VC programmer relates to. In short, you got ISAPI the easy way. A way that no other development tool provides.

As a Delphi programmer do ASP only because you love to spout industry buzzwords. So why do I bother writing such an extensive Tutorial on Delphi and ASP ? First and foremost, it's nice to know that the Delphi R&D team has taken the trouble to give the Delphi programmer access to ASP objects as a technology. Secondly, It's good to know that Delphi does ASP. And thrid, for those of you who can't get around the buzzword (vicious) circle, you have the option to do ASP with Delphi.

I've since modified Ronaldo's code a bit to fit this tutorial as well as Doug's ASP script to change the output to look like that of the previous tutorial's. The similarity of the output should give people a good idea of how to do things in the "typical" ASP way and the "Delphi way".

The ASP page that instantiates our ASP object and gets it to return an ADO Recordset looks like this:

<html>
<head>
<LINK REL=STYLESHEET TYPE="text/css" HREF="http://www.matlus.com/home-styles.css">
</head>
<body>
<% Dim ASPObj %>
<% Dim rs %>
<% set ASPObj = Server.CreateObject("DelphiADO.Recordset") %>
<% set rs = ASPObj.ReturnADO %>
<Table Cellspacing="1" Cellpadding="1" Border="1">
  <tr>
  <% For j = 0 to rs.fields.count - 1 %>
    <td align="center">
      <b><% Response.Write(rs.fields(j).name) %></b>
    </td>
  <% Next %>
  </tr>
<%Do Until rs.Eof %>
  <tr>
  <% For j = 0 to rs.fields.count - 1 %>
    <td>
      <% Response.Write(rs.fields(j)) %>
    </td>
  <% Next %>
  </tr>
<%  rs.movenext %>
<%Loop%>
</Table>
<% set ASPObj = nothing %>
<% set rs = nothing %>
</body>
</html>

What's Required

Getting started

1. Select File | New
2. Switch to the ActiveX page of the New item dialog
3. Select ActiveX Library
4. Click on the OK Button

1. Change the output directory to your web server's scripts folder (C:\inetpub\scripts)
2. Save this Project as DelphiADO
3. From the File menu, select New
4. Swtich to the ActiveX page again
5. Choose ASPObject
6. Click OK
7. In the dialog box presented, fill out the fields as shown in Figure 1 and click OK

If you are running IIS 4.0 leave the Active Server Type in its default setting. For IIS 5.0 and above, choose the option as shown in Figure 1.

You should see the .asp page that Delphi generates for us as well as the Type Library Editor and the unit that implements the IRecordset interface. Delphi generates the following code for us:

unit Unit1;
interface
uses
  ComObj, ActiveX, AspTlb, Project1_TLB, StdVcl;
type
  TRecordset = class(TASPMTSObject, IRecordset)
  end;
implementation
uses ComServ;
initialization
  TAutoObjectFactory.Create(ComServer, TRecordset, Class_Recordset,
    ciMultiInstance, tmApartment);
end.

As usual, we need to use the Type Library Editor to add methods to our ASP object.

1. In the Type Library editor, select the IRecordset interface and add a new method by either right clicking and choosing New Method or clicking on the New Method icon on the tool bar
2. Name this method - ReturnADO
3. Swtich to the Parameters tab on the right
4. Add a parameter for this method such that your Type library editor looks like that shown in Figure 2
5. Once done, click on the Refresh Implementation tool bar button

Refreshing the implementation of the ASP object (in the type library editor) will generate the method declaration in our TRecordset object for the method we just added to the IRecordset interface. The interface section of the TRecordset object should look like that shown below. In particular, make sure the declaration of the ReturnADO method in your project looks like that shown here.

interface
uses
  ComObj, ActiveX, AspTlb, DelphiADO_TLB, StdVcl, ADOdb, Dbtables;
type
  TRecordset = class(TASPMTSObject, IRecordset)
  protected
    function ReturnADO: OleVariant; safecall;
  end;

Next, we will implement the ReturnADO method of our TRecordset. This part is really simple as we once again come back to Delphi programming. We aren't using a DataModule in this project like we did in the last one. There is no specific reason for this expect that I wanted to keep this project simple. Since we don't have a DataModule here we need to create an instance of a TADODataset on the fly, assign the required properties and then return the Recordset as the result of this function. The RecordsetImpl unit's listing is shown below:

unit RecordsetImpl;
interface
uses
  ComObj, ActiveX, AspTlb, DelphiADO_TLB, StdVcl, ADOdb;
type
  TRecordset = class(TASPMTSObject, IRecordset)
  protected
    function ReturnADO: OleVariant; safecall;
  end;
implementation
uses ComServ;
function TRecordset.ReturnADO: OleVariant;
var
  ADODataSet1 : TADODataSet;
  RecordSet   : _Recordset;
begin
  ADODataSet1 := TADODataSet.Create(nil);
  try
    ADODataSet1.ConnectionString := 'Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Program Files\Common Files\Borland Shared\Data\dbdemos.mdb;Persist Security Info=False';
    ADODataSet1.CommandText := 'SELECT * FROM VENDORS';
    ADODataSet1.Open;
    RecordSet := ADODataSet1.Recordset._xClone;
    RecordSet.Set_ActiveConnection(nil);
    Result := RecordSet;
    ADODataSet1.Close;
  finally
    ADODataSet1.Free;
  end;
end;
initialization
  TAutoObjectFactory.Create(ComServer, TRecordset, Class_Recordset,
    ciMultiInstance, tmApartment);
end.

The complete project is available for download from the link below.

What do you need to start?

1. Delphi 3/4/5 Client/Server or Enterprise Edition
2. A Web Server (software).
   You may use Microsoft's Personal Web Server (PWS) which is available for free from their web site. You may already have PWS if you use Win98 Second Edition, which comes with Personal Web Server 4.0. You may also use Microsoft's IIS on Windows NT/ Windows 2000. In any case, be sure to use a web server that supports ISAPI. If the server you use does not support ISAPI, you may work with the project as a CGI (EXE) program instead. It will not have the same resource and speed advantages that an ISAPI DLL will have, but it is certainly adequate to develop your application as a CGI program during the development phase, or if you know that the site where you employ the CGI will not be heavily trafficked. You can also use Omni httpd (you can download it from here) or Falcon WebServer which is a web server written in Delphi (you can download it from here). Both these web server should allow you to debug your ISAPI projects like any other DLL project from within the IDE. I suggest you don't run these web servers as NT services for debugging purposes.
3. Some basic HTML knowledge.
   HTML is a scripting language that uses tags to delineate different parts of a document. All tags take the form of <tagname> to open the tag, and most have a closing tag </tagname> to close the tag. Tags may are embedded in other tags. Some tags may have attributes, such as the <FONT> tag that has a COLOR attribute. We will use some of these tags in the exercise in this article. Your web projects will benefit greatly with an advanced knowledge of HTML/DHTML.
4. Knowledge of Delphi.

What you do in Delphi to access databases (and other programming stuff) will be the same as what you do in your ISAPI/CGI application. To write web applications, you just need to learn the ISAPI part. Your existing Delphi programming knowledge will be leveraged. For a good Delphi programmer, wanting to start with web development, the ISAPI part is the simplest! It's actually the HTML, JavaScript, Graphics etc. that is much harder to do. In my experience in developing web sites, I spend 60-70% of my time trying to come up with good graphics and functional JavaScript to make the web pages interesting. After being used to developing front end applications, one feels handicaped trying to get a browser to do what you could so easily achieve with a front end GUI. Mind you, the simplicity of ISAPI is only for the Delphi/BC developer, thanks to the Delphi R&D team. A VC programmer has a ton of work to do before he can get his ISAPI up and running!

Now that I've made you feel comfortable, let's get on with it shall we ?

Web Applications Concepts

Let's explain some basic concepts and terms before we begin.

You have a browser as your "front end". The browser makes "requests" to the web server. These requests could be a request for an HTML page, or information from a database, or a combination of the two.

The request made by the browser goes to the web server. The web server will pass this request onto your ISAPI (or CGI) application which is targeted by the URL of the request.

(To understand the differences between creating an ISAPI DLL and a CGI EXE, please see the note at the bottom of this article.)

Within your ISAPI application you can "see" this request as an event that is generated. The request may have parameters passed to it. What you must program then is a response to this request, and return that response along with any requested information to the client (browser) via the web server. Your response will be in the form of an HTML string.

After you have installed a web server on your PC, you may "run" your web application by entering the URL in your browser. To access your URL's "domain name", use the name of your PC. Let's say the name of your PC (Computer Name) is "MyPC". To get the default home page to display, you need to type in http://mypc/, or http://MyPC.default.htm. The web server will always look for a file called "default.htm" (or default.asp) in your web server's "root" folder if not instructed otherwise. Web servers have what is known as a "root" folder. In the case of Personal WebServer 4.0 and IIS, the "root" folder is C:\Inetpub\wwwroot.

The root folder is the equivalent of the "C:\" folder of the hard drive. This root folder can be any subfolder on the hard drive, but the server needs to be informed of where that root folder is.

The web server cannot "see" any folder higher than its root folder. This provides for security. The root folder is the starting point for the web server, and it can "see" all the folders and subfolders in its own tree. Most folders are read access only. One of the subfolders of the web server is /scripts (or /cgi-bin) and it is this folder only that has read/write/execute access by default. Your ISAPI or CGI application will reside in this folder.

You can access another page called "MyHTML.htm" from your web server's root folder by typing http://MyPC/MyHTML.htm as the URL. To access a script with a name of MyISAPI.DLL, the URL would be http://MyPC/scripts/MyISAPI.DLL. Since you have not specified any "action" (after the DLL name), the default "action" of your web application, (something you define) will be executed.

Let's say we had a logon screen that we wanted displayed. The action we decided for this is "/logon". (Note use of the forward slash.) To get the Logon page (dynamically generated by our ISAPI application) the URL would be http://MyPC/scripts/MyISAPI.DLL/logon. This request is sent on to PWS. PWS receives this request, loads our DLL in memory, and sends the "logon" action. In our application, this action's event will be fired.

The key point to understand is that it is our job to send back an HTML page in the form of a string. So in this way a form of communication is established between the client and the server. If you understand this concept, you can go on to building an ISAPI application using Delphi.

Building your first ISAPI application

• Start Delphi
• Choose File | New
• From the dialog, choose - Web Server Application and then OK.
• In the next dialog, leave the selected option as ISAPI (you have CGI and Win-CGI options as well).

You should now see a new project with a Web Module and its unit.

At this point, I suggest you go into the project options dialog and set the "output directory" on the Directories and Conditionals page, to the scripts folder of your web server. That is - C:\Inetpub\scripts. The reason I suggest doing this is so when you compile your application, the DLL will be generated in the folder in which you need it.

• Save the project with the of name MyISAPI.

The web module is where you place you Data access components.

• To add actions to your web application, either click on the ellipses for the "actions" property in the object inspector or double click on the web module, to display the Actions editor.

• Add an action to the web module. Once you have the Actions editor active, click on the "Add new" toolbar button of the actions editor.

• With the new action selected in the (Actions) editor, switch to the object inspector. You should see the properties of the selected action. The "PathInfo" property is what we need to set. In this case, we want to set the path to "/logon". Even if you type just "logon", the object inspector will change it to "/logon".
• Now switch to the events page of this action item, and create an event handler for the one (and only) event you see there, called "OnAction".

At the point of writing code for the OnAction event, you should notice the parameters that are passed onto you, namely, the "request" and the "response" parameters. Both of these are objects and have their own set of properties and methods.

Our "logon" action needs to return the logon screen to the browser. So what we need to do is return the HTML tags and text that will produce a logon screen in a browser. One needs to know HTML to some degree to know what tags need to be sent back to the browser to display and HTML screen.

We use the request object to find out what was requested of us, and the response object to send data back to the web browser. In this case (because this event will be fired for us) we don't need to know what was requested, since all we need to know is that a logon screen was requested. But what we do need to do is send back the logon screen. The way we do that is:

procedure TWebModule1.WebModule1WebActionItem1Action(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
begin
  Response.Content :=
    '<html>'  
    '<head>'  
    '        <title>User Log On</title>'  
    '</head>'  
    '<body>'  
    { Remember to change the URL from skumar to your PC's name !! }
    '<form action="http://skumar/scripts/MyISAPI.dll/logUser" method="post">'  
    '<BR/>UserID<input name="txtUserID">'  
    '<BR/>Password<input name="txtPassword">'  
    '<BR/><BR/>'  
    '<input type="submit" value="Submit">'  
    '<input type="reset" value="Reset">'  
    '</form>'  
    '</body>'  
    '</html>';
end;

The Response.Content property contains the HTML that needs to be sent back. What is sent back is an HTML Form. "Data Entry" screens in HTML are known as "Forms" and use the <FORM> tag to delineate the form. What happens when the "submit" button is clicked is determined by the forms' "action". In this case:

<FORM action=http://MyPC/scripts/MyISAPI.DLL/logUser method=post>

So when the submit button is clicked in this case, the request will be made to our ISAPI application (MyISAPI.DLL) with the "/logUser" action sent to it. So we need to have a "/logUser" action item in our application as well. So lets go back and:

1. Add a new action to the web module.
2. Set the PathInfo property of this action item to - /logUser.
3. Generate an OnAction event handler for this action item.

What we want to do now is verify that the user id and password are valid. To be able to do that, we need to know what the "user id" and "password" are that were sent. How do we get the user id and password so that it is available to the LogUser action?

Notice that the "method" of the <FORM> above is "post". When you use the "post" method of an HTML form, the parameters of the form are made available to you in the "ContentFields" property of the Request Object sent to you as a parameter in the OnAction event. The ContentFields property is of type TStrings.

The HTML form's "values" (values of the various fields of the form) are made available to you in the ContentFields property as Name value pairs in the format:

txtUserID=skumar
txtPassword=shiv

The "name" or left part of the equation is the name of the field, got from the <INPUT> tags, here txtUserID and txtPassword. The actual values sent back will be returned as the element to the right of the "=".

The TStrings object has methods to make extracting these values simple. To extract these values you need to use the following code:

sUserID := Request.ContentFields.Values['txtUserID'];
sPassword := Request.ContentFields.Values['txtPassword'];

where sUserID and sPassword are declared as local string type variables.

So the whole event handler of the /loguser action item will look like:

procedure TWebModule1.WebModule1WebActionItem2Action(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
var
  sUserID: string;
  sPassword: string;
begin
  { Extract the values for the forms' fields }
  sUserID := Request.ContentFields.Values['txtUserID'];
  sPassword := Request.ContentFields.Values['txtPassword'];

  { Validate the UserID and Password fields }
  if (sUserID = '') or (sPassword = '') then
  begin
    Response.Content :=
      '<html>'  
      '<head>'  
      '        <title>Log On Error</title>'  
      '</head>'  
      '<body>'  
      'Either the UserID or Password was blank.'  
      'Please make sure your user information is entered correctly'  
      '</body>'  
      '</html>';
  end
  else
  begin
    { At this point you could verify the userid and password with
      data in a database or any other way. Assuming the userid
      and password are valid. You can then send back an HTML page
      indicating that to the user.
    }
    Response.Content :=
      '<html>'  
      '<head>'  
      '        <title>User is Valid</title>'  
      '</head>'  
      '<body>'  
      'Welcome. Your profile has been recognized.'  
      '</body>'  
      '</html>';
  end;
end;

Remember, you need to use the Request object in this case and not the Response object. The Request Object is used to GET information about the request. The Response Object is used to send information back to the requestor.

Once we have this information, we can determine the validity of the user using standard Delphi methods.

Testing MyISAPI

1. We are now ready to compile and test MyISAPI DLL. If you changed the Output directory to the scripts folder of your web server then you should see the file MyISAPI.DLL in this folder once you've compiled your application.
2. Open up your browser and type in the following URL. Remember to substitute "MyPC" with the name of your PC. The URL is http://MyPC/scripts/MyISAPI.DLL/Logon
3. This should show you a page similar to this.

Fill in the Fields and hit the submit button. Unless you've left any of the fields blank, you should see an HTML page like this:

Developing Web applications: ISAPI or CGI?

Those using PWS should choose CGI instead of ISAPI when creating the web application. The reason is that PWS does not have the option to stop the HTTP service. Due to this. DLLs once loaded can't be released by the web server easily, and you will not be able to compile your ISAPI DLL more than once without re-booting. The down side of this is that you can't debug CGI applications like you can an ISAPI application.

If you are using IIS and you wish to recompile your project, stop the HTTP service, recompile and then start the service again before attempting to refresh the browser. You could also set IIS such that it does not cache ISAPI Applications. But remember to turn on caching on your production web server.

From a development perspective there is no difference between ISAPI and CGI. You may find it convenient to develop your applications as CGI through the development and de-bugging stages, and then when done, convert the CGI to an ISAPI. To do this a few minor changes are required in the Project source file:

1. Change the word "program" to "library" in the main project file.
2. Add an "export" clause for ISAPI.
3. Change the "CGIApp" unit to "ISAPIApp" in the uses clause.

You can use compiler directives to account for these differences, so it becomes simple to change from CGI to ISAPI and back. There will be absolutely no change required to your code, except for the consideration that an ISAPI app loads only once so the OnCreate event of the web data module is called only once. Database access needs to be multi-threaded which is easily accomplished by using a TSession component with its AutoSessionName property set to True. Any initialization code needs to be considered.

Add the following compiler directives to your project file:

{$IFDEF ISAPI}
library Project1;
{$ELSE}
program Project1;
  {$APPTYPE CONSOLE}
{$ENDIF}
uses
  WebBroker,
  {$IFDEF ISAPI}
  ISAPIApp,
  {$ELSE}
  CGIApp,
  {$ENDIF}
  Unit1 in 'Unit1.pas'  {WebModule1: TWebModule};
{$R *.RES}
{$IFDEF ISAPI}
exports
  GetExtensionVersion,
  HttpExtensionProc,
  TerminateExtension;
{$ENDIF}
begin
  Application.Initialize;
  Application.CreateForm(TWebModule1, WebModule1);
  Application.Run;
end.

Note: The WebBroker unit found in the uses clause was theHTTPApp unit in Delphi 3 and 4.

Using Code Templates to Make HTML'ing Faster and Easier

One can make good use of the code template features of Delphi's code editor, which will speed up your HTML typing. Some examples are.

'<INPUT TYPE="TEXT" NAME="txt|">'
'<FORM METHOD="POST" ACTION="'   Response.ScriptName   '/|">'   crlf  
'</FORM>'

Even a simple thing like typing "Response.Content := " can be painful since the code completion wizard will show you "Response.ContentEncoding". So set up a short cut such as "res" that generates

Response.Content :=  | 

This time we will build an application that:

1. Generates an HTML form, allowing users to enter some data.
2. Validates and posts this information to a database.
3. Displays the information stored in the database in a dynamically generated HTML page.

The application that we will build is a simple application that allows other web site owners to add a link to their web site to be accessed from our web site. Rather than having them send us an email and then we manually make the change in our database, we will build an application that will automate the process for us.

To create a data entry form, we could create an HTML file and place it in the web server's root folder. To display it, you would enter the URL to the HTML form, such as:

http://ServerName/DataEntry.htm

ServerName is the Computer Name of your PC or web server. DataEntry.htm is the physical name of the HTML file that resides in the root folder of your web server (C:\inetpub\wwwroot).

The other approach, the one we will use here, is to generate the HTML form from our application. Here, we will:

1. Create a web server application called AddLink, and add an "action" to it called "AddLinkPage". The URL to this would be - http://servername/AddLink.Dll/AddLinkPage

   Notice the "scripts" word. If you remember, all ISAPI and CGI applications need to be in the scripts folder of the web server (C:\Inetpub\scripts). Or any folder with access rights similar to that of the scripts folder.

2. Write some code in the OnAction event of this action that will send back the HTML required for the browser to show the form.

Let's start a new ISAPI application using the Wizard.

• From Delphi's main menu, choose File | New and in the dialog box presented, select - Web Server Application.
• Click OK in the next dialog box shown (ISAPI application option is selected)

You should now see a Web Data Module as a blank white form.

To ensure that your applications will reside in the scripts folder, you will want to compile directly to that folder. To do this, choose Project | Options from Delphi's main menu. In the dialog box presented, switch to the - Directories/Conditionals page, and in the "output directory" field, enter the path to the scripts folder, for example, C:\Inetpub\scripts. Then click the OK button. We do this so that our ISAPI DLL is generated in this folder rather than copy it over to this folder each time we re-compile.

To create an Action item, select the Web Data Module, and then from the object inspector's properties page, select "Actions" and click on the ellipses (or double click on the data module (not in the TreeView partition of the Datamodule (D5)) to active the Actions editor).

You will be presented with the Actions Editor. Click on the "Add new" button.

In the object inspector, fill in the PathInfo property as "/AddLinkPage". Set the "Name" property to "waAddLinkPage".

The object inspector and actions editor should look like that shown in Figure 1.


Figure1: Showing the Object Inspector and Actions Editor with the /AddLinkPage action item.

Now, choose the Events page of the object inspector and generate the OnAction event handler for this action item. In the event handler, type in the following code:

procedure TWebMod1.WebMod1waAddLinkPageAction(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
begin
  Response.Content :=
    '<html>'   NewLine  
    '<head>'   NewLine  
    '	<title>Add a Link to your Web Site</title>'   NewLine  
    '</head>'   NewLine  
    '<body>'   NewLine  
    '<h2>Please Enter the Required information to be able to link your Site from here.</h2>'   NewLine  
    '<form action="'   Request.ScriptName   '/PostLinkInfo" method="post"'   NewLine  
    '  title="Enter the information required to Add a link to your Web Site.">'   NewLine  
    '<table>'   NewLine  
    '<tr>'   NewLine  
    '<td><font face="Tahoma">URL to your Web Site</font></td>'   NewLine  
    '<td><font face="Tahoma"><input type="text" name="txtLinkURL"'   NewLine  
    '  style="height: 22px; width: 274px" value="http://"></font></td></tr>'   NewLine  
    '<tr>'   NewLine  
    '<td><font face="Tahoma">Title to be Shown</font></td>'   NewLine  
    '<td><font face="Tahoma"><input type="text" name="txtTitle"'   NewLine  
    '  style="height: 22px; width: 274px"></font></td></tr>'   NewLine  
    '<tr>'   NewLine  
    '<td><font face="Tahoma">Description to be shown</font></td>'   NewLine  
    '<td><textarea name="txtDescription" style="height: 80px; width: 274px"></textarea></td></tr>'   NewLine  
    '<tr>'   NewLine  
    '<td><font face="Tahoma">Owner''s First Name</font></td>'   NewLine  
    '<td><font face="Tahoma"><input type="text" name="txtOwnerFirstName"'   NewLine  
    '  style="height: 22px; width: 274px"></font></td></tr>'   NewLine  
     '<tr>'   NewLine  
    '<td><font face="Tahoma">Owner''s Last Name</font></td>'   NewLine  
    '<td><font face="Tahoma"><input type="text" name="txtOwnerLastName"'   NewLine  
    '  style="height: 22px; width: 274px"></font></td></tr>'   NewLine  
    '<tr>'   NewLine  
    '<td><font face="Tahoma">Email Address</font></td>'   NewLine  
    '<td><font face="Tahoma"><input type="text" name="txtEmailAddress"'   NewLine  
    '  style="height: 22px; width: 274px"></font></td></tr>'   NewLine  
    '<tr>'   NewLine  
    '<td><font'   NewLine  
    '  face="Tahoma"><input type="submit" name="btnSubmit" value="Submit"></font></td>'   NewLine  
    '<td><font'   NewLine  
    '  face="Tahoma"><input type="reset" value="Reset"></font></td></tr>'   NewLine  
    '</table>'   NewLine  
    '</form>'   NewLine  
    '<P><h4>The server will attempt to validate the URL you are attempting to submit. If you get an error'   NewLine  
    ' due to an invalid URL. Please refresh the page before attempting to re-sumbit.'   NewLine  
    ' if everything goes fine, you should be re-directed to the Links Page.'   NewLine  
    ' You should be able to see the link you just added.'   NewLine  
    '<P>Thank you for taking the time to link your web site from here.</h4>'   NewLine  
    '</body>'   NewLine  
    '</html>';
end;

Note: You may want to use the variable "NewLine" in your web applications to make the generated HTML more readable. You may declare it as a constant in the interface section of the unit, as:

const
  NewLine = #13#10;

Instead of NewLine, you may prefer crlf (easier to type). Also, remember that we don't need to have a new line per se. We do this only to format the generated HTML. The browser will render the page in exactly the same way, with or without the new line. But if one was to see the source of the HTML, then it would all be in one line. This would make it awfully difficult to debug (the HTML) if things were to go wrong. I personally like to see well formatted HTML when I look at the source of an HTML page.

Now let's have a closer look at the Form's "Action":

<FORM action='   Request.ScriptName   '/PostLinkInfo method=post'   NewLine   ' title="Enter the information required to Add a link to your Web Site.">

The Action tells the browser what to do when the "submit" button is pressed. In this case, we tell the browser to execute the action item with the PathInfo property set as /PostLinkInfo in our ISAPI. The Action evaluates to:

/scripts/AddLink.dll/PostLinInfo.

The

Method

Title

Since we have told the web server to direct the form's data to the /PostLinkInfo action of our application (AddLink.dll), we will need to create an action item with a PathInfo of "/PostLinkInfo". We'll do that later.

For now, let's see what is happening in the OnAction event created above. What we're doing, is sending back (using the "Response" object's "Contents" property) the HTML required for a data entry HTML form. The Contents property is a string that is sent back via the web server to the requesting browser.

For this example, the fields we need our user (who is interested in adding a link to her site from our web site) to enter, are:

1. The URL to the site (for example - http://www.matlus.com)
2. The Title to be shown on your web site (for example - The Delphi Stop)
3. The description of the web site.
4. The web site owner's First Name.
5. The web site owner's Last Name.
6. The web site owner's email address.

When you see this form, you will notice that the URL field already has the text - "http://". This is done at the time of generating the form, by entering "http://" in the "value" attribute as follows:

'<TD><FONT face=Tahoma><INPUT name=txtLinkURL'   NewLine  
' style="HEIGHT: 22px; WIDTH: 274px" value="http://"></FONT></TD>

Notice also that each field on the HTML Form (recognized by the <INPUT> tag) has a unique name such as txtLinkURL. Later, we will use these names to extract the values for each of the required fields in order to post this information to a database.

So we have an action item in our ISAPI DLL that will generate a data entry form. To call this action, you will enter the following URL in the web browser's address field:

http://ServerName/scripts/AddLink.dll/AddLinkPage

Before you can use this URL in your browser, you must:

1. Make sure that your web server is running and the HTTP service has been started.
2. Compile your application and make sure that a DLL by the name AddLink.dll exists in your web servers "scripts" folder.
3. Substitute the ServerName with your PC's name or IP address.

Note that if you need to recompile your project for any reason as an ISAPI (DLL), you must stop and restart the WWW service, and then recompile your application. (This is not necessary for a CGI (EXE)). If you are using IIS, you could turn off - Cache ISAPI Applications checkbox in the Internet service manager options. Be sure to turn it on, on your production web server machine.

In order to release the lock on a DLL, PWS must be manually stopped using the command prompt. By default, Pws.exe resides in the folder C:\Windows\System\Inetsrv.

To stop PWS, type the following command:

You can then restart PWS manually restarted from the Command Prompt by using the following command:

Once PWS is stopped, this will release the ISAPI DLL. Recompile the DLL, if necessary. Once PWS restarts, it will again lock the DLL when it gets instantiated by your browser.

At the run line, type: net stop iisadmin /y and then press Enter. This will stop all services while running the make on the DLL.

After recompiling your DLL, type: net start w3svc from the run line. Your services will be up again.

After you have compiled the ISAPI DLL, make sure it is present in your scripts folder. Type in the URL and you should see the form as shown in Figure 2.


Figure 2: Showing the dynamically generated Data Entry Screen in a browser.

If we set the Default property of this action to True, we could simply type in the URL

http://ServerName/scripts/AddLink.dll/AddLinkPage

http://ServerName/scripts/AddLink.dll and we would get the same form.

Now that we have an HTML form that will allow us to capture data, we need to "receive" this data, validate it and post it to our database.

We need to create an Action item that corresponds to the Form's action. The form's action is:

<FORM action='   Request.ScriptName   '/PostLinkInfo method=post>

This evaluates to - /scripts/AddLink.dll/PostLinkInfo.

To do this, we need to create a new action item. Set the pathinfo property to - /PostLinkInfo and the Name property to waPostLinkInfo. Then we need to write an event handler for the OnAction event of this action item. But before that, we need our database in place.

For this example, we'll use an Access database. Access is fine for small ISAPI/CGI applications. But ideally you should use an RDBMS. The name of the table in the Access mdb is LINKS and the structure of the table is as shown in Figure 3.

Key	FieldName	Type
Yes	LinkURL	Text
	Title	Text
	Description	Text
	DateAdded	Text
	OwnerFirstName	Text
	OwnerLastName	Text
	EmailAddress	Text

Figure 3: The structure of the LINKS table in the Access mdb.

Create an ODBC alias for this mdb file called WEBSITE_ODBC using the ODBC Manager. The ODBC DSN should be a System DSN since it will be used by the Webserver(IIS) and not by a logged-on user. This point is very important to note. On Windows NT, IIS uses IUSER_ as the user. This user has limited access to the system. Also, I suggest creating a folder called Database under the scripts folder and keeping all databases in this folder.

Lets add some data access component and set of few properties.

1. Drop a TDatabase component, a TQuery and a TSession component.
2. Set the AliasName property of the database component to WEBSITE_ODBC.
3. Set the DatabaseName of the database component to DELPHILINKS.
4. Set the DatabaseName of Query1 to DELPHILINKS.
5. Set the Login property of the TDatabase component to False.
6. Set the params property to

We can't have a login dialog box popping up in our ISAPI/CGI applications. We will never see this dialog box and therefore we'll never be able to log in to the database. When that happens, the application will seem to hang. It's not really hanging, but since you didn't login, you won't be able to use the application either. Setting the LogInPrompt property to False and setting the parameters as shown above, will allow our ISAPI/CGI application to log in to the database non-interactively.

Set the AutoSessionName of the TSession component to True.

Remember that an ISAPI DLL runs in the process space of the web server. Each time a request is made to the ISAPI DLL, a new thread is spawned (An instance of the web data module is created in this thread). To be able to connect to a database multiple times (like in a multi-threaded application) using the same instance we need to provide a unique session name for each connection. The TSession component handles that for us when we set the AutoSessionName property to true. Do not use a TSession component in your CGI applications. The web server creates a new instance of your CGI application for each request and so a unique session name is not required. Your data module should look like that shown in Figure 4.


Figure 4 shows the web data module with the data access components thus far.

Every action's event (OnAction) makes 2 objects available to you -- the Request object and the Response object. You can see above that we've used the Request object's ScriptName property.

The Request.ScriptName property evaluates to - /scripts/AddLink.DLL. It is good practice to not hard- code the script's name, but instead use the ScriptName property. Later if you change the name of the script or the scripts folder, you won't have to modify your code.

Since we used the POST method of the form above, the data of that form will be made available in the ContentFields property of the Request object - "Request" since it comes to this event as a Request made by the browser via the web server. If we use the GET method in the HTML form, then the same information would be made available to us in the QueryFields property of the Request object.

To make our data validation easier, we will first create two custom Exception objects that can be raised if any part of the data is invalid, by putting the following code in the Type section:

type
  EInsufficientInfo = class(Exception);
  EInvalidURL = class(Exception);

The ContentFields and QueryFields properties are TStrings derivatives. The Form's data is made available to us in the form of name=value pairs. So the data entered in the URL field will look like

txtLinkURL=http://www.matlus.com

We can therefore use the Values method of the ContentFields object to get the Value for a given (Field) Name. The code in this action item's OnAction event will look like this:

procedure TWebMod1.WebMod1waPostLinkInfoAction(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
begin
  { I've create a custom Exception object called - EInsufficientInfo that will
    be rasied if any part of the data is invalid. In this case invalid = null.
  }
  try
    { Validate Data Entered by the User }
    if Request.ContentFields.Values['txtLinkURL'] = '' then
      raise  EInsufficientInfo.Create('Please Enter the URL of your Web Site');
    if Request.ContentFields.Values['txtTitle'] = '' then
      raise  EInsufficientInfo.Create('Please Enter the Title you want Displayed for your Web Site');
    if Request.ContentFields.Values['txtDescription'] = '' then
      raise  EInsufficientInfo.Create('Please Enter the Description you want Displayed for your Web Site');
    if Request.ContentFields.Values['txtOwnerFirstName'] = '' then
      raise  EInsufficientInfo.Create('Please Enter Your First Name.');
    if Request.ContentFields.Values['txtOwnerLastName'] = '' then
      raise  EInsufficientInfo.Create('Please Enter Your Last Name');
    if Request.ContentFields.Values['txtEmailAddress'] = '' then
      raise  EInsufficientInfo.Create('Please Enter your contact Email Address');

    { In this particular case, we'd like to validate the URL that the user has
      entered as well. To do that, we'll use an HTTP component in the URLIsValid
      function. Warn the user if the URL is found to be invalid.
    }
    if not URLIsValid(Request.ContentFields.Values['txtLinkURL']) then
      raise EInvalidURL.Create('The URL you submitted is not a valid URL.'   #13#10  
        'Please make sure you type a valid URL before submitting');

    { If data is Valid and URL is Valid, post it to the database }
    Query1.Close;
    Query1.SQL.Clear;
    Query1.SQL.Add('INSERT INTO LINKS');
    Query1.SQL.Add('(LinkURL, Title, Description, DateAdded, OwnerFirstName, OwnerLastName, EmailAddress)');
    Query1.SQL.Add('Values(:LinkURL, :Title, :Description, :DateAdded, :OwnerFirstName, :OwnerLastName, :EmailAddress)');
    Query1.ParamByName('LinkURL').AsString := Request.ContentFields.Values['txtLinkURL'];
    Query1.ParamByName('Title').AsString := Request.ContentFields.Values['txtTitle'];
    Query1.ParamByName('Description').AsString := Request.ContentFields.Values['txtDescription'];
    Query1.ParamByName('DateAdded').AsDateTime := Now;
    Query1.ParamByName('OwnerFirstName').AsString := Request.ContentFields.Values['txtOwnerFirstName'];
    Query1.ParamByName('OwnerLastName').AsString := Request.ContentFields.Values['txtOwnerLastName'];
    Query1.ParamByName('EmailAddress').AsString := Request.ContentFields.Values['txtEmailAddress'];
    Query1.ExecSQL;
    { If every thing went fine, we want to show the user the links page, so he
      can see the link he just added
    }
    Response.SendRedirect(Request.ScriptName   '/ShowDelphiLinks');
  except
    on E : Exception do
      Response.Content := Format('<html><head><title>Error Posting Inforamtion</title>'  
        '</head><body><H1>%s</H1></body></html>',
        [E.Message]);
  end;
end;

If the data was posted successfully to the table then we want to show a list of links in our database. This line will redirect the browser to the action in our ISAPI DLL that can do that. We have yet to create that action and the code for it. We'll do that soon.

The Code for the URLIsValid function looks like:

function TWebMod1.URLIsValid(URL : string) : Boolean;
begin
  try
    URLValid := True;
    NMHTTP1.Get(URL);
    Result := URLValid;
  except
    Result := False;
  end;
end;

NMHTTP1 is a NetMaster's HTTP component. We use this component to try and retrieve the web site the user gave us. If the HTTP component can not find the URL it fires the OnInvalidHost event. In this event we set the URLValid variable to false, indicating that the URL was not found. If we find the URL, we set this variable to true.

Those using Indy (Indy aka Winshoes 8 can be downloaded from the Indy Web Site) can use the IdHTTP component for this function like this:

function TWebMod1.URLIsValid(URL : string) : Boolean;
begin
 try
   { If the URL is not found an exception will be rasied }
   IdHTTP1.Get(URL);
   Result := True;
 except
  Result := False;
 end;
end;

Before we go onto create the waShowDelphiLinks action item let's briefly discuss the difference between the GET method and the POST method. We have used the POST method here. If instead we used the GET method, the URL would change when you hit the submit button. The browser will add (to the path information) the information as parameters to send back to the server.

In this case the URL would look like:

http://ServerName/scripts/AddLink.dll/PostLinkInfo?txtLinkURL=http://mywebsite.com&txtTitle=My%20Site%20Title&txtDescription=My%20Sites%20description

Your application accesses the data from the Request object's "QueryFields" property rather than its "ContentFields" property, extracting the values from Request.QueryFields in the same manner as Request.ContentFields since both properties are TStrings derivatives.

The advantage of the GET method is that it does not require a form to send information back to your application. You can simply append the value you need to send, to the end of the URL. In the POST method, the information is captured from the form and sent as a separate stream. Of course you may find that the POST method is advantageous because the information does not appear in the address box of the browser. Additionally, the POST method can handle much greater volumes of information.

So what have we done so far?

1. We have an action item that will generate an HTML data entry form. To see this form in the browser, the URL we need to use is http://ServerName/scripts/AddLink.DLL/AddLinkPage
2. We have another action item whose path info is set to /PostLinkInfo. This is the action item that will be called (it's OnAction event) when the user hits the submit button of the form. The reason this action item's OnAction event is fired when the submit button is hit, is that the Form's Action property is set to the above action item's path info.
3. The /PostLinkInfo's OnAction event will validate the data entered and will either send back the appropriate information if the data is not valid or post the information to a database table if everything is working fine. Before the data is actually posted in the tables, we also check to see if we have been given a valid URL for the site to link to.

We can do this in two ways. The simpler way is to use the TQueryTableProducer component that comes with Delphi. The second way is to do the work manually. For now, we'll take the manual approach

To display the information, which in our example is links to other sites, we will create a new Action item and call it waShowDelphiLinks and set its PathInfo property to /ShowDelphiLinks.

Drop another TQuery component on the web data module. Set its DatabaseName property to DELPHILINKS and its SQL property to:

In the OnAction event of this action we have the following Code:

procedure TWebMod1.WebMod1waShowDelphiLinksAction(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
begin
  with Query2 do
  begin
    Open;
    Response.Content :=
      '<html>'   NewLine  
      '  <head>'   NewLine  
      '    <title>Delphi Links People have added</title>'   NewLine  
      '  </head>'   NewLine  
      '<body>'   NewLine  
      { The Image is in a sub folder of your web server's root folder called "Images"
        for exmaple C:\inetpub\wwwroot\images\ }
      '<img src="/Images/DelphiLinksHead.gif">'   NewLine  
      '<a href="'   Request.ScriptName  
        '/AddLinkPage"><img alt="Add a link to your web site from here" border="0" src="'  
        '/Images/AddLink.gif"></a>'   NewLine  
      '<p/><hr/>'   NewLine  
      '<table>'   NewLine;

    while not Eof do
    begin
      Response.Content := Response.Content   Format('<tr>%s<td><table><tr><td><a href="%s"><b>%s</b></A></td>%s'  
      '<td><b>Posted By:</b>%s</td>'  
      '%s<td><b>Date Posted:</b>%s</td></tr></table>%s<b>Description:</b><br>%s%s</td>%s</tr><tr><td><hr/></td></tr>',
        [NewLine,
         FieldByName('LinkURL').AsString,
         FieldByName('Title').AsString,
         NewLine,
         FieldByName('OwnerFirstName').AsString   ' '   FieldByName('OwnerLastName').AsString,
         NewLine,
         FieldByName('DateAdded').AsString,
         NewLine,
         FieldByName('Description').AsString,
         NewLine,
         NewLine]);
      Next;
    end; { while not Eof }
    Close;
    Response.Content := Response.Content  
      '</table>'   NewLine  
      '</body>'   NewLine  
      '</html>';
  end;
end;

Notice the line

      '<img src="/Images/DelphiLinksHead.gif">'   NewLine  
      '<a href="'   Request.ScriptName  
        '/AddLinkPage"><img alt="Add a link to your web site from here" border="0" src="'  
        '/Images/AddLink.gif"></a>'   NewLine  

We've referenced 2 images here. These images should be in a sub folder of your web server's root folder. The name of the sub folder should be Images. You can call this folder anything you like but be sure to change the code above to match your folder's name.

It is a good idea to keep images in a separate folder, rather than in the root folder. It's easier to manage your web sites that way. The second image is hyper-linked. This link will direct the user to our Data Entry screen.

Also notice the line with the Format procedure. This line of code generates a string that looks something like this:

<A href="http://www.matlus.com"><B>The Delphi Stop</B></A>

In the browser this will be rendered as words - The Delphi Stop, in bold typeface as hyper-linked text. When one clicks on the hyperlink, the browser will direct you to the URL specified in the HREF attribute of the anchor <A> tag.

To see this page, the URL will be http://ServerName/scripts/AddLink.dll/ShowDelphiLinks.

Since we'd like our users to hit this page by default we'll set the Default property of this action item to True. This will automatically set all other action item's Default property to False. There can be one and only one default action in an ISAPI/CGI application.

If you have data in your table, then the generated HTML page should look like that shown in Figure 5.

Figure 5: Showing the default page of our ISAPI.

There you have it -- an ISAPI/CGI that allows data entry into a database and then displays that information in an HTML page.

Starting the Project

1. Start a new Web Server Application using the Delphi wizard.
2. Choose CGI in the dialog box (you can choose ISAPI also. There will be no change in the code)
3. Choose the Project menu from the IDE.
4. Choose Options from the Project menu.
5. In the Project Options dialog, click on the Directories/Conditionals page.
6. Set the Output directory to - C:\inetpub\scripts (or your scripts folder of you web server).
7. Create 2 action items by double clicking on the Web Data Module.
8. Set the PathInfo property of the first action item to /Fish, the Name to waFish and the defalt property to True.
9. Set the PathInfo of the second action item to /SendImage and the Name to waSendImage.
10. Drop a TQuery component onto the Web Data Module and set its DatabaseName property to DBDEMOS.

In the OnAction event of the waFish action item, type the following code:

procedure TWebModule1.WebModule1waFishAction(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
begin
  try
    with Query1 do
    begin
      Close;
      SQL.Clear;
      SQL.Add('SELECT BIOLIFE."Species No", Common_Name FROM BIOLIFE');
      Open;
      Response.Content := Response.Content  
      '<h2>The various species of Fish</h2><br>'   #13#10  
      'Click on the hyperlinks below to see the picture of the given species<P>';
      while not Eof do
      begin
        Response.Content := Response.Content  
          Format('<a href="%s/%s?No=%s">%s</a><br>'   #13#10,
                [Request.ScriptName,
                 'SendImage',
                 Fields[0].AsString,
                 Fields[1].AsString]);
        Next;
      end; { while not Eof }
      Close;
    end; { with Query1 do }
  except
    on E : Exception do
      Response.Content := '<b>ERROR</b><br>'   #13#10  
        E.Message;
  end;
end;

<A HREF="/scripts/Fish.exe/SendImage?No=90030">Red Emperor</A><BR>

This is standard HTML. Notice here that the /SendImage action is called sending it a parameter -"No=90030". We will "extract" the value of "No" from this to use in the next query that we will build dynamically in the /SendImage action's OnAction event.

The /SendImage action's OnAction event looks like this :

procedure TWebModule1.WebModule1waSendImageAction(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
var
  JPEG   : TJPEGImage;
  MemStrm: TMemoryStream;
  Bitmap : TBitmap;
begin
  { In this action event, I "extract" the Species No parameter from the QueryFields
    property of the Request object and use that to get the image from the
    table.
    Then I stream out the image as a Jpeg image
  }
  try
    JPEG := TJPEGImage.Create;
    MemStrm := TMemoryStream.Create;
    Bitmap := TBitmap.Create;
    try
      with Query1 do
      begin
        Close;
        SQL.Clear;
        SQL.Add('SELECT Graphic FROM BIOLIFE');
        SQL.Add('WHERE BIOLIFE."Species No" = :LastName');
        Params[0].AsInteger := StrToInt(Request.QueryFields.Values['No']);
        Open;
        { Assign the image from the database to a Bitmap object since the
          field type is a TGraphicField.}
        Bitmap.Assign(FieldByName('GRAPHIC'));
        JPEG.Assign(Bitmap);
        JPEG.SaveToStream(MemStrm);
        MemStrm.Position := 0;
        { The content type needs to be set !! }
        Response.ContentType := 'image/jpeg';
        Response.ContentStream := MemStrm;
      end;
    finally
      JPEG.Free;
      { Do not Free MemStrm. The Web server will take care of it. }
      Bitmap.Free;
    end;
  except
    on E : Exception do
      Response.Content := '<b>ERROR</b><br>'   #13#10  
        E.Message;
  end;
end;

The code above is commented to explain what is going on. If one had instantiated the fields of the Query object than one could have assigned the field object (for the image field) directly to the bitmap. The code for that would look like Bitmap.Assign(Query1Graphic). In this particular example, you shouldn't/can't instantiate the field object explicitly since we use the same Query object for different SQL queries that return different sets of fields.

The ContentType property of the Response object can be set to 'image/gif' if you want to send gif images. The various ContentType values can be found in the HTTP specifications.

Another interesting Project is the next project where we reduce the image size just before we send the image. This technique is very useful and effective is real world ISAPI application development. Check it out.

Sending Data

This part is really simple. Actually, Delphi makes it really simple. We won't need to write any code for this so let's start building the project.

1. Start a new ISAPI Web server (extension) application.
2. Drop down a TQuery component and change its name to qryData.
3. Set the Database property of qryData to DBDEMOS.
4. Set the Active property to True.
5. Set the SQL property to SELECT * FROM BIOLIFE.
6. Drop down a TQueryTableProducer component on the Web Data Module.
7. Drop down its Query property and set it to qryData.
8. Double click on the Web Data Module (or right click on it and choose "Action Editor...") and create a new action item.
9. Set the PathInfo property of this action item to

   /data

   .
10. Change the Name property of the action item to

    waData

11. Set the Default property to

    True

12. Drop down the Producer property of the action item and set it to

    QueryTableProducer1

    .
13. Drop down a TSession component and set its AutoSessionName property to

    True

    .
14. From the Project | Options menu, set the output directory to C:\inetpub\scripts (or the scripts folder of your web server. This step is followed in all ISAPI/CGI projects.

Your Object inspector and Web Data Module should look like that shown in Figure 1.

Figure1: Showing the Object inspector and Web Data Module thus far.

Explanation

There can be only one action item per application with its default property set to True. What this really does is, it allows you to call your ISAPI/CGI application from a browser without the need to specify an action. So the URLs http://www.mydomain.com/scripts/myserverextension.dll/data and http://www.mydomain.com/scripts/myserverextension.dll will return the same page. In other words, the same action is executed in this case since the action item with the pathinfo - /data has been set as the default action.

Setting the Producer property of the action item to the QueryTableProducer1 causes the Response.Content property of the web module to be automatically set to QueryTableProducer1.Content in the OnAction event of the action item. One could create an OnAction event for this action item and write the line

Response.Content := QueryTableProducer1.Content;

to achieve the same end result without setting the Producer property. In this case we'll use the property and so we won't write any code in the OnAction event.

Every request from the web server causes your ISAPI application to spawn a new thread within which a new instance of the web data module is created. To allow for multiple simultaneous access to a we use a TSession component and set its AutoSessionName property to True so it generates a new session name for every session (thread). For CGI applications this is not required (and should not be done) since every request from the web server creates a new instance of your CGI application (simulating multiple simultaneous users, each using an instance of your application) thereby allowing for multiple simultaneous access to your database.

Seeing the output

Save your project as Biolife.dpr and compile your application. This should create a DLL by the name of Biolife.dll in the scripts folder of your web server. In your browser, type in the URL

http://mypcname/scripts/biolife.dll (replace mypcname with the IP address or machine name of the machine running the web server). You should see a page like the one shown in Figure 2.

Figure 2: Showing the output generated by the QueryTableProducer component.

Notice how the Notes Field has the word (MEMO) in it instead of the actual memo text. Notice also that the Graphic field shows the word (GRAPHIC) instead of the actual graphic. In the remainder of this article, we will attempt to correct this.

Before we get the memo and graphic fields to show, we'll remove some of the unnecessary fields so we see only the fields we want in our browser. This process will also demonstrate to you, how you can re-order the fields in the output if you need to do that using the TxxxTableProducer components that come with Delphi.

Using the TQueryTableProducer

The TQueryTableProducer component has a response editor that can be invoked by double clicking on it or right clicking on it and choosing the "Response editor" pop up menu option. Before you do this, you need to set the TQuery, qryData's Active property to True. The Response Editor should like that that shown in Figure 3 after you've set the Active property of qryData to True and double click on the QueryTableProducer1 component.


Figure 3: The QueryTableProducer's Response Editor

You will notice here that you see all the fields of the dataset, since our SQL statement does not explicitly specify fields. You could change the SQL statement such that you see only the fields you are interested in. This will speed up your application as well, but for now we'll see how we can accomplish field ordering and selection using the table producer component's response editor. Before we can start manipulating fields, you need to first add all fields (kind of like instantiating fields of a dataset). To do this, click on the "Add All Fields" tool bar button in the response editor. Once you've done that, you can:

1. Drag-drop fields to re-order them or use the toolbar buttons with up-down arrows.
2. Select each field in turn and set its properties listed in the object inspector.

You can also set the table properties (HTML table) using the response editor. Lets delete the fields, Length(cm), Length_in and Common_Name. This should give us some extra space to show the notes field and graphic field in the browser, instead of the words (MEMO) and (GRAPHIC). We'll also set the Border property of the HTML table (in the response editor) to 1. You should see the effect of doing this in the response editor.

Getting the Notes Field to show in the browser

To be able to see the Notes field in the browser we need to write some code in the OnFormatCell event of the QueryTableProducer component. This event is fired automatically before rendering each cell in the HTML table. At this point, you have the ability to change the content of the cell, the background color and the horizontal and vertical alignments of the content of the cell etc.

procedure TWebModule1.QueryTableProducer1FormatCell(Sender: TObject;
  CellRow, CellColumn: Integer; var BgColor: THTMLBgColor;
  var Align: THTMLAlign; var VAlign: THTMLVAlign; var CustomAttrs,
CellData: String);

Figure 4: Showing the Fields instantiated in qryData's fields editor.

Now in the OnFormatCell event, write the following code:

procedure TWebModule1.QueryTableProducer1FormatCell(Sender: TObject;
CellRow, CellColumn: Integer; var BgColor: THTMLBgColor;
var Align: THTMLAlign; var VAlign: THTMLVAlign; var CustomAttrs,
CellData: String);
begin
  { Row 0 is the Column Header, so check for CellRow > 0 }
  if (CellRow > 0) and (CellColumn = 4) then
    CellData := qryDataNotes.Value;//Memo Field data
end;

If you recompile your project and refresh your browser, you should see a result similar to that shown in Figure 5.

Figure 5: The output in the browser showing the contents of the Memo field.

Notice that the Notes field now shows the contents rather than the word (NOTES). The graphic field still shows the word (GRAPHIC) since we haven't yet done anything to change that.

Showing the Graphics Field in the browser

Getting the browser to show the graphic along with the data is a bit trickier than what we had to do to get the Notes field's contents to show. Trickier, not harder. Nothing in Delphi is hard.

Lets see what the concept is before we attempt to do this in code. The CellData (in the OnFormatCell event) for the graphics field is being set to (GRAPHIC) by the QueryTableProducer. That's why we see (GRAPHIC) in the browser instead of the graphic itself. If we change the CellData variable for the Graphic column to an HTML <IMG> tag then we should see an image instead. The problem, however is that we need to extract the image from the table and show that image. If we wanted to show an image that resided on the hard drive, we could have simply given the correct URL in the SRC attribute of the <IMG> tag and the browsers would have loaded the required image and shown it.

The concept is similar however. The change is that the image needs to come from the table and not the hard drive. We can write a procedure in our ISAPI to extract the image from the table for the given record. This image then needs to be streamed out to the browser. To get the browser to load the image, we simply give the SRC attribute of the <IMG> tag as an action item in our ISAPI. The action will then have the responsibility of sending back the corresponding image. All this may seem complicated at this point, but it really isn't. We'll work this out step by step to simplify the process.

First we need to change the CellData to an HTML <IMG> tag. Add code such that your OnFormatCell event looks like the following:

procedure TWebModule1.QueryTableProducer1FormatCell(Sender: TObject;
CellRow, CellColumn: Integer; var BgColor: THTMLBgColor;
var Align: THTMLAlign; var VAlign: THTMLVAlign; var CustomAttrs,
CellData: String);
begin
  { Row 0 is the Column Header, so check for CellRow > 0 }
  if (CellRow > 0) and (CellColumn = 4) then
    CellData := qryDataNotes.Value;//Memo Field data
  { Change the CellData from (GRAPHIC) to an HTML <IMAGE> TAG }
  if (CellRow > 0) and (CellColumn = 5) then
    CellData :=
      Format('<IMG SRC="%s/image?No=%s">',
        [Request.ScriptName,
         qryDataSpeciesNo.AsString]);
end;

The result of the Format procedure and therefore the value of the CellData variable will be something like this:

<IMG SRC="/biolife.dll/image?No=90020">

Notice that there is a reference to a /image action item in our ISAPI. We don't have this action item as yet, but we will create one soon. A parameter that we send in the form of a Name=Value pair, to this action item is No=90020. 90020 being the Species No value for the first record in the biolife table. This will change to correspond with each record's Species No value.

In our /image action item's OnAction event, we can extract this parameter using the Request object's QueryFields property. Using the Species No value, we can zero in on the required record, extract the image from the field and send it back to the browser as a response.

Let's first create a new action item and set the pathinfo property to /image and call it waImage as shown in Figure 6.

Figure 6: Showing the Actions Editor with the waImage Action item created.

If you compile your ISAPI and refresh your browser, you should see an output like that shown in Figure 7.

Figure 7: Showing the place holders for images in our database.

Notice how the actual image is not shown, since we have yet to do something about that, but the word (GRAPHIC) has now been replaced with what the browser shows for an image it has not been able to find. Since we have yet to write code in the waImage action item's OnAction event, this is expected.

1. Add the Graphics and JPEG unit to the uses clause of the interface section of the Web data module.
2. Then drop down another TQuery component on the web data module
3. Set the Name property to qryImage
4. Set the DatabaseName property to DBDEMOS.
5. Set the SQL property to

SELECT Graphic FROM BIOLIFE
WHERE BIOLIFE."Species No" = :SpeciesNo

We'll be streaming the image out as a jpeg image and we'll use another query componet, qryImage to "zero in" on the record with the species no given to us. The code in the OnAction event of the waImage action item should look like this:

procedure TWebModule1.WebModule1waImageAction(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
var
  JPEG    : TJPEGImage;
  MemStrm : TMemoryStream;
  Bitmap  : TBitmap;
begin
{ In this action event, we "extract" the Species No parameter from the QueryFields
property of the Request object and use that to get the image from the
table.Then we stream out the image as a Jpeg image
}
  try
    JPEG := TJPEGImage.Create;
    MemStrm := TMemoryStream.Create;
    Bitmap := TBitmap.Create;
    try
      with qryImage do
      begin
        { Assign the :SpeciesNo paramter the value received in the Request
          object's QueryFields property. Remember that it comes as eg. No=90020
        }
        Close;
        Params[0].AsInteger := StrToInt(Request.QueryFields.Values['No']);
        Prepare;
        Open;
        { Assign the image from the database to a Bitmap object since the
          field type is a TGraphicField.}
        Bitmap.Assign(FieldByName('GRAPHIC'));
        JPEG.Assign(Bitmap);
        { Save the JPEG image to the memory stream object}
        JPEG.SaveToStream(MemStrm);
        { Set the position to the start }
        MemStrm.Position := 0;
        { The content type needs to be set to image/jpeg. Default is 'text/html' }
        Response.ContentType := 'image/jpeg';
        Response.ContentStream := MemStrm;
        Unprepare;
        Close;
      end;
    finally
      JPEG.Free;
      { We don't need to  free MemStrm since the WebServer will do that }
      Bitmap.Free;
    end; { try - finally }
  except
    on E : Exception do
    begin
      Response.ContentType := 'text/html';
      Response.Content := '<B>ERROR</B><BR>'   #13#10   E.Message;
    end;
  end; { try - except }
end;

What we do in here is extract the Species No from the QueryFields property of the Request object and assign that to the :SpeciesNo parameter of the SQL statement used to "zero in" on the correct record. Next we extract the graphic from this record and assign it to a TBitmap object. The graphic in the table happens to be a bitmap in this case. To convert the bitmap to a jpeg image, we simply assign the Bitmap to the JPEG image. To be able to stream the image we save the JPEG image to a memory stream object.

Before we can actually send back the stream, we need to let the browser know what kind of data to expect. We do this by setting the response object's ContentType to 'image/jpeg'. Once we've done this, we send the response using the SendResponse method of the Response object.

If you now recompile the ISAPI and refresh the browser you should see an output like that shown in Figure 8.

Figure 8: Showing the contents of the Notes field and Graphic field in the browser.

There we have it. The Notes field and the Graphic field shown in the browser along with the other fields. On a slow network, this kind of thing could take a long time to process, since there are a number of images involved. We could change this application to first show hyper linked names of each of the species. When one clicks on these links, one is shown the Notes field and the Graphics field either is a separate browser window or using HTML frames in the same window but in the bottom half. We could also show the notes and graphic fields in another page (so you will need to hit the "BACK" button on your browser to see the list of Species names once again).

All of this is made simple enough with the QueryTableProducer component. Your knowledge of HTML comes into play here, since we now know how to extract the image and memo fields and show it in the browser.

Rather than change this application's behavior, we'll add to it. What we'll do is create additional action items that will produce a different output. What we want to do now is show a page that contains only the Common Name column of the table with hyperlinks. When one clicks on the hyperlink, one should be shown the Notes Field and the Graphic field for the record in question.

1. Drop another TQueryTableProducer component on the form.
2. Set its Query property to qryData.
3. Double click on it to invoke the Response Editor.
4. Add All Fields.
5. Then delete all fields except for the Common_Name field.
6. Select the Common_Name field in the Response Editor.
7. Set its Title's align property to haLeft.

The Response Editor should look like that shown in Figure 9.

Figure 9: Showing the Response Editor for our second QueryTableProducer component.

In the Web Data Module, create a new action item.

1. Set its Name property to waNames.
2. Set its PathInfo property to /names.
3. Set its Producer property to QueryTableProducer2.

Your web data module should look like that shown in Figure 10

Figure 10: Showing the updated Web Data Module.

What we've done so far is linked a second QueryTableProducer component to our qryData query component. We've made sure that only the Common_Name field is produced in the output. We then created a new action item with the pathinfo of /names. Next we linked the Producer property of this action item to QueryTableProducer2.

If we re-compile our ISAPI and change the URL in our browser to http://myservername/scripts/biolife.dll/names, we should see an HTML page similar to that shown in Figure 11.

Figure 11: Showing the Result of the /names action of our ISAPI DLL.

The names are not yet hyper linked. To do this, we generate the OnFormatCell event of QueryTableProducer2 and write the following code in there:

procedure TWebModule1.QueryTableProducer2FormatCell(Sender: TObject;
CellRow, CellColumn: Integer; var BgColor: THTMLBgColor;
var Align: THTMLAlign; var VAlign: THTMLVAlign; var CustomAttrs,
CellData: String);
begin
  if (CellRow > 0) and (CellColumn = 0) then
    CellData := Format('<A HREF="%s/Details?No=%s">%s</A>',
      [Request.ScriptName,
       qryDataSpeciesNo.AsString,
       qryDataSpeciesName.AsString]);
end;

The result of the Format function will look like this:

<A HREF="/scripts/biolife.dll/Details?No=90020">Clown Triggerfish</A>

We reference an action item with a pathinfo of /details that expects to see a parameter called No. We don't have an action item with a PathInfo of /details yet. But we will soon.

If you re-compile the ISAPI and refresh the browser, you should see an output similar to that shown in Figure 12.

Figure 12: Showing the Names hyper-linked in the browser.

If you move your mouse over each of these hyperlinks, you should see in the status bar of the browser (as shown in Figure 12 above) that each species has its associated species no.

If you click on any of the hyperlinks now, you'll get an error since we have not created an action item with a pathinfo of /details. So lets go ahead and create it now.

Create a new action item.

1. Set its PathInfo property to /details.
2. Set its Name property to waDetails.

Your Actions Editor should look like that shown in Figure 13.

Figure 13: Showing the Action Editor with the new action items 

To keep things simple, we'll drop another TQuery component on the web data module

1. Set its Name property to qryNotes.
2. Set its DatabaseName property to DBDEMOS.
3. Set its SQL property to:

SELECT Notes FROM BIOLIFE
WHERE BIOLIFE."Species No" = :SpeciesNo

We'll use this query component to zero in on the required record and get the value of the Notes field to be displayed in the browser.

In the OnAction event of the waDetails action item, write the following code:

procedure TWebModule1.WebModule1waDetailsAction(Sender: TObject;
Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
begin
{ Manually create an HTML table with two columns. Populate the first
one with the contents of the Notes field. The second column will contain
the graphic from the table. Here we'll only put an HTML <IMG> tag
with the correct URL to extract the required image from the table using
the species no parameter sent to us here in the QueryFields property
of the Request object
}
  Response.Content := '<H3>Notes</H3><BR>'   #13#10  
  '<TABLE>'   #13#10  
  ' <TR>'   #13#10  
  ' <TD>';
  { Zero in on the correct record in the table }
  with qryNotes do
  begin
    { Assign the :SpeciesNo paramter the value received in the Request
      object's QueryFields property. Remember that it comes as eg. No=90020
    }
    Close;
    Params[0].AsInteger := StrToInt(Request.QueryFields.Values['No']);
    Prepare;
    Open;
  end;
  Response.Content := Response.Content  
    { Put the value of the Notes field in the First cell }
    qryNotes.FieldByName('Notes').AsString   '</TD>'   #13#10  
    { Put an <IMG> tag in the second cell and set its SRC parameter's value
     to the waImage action item, sending it the species no received in the
     Request object's QueryFields property.
    }
    ' <TD><IMAGE SRC="'   Request.ScriptName   '/image?No='  
    Request.QueryFields.Values['No']   '"></TD>'   #13#10  
    ' </TR>'   #13#10  
    '</TABLE>';
end;

You will find the explanation of the code in the comments above. I'll explain the part with the <IMAGE> HTML tag some more. Just like we did the first time, all we're doing is setting the SRC parameter of the <IMAGE> tag to our waImage action item (pathInfo of /image). This action item can extract the graphic and stream it out to the browser given the species no of the record for which we require an image.

If you re-compile the ISAPI and refresh your browser and then click on a hyperlink, you should see an as showin in Figure 14:

Figure 14: Showing the notes and Graphic field

I have noticed that if an ISAPI/CGI is attempting to send a number of images in this fashion, things tend to get a bit funny. If you play with this application a bit, you may see that at times the browser won't show the right image for the Common Name that you clicked on, or that you won't see an image at all, or you may even get access violation errors.