4D Doc Center : Support des CGI

4D v12.4

Support des CGI

Le serveur Web 4D permet de tirer parti des CGI (Common Gateway Interface). Les CGI sont aux pages Web ce que les plug-ins sont aux méthodes 4D. Appelé par le serveur Web, le CGI exécute une tâche et retourne une réponse — une page Web complète ou du code HTML venant s’insérer dans une page envoyée par le serveur. Des CGI sont fréquemment utilisés pour afficher les compteurs d’accès, gérer les livres d’or (guestbook), recevoir le résultat d’un formulaire (form to mail), etc. Une multitude de CGI sont aujourd’hui disponibles. La plupart d’entre eux sont dans le domaine public.

Note : Le terme CGI désigne, à l’origine, la norme définissant l’interfaçage des applications externes avec les serveurs HTTP. Par extension, “CGI” est aujourd’hui utilisé pour désigner ces applications externes elles-mêmes.

Exécuter des CGI depuis le serveur Web 4D

4D prend en charge tous les types de CGI, sous Mac OS X et sous Windows. Un CGI se présente sous la forme d’un programme exécutable, d’un script PERL ou d’une DLL s’interfaçant avec un serveur Web.

des exécutables (.EXE) utilisant la “console” et les variables d’environnement. Le code source est généralement multi-plate-forme (Windows et Unix). Leurs noms sont de la forme nnnn.exe ou nph-nnnn.exe. Pour plus d’informations sur ce type de CGI, veuillez consulter le site http://httpd.apache.org/docs/2.1/howto/cgi.html.
des scripts PERL utilisant la “console” et les variables d’environnement. Ces CGI nécessitent la présence d’un interpréteur permettant de les exécuter. Ils présentent l’avantage d’être entièrement multi-plate-forme (Windows, Unix et Mac OS). Leurs noms sont de la forme nnnn.pl, nph-nnnn.pl, nnnn.cgi ou encore nph-nnnn.cgi. Pour plus d’informations sur ce type de CGI, veuillez consulter le site http://www.perl.com/.
des DLL ISAPI, c’est-à-dire des extensions pour IIS (Internet Information Server). Leurs noms sont de la forme nnnn.dll ou nph-nnnn.dll. Pour des raisons de performances, les DLL appelées de la sorte ne sont déchargées qu’à l’arrêt du serveur Web. Pour plus d’informations sur ce type de CGI, veuillez consulter le site http://www.microsoft.com/iis/.

Exécuter des CGIs en mode automatique

L’appel automatique d’un CGI s’effectue par l’intermédiaire d’un URL, d’une action de formulaire ou d’une balise HTML inséré(e) dans une page, en fonction de la tâche effectuée par le CGI. Dans tous les cas, la chaîne HTML doit contenir /cgi-bin/ suivi du nom du CGI et éventuellement d’un chemin d’accès (utilisant la syntaxe HTML) ainsi que d’une chaîne d’interrogation.

Par exemple, l’URL “http://195.1.2.3/cgi-bin/search.exe” provoquera l’exécution du CGI search.exe. De même, si vous placez la balise <IMG SRC="/special/cgi-bin/counter.exe"> au sein d’une page HTML, le CGI counter.exe sera exécuté lors de l’envoi de la page.

Pour pouvoir être appelés, les CGI doivent obligatoirement être placés à la racine d’un dossier nommé cgi-bin. Ce dossier doit lui-même être situé à la racine du serveur Web ou dans un sous-dossier. Il peut y avoir plusieurs dossiers cgi-bin par serveur. Ce dossier peut contenir d’autres fichiers que des exécutables, mais seuls ces derniers peuvent être appelés depuis un client Web.

Exemple d'installation avec un CGI appelé “Count.exe”:

Voici des exemples d’emplacements et les URL pouvant être appelés :

