Shiv Kumar's Tutorials - Building your First ISAPI Application using Delphi

In this article we will take you through the steps in building an ISAPI application using Delphi 3/4/5 Client/Server (Enterprise) edition.

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!

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.

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.

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:

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:

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:

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:

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.

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:

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:

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.

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

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.

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

Building your First ISAPI Application using Delphi

Comments have been Disabled for this post