4D v12.4

Using CGIs

Home

 
4D v12.4
4D Language Reference
Web Server
Using CGIs

 

Using CGIs  


 

 

The 4D Web Server supports CGIs (Common Gateway Interface). CGIs for Web servers are similar to plug-ins for 4D methods. They are called by the Web server to execute a task and return an answer, i.e. a full Web page or some HTML code inserted in the page sent by the server. CGIs are frequently used to display visitors counters, generate guest books, receive a form-mail, etc. A multitude of CGIs are available today, most of which are freeware.

Note: Originally, CGI was a standard for interfacing external applications with HTTP server. The "CGI" word is now used for the external applications themselves.

4D supports all types of CGIs, under Mac OS X and under Windows. A CGI can be an application, a PERL script or a DLL interfacing with a Web server.

  • Executables (.EXE) using the “console” and the environment variables. The source code is usually cross-platform (Windows and Unix). The CGI names are usually written as follows: nnn.exe or nph-nnn.exe. For more information on this kind of CGI, please refer to the http://httpd.apache.org/docs/2.1/howto/cgi.html Internet site.
  • DLL ISAPI, i.e. extensions for IIS (Internet Information Server). The CGI names are written as follows: nnn.dll or nph-nnn.dll. The DLLs are downloaded once the Web server has been stopped for performance purposes.
    For more information on this type of CGI, please refer to the http://www.microsoft.com/iis/ Internet site.
    PERL scripts     using the “console” and the environment variables. The CGIs require an interpreter to execute. However they are cross-platform (Windows, Unix and Mac OS). Their names are written as follows: nnnn.pl, nph-nnnn.pl, nnnn.cgi or nph-nnnn.cgi.
    For more information on this kind of CGI, please refer to th    e http://www.perl.com/ Internet site.

An automatic CGI call is made through an URL, an action or a HTML tag inserted within a page according to the task to be done by the CGI. In any case, the HTML string has to contain /cgi-bin/ followed by the CGI name or possibly a path using the HTML syntax as well as the search string.

For example, an URL “http://195.1.2.3/cgi-bin/search.exe” will trigger the search.exe CGI launch. Similarly, the <IMG SRC="/special/cgi-bin/counter.exe"> marker is placed within a HTML page, the counter.exe CGI will be launched when the page will be sent.

The CGI should be located at the root of the folder named cgi-bin. This folder should be placed at the Web server root or in a subfolder. A server can have several cgi-bin folders. This folder can contain other files than executable application, but only the latest can be called from a Web client.

Example of installation with a CGI called “Count.exe”:

Below are some examples or locations and matching URLs:

Items locationMatching URLs(Web server root)
[mybase] folder
+ mybase.4db (structure)(http://195.1.2.3/)
[cgi-bin] folder
+ counter.exe(http://195.1.2.3/cgi-bin/counter.exe)
[Misc] folder
+ [cgi-bin] folder
++script.pl(http://195.1.2.3/Misc/cgi-bin/script.pl)

Calling CGIs in manual mode requires the use of the SET CGI EXECUTABLE command. In particular, this command lets you execute a CGI without it being visible for the Web user in the URL.
For more information about this point, refer to the description of this command.

A call to a CGI does not modify the 4D environment (selection, variables...).
4D does not limit the response size. However, note that the maximum processing time allocated to a CGI is limited to 30 seconds. After that time, the Web server will return an error.

When a call to a CGI generates an error, 4D will return one of the following answers in a standard HTML page:

  • Not found: 4D does not find the CGI, or a PERL interpreter is missing
  • Forbidden: the Web client is asking something other than an executable in a [cgi-bin] folder
  • Timeout: the request has not been processed by the CGI in less than 30 seconds
  • Bad Answer: 4D was not able to process the CGI answer, or the ISAPI DLL caused an exception
  • Internal Error: memory full, etc.

Note: When a CGI does not work, check that the execution privileges of the CGI are adequate and that the line feeds in the CGI script are correct.

This section in mainly intended for programmers who wish to develop specific CGIs for their 4D databases.

Environment variables
4D defines environment variables in compliance with CGI/1.1 specifications, and the following information:
GATEWAY_INTERFACE: always “CGI/1.1”
SERVER_SOFTWARE: always “4D WebStar_D/version”
SERVER_PROTOCOL: always “HTTP/1.0”
SERVER_PORT_SECURE: contains “1” if the HTTP connection is secure, else “0”.
PATH_TRANSLATED: contains the full path to the HTML server root, and the part of the path following the CGI name. For security reasons, this part cannot contain the character sequences // or ..
Example : Root of the server “C:/web”. For a CGI call such as /cgi-bin/cgi.exe/path, PATH_TRANSLATED value is “C:/web/path”. For a CGI call such /cgi-bin/cgi.exe/../path, 4D returns the error Forbidden.
REMOTE_IDENT: user name (if relevant), else undefined.
HTTP_AUTHORIZATION, HTTP_CONTENT_LENGTH and HTTP_CONTENT_TYPE: undefined.
ALL_HTTP and URL are defined in case of ISAPI DLLs calls.
CERT_xxx and HTTPS_xxx are defined if the connection is secured (for DLL only).

Note: The SET ENVIRONMENT VARIABLE command lets you set these variables.

In addition to the standard environment variables, 4D provides text variables FORMVAR_variablename:

  • if the request is sent using the "POST" method, these variables are filled with the form entry areas (for example FORMVAR_NAME, FORMVAR_FIRSTNAME...) except for binary fields (INPUT TYPE="FILE"). This system can be used with both “www/url-encoded” and “multipart/form-data” encoded forms.
  • if the request is sent using the "GET" method, these variables are filled with the values passed in the request string (for example, in the case of the URL .../cgi.exe?name=smith&code=75, FORMVAR_NAME will get the value “smith” and FORMVAR_CODE will get the value “75”).

This functionality makes form processing easier (it is not necessary to parse strings such as a=1&b=2&...), however the CGI is made 4D-specific.

Processing of the answers sent by the CGI
If the name of the CGI (Windows executable or PERL script) starts with nph- (No Parsing Header), 4D sends the answer “as is” to the Web client. In this case, it is up to the CGI to comply with HTTP rules. Regarding ISAPI DLLs, 4D will never parse the response, whatever the prefix.

Otherwise, 4D will send the HTTP header:

  • if “Content-Type” is not specified by the CGI, 4D will always send “Content-Type: text/html”,
  • if “Location” is specified, 4D will not take the other elements of the answer into account and will perform a HTTP redirection,
  • if “Status” not specified, 4D will send “HTTP/1.0 200 OK”.

4D accepts any kind of line return combination (Windows-CRLF, Mac OS-CR, Unix-LF) in the header of the HTTP answer and will reformat it.

Regarding ISAPI DLLs, 4D accepts asynchrone processings (HttpExtensionProc returns HSE_STATUS_PENDING). A call to ServerSupportFunction (HSE_REQ_DONE_WITH_SESSION) must occur during the next 30 seconds. If the function TerminateExtension is defined, it is always called with the value HSE_TERM_MUST_UNLOAD.

 
PROPERTIES 

Product: 4D
Theme: Web Server

 
SEE ALSO 

SET CGI EXECUTABLE
SET ENVIRONMENT VARIABLE