Emplacement des éléments	URLs correspondants
(racine du serveur Web)
Dossier [mabase]
+ mabase.4db (structure)	(http://195.1.2.3/)
Dossier [cgi-bin]
+ compteur.exe	(http://195.1.2.3/cgi-bin/compteur.exe)
Dossier [Divers]
+ Dossier [cgi-bin]
++ script.pl	(http://195.1.2.3/Divers/cgi-bin/script.pl)

Exécuter des CGIs en mode manuel

L'appel de CGIs en mode manuel requiert l'utilisation de la commande FIXER EXECUTABLE CGI. Cette commande permet notamment d’exécuter un CGI sans que celui-ci soit visible pour l’utilisateur Web dans l’URL.
Pour plus d'informations sur ce point, reportez-vous à la description de cette commande.

Interaction entre le serveur Web 4D et les CGI

L’appel d’un CGI ne modifie jamais l’environnement de 4D (sélections, variables...).
4D n’impose aucune limite de taille de la réponse. Cependant, la durée maximum de traitement allouée au CGI est fixée à 30 secondes. Au-delà de ce délai, le serveur Web retournera une erreur.

Erreurs renvoyées par 4D lors d’un appel CGI

Lorsque l’appel d’un CGI génère une erreur, 4D retourne une des réponses suivantes, sous forme de page HTML standard :

Non trouvé : le CGI n’a pu être localisé par 4D, ou bien l’interpréteur PERL n’est pas installé
Interdit : le client Web demande autre chose qu'un exécutable dans un dossier [cgi-bin]
Timeout : le CGI n’a pu traiter la requête en 30 secondes
Mauvaise réponse : la réponse du CGI n’a pu être traitée par 4D ou la DLL ISAPI a causé une exception
Erreur interne : mémoire saturée, etc.

Note : Lorsqu'un CGI ne fonctionne pas, vérifiez que les privilèges d'exécution du CGI sont suffisants et que les retours à la ligne dans le script CGI sont corrects.

Informations à destination des développeurs de CGI

Ce paragraphe est principalement destiné aux programmeurs souhaitant développer des CGI pour leur bases 4D.

Variables d’environnement

4D définit les variables d’environnement en conformité avec les spécifications CGI/1.1, avec les précisions suivantes :
GATEWAY_INTERFACE : toujours “CGI/1.1”
SERVER_SOFTWARE : toujours de la forme “4D WebStar_D/version”
SERVER_PROTOCOL : toujours “HTTP/1.0”
SERVER_PORT_SECURE : contient “1” si la connexion HTTP est sécurisée, sinon “0”.
PATH_TRANSLATED : contient le chemin d’accès complet de la racine HTML du serveur, auquel est ajouté la portion de chemin qui suit le nom du CGI. Par sécurité, la portion de chemin ne peut contenir les séquences // ou ..
Exemple : Racine du serveur C:/web
Pour un appel CGI du type /cgi-bin/cgi.exe/path, PATH_TRANSLATED vaut “C:/web/path”. Pour un appel CGI du type /cgi-bin/cgi.exe/../path, 4D renvoie l’erreur Interdit.
REMOTE_IDENT : nom d’utilisateur, sinon non définie
HTTP_AUTHORIZATION, HTTP_CONTENT_LENGTH et HTTP_CONTENT_TYPE : non définies
ALL_HTTP et URL sont définies dans le cas d’appels de DLL ISAPI.
CERT_xxx et HTTPS_xxx sont définies si la connexion est sécurisée (pour les DLL uniquement).

Note : La commande FIXER VARIABLE ENVIRONNEMENT permet de définir ces variables.

En plus des variables d’environnement standard, 4D ajoute des variables texte du type FORMVAR_nomvariable :

si la requête est envoyée avec la méthode "POST", ces variables correspondent aux zones de saisie du formulaire (par exemple FORMVAR_NOM, FORMVAR_PRENOM...) à l’exception des champs binaires (INPUT TYPE="FILE"). Ce système peut être utilisé avec les formulaires encodés “www/url-encoded” et “multipart/form-data”.
si la requête est envoyée avec la méthode "GET", ces variables correspondent aux valeurs passées par la chaîne d’interrogation (par exemple, dans le cas de l’URL .../cgi.exe?nom=martin&code=75, FORMVAR_NOM vaudra “martin” et FORMVAR_CODE vaudra “75”).

Ce fonctionnement présente l’avantage de faciliter le traitement des formulaires (il n’est pas nécessaire d’analyser les chaînes a=1&b=2&...), mais rend le CGI spécifique à 4D.

Traitement des réponses retournées par les CGI

Si le nom du CGI (exécutable Windows ou script PERL) débute par nph- (No Parsing Header), 4D retourne la réponse “telle quelle” au client Web. Dans ce cas, il revient au CGI de respecter la norme HTTP. En ce qui concerne les DLL ISAPI, 4D n’analyse jamais la réponse, que le préfixe nph- soit présent ou non.

Si ce n’est pas le cas, 4D se charge de renvoyer l’en-tête HTTP :

si “Content-Type” n’est pas spécifié par le CGI, 4D renvoie systématiquement “Content-Type: text/html”,
si “Location” est spécifié, 4D ignore les autres éléments de la réponse et effectue une redirection HTTP,
si “Status” n’est pas spécifié, 4D renvoie “HTTP/1.0 200 OK”.

4D accepte tout type de changement de ligne (Windows-CRLF, Mac OS-CR, Unix-LF) dans l’en-tête de la réponse HTTP et se charge de la reformater.

Dans le cas des DLL ISAPI, 4D accepte les traitements asynchrones (HttpExtensionProc retourne HSE_STATUS_PENDING). L’appel à ServerSupportFunction (HSE_REQ_DONE_WITH_SESSION) doit avoir lieu dans les 30 secondes. Si la fonction TerminateExtension est définie, elle est toujours appelée avec la valeur HSE_TERM_MUST_UNLOAD.