Version History

Notes

CGIShell gets around this limitation because it conforms to the web server's requirements, and all communication with the web server goes through CGIShell.

The Steps:

1. The web server launches CGIShell
2. CGIShell retrieves all the form information
3. CGIShell creates two temporary files -- one to hold the input to your subprocess, and one to hold the output from your subprocess
4. CGIShell launches your subprocess and waits
5. Your subprocess looks at the information supplied in its input file, and writes its output to the output file
6. Your subprocess deletes the input file and terminates
7. CGIShell reads your output file and sends it to the web server
8. CGIShell deletes your output file and terminates

Why Use Temporary Files?
CGIShell was designed to work with as many types of programs as possible. Almost all programming environments let you read and write files. Named pipes, mutexes, DLLs, and other techniques restrict the possibilities to only certain types of environments.

Syntax
Like any other CGI program, CGIShell is launched from a form (the POST method) or an anchor (the GET method). In the following examples, we'll use the values below when forming HTML. Substitute the correct values from your own system.

• Your base URL is http://my.place.com
• Your server root is d:\web
• Your CGI directory is d:\web\cgi-bin (relative path /CGI-bin from server root)
• Your subprocess is called myprog.exe

• Using GET with CGIShell
  The general syntax for GET is to make an anchor with the following characteristics:

  <a href="http://my.place.com/CGI-bin/cgishell.exe/myprog.exe?parm1=value1&parm2=value2...">

  Parms are passed to CGIShell by your HTTP server via the QUERY_STRING environment variable. CGIShell passes this information to your subprocess. In addition, if the REQUEST_METHOD is GET, CGIShell also parses this information and creates ersatz environment variables for you. For example, this link uses GET with two parms after the question mark. Notice how CGIShell has placed two variables, parm1 and parm2, in the list of variables. The same information still exists in the QUERY_STRING data.

• Using POST with CGIShell
  The general syntax for POST has the following characteristics:

  <form method="POST" action="http://my.place.com/CGI-bin/cgishell.exe/myprog.exe">
  Prompt <input type="text" name="field1">
  ...
  <input type="submit" value=" OK ">

• Special HTML tags
  CGIShell recognizes TimeOut and TimeOutMsg if present in the input (either from POST or from GET). TimeOut lets you override the default timeout value in the registry; TimeOutMsg lets you specify a custom message for when a timeout occurs. These tags are useful in situations where you know your server may be busy, but you don't want to increase the general timeout for the entire server. The syntax for these tags is

  <input type=hidden name=TimeOut value=nn>, where nn is the number of seconds you want to wait (values of 1 through 999 are supported); and

  <input type=hidden name=TimeOutMsg value="<h1>Your Message Here</h1><hr>A TimeOut happened!">, where the value is any legal HTML you want to use.

Subprocess Environment

• How Do I find the Temporary Files? The names of the temporary files are passed to your subprocess as the command tail, separated by a comma, thus: inputfile,outputfile. From a C program, retrieve these arguments as argv[1] and argv[2]. From a VB program, parse the command line and separate the filenames.

                  x = instr(Command$, ",")
                  infilename = Left(Command$, x-1)
                  outfilename = Mid(Command$, x+1)
  

• What's in the input file? The input file contains all the environment variables, form variables (if invoked with POST) or command-line variables (if invoked with GET). The format of the file is as follows:

                  VAR1=value-1
                  ...
                  VARx=Value-x
  

