Using CGIs

version 2004 (Modified)

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.

The 4D Web Server supports CGIs in two ways:

• 4D Web Server can use CGIs in automatic or manual mode

• 4D Web Server can be interfaced with other HTTP servers using CGIs extensions (Windows only)

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://hoohoo.ncsa.uiuc.edu/cgi/ 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 the 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.

Below are some examples or locations and matching URLs:

Items location         Matching 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.

A CGI is always executed without context, regardless of the calling mode. Note however, that in contextual mode, we strongly recommend that you not use a CGI sending back HTML code, as it might desynchronize the context.

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.

4th Dimension is provided with two new extensions, 4DISAPI.DLL and NPH-CGI4D.EXE. These extensions have been designed to allow a HTTP server to send requests to a 4D HTTP server. For example, a non secured 4D Web server can be interrogated via another HTTP server, running in secured mode.

Warning: These two extensions are available under Windows only.

• The 4DISAPI extension complies to the specifications defined by ISAPI (Internet Services Application Programming Interface). The ISAPI technology has been developed originally by Microsoft® for the IIS server but since it has been made compatible with various HTTP servers such as Netscape®, Apache® or Sambar®.

• The NPH-CGI4D.EXE extension complies to the CGI specifications (Common Gateway Interface) and can be used with all the CGI compatible servers.

These two extensions work the same way. The CGI compatibility is broadly used with HTTP servers, however the CGI extension performances are usually lower than the ISAPI ones.

These extensions work as follow: HTTP server "A" publishes pages on the Internet, another HTTP server "B" is a 4D Server used in Intranet. To make the two servers communicate, you just have to add the 4DISAPI or NPH-4DCGI extension in the server "A" [Scripts] directory.

When a Web browser sends a request to the server A, it transmits it to the server B via the 4DISAPI or NPH-4DCGI extension through the URL (usually, the extension transmits to the server B the URL part located after the call, including the request items). The answer is then sent back to the browser. When the CGI name starts with NPH (No Parsing Header), the server does not have to parse the answer HTTP header, the CGI does the formatting. The extensions do not change the HTTP request or answer body.

The initial request sent to the server A can be done in a normal or secured mode (SSL). The communication between the two HTTP servers and the 4DISAPI.DLL extension is done in a non secured mode.

Note: The 4DISAPI and NPH-4DCG extensions are not compatible with 4D Web server contextual mode.

The following figure illustrates this principle:

• The extensions identify the GET, HEAD and POST methods which manage the various status sent back by 4D (200 OK, 302 Moved Temporarily, 404 Not Found...).

• It is not possible to authenticate at the HTTP level via the 4DISAPI or NPH-CGI4D extension. To do so, an HTML form should be used (which can be done in a secured connection).

Note: The extensions have been designed to receive and send dynamic data and more specifically to post data. The basic Web page service does not offer good performance when the ISAPI or CGI extensions are used.

To install 4DISAPI and NPH-CGI4D extensions, copy the 4DISAPI.DLL or NPH-CGI4D.EXE files in the HTTP server [Scripts] folder.

Each installed extension file is provided with a configuration file (.INI file). The .INI file should bear the same name as the extension (for example 4DISAPI.INI). The extension and configuration files should be located in the same folder.

An HTTP server can be defined to target several other HTTP servers. In this case, copy in the HTTP server [Scripts] folder as many extensions as target servers. You just need to rename them (for example, 4DISAPI2.DLL, 4DISAPI3.DLL, etc.). Make sure that a configuration file is associated to each extension and that its name is correct (4DISAPI2.INI, 4DISAPI3.INI, etc.).

A .INI file contains one section: [Forward] which authorizes the following commands:

• TargetServer =

IP name or address of the Web server to target (for example, myserver.net or 192.193.194.195). The line can be left blank for targeting a server by its address if the name resolution is unavailable.

The "localhost" name is identified to the 127.0.0.1 address.

The address 127.0.0.1 is used by default.

• TargetPort =

Port used by the target server (by example, 81). The port number 8080 is used by default.

• Timeout =

Maximum timeout for the server answer (in seconds). The default value is set to 30 seconds.

• Allowed =

Allowed URL list, separated by a comma. For example: /pages, /img to give access only to the URL starting with /pages and /img. To give access to the full site, enter a slash character / (default setting).

• Forbidden =

Forbidden URL list, separated by a comma. For example: /4DMETHOD, /pages2 to forbid the access to the URL starting with /4DMETHOD and /pages2. To give unlimited access, do not enter anything in the list (default setting).

According to the rules stated above, the access to the following URLs will be given or not:

If a forbidden URL is called, the extension directly returns the error "HTTP/1.0 403 Forbidden".

4DISAPI and NPH-CGI4D extensions support the following URLs:

• 4D call (4D will receive only the URL part located after the extension name):

http://server-address/cgi-bin/4disapi.dll/[Path]

http://server-address/cgi-bin/nph-cgi4d.exe/[Path]

• Checking of the extension (echo of the request):

http://server-address/cgi-bin/4disapi.dll/~~echo

http://server-address/cgi-bin/nph-cgi4d.exe/~~echo

• Information about the extension (technical support):

http://server-address/cgi-bin/4disapi.dll/~~info

http://server-address/cgi-bin/nph-cgi4d.exe/~~info

The following information is returned:

name and version of the extension, for example "Script name: 4disapi.dll (6.7.0b1.2)"

name and version of the server calling the extension, for example "Server software: 4D_WebStar_D/6.7"

version of the HTTP protocol, for example "Server protocol: HTTP/1.0"

version of the CGI protocol, for example "Gateway interface: CGI/1.1"

• Checking of the target server (is the server available?) :

http://server-address/cgi-bin/4disapi.dll/~~target

http://server-address/cgi-bin/nph-cgi4d.exe/~~target

The answer is either:

"Good: target server reached.": the target server answered (whatever the contents of the answer).

or "Bad: target server not reached.": the target server cannot be reached or did not answer.

In this case, the fail can be caused by:

- the configuration file is missing;

- the target address or port is incorrect;

- the target server is out;

- the target server did receive the request but is unable to answer.

Note concerning 4D WebSTAR: 4D WebSTAR® is one of the most popular Web servers on Mac OS. Various interaction possibilities between 4D and 4D WebSTAR have been developed, in particular the 4D WebSTAR plug-in called 4D Link. For more information about this plug-in, please refer to the 4D WebSTAR documentation.

SET CGI EXECUTABLE, SET ENVIRONMENT VARIABLE.