HTTPd Scripting5

HFRD Hypertext Services - Technical Overview

p [next] [previous][contents]


6 - HTTPd Scripting




? Scripts are mechanisms for creating simple ``servers'' Psending data to a client, extending the services provided by the basic server. >Anything that can write to SYS$OUTPUT can be used to Ngenerate script output. A DCL procedure or an executable can be the basis for@a script. Simply TYPE-ing a file can be provide scriptoutput.

V Scripts are enabled using the exec or script rules in the mapping file Y(see 5 - HTTPd Mapping Rules). The script portion of the Gresult must be a URL equivalent of the physical VMS procedure orCexecutable specification. It is not necessary to supply the2.COM or .EXE file type (althoughNnot forbidden either), the server will first check for a procedure and if none#found then check for an executable. 

6.1 - CGI Compliance



I The HTTPd scripting mechanism is designed to be largely WWW CGI (Common Gateway Interface) compliant.

CGI Compliant Variables



J Environment variables are created in a similar way to the CERN VMS HTTPd Oimplementation, where CGI environment variables are provided to the script via CDCL global symbols. Each CGI variable symbol name is prefixed with<``WWW_'' (by default, although this can be changed using the#/CGI_PREFIX qualifier, see`3.1 - HTTPd Command Line, this is not recommended if the HFRD VMSMscripts are to be used, as they expect CGI variable symbols to be prefixed in this manner). $

Extensions to CGI Variables



K In line with other CGI implemenations, additional, non-compliant variablesNare provided to ease CGI interfacing. These provide the various components ofBthe query string. A keyword query string and a form7query string are parsed into separated variables, named

  WWW_KEY_number  WWW_KEY_COUNT#  WWW_FORM_form-element-name


 See the example below. 

CGI Variable Capacity



J DCL symbol values are limited to approximately 1000 characters. The CGI Ointerface will provide symbols with values up to that limit if required. This ,should be sufficient for most circumstances.

J The basic CGI symbol names are demonstrated here with a call to a script ,that simply executes the following DCL code:

  $ SHOW SYMBOL WWW_*  $ SHOW SYMBOL *
5 Note how the request components are represented for @ISINDEX-style searching (third item) and a forms-based query (fourth item). 
    K
  1. <A HREF="/script/cgi_symbols">3
  2. = <A HREF="/script/cgi_symbols/ht_root/doc/htd">G
  3. Q <A HREF="/script/cgi_symbols/ht_root/doc/htd/*.*?string1+string2">S
  4. ] <A HREF="/script/cgi_symbols/ht_root/doc/htd?FirstField=for&SecondField=this">


CGI Compliant Output




K Script output must behave in a CGI-compliant fashion (by way of contrast, isee 6.2 - Non-CGI Compliance Output). That is, a CGI script may redirect Gthe location of the document, using a Location: header line, or Fmay supply a data stream beginning with a Content-Type: header .line. Both must be followed by a blank line. 

F If the script output begins with either of the these two lines HTTPd Oassumes that output will be line-oriented, without HTTP carriage-control (each Lline terminated by a carriage-return then a line-feed), and will thereafter Lensure each record it receives is correctly terminated before passing it to Nthe client. In this way DCL procedure output (and the VMS CLI in general) is supported transparently. $

6.1.1 - Example DCL Scripts



5 A simple script to provide the system time might be:!

  $ say = "write sys$output"-  $! the next two lines make it CGI-compliant"  $ say "Content-Type: text/plain"
  $ say ""&  $! start of plain-text script output
  $ show time


C A script to provide the system time more elaborately (using HTML):

  $ say = "write sys$output"-  $! the next two lines make it CGI-compliant!  $ say "Content-Type: text/html"
  $ say ""   $! start of HTML script output  $ say "<HTML>"3  $ say "Hello ''WWW_REMOTE_HOST'"  !(CGI variable)  $ say "<P>"9  $ say "System time on node ''f$getsyi("nodename")' is:",  $ say "<H1>''f$cvtime()'</H1>"  $ say "</HTML>"
(

6.2 - Non-CGI Compliance Output




F A script does not have to output a CGI-compliant data stream. If it ?begins with a HTTP header status line (e.g. ``HTTP/1.0 200 @OK''), HTTPd assumes it will supply a raw HTTP data .stream, containing all the HTTP requirements. 

H Any such script must observe HyperText Transfer Protocol (for detailed ]information on HTTP see 10 - References). Every line must be <terminated by a carriage-return and line-feed /(represented as ``\r''``\n''), or as a minimum Iby a single line-feed. In particular, the type of the data being Mreturned by the scripts must be included in an HTTP header sent prior to the Mdata itself. Headers for the two most common data types will be illustrated Ihere. Note that the blank line is strictly necessary, it terminates the header. 

Plain-Text


  HTTP/1.0 200 ok\r\n  Content-Type: text/plain\r\n  \r\n

HTML



  HTTP/1.0 200 ok\r\n  Content-Type: text/html\r\n  \r\n
%

Non-CGI-Compliant DCL script




F The following example show a non-CGI-compliant DCL script similar in Mfunction to the CGI-compliant one above. Note the full HTTP header and each Eline explictly terminated with a carriage-return and line-feed pair. 

  $ cr[0,8] = %x0d  $ lf[0,8] = %x0a  $ say = "write sys$output"-  $! the next line makes it non-CGI-compliant.  $ say "HTTP/1.0 200 Time follows.''cr'''lf'"+  $ say "Content-Type: text/html''cr'''lf'"  $ say "''cr'''lf'"   $! start of HTML script output   $ say "<HTML>''cr'''lf'"=  $ say "Hello ''WWW_REMOTE_HOST'''cr'''lf'"  !(CGI variable)  $ say "<P>"C  $ say "System time on node ''f$getsyi("nodename")' is:''cr'''lf'"6  $ say "<H1>''f$cvtime()'</H1>''cr'''lf'"!  $ say "</HTML>''cr'''lf'"


6.3 - Raw HTTP Input




8 The logical name HTTP$INPUT defines a mailbox Lproviding the raw HTTP input stream from the client. This is available for 6procedures and executables to explictly open and read.

A Note that this is a raw stream, and HTTP lines (carriage-Ireturn/line-feed terminated sequences of characters) may have be blocked Ltogether for network transport. These would need to be expliclty parsed by the program.

JTo make this stream implicitly available to an executable as the standard Minput stream the following DCL command should be executed immediately before invoking the image:-

  DEFINE /USER_MODE SYS$INPUT HTTP$INPUT





p [next] [previous][contents]