Soporte de los CGIs

versión 2004 (Modificado)

El servidor Web 4D soporta CGIs (Common Gateway Interface). Los CGIs son para las páginas Web similares a los que plug-ins son para los métodos 4D. Son llamados por el servidor Web para ejecutar una tarea y devolver una respuesta, una página Web completa o algo del código HTML insertado en la página enviada por el servidor. Los CGIs son utilizados con frecuencia para mostrar los contadores de visitantes, generar libros de visitantes, recibir el resultado de un formulario (form-mail), etc. Hoy en día hay una multitud de CGIs disponibles, la mayoría de los cuales son públicos.

Nota: Originalmente, el término CGI era un estándar para designar la interfaz de las aplicaciones externas con el servidor HTTP. Ahora la palabra "CGI" se utiliza para designar estas mismas aplicaciones externas.

El servidor Web 4D soporta CGIs de dos formas:

• El servidor Web 4D puede ejecutar los CGIs en modo automático o en modo manual

• El servidor Web 4D puede interactuar con otros servidores HTTP utilizando las extensiones CGIs (Windows únicamente)

4D soporta todos los tipos de CGIs, bajo Mac OS X y bajo Windows. Un CGI puede ser una aplicación, un script PERL o una DLL que interactúa con un servidor Web.

- Ejecutables (.EXE) utilizando la "consola" y las variables de entorno. El código fuente generalmente es multiplataforma (Windows y Unix). Los nombres CGI generalmente se escriben de esta forma: nnn.exe o nph-nnn.exe. Para mayor información de CGI, por favor consulte el sitio Web http://hoohoo.ncsa.uiuc.edu/cgi/.

- DLL ISAPI, es decir las extensiones para IIS (Internet Information Server). Los nombres CGI se escriben de esta forma: nnn.dll o nph-nnn.dll. Los DLLs se descargan una vez el servidor Web haya sido detenido por razones de rendimiento.

Para mayor información de este tipo de CGI, por favor consulte http://www.microsoft.com/iis/.

- PERL scripts utilizando la "consola" y las variables de entorno. Los CGIs necesitan la presencia de un intérprete para ejecutarlos. Sin embargo son multiplataforma (Windows, Unix y Mac OS). Sus nombres se escriben de esta forma: nnnn.pl, nph-nnnn.pl, nnnn.cgi o nph-nnnn.cgi.

Para mayor información sobre este tipo de CGI, por favor consulte http://www.perl.com/.

La llamada automática de un CGI se efectúa por intermedio de un URL, de una acción de formulario o de una etiqueta HTML insertada en una página, en función de la tarea efectuada por el CGI. En todos los casos, la cadena HTML debe contener /cgi-bin/ seguida por el nombre del CGI y eventualmente de una ruta de acceso (utilizando la sintaxis HTML) así como la cadena de búsqueda.

Por ejemplo, el URL "http://195.1.2.3/cgi-bin/search.exe" provoca la ejecución del CGI search.exe. De la misma forma, si coloca el marcador <IMG SRC="/special/cgi-bin/counter.exe"> dentro de una página HTML, el CGI counter.exe será ejecutado cuando la página se envíe.

Para poder ser llamados, los CGI deben obligatoriamente estar ubicados en la raíz de una carpeta llamada cgi-bin. Esta carpeta debe estar ubicada en la raíz del servidor Web o en una subcarpeta. Un servidor puede tener varias carpetas cgi-bin. Esta carpeta puede contener otros archivos diferentes de los ejecutables, pero sólo estos últimos pueden ser llamados desde un cliente Web.

Ejemplo de instalación con un CGI llamado "Count.exe":

A continuación algunos ejemplos de ubicaciones y URLs:

