4D Doc Center : Usar CGI

4D v12.4

Usar CGI

O servidor web 4D compatível com CGIs (Commom Gateway Interface). Os CGIs são para os servidores web similares aos que plug-ins são para os métodos 4D. São chamados pelo servidor web para executar uma tarefa e devolver uma resposta, uma página web completa ou algo do código HTML inserido na página enviada pelo servidor. Os CGIs se utilizam com frequência para mostrar os contadores de visitantes, gerar livros de visitantes, receber o resultado de um formulário (form-mail), etc. Hoje em dia há várias CGIs disponíveis, a maioria dos quais são públicos.

Nota: originalmente, o termo CGI era um padrão para designar a interface das aplicações externas com o servidor HTTP. Agora a palavra "CGI" são utilizadas para designar estas mesmas aplicações externas

Executar CGIs de 4D Web Server

4D é compatível todos os tipos de CGIs, em Mac OS X e em Windows. Um CGI pode ser uma aplicação, um script PERL ou uma DLL que interage com um servidor Web.

- Executáveis (.EXE) utilizando o “console” e as variáveis de ambiente. O código fonte geralmente é multiplataforma (Windows e Unix).
Os nomes CGI geralmente são escritos desta forma: nnm.exe ou nph-nnm.exe.
Para maior informação de CGI, por favor consulte o website http://httpd.apache.org/docs/2.1/howto/cgi.html.

- DLL ISAPI, ou seja as extensões para IIS (Internet Information Server). Os nomes CGI são escritos desta forma: nnn.dll ou nph-nnn.dll. Os DLLs são descarregados quando tiver o servidor web tenha sido parado por razões de eficiência.
Para maior informação deste tipo de CGI, por favor consulte http://www.microsoft.com/iis/.

- PERL scripts utilizando o “console” e as variáveis de ambiente. Os CGIs necessitam a presença de um intérprete para executá-los. Entretanto são multiplataforma (Windows, Unix e Mac OS). Seus nomes são escritos desta forma: nnnn.pl, nph-nnnn.pl, nnnn.cgi ou nph-nnnn.cgi.
Para maior informação sobre este tipo de CGI, por favor consulte http://www.perl.com/.

Executar CGIs em modo automático

A chamada automática de um CGI é realizada através de uma URL, de uma ação de formulário ou de uma etiqueta HTML inserida em uma página, em função da tarefa efetuada pelo CGI. Em todos os casos, a string HTML deve conter /cgi-bin/ seguida pelo nome do CGI e eventualmente de uma rota de acesso (utilizando a sintaxe HTML) assim como a string de pesquisa.

Por exemplo, a URL “http://195.1.2.3/cgi-bin/search.exe” provoca a execução do CGI search.exe. Da mesma forma, se coloca o marcador <IMG SRC="/special/cgi-bim/counter.exe"> dentro de uma página HTML, o CGI counter.exe será executado quando a página seja enviada

Para poderem ser chamados, os CGI devem obrigatoriamente estar localizados na raiz de uma pasta chamada cgi-bin. Esta pasta deve estar na raiz do servidor web ou em uma subpasta. Um servidor pode ter várias pastas cgi-bin. Esta pasta pode conter outros arquivos diferentes dos executáveis, mas só esses últimos podem ser chamadose desde um cliente web.

Exemplo de instalação com um CGI chamado “Count.exe”:

A seguir alguns exemplos de localizações e URLs:

 Localização dos elementosURLs correspondentes

 (raiz do servidor Web)

 [meubanco] pasta

 meubanco.4db(estrutura)(http//195.1.2.3/)

 [cgi-bin] pasta

 contador.exe(http//195.1.2.3/cgi-bin/counter.exe)

 [Misc] pasta

 [cgi-bin] pasta

 script.pl(http//195.1.2.3/Misc/cgi-bin/script.pl)

Executar CGIs em modo manual

A chamada de CGIs em modo manual necessita a utilização do comando SET CGI EXECUTABLE. Em particular, este comando lhe permite executar um CGI sem que seja visível para o usuário web no URL.

Para maior informação sobre este ponto, consulte a descripção deste comando.

Interação entre 4D Web Server e CGIs

A chamada de um CGI não modifica o ambiente de 4D (seleção, variáveis...).

4D não limita o tamanho da resposta. Entretanto, a duração máxima do processo concedida ao CGI está limitada a 30 segundos. Depois desse tempo, o servidor web devolverá um erro.

Erros retornados por 4D relativos a chamadas CGI

Quando a chamada a um CGI gera um erro, 4D devolverá uma das seguintes respostas, em uma página HTML padrão:

Não foi encontrado: 4D não encontrou o CGI, ou não está instalado o intérprete PERL
Proibido: o cliente Web está solicitando algo diferente a um executável em uma pasta [cgi-bin]
Timeout: o CGI não pode processar a solicitação em menos de 30 segundos
Resposta incorreta: a resposta do CGI não pode ser processada por 4D ou a DLL ISAPI produziu uma exceção
Erro interno: memória cheia, etc.

Nota: quando um CGI não funciona, verifique que os privilégios de execução do CGI são os adequados e que os retornos de linha no script CGI sejam corretos.

Informação de CGI Developers

Esta seção está destinada principalmente aos programadores que desejam desenvolver CGIs específicos para seus bancos 4D.

Variáveis de ambiente
4D define as variáveis de ambiente em conformidade com as especificações CGI/1.1, além das informações abaixo:

GATEWAY_INTERFACE: sempre “CGI/1.1”
SERVER_SOFTWARE: sempre “4D WebStar_D/version”
SERVER_PROTOCOL: sempre “HTTP/1.0”
SERVER_PORT_SECURE: contém “1” se a conexão HTTP é segura, senão “0”.
PATH_TRANSLATED: contém a rota completa da raiz do servidor HTML e a parte do caminho que segue o nome CGI. Por razões de segurança, essa parte não pode conter as sequências de caracteres // ou ..
Exemplo: Raiz do servidor “C:/web”. Para uma chamada CGI tal como /cgi-bin/cgi.exe/path, PATH_TRANSLATED vale “C:/web/path”. Para uma chamada CGI do tipo /cgi-bin/cgi.exe/../path, 4D retorna o erro Proibido.

REMOTE_IDENT: nome de usuário (se relevante) senão indefinido.
HTTP_AUTHORIZATION, HTTP_CONTENT_LENGTH e HTTP_CONTENT_TYPE: indefinido.
ALL_HTTP e URL são definidos em caso de chamadas ISAPI DLLs.
CERT_xxx e HTTPS_xxx são definidos se a conexão é assegurada (apenas para DLL).

Nota: O comando SET ENVIRONMENT VARIABLE deixa que você estabeleça essas variáveis.

Além disso das variáveis do ambiente padrão, 4D oferece variáveis de texto do tipo FORMVAR_nomvariável:

se a petição for enviada utilizando o método "POST", estas variáveis correspondem às áreas de entrada do formulário (por exemplo FORMVAR_NAME, FORMVAR_FIRSTNAME...) exceto os campos binários (INPUT TYPE="FILE"). Este sistema pode utilizado com os formulários codificados “www/url-encoded” e “multipart/form-data”.

se a petição for enviada através do método "GET", estas variáveis são preenchidas com os valores passados na string de consulta (por exemplo, no caso do URL.../cgi.exe?name=smith&code=75, FORMVAR_NAME obtenrá o valor “smith” e FORMVAR_CODE obterá o valor “75”).

Esta funcionalidade presenta a vantagem de facilitar o processamento dos formulários (não é necessário analizar as strings a=1&b=2&...), entretanto o CGI é específico para 4D.

A funcionalidade faz o processamento do fomulário mais fácil (não é necessário analisar as strings como a=1&b=2&...), entretanto a CGI se torna específica a 4D

Processamento das respostas enviadas pelo CGI

Se o nome do CGI (executável Windows ou script PERL) começa por nph- (No Parsing Header), 4D envia a resposta “as is” ao cliente Web. Neste caso, depende do CGI cumprir com as reglas HTTP. Relativo aos DLL ISAPI, 4D não analizará nunca a resposta, sem importar o prefixo.

Do contrário, 4D enviará o cabeçalho HTTP:

se “Content-Tipo” não for especificado pelo CGI, 4D enviará sistematicamente “Content-Tipo: text/html”,
se “Location” for especificada, 4D ignora os outros elementos da resposta e realiza uma redireção HTTP,
se “Status” não for especificada, 4D enviará “HTTP/1.0 200 OK”.

4D aceita todo tipo de retorno de linha (Windows-CRLF, Mac OS-CR, Unix-LF) no cabeçalho da resposta HTTP e se encarrega do reformatação.

No caso dos DLL ISAPI, 4D aceita os processos assincrônicos (HttpExtensionProc retorna HSE_STATUS_PENDING). Uma chamada a ServerSupportFunction (HSE_REQ_DONE_WITH_SESSION) deve ocorrer nos próximos 30 segundos. Se a função TerminateExtension estiver definida, sempre se chama com o valor HSE_TERM_MUST_UNLOAD.