• What about special characters? CGIShell undecodes URLs and normalizes escape characters before creating the input file. This means all forward slashes ("/") become backslashes ("\"), all plus signs ("+") become spaces (" "), and all escaped characters ("%xx") become themselves. In addition, CGIShell handles CRs and LFs specially:

                  CR (hex 0x0d, Chr$(13), or '\r') becomes 0xFE, or Chr$(254)
                  LF (hex 0x0a, Chr$(10), or '\n') becomes 0xFF, or Chr$(255)
  

  This way, strings from a related field (for instance, a TEXTAREA input field) remain as one string, no matter how many lines, and no matter how the lines are separated. In some environments, lines are terminated by a CRLF pair (Chr$(13) + Chr$(10), or '\r\n'). In other environments, lines are terminated by a single CR or single LF. You may even encounter the oddball LFCR from time to time. For an example of how to handle all these conditions, see the cgiStartup code in cgishell.bas. This code takes any occurrence of any of the above combinations, and normalizes the resulting string with simple CRLF pairs.

• What if I want the special characters? Start the name of the field with a bang (exclamation mark). CGIShell will still decode CRs and LFs, but nothing else. For example, Field1 will be normalized, but !Field1 will not.

• What's in the output file? Nothing, until you put something there. What you put there should be valid HTML, starting with a "Content-Type:" line. There is nothing special or fancy about how CGIShell handles your output file. Whatever you put there gets sent back to the web server without any changes. Refer to basic CGI authoring guides for help on different content types or other HTML areas.

Using CGISHELL.BAS
If you're developing in VB, you might want to use our cgishell.bas file. Simply add it to your project and call the various functions as required. Here's a sample VB program that makes use of cgishell.bas to dump the environment variables to the screen:

                Sub Main()
                    cgiStartup
                    cgiDumpEnv
                    cgiShutdown
                End Sub

Registry Entries
You may customize the behavior of CGIShell by changing parameters in the registry. Parameters are stored under HKEY_LOCAL_MACHINE\Software\Greyware\CGIShell\Parameters.
Note: If you want to change any of these values from their defaults, you must first create the registry key and values, then set them to your desired settings. CGIShell will read the values if present, or use the defaults if not.

• TimeOut
  • Type: REG_SZ
  • Range: 1 through 999
  • Default: 60
  • Explanation: This is the amount of time (in seconds) CGIShell will wait for the secondary process (your CGI program) to finish. After this time expires, CGIShell will attempt to remove the temporary files. The default value of 60 seconds should be more than sufficient for most situations. If the value is outside the range of 1 through 999, it will be adjusted at run-time to fit that range.

    This value may be overridden for any particular process by including a <input type=hidden name=timeout value=nn> line in your form's HTML. The value of nn will override the registry setting.

• Temp
  • Type: REG_SZ
  • Default: . (current directory)
  • Explanation: Since CGIShell runs in the context of the web server (that is, an NT service rather than an interactive program), the TEMP environment variable does not reliably point to an appropriate temporary directory. If this value is not present, CGIShell defaults to "." -- that is, the current directory, often the same as the web server tree root. Change this value to point to C:\TEMP, or whatever temporary directory you want.

Error Codes & Explanations
ERROR 1000: PATH_INFO not supplied.
No supplemental program was specified, or not separated from cgishell.exe with a slash. The PATH_INFO is everything following /cgishell.exe on the anchor.

ERROR 1022: Could not create temporary filename (output to subprocess)
The operating system call to create a unique filename failed. Causes are (1) disk full; (2) invalid temporary path specified; (3) insufficient security. CGIShell runs in the same security context as the web server. Make sure the web server has at least Change rights in the temporary directory. Refer to Registry Entries for information on specifying the temp path.

ERROR 1023: Could not create temporary filename (input from subprocess)
See explanation for ERROR 1022. The only difference between these errors is which file CGIShell could not create.

ERROR 1024: Could not write to temporary file (input to subprocess)
CGIShell could not open the temporary file for output after creating it. Probable causes are (a) full disk or (b) insufficient security rights to the temporary directory.

ERROR 1026: Could not open temporary file for read (output from subprocess)
CGIShell could not open, or after opening, could not read, the temporary file containing the output from your subprocess. Probable causes are (a) your subprocess deleted the file or (b) insufficient security rights to the temporary directory.

ERROR 1030: Insufficient memory.
There is insufficient memory to launch your subprocess. Note: This error can also mean insufficient resources--particularly space and permissions for temporary files. If you get this error for every program, try setting a temp directory explicitly (as explained in the Registry Settings part of the documentation).

ERROR 1032: Invalid .EXE image.
The executable file for your subprocess has become corrupt.

ERROR 1034: .EXE not found.
CGIShell could not find your subprocess. Your subprocess must be located in the same directory as cgishell.exe, or below it in the directory tree. Only relative paths are supported. This behavior is intentional; it prevents callers from executing programs elsewhere on your system.

ERROR 1036: Path not found.
You specified a relative path, and CGIShell could not find it. You cannot specify absolute paths; your executable must reside in the same directory as cgishell.exe, or in a directory below it.

ERROR 1038: General failure.
A WinExec error other than those specified above occurred. Problems may relate to an invalid .EXE file, insufficient security rights for the user account in whose context CGIShell is running, or system hardware failure.

ERROR 1050: Subprocess did not terminate within timeout. Probable error condition exists.
Your subprocess did not terminate before the timeout timer expired. (See Registry Entries for information on changing this value.)

==> This usually indicates a problem with your program rather than the timeout period being too short! If your program gets caught in a loop, or terminates due to some untrapped error, it will not be able to signal CGIShell that it is finished, even if the output has already been created. Step through your code carefully and make sure it does what you want it to do without errors.

Do you have all the proper DLLs installed, such as the VB runtime files? Does your program run without errors when you run it from the web server's console?

==> Make sure that the last thing your program does is delete the input file! CGIShell watches for the input file to be deleted. If you don't delete the input file, CGIShell won't know your program has finished, even if it worked without error and has long since terminated.

Working Examples
Note--All of these examples and available source code are included in the main cgishell.zip file.

• Perpetual Calendar
  • View the Calendar
  • Download the Compiled Program
  • (Source code for Calendar not available for download)
• GuestBook
  • View the Guest Book
  • Sign the Guest Book
  • Download the Source Code (requires cgishell.bas)
  • Download the Compiled Program (requires VB4 runtime files)
• DumpEnv
  • This simple program just dumps the environment variables to the screen.
  • Test DumpEnv using the GET method.
  • Type something to test using the POST method.
  • Download the Source Code (requires cgishell.bas)
  • Download the Compiled Program (requires VB4 runtime files)
• QBDemo
  • This QuickBasic (compiled QB4) program dumps the environment variables to the screen.
  • Test QBDemo using the GET method.
  • Type something to test using the POST method.
  • Download the Source Code (no include files needed)
  • Download the Compiled Program (no runtime files needed)
• CDemo
  • This simple C program dumps the environment variables to the screen.
  • Test CDemo using the GET method.
  • Type something to test using the POST method.
  • Download the Source Code
  • Download the Compiled Program (no runtime files needed)
• ServStat
  • This VB3 program shells out to DOS, runs some programs, captures the output, and sends it back.
  • (Not enabled for testing on this server)
  • Download the Source Code (does not use cgishell.bas)
  • Download the Compiled Program (requires vbrun300.dll only)