If you are reading this, you must want to add CGI sripting support to your visual basic application. You have downloaded the right code my friend. This DLL will do all the hard work in providing CGI script support into your software, all you have to do is a few simple things prior to executing the final function. There are a few points we must cover prior to using this DLL, such as: Properties to Set and Functions to run. Also when to do set these properties and execute these functions.

    Order of operations for this DLL to work effectively:

1. Set "ServerSoftware" property at load-time with the name of your software in the format: SoftwareName/1.0Beta1 (or version of and beta of)

2. The function "setHandlers" must be executed at load-time atleast once with a script file extensions and the path to the interpreter

3. The function "SetLocalFilePath" must be executed at script-request time with the local file path to the script file to be interpreted

4. The function "SetRemoteUserIP" must be executed at script-request time with the IP address of the client requesting the file

5. The function "SetHeader" must be executed at script-request time with header request data directly from the client

6. The function "Execute" is the function that will set the environment variables and execute the interpreter piping post data into standard input. You must get the return data from this function. If there are errors, it will be presented in error form, if not, you will get the output from the script interpreter

That's It!!

    Now we will cover the functions and properties and thier purpose:

    These functions (public and private) are in the class module CGIProcessor (Processor.cls)


• Property - ServerSoftware:
  Variables passed to this property: 1
  Type: String
  Format: See property description
  Property Description:
  

  This property is set at Load-Time and is passed the name of the server software. This has to be in a specific format (following the HTTP Header Request specification). The name you pass to this property should be formatted as such: WebServerName/1.0 (where "webservername" is your software's name, and the version is allowed two periods). You can also add text to the end of your version such as "beta1" for example. You may also retrieve this property and use it elsewhere in your code. Remember, this property is set at Load-Time and only needs to be set once.

  
  
• Function - ClearHandlers:
  Variables passed to this function: 0
  Type: NONE
  Format: N/A
  Function Description:
  

  This function can be executed Any-Time. I suggest you execute it at Load-Time to ensure that any old information is not still "hanging around". This function is used to clear the arrays that hold the file extension and CGI interpreters meant to handle those extensions. Use this funtion if you wish to reset ALL of the CGI handlers stored in memory. See the setHandler function to find out how to set those handlers.

  
  
• Function - remHandlers:
  Variables passed to this function: 1
  Type: String
  Format: file extension passed to setHandler (not case-sensitive)
  Function Description:
  

  This function removes a particular script file interpreter by extension. Just pass the extension (not case sensitive) you want to remove from the handler arrays. The handler arrays are dynamic in size, so this function will also reduce the number of indexes in the array. If the extension you are removing is somewhere in the middle of the array it will be removed, and the other values will be moved down in the indexes and the array will be shrunk.

  
  
• Function - setHandlers:
  Variables passed to this function: 2
  Type: String (both)
  Format: file extension (not case-sensitive), and path to the script interpreter for that extension.
  Function Description:
  

  This function adds a script interpreter for a particular script file extension (for example: .php and c:\php\php.exe). This function will automatically expand the arrays that hold these values. You can run this function as many times as you like, for instance, you are loading your program and retrieving CGI interpreter settings, just run a loop through all of your handlers, and run this function passing the values each time you loop.

  
  
• Function - setHeader:
  Variables passed to this function: 1
  Type: String
  Format: Header request data as sent from the client's browser, exactly as it is sent.
  Function Description:
  

  This function takes all of the client request header and parses it line by line, grabbing the neccessary values that need to be set in the environment variables to be interpreted by a cgi executable. This function will return a number of error codes based upon the error that occurs. See Table 1 for a list of these error codes.

  
  
• Function - Execute:
  Variables passed to this function: 1
  Type: String
  Format: Directory you would like to use as a temporary directory, if you use "" the local user's "temp" directory will be used
  Function Description:
  

  This function takes all of the variables collected in all of the functions set prior to this, builds a dos batch file with commands to set the appropriate environment variables. It will also generate a file containing the POSt data and use it for standard input. It will execute the dos batch file, read the data on the screen, clean it with the "cleanReturn" function, and send it back to the code calling the function as a string.

  
  
• Function - cleanReturn:
  Variables passed to this function: 2
  Type: String (for both)
  Format: The return data to be cleaned (in a stirng) and the Capture Point to start cleaning (usually the path of the interpreter0
  Function Description:
  

  This function (called from within the Execute function) will rid the return data from the dos batch file's commands to set the environment variables as well as the command to run the cgi interpreter. No need to use this function from the webserver, however it will return the cleaned data.

  
  
• Function - setRemoteUserIP:
  Variables passed to this function: 1
  Type: String
  Format: The IP address (in IPv4) of the user requesting the page.
  Function Description:
  

  This function just sets a public variable to the ip address of the client requesting the script. It will test the IP address for validity and return an error code if invalid. See Table 2 for the error codes.

  
  
• Function - setLocalFilePath:
  Variables passed to this function: 1
  Type: String
  Format: The path (on the webserver machine) to the script file that was requested.
  Function Description:
  

  This function just sets a public variable to the path of the script file requested. This function will also return an error if the filepath is invalid. See Table 3 for error codes.

  
  
• Function - GenNum:
  Variables passed to this function: 0
  Type: N/A
  Format: N/A
  Function Description:
  

  This function returns a 10 digit random number for use in generating temporary files. This function may be called a number of times during one execution of the "Execute" function if the temporary file already exists.

    This function (public) is in the module ExecApp (ExecuteApp.bas)


• Function - ExecuteApp:
  Variables passed to this property: 1
  Type: String
  Format: Command line value for the file to run (in our case the generated dos batch file)
  Function Description:
  

  This function was borrowed (see code comments for credits). All this function does is create a process and run an executable, wait for it to finish, and grab the data from the screen. It then returns that data to the function calling it (the Execute function in our case)

    This function (public) is in the module mdlVars (mdlvars.bas)


• Function - Log_Entry:
  Variables passed to this property: 1
  Type: String
  Format: Data to be written to an error log file
  Function Description:
  

  The function will write errors to the logfile "cgigateway.log". It will date and time stamp those errors (all errors within the setHeader function will be added) as well as the errors from the ExecuteApp function.

  
  
• Sub - Main:
  Variables passed to this property: 0
  Type: N/A
  Format: N/A
  Sub Description:
  

  Startup sub, here we determine the path to our log file, and store it to a public variable, that's it.