Microsoft KB Archive/239588

= How to Write CGI Applications in Visual Basic =

Article ID: 239588

Article Last Modified on 12/3/2007

-

APPLIES TO


 * Microsoft Internet Information Server 3.0
 * Microsoft Internet Information Server 4.0
 * Microsoft Internet Information Services 5.0
 * Microsoft Internet Information Services 6.0

-



This article was previously published under Q239588



SUMMARY
A Common Gateway Interface (CGI) application can be written in any programming language that can access both the environment variables and STDIN or STDOUT. Because of the powerful text handling capability of the Microsoft Visual Basic programming language, many Web developers want to write CGI programs in Visual Basic. This article illustrates the techniques for writing CGI applications in Visual Basic, and provides a simple Visual Basic CGI sample.



MORE INFORMATION
NOTE: Microsoft provides programming examples for illustration only, without warranty either expressed or implied. This includes, but is not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and with the tools that are used to create and to debug procedures. Microsoft support engineers can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific requirements.

Retrieving Environment Variables
To retrieve an environment variable, use the Environ$ function in Visual Basic as follows: VALUE = Environ$(NAME)

Note that NAME is the environment variable that you want to retrieve. Its value is returned in VALUE.

Reading from STDIN and Writing to STDOUT
Use the Win32 ReadFile function to read from STDIN and the WriteFile function to write to STDOUT. These functions require you to provide a handle to STDIN or STDOUT. You can use the GetStdHandle function to get the handles to STDIN or STDOUT. In this article, aliasing is used on the GetStdHandle function to simplify the function calls. The declarations for these functions are as follows: Public Declare Function stdin Lib "kernel32" Alias "GetStdHandle" _ (Optional ByVal Handletype As Long = STD_INPUT_HANDLE) As Long

Public Declare Function stdout Lib "kernel32" Alias "GetStdHandle" _ (Optional ByVal Handletype As Long = STD_OUTPUT_HANDLE) As Long

Public Declare Function ReadFile Lib "kernel32" _ (ByVal hFile As Long, ByVal lpBuffer As Any, ByVal nNumberOfBytesToRead As Long, _ lpNumberOfBytesRead As Long, Optional ByVal lpOverlapped As Long = 0&) As Long

Public Declare Function WriteFile Lib "kernel32" _ (ByVal hFile As Long, ByVal lpBuffer As Any, ByVal nNumberOfBytesToWrite As Long, _ lpNumberOfBytesWritten As Long, Optional ByVal lpOverlapped As Long = 0&) As Long The constants passed to the GetStdHandle function are defined as: Public Const STD_INPUT_HANDLE = -10& Public Const STD_OUTPUT_HANDLE = -11& Please refer to the MSDN documentation for the definition of each parameter in those functions. In the following sample, a full list of CGI environment variables is made constant. This lists all the constants together on a Ctrl-J. It also eliminates programming errors by providing compiler and IntelliSense validation, yet does not preclude you from entering your own strings.

Sample Code
For simplicity, error trapping is omitted in the following sample (Hello.bas): Option Explicit

Public Const STD_INPUT_HANDLE = -10& Public Const STD_OUTPUT_HANDLE = -11&

Public Const CGI_AUTH_TYPE        As String = "AUTH_TYPE" Public Const CGI_CONTENT_LENGTH   As String = "CONTENT_LENGTH" Public Const CGI_CONTENT_TYPE     As String = "CONTENT_TYPE" Public Const CGI_GATEWAY_INTERFACE As String = "GATEWAY_INTERFACE" Public Const CGI_HTTP_ACCEPT      As String = "HTTP_ACCEPT" Public Const CGI_HTTP_REFERER     As String = "HTTP_REFERER" Public Const CGI_HTTP_USER_AGENT  As String = "HTTP_USER_AGENT" Public Const CGI_PATH_INFO        As String = "PATH_INFO" Public Const CGI_PATH_TRANSLATED  As String = "PATH_TRANSLATED" Public Const CGI_QUERY_STRING     As String = "QUERY_STRING" Public Const CGI_REMOTE_ADDR      As String = "REMOTE_ADDR" Public Const CGI_REMOTE_HOST      As String = "REMOTE_HOST" Public Const CGI_REMOTE_USER      As String = "REMOTE_USER" Public Const CGI_REQUEST_METHOD   As String = "REQUEST_METHOD" Public Const CGI_SCRIPT_NAME      As String = "SCRIPT_NAME" Public Const CGI_SERVER_NAME      As String = "SERVER_NAME" Public Const CGI_SERVER_PORT      As String = "SERVER_PORT" Public Const CGI_SERVER_PROTOCOL  As String = "SERVER_PROTOCOL" Public Const CGI_SERVER_SOFTWARE  As String = "SERVER_SOFTWARE"