Ubicación de los elementos         URLs correspondientes
(raíz del servidor Web)         
[mibase] carpeta         
   mibase.4db (estructura)      (http://195.1.2.3/)
[cgi-bin] carpeta         
   contador.exe         (http://195.1.2.3/cgi-bin/counter.exe)
[Misc] carpeta         
   [cgi-bin] carpeta      
      script.pl      (http://195.1.2.3/Misc/cgi-bin/script.pl)

La llamada de CGIs en modo manual requiere la utilización del comando SET CGI EXECUTABLE. En particular, este comando le permite ejecutar un CGI sin que sea visible para el usuario Web en el URL.

Para mayor información sobre este punto, consulte la descripción de este comando.

La llamada de un CGI no modifica el entorno de 4D (selección, variables...).

4D no limita el tamaño de la respuesta. Sin embargo, la duración máxima del proceso concedida al CGI está limitada a 30 segundos. Después de ese tiempo, el servidor Web devolverá un error.

Un CGI siempre se ejecuta sin contexto, sin importar el modo de llamado.

Note sin embargo, que en modo contextual, recomendamos que no utilizar un CGI que renvíe el código HTML, porque podría desincronizar el contexto.

Cuando la llamada a un CGI genera un error, 4D devolverá una de las siguientes respuestas, en una página HTML estándar:

• No se encontró: 4D no encuentra el CGI, o no está instalado el interprete PERL

• Prohibido: el cliente Web está solicitando algo diferente a un ejecutable en una carpeta [cgi-bin]

• Timeout: el CGI no pudo procesar la solicitud en menos de 30 segundos

• Respuesta incorrecta: la respuesta del CGI no pudo ser procesada por 4D o la DLL ISAPI produjo una excepción

• Error interno: memoria llena, etc.

Nota: Cuando un CGI no funciona, verifique que los privilegios de ejecución del CGI son los adecuados y que los retornos de línea en el script CGI sean correctos.

Esta sección está destinada principalmente a los programadores que quieren desarrollar CGIs específicos para sus bases 4D.

• Variables de entorno

4D define las variables de entorno en conformidad con las especificaciones CGI/1.1, con las siguientes precisiones:

GATEWAY_INTERFACE: siempre "CGI/1.1"

SERVER_SOFTWARE: siempre "4D WebStar_D/version"

SERVER_PROTOCOL: siempre "HTTP/1.0"

SERVER_PORT_SECURE: contiene "1" si la conexión HTTP es segura, de lo contrario "0".

PATH_TRANSLATED: contiene la ruta de acceso completa de la raíz HTML del servidor y la parte de la ruta después del nombre del CGI. Por razones de seguridad, esta parte no contiene las secuencias de caracteres // o ..

Ejemplo: Raíz del servidor "C:/web"

Para una llamada CGI tal como /cgi-bin/cgi.exe/path, PATH_TRANSLATED vale "C:/web/path". Para una llamada CGI del tipo /cgi-bin/cgi.exe/../path, 4D devuelve el error Prohibido.

REMOTE_IDENT: nombre del usuario (si es relevante), de lo contrario indefinido.

HTTP_AUTHORIZATION, HTTP_CONTENT_LENGTH y HTTP_CONTENT_TYPE: no definidos.

ALL_HTTP y URL son definidos en caso de llamadas de DLL ISAPI.

CERT_xxx and HTTPS_xxx son definidos si la conexión es segura (para los DLL únicamente).

Nota: El comando SET ENVIRONMENT VARIABLE permite definir estas variables.

Además de las variables del entorno estándar, 4D ofrece variables de texto del tipo FORMVAR_nomvariable:

- si la petición se envía utilizando el método "POST", estas variables corresponden a las áreas de entrada del formulario (por ejemplo FORMVAR_NAME, FORMVAR_FIRSTNAME...) excepto los campos binarios (INPUT TYPE="FILE"). Este sistema puede utilizarse con los formularios codificados "www/url-encoded" y "multipart/form-data".

- si la solicitud se envía utilizando el método "GET", estas variables se llenan con los valores pasados en la cadena de consulta (por ejemplo, en el caso del URL .../cgi.exe?name=martin&code=75, FORMVAR_NAME obtendrá el valor "martin" y FORMVAR_CODE obtendrá el valor "75").

Esta funcionalidad presenta la ventaja de facilitar el procesamiento de los formularios (no es necesario analizar las cadenas a=1&b=2&...), sin embargo el CGI es específico para 4D.

• Procesamiento de las respuestas devueltas por los CGI

Si el nombre del CGI (ejecutable Windows o script PERL) comienza por nph- (No Parsing Header), 4D envía la respuesta "as is" al cliente Web. En este caso, depende del CGI cumplir con las reglas HTTP. Respecto a los DLL ISAPI, 4D no analizará nunca la respuesta, sin importar el prefijo.

De lo contrario, 4D enviará el encabezado HTTP:

- si "Content-Tipo" no es especificado por el CGI, 4D enviará sistemáticamente "Content-Tipo: text/html",

- si "Location" se especifica, 4D ignora los otros elementos de la respuesta y efectúa una redirección HTTP,

- si "Status" no se especifica, 4D enviará "HTTP/1.0 200 OK".

4D acepta todo tipo de cambio de línea (Windows-CRLF, Mac OS-CR, Unix-LF) en el encabezado de la respuesta HTTP y se encarga del reformato.

En el caso de los DLL ISAPI, 4D acepta los procesos asincrónicos (HttpExtensionProc devuelve HSE_STATUS_PENDING). Una llamada a ServerSupportFunction (HSE_REQ_DONE_WITH_SESSION) debe ocurrir en los próximos 30 segundos. Si la función TerminateExtension está definida, siempre se llama con el valor HSE_TERM_MUST_UNLOAD.

4D está acompañado por dos extensiones, 4DISAPI.DLL y NPH-CGI4D.EXE. Estas extensiones han sido diseñadas para permitir a un servidor HTTP enviar peticiones al servidor Web 4D. Por ejemplo, un servidor Web 4D no seguro puede ser interrogado vía otro servidor HTTP, corriendo en modo seguro.

Advertencia: Estas dos extensiones están disponibles bajo Windows únicamente.

• La extensión 4DISAPI cumple las especificaciones definidas por ISAPI (Internet Services Application Programming Interface). La tecnología ISAPI fue desarrollada originalmente por Microsoft® para el servidor IIS pero desde entonces se ha vuelto compatible con varios servidores HTTP tales como Netscape®, Apache® o Sambar®.

• La extensión NPH-CGI4D.EXE cumple con las especificaciones CGI (Common Gateway Interface) y puede utilizarse con todos los servidores compatibles CGI.

Estas dos extensiones funcionan de la misma manera. La compatibilidad CGI es ampliamente utilizada con los servidores HTTP, sin embargo el rendimiento de las extensiones CGI es generalmente inferior al de las extensiones ISAPI.

Estas extensiones funcionan de esta forma: un servidor HTTP "A" publica las páginas en Internet, otro servidor HTTP "B" es un servidor 4D Server utilizado en Intranet. Para que los dos servidores se puedan comunicar, es suficiente con añadir la extensión 4DISAPI o NPH-4DCGI en el directorio [Scripts] del servidor "A".

Cuando un navegador Web envía una petición al servidor A, la transmite al servidor B vía la extensión 4D ISAPI o NPH-4DCGI, por intermedio de la URL. La respuesta luego es enrutada al navegador en sentido contrario. El cuerpo de la solicitud HTTP nunca es modificado por las extensiones.

La respuesta inicial enviada al servidor puede efectuarse en modo normal o en modo seguro (SSL). La comunicación entre los dos servidores HTTP y la extensión 4DISAPI.DLL se efectúa en un modo no seguro.

Nota: Las extensiones 4DISAPI y NPH-4DCG no son compatibles con el modo contextual del servidor Web 4D.

La siguiente imagen ilustra este principio:

• Las extensiones identifican los métodos GET, HEAD y POST, administran los diferentes estados renviados por 4D (200 OK, 302 Moved Temporarily, 404 Not Found...).

• No es posible autenticar el nivel HTTP vía la extensión 4DISAPI o NPH-CGI4D. Para hacer esto, es necesario utilizar un formulario HTML (lo cual es perfectamente factible en conexión segura).

Nota: Las extensiones han sido diseñadas para recibir y enviar datos dinámicos y en particular para enviar datos. El servicio básico de páginas Web no ofrece un buen rendimiento cuando se utilizan las extensiones ISAPI o CGI.

La instalación de las extensiones 4DISAPI y NPH-CGI4D, se efectúa simplemente copiando los archivos 4DISAPI.DLL o NPH-CGI4D.EXE en la carpeta [Scripts] del servidor HTTP.

Cada extensión instalada debe estar acompañada por un archivo de configuración (de tipo .INI). El archivo .INI debe tener el mismo nombre que la extensión (por ejemplo 4DISAPI.INI). La extensión y sus archivos de configuración deben estar ubicados en la misma carpeta.

Puede configurar un servidor HTTP de manera que pueda dirigirse a varios servidores HTTP. En este caso, copie en la carpeta [Scripts] del servidor HTTP tantas extensiones como servidores objetivo. Sólo necesita renombrarlas (por ejemplo, 4DISAPI2.DLL, 4DISAPI3.DLL, etc.). Asegúrese de que un archivo de configuración esté asociado a cada extensión y que su nombre sea correcto (4DISAPI2.INI, 4DISAPI3.INI, etc.).

El archivo .INI contiene una sección: [Forward] la cual acepta los siguientes comandos:

• TargetServer =

Nombre o dirección IP del servidor Web al cual dirigirse (por ejemplo, miservidor.net o 192.193.194.195). Dejar la cadena vacía para dirigirse a un servidor por su dirección si la resolución del nombre no está disponible.

El nombre "localhost" es reconocido como la dirección 127.0.0.1.

La dirección 127.0.0.1 se utiliza por defecto.

• TargetPort =

Puerto utilizado por el servidor objetivo (por ejemplo, 81). El puerto número 8080 se utiliza por defecto.

• Timeout =

Tiempo máximo de respuesta del servidor (en segundos). El valor por defecto es de 30 segundos.

• Allowed =

Lista de los URLs autorizados, separados por comas. Por ejemplo: /pages, /img para dar acceso únicamente a los URL que comienzan por /pages y /img. Para dar acceso a la totalidad del sitio, introduzca una barra oblicua / (parámetro por defecto).

• Forbidden =

Lista de los URLs prohibidos, separados por una coma. Por ejemplo: /4DMETHOD, /pages2 para prohibir el acceso a los URLs que comienzan por /4DMETHOD /pages2. Para dar acceso ilimitado, no introduzca nada en la lista (parámetro por defecto).

De acuerdo a las reglas establecidas anteriormente, los siguientes URLs serán accesibles o no:

Si se llama un URL prohibido, la extensión devuelve directamente el error "HTTP/1.0 403 Forbidden".

Las extensiones 4DISAPI y NPH-CGI4D soportan los siguientes URLs:

• Llamada de 4D (4D sólo recibirá la parte del URL ubicada después del nombre de la extensión):

http://server-address/cgi-bin/4disapi.dll/[ruta de acceso]

http://server-address/cgi-bin/nph-cgi4d.exe/[ruta de acceso]

• Verificación de la extensión (eco de la solicitud):

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

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

• Information about the extension (soporte técnico):

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

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

Se devuelve la siguiente información:

Nombre y versión de la extensión, por ejemplo "Script name: 4disapi.dll (6.7.0b1.2)"

Nombre y versión del servidor que llama la extensión, por ejemplo "Server software: 4D_WebStar_D/6.7"

Versión del protocolo HTTP, por ejemplo "Server protocol: HTTP/1.0"

Versión del protocolo CGI, por ejemplo "Gateway interface: CGI/1.1"

• Checking of the target server (¿está disponible el servidor?) :

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

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

La respuesta es:

"Good: target server reached.": el servidor objetivo ha respondido (cualquiera que sea el contenido de la respuesta).

o "Bad: target server not reached.": el servidor objetivo no pudo ser alcanzado o no respondió.

En este caso, la falla puede ser causada por:

- la falta de archivo de configuración;

- la dirección o el puerto objetivo es incorrecto;

- el servidor objetivo está fuera de servicio;

- el servidor objetivo recibió la petición pero no puede responder.

Nota sobre 4D WebSTAR: 4D WebSTAR® es uno de los servidores Web más populares en plataforma Mac OS. Se han desarrollado varias posibilidades de interacción entre 4D y 4D WebSTAR, en particular el plug-in 4D WebSTAR llamado 4D Link. Para mayor información sobre este plugin, consulte la documentación de 4D WebSTAR.

SET CGI EXECUTABLE, SET ENVIRONMENT VARIABLE.