Public Declare Function Sleep Lib "kernel32" _ (ByVal dwMilliseconds As Long) As Long

Public Declare Function stdin Lib "kernel32" Alias "GetStdHandle" _ (Optional ByVal Handletype As Long = STD_INPUT_HANDLE) As Long

Public Declare Function stdout Lib "kernel32" Alias "GetStdHandle" _ (Optional ByVal Handletype As Long = STD_OUTPUT_HANDLE) As Long

Public Declare Function ReadFile Lib "kernel32" _ (ByVal hFile As Long, ByVal lpBuffer As Any, ByVal nNumberOfBytesToRead As Long, _ lpNumberOfBytesRead As Long, Optional ByVal lpOverlapped As Long = 0&) As Long

Public Declare Function WriteFile Lib "kernel32" _ (ByVal hFile As Long, ByVal lpBuffer As Any, ByVal nNumberOfBytesToWrite As Long, _ lpNumberOfBytesWritten As Long, Optional ByVal lpOverlapped As Long = 0&) As Long

Sub Main

Dim sReadBuffer As String Dim sWriteBuffer As String Dim lBytesRead As Long Dim lBytesWritten As Long Dim hStdIn As Long Dim hStdOut As Long Dim iPos As Integer ' sleep for one minute so the debugger can attach and set a break ' point on line below ' Sleep 60000 sReadBuffer = String$(CLng(Environ$(CGI_CONTENT_LENGTH)), 0) ' Get STDIN handle hStdIn = stdin ' Read client's input ReadFile hStdIn, sReadBuffer, Len(sReadBuffer), lBytesRead

' Find '=' in the name/value pair and parse the buffer iPos = InStr(sReadBuffer, "=") sReadBuffer = Mid$(sReadBuffer, iPos + 1) ' Construct and send response to the client sWriteBuffer = "HTTP/1.0 200 OK" & vbCrLf & "Content-Type: text/html" & _ vbCrLf & vbCrLf & "Hello " hStdOut = stdout WriteFile hStdOut, sWriteBuffer, Len(sWriteBuffer) + 1, lBytesWritten WriteFile hStdOut, sReadBuffer, Len(sReadBuffer), lBytesWritten

End Sub

HTML form to test the CGI (Test.htm)   Testing VB CGI     Name    

Steps to build the simple CGI Hello.exe file:


 * 1) Create a New Project as a standard .exe project.
 * 2) Remove Form from the Project.
 * 3) Add a Module to the Project and name it HELLO.
 * 4) Set Sub Main as the Startup Object (under Project Properties).
 * 5) Copy the above Visual Basic code and paste it to the Module.
 * 6) Make Hello.exe.

Notes:

<ul> <li>The sample code demonstrates how to handle an HTTP POST request. To handle a GET request, the CGI application needs to retrieve the QUERY_STRING environment variable. The QUERY_STRING variable contains name/value pairs separated by the & in the format "Name=Joe&Color=Red." Note that URL encoding is used, all spaces are converted to +, and all special characters such as ! are converted to their HEX ASCII values. In other words, "Hello, World!" string is represented as "Hello,+World%21." Visual Basic CGI applications have to implement all the parsing code.</li> <li>Because the CGI application is started by the service, it may not be able to access network shares.</li> <li>Be aware that CGI runs as a service, which communicates with the server. Therefore, visual interface forms, controls, and message boxes are completely meaningless. As a matter of fact, a message box will cause a CGI application to stop responding.</li> <li>Error handling should be conducted throughout a CGI code in Visual Basic, so that the default error message box is not be displayed. You can either log error messages on the server or write them to the user's browser.</li> <li>Visual C debuggers can debug applications written in Visual Basic. Therefore, you can use the CGI debugging techniques referenced below. To debug a Visual Basic application with Visual C, choose Compile to Native Code, and then select Create Symbolic Debug Info and No Optimization. When it is completed and the .exe is generated, Visual C can attach to the running CGI application written in Visual Basic.</li> <li>To test a CGI application, copy it to the IIS virtual directory with Execute permissions.</li> <li>Be aware that runtime errors or dialog boxes in the Visual Basic code may cause the CGI application to stop responding. If the CGI application stops responding, it can be run in the Visual Studio debugger. For additional information, click the article number below to view the article in the Microsoft Knowledge Base:

238788 How to Debug CGI Applications Running Under IIS

</li></ul>

<div class="references_section">