<COMMENT>(--------------------------------------------------------------------)

<FRONT_MATTER>
<TITLE_PAGE>

<TITLE>(DEFORM Scripting Utility)

<LINE>

<HEAD>(19th April 1995\head_date)

<HEAD>(This is a new <EMPHASIS>(and draft) document.\head_draft)

<HEAD>(Abstract\head_abstract)

<P> This document describes a utility to assist in the processing of HTTPd 
scripts, and for the HTTP <EMPHASIS>(POST\SMALLCAPS) method in particular.  It 
is intended for Hypertext maintainers who have a requirement to implement 
scripting. 

<COMMENT>(HTML/OFF)
<P> It is strongly suggested those using printed versions of this document 
also access the Hypertext version.  It provides online demonstrations of some 
concepts. <COMMENT>(HTML/ON) 

<HEAD>(Contact\head_contact)

<P> M.G.Daniel 

<HEAD>(Printed Copy\head_printed_copy)

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> For Hypertext browsers a PostScript version of this document is available
 <A HREF="/ht_root/docs/deform/deform.ps">viewing</A> 
 and for
 <A HREF="/print/ht_root/docs/deform/deform.ps">printing</A>.
)

<COMMENT>(HTML/OFF)
<P> This book is available for printing to a PostScript printer.  At the VMS 
command line enter <QUOTE>(PrintBook), the facility is menu driven.  For 
multiple copies it is better to print once, then <EMPHASIS>(photo-copy). 
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<LINE>

<ENDTITLE_PAGE>

<CONTENTS_FILE>

<ENDFRONT_MATTER>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Introduction\chapter_introduction)

<P> This document describes a utility to assist in the processing of HTTPd 
scripts, and for the HTTP <EMPHASIS>(POST\SMALLCAPS) method in particular. 
It is intended for Hypertext maintainers who have a requirement to implement 
scripting. 

<P> One of the primary functions of DEFORM is to parse 
<EMPHASIS>(POST\SMALLCAPS) method requests of <EMPHASIS>(Content-Type:) 
<QUOTE>(application/x-www-form-urlencoded), making the values of the form 
fields readily available in DCL scripts.  This is done by creating DCL symbols 
corresponding to the fields, or by creating a temporary plain-text file 
containing the fields and their values.  It is anticipated that most
requirements will be met using the DCL symbol functionality.

<P> Other functions of the utility include user authentication, document 
redirection, and HTTP response header generation.  User authentication is 
significant because it provides the identity of the user of the browser 
activating the script and confidence that this identity has been verified by 
password.

<COMMENT>(HTML/OFF)
<P> It is strongly suggested those using printed versions of this document 
also access the Hypertext version.  It provides online demonstrations of some 
concepts.
<COMMENT>(HTML/ON) 

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(General Script Environment\chapter_general_environment)

<P> The following section provides some general information on the VMS HTTPd 
scripting enviroment.

<P> <EMPHASIS>(Scripts) are mechanisms for creating simple <QUOTE>(servers) 
for accepting data from and sending data to a client, extending the services 
provided by the basic server.  A DCL procedure is the basis for a script.  An 
executable can be invoked by a script.  <EMPHASIS>(TYPE\SMALLCAPS)-ing a file 
can be provide script output.  Anything that can write to 
<EMPHASIS>(SYS$OUTPUT\SMALLCAPS) can be used to generate script output. 

<P> Specific scripts are enabled by VMS system management.  Scripts cannot be 
implemented by just anyone.

<HEAD1>(CGI Compliance\head_cgi_compliance)

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

<HEAD>(CGI Compliant Variables\head_cgi_variables)

<P> Environment variables are created in a similar way to the CERN VMS HTTPD 
implementation, where CGI environment variables are provided to the script via 
DCL global symbols.  These variables represent various aspects of the call to 
the script, aspects such as:

<LIST>(UNNUMBERED)

<LE><EMPHASIS>(WWW_PATH_INFO\SMALLCAPS)
<LINE> The URL format path to the document.

<LE><EMPHASIS>(WWW_PATH_TRANSLATED\SMALLCAPS)
<LINE> The native file system (VMS) path to the document.

<LE><EMPHASIS>(WWW_REMOTE_HOST\SMALLCAPS)
<LINE> The internet host name of the system the browser is executing on.

<LE><EMPHASIS>(WWW_REMOTE_USER\SMALLCAPS)
<LINE> The authenticated name of the user of the browser client.

<ENDLIST>

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

<CODE_EXAMPLE>
  $ SHOW SYMBOL WWW_*
<ENDCODE_EXAMPLE>

<CP> Note how the request components are represented for 
<EMPHASIS>(ISINDEX\SMALLCAPS)-style searching (third item) and a forms-based 
query (fourth item). 

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<OL>
<LI> <A HREF="/cgi_symbols">&lt;A HREF="/cgi_symbols"&gt;</A>
<LI> <A HREF="/cgi_symbols/some/path/or/another">
     &lt;A HREF="/cgi_symbols/some/path/or/another"&gt;</A>
<LI> <A HREF="/cgi_symbols/path/search/*.*?string1+string2">
     &lt;A HREF="/cgi_symbols/path/search/*.*?string1+string2"&gt;</A>
<LI> <A HREF="/cgi_symbols/path/form?FirstField=for&SecondField=this">
     &lt;A HREF="/cgi_symbols/path/form?FirstField=for&SecondField=this"&gt;</A>
</OL>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<HEAD>(CGI Compliant Output\head_cgi_output)

<P> Script output must behave in a CGI-compliant fashion (by way of contrast, 
see <REFERENCE>(head_non_cgi_compliance)).  That is, a CGI script may redirect 
the location of the document, using a <EMPHASIS>(Location:) header line, or 
may supply a data stream beginning with a <EMPHASIS>(Content-Type:) header 
line.  Both must be followed by a blank line.  The DEFORM utility can readily 
and transparently provide this functionality. 

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

<COMMENT>(....................................................................)

<HEAD>(Example DCL Scripts\head_example_dcl_scripts)

<P> A simple script to provide the system time might be:

<CODE_EXAMPLE>
  $ 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
<ENDCODE_EXAMPLE>

<P> A script to provide the system time more elaborately (using HTML):

<CODE_EXAMPLE><LITERAL>  $ 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>"
  $ say "Hello ''WWW_REMOTE_HOST'"  !(CGI variable)
  $ say "<P>"
  $ say "System time on node ''f$getsyi("nodename")' is:"
  $ say "<H1>''f$cvtime()'</H1>"
  $ say "</HTML>"
<ENDLITERAL><ENDCODE_EXAMPLE>

<HEAD1>(Non-CGI Compliance Output\head_non_cgi_compliance)

<P> A script does not have to output a CGI-compliant data stream.  If it 
begins with a HTTP header status line (e.g. <QUOTE>(<EMPHASIS>(HTTP/1.0 200 
OK\SMALLCAPS))), HTTPD assumes it will supply a <EMPHASIS>(raw\BOLD) HTTP data 
stream, containing all the HTTP requirements.   Any such script must observe 
HyperText Transfer Protocol.  Every line must be terminated by a 
<EMPHASIS>(carriage return), then a <EMPHASIS>(line feed). 

<HEAD>(Non-CGI-Compliant DCL script\head_non_cgi_script)

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

<CODE_EXAMPLE><LITERAL>  $ 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>"
  $ say "System time on node ''f$getsyi("nodename")' is:''cr'''lf'"
  $ say "<H1>''f$cvtime()'</H1>''cr'''lf'"
  $ say "</HTML>''cr'''lf'"
<ENDLITERAL><ENDCODE_EXAMPLE>

<HEAD1>(Raw HTTP Input\head_raw_http_input)

<P> The logical name <EMPHASIS>(HTTP$INPUT\SMALLCAPS) defines a mailbox 
providing the raw HTTP input stream from the client.  This is available for 
procedures and executables to explictly open and read.

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

<P> It is this stream that the DEFORM utility parses for the
<EMPHASIS>(POST\SMALLCAPS) method..

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(General DEFORM Considerations\chapter_general_deform)

<P> The utility is activated via a foreign command.  It needs to be assigned
before the script uses it.  For example:

<CODE_EXAMPLE>
  $ DEFORM = "$HT_EXE:DEFORM"
  $ DEFORM <EMPHASIS>([qualifiers])
<ENDCODE_EXAMPLE>

<P> Individual qualifiers placed on the command line should be space separated
(due to the laziness of both the author and the C language).

<HEAD>(Script Environment\head_script_environment)

<P> The script executes in an unprivileged user account.  No assumptions should
be made concerning the symbol or logical name environment.  File system scratch
space can only be depended upon via the mechanism documented
below.

<P> The script will execute in a multi-threaded environment and so may not be
the only script, or the only instance of any one script, active at the one
time.  For any scratch file space or other shared resources use the
<EMPHASIS>(DEFORM_UNIQUE\SMALLCAPS) symbol documented immediately below.

<HEAD>(Scratch Space\head_scratch)

<P> Using the <EMPHASIS>(/SCRATCH\SMALLCAPS) qualifier at any stage (by itself
or in conjunction with others) assigns two DCL symbols indicating the location
of a directory for scratch files (<EMPHASIS>(DEFORM_SCRATCH\SMALLCAPS)) and a
time string that can be used to create unique file names, etc.
(<EMPHASIS>(DEFORM_UNIQUE\SMALLCAPS)).

<P> <EMPHASIS>(Do not\BOLD) use this qualifier more that once during the one
script, it may be confusing to your script.

<P> An example:

<CODE_EXAMPLE>
  $ DEFORM = "$HT_EXE:DEFORM"
  $ DEFORM /SCRATCH
  $ ON ERROR THEN GOTO CLEANUP_OUT_FILE
  $ OPEN /WRITE OUT_FILE 'DEFORM_SCRATCH''DEFORM_UNIQUE'.TXT
    .
    .
    .
  $ CLOSE OUT_FILE
    .
    .
    .
  $ CLEANUP_OUT_FILE:
  $    IF F$TRNLNM("OUT_FILE") .NES. "" THEN CLOSE OUT_FILE
  $    DELETE 'DEFORM_SCRATCH''DEFORM_UNIQUE'.TXT;*
<ENDCODE_EXAMPLE>

<P> <EMPHASIS>(Do not\BOLD) use the file type <EMPHASIS>(.TMP\SMALLCAPS), this
is employed when the <EMPHASIS>(/FILE\SMALLCAPS) qualifier is used, it may be
confusing to your script.

<P> <EMPHASIS>(Please ensure all scripts include error trapping and final
cleaning up of any temporary file space used.\BOLD) 

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(GET Method\chapter_get)

<P> Any functionality specified can be limited to the 
<EMPHASIS>(GET\SMALLCAPS) method by specifying the <EMPHASIS>(/GET\SMALLCAPS) 
qualifier.  If the script was activated via the <EMPHASIS>(POST\SMALLCAPS) 
method the utility will simply exit with a success status. 

<P> With HTTP <EMPHASIS>(GET\SMALLCAPS) method requests the HTTPd server has 
already parsed query string form fields into corresponding DCL symbols (see 
<REFERENCE>(head_cgi_compliance)) which are directly accessable to a script 
without further processing.

<P> The DEFORM utility can however be used to conveniently perform other 
functions in the <EMPHASIS>(GET\SMALLCAPS) environment.  These include:

<LIST>(UNNUMBERED)

<LE> Ensuring script activation is by an authenticated user, done using the 
<EMPHASIS>(/AUTHENTICATE\SMALLCAPS) qualifier.

<LE> Providing a document/link via redirection, using the 
<EMPHASIS>(/LOCATION\SMALLCAPS) qualifier.  This will cause the HTTPd server 
or browser to transparently request the specified URL.

<LE> Providing HTTP response header components using the
<EMPHASIS>(/HTML\SMALLCAPS),
<EMPHASIS>(/STATUS\SMALLCAPS),
<EMPHASIS>(/TEXT\SMALLCAPS) and
<EMPHASIS>(/TYPE\SMALLCAPS)
qualifiers.

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(POST Method\chapter_post)

<P> Any functionality specified can be limited to the 
<EMPHASIS>(POST\SMALLCAPS) method by specifying the 
<EMPHASIS>(/POST\SMALLCAPS) qualifier.  If the script was activated via the 
<EMPHASIS>(GET\SMALLCAPS) method the utility will simply exit with a success 
status. 

<P> One of the primary functions of DEFORM is to parse 
<EMPHASIS>(POST\SMALLCAPS) method requests of <EMPHASIS>(Content-Type:) 
<QUOTE>(application/x-www-form-urlencoded).  This content type is generated by 
<EMPHASIS>(<LITERAL>(<)FORM METHOD=POST ACTION="..."<LITERAL>(>)\SMALLCAPS) 
HTML and comprises a body in URL-escaped form format. 

<P> An example form would be:

<CODE_EXAMPLE><LITERAL>  <FORM METHOD=POST ACTION="/example/only">
  <INPUT TYPE=text NAME=field_one VALUE="default text">
  <INPUT TYPE=radio NAME=field_two VALUE="two-a" CHECKED> two-a
  <INPUT TYPE=radio NAME=field_two VALUE="two-b"> two-b
  <INPUT TYPE=radio NAME=field_two VALUE="two-c"> two-c
  <INPUT TYPE=textarea NAME=field_three ROWS=4 COLS=32 VALUE="Line 1;
  Line 2;
  "
  <INPUT TYPE=submit>
  </FORM>
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> This would generate an HTTP request body comprising:

<CODE_EXAMPLE><LITERAL>  field_one=default%20text&field_two=two-a&field_three=Line%201;%0aLine%202;%0a
<ENDLITERAL><ENDCODE_EXAMPLE>

<HEAD1>(DCL Symbols\head_dcl_symbols)

<P> To make these form fields conveniently available to scripts DEFORM will 
parse the request body into a series of DCL symbols named after the 
corresponding field and containing the field's value.  The field name is 
prefixed with <EMPHASIS>(WWW_FORM_\SMALLCAPS) to create the symbol name.  That 
is, a field within the body comprising <QUOTE>(test_field=Test%20value!) would 
be represented by a symbol named <EMPHASIS>(WWW_FORM_TEST_FIELD\SMALLCAPS) and 
containing the string <QUOTE>(Test value!).  This naming convention 
corresponds to the CERN HTTPd VMS implementation and to the HFRD 
implementation (for further information see the Technical Guide to the HFRD 
hypertext enviroment). 

<P> This functionality is activated by using the 
<EMPHASIS>(/SYMBOLS\SMALLCAPS) qualifier.

<P> An example form (the same as in the earlier example) would be:

<CODE_EXAMPLE><LITERAL>  <FORM METHOD=POST ACTION="/example/only">
  <INPUT TYPE=text NAME=field_one VALUE="default text">
  <INPUT TYPE=radio NAME=field_two VALUE="two-a" CHECKED> two-a
  <INPUT TYPE=radio NAME=field_two VALUE="two-b"> two-b
  <INPUT TYPE=radio NAME=field_two VALUE="two-c"> two-c
  <INPUT TYPE=textarea NAME=field_three ROWS=4 COLS=32 VALUE="Line 1;
  Line 2;
  "
  <INPUT TYPE=submit>
  </FORM>
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> This would generate symbols comprising:

<CODE_EXAMPLE>
  $ SHOW SYMBOL WWW_FORM_*
    WWW_FORM_FIELD_ONE == "default text"
    WWW_FORM_FIELD_TWO == "two_a"
    WWW_FORM_FIELD_THREE == "Line 1;.Line 2;.."
<ENDCODE_EXAMPLE>

<HEAD2>(Example DCL\head_post_file_dcl)

<P> Symbols could be processed in DCL using the following syntax: 

<CODE_EXAMPLE>
  $ DEFORM /SYMBOLS
  $ IF .NOT. $STATUS THEN EXIT
  $ IF WWW_FORM_FIELD_TWO .EQS. "two-a"
  $ THEN
       WRITE SYS$OUTPUT "a:" + WWW_FORM_FIELD_THREE
       EXIT
  $ ENDIF
  $ IF WWW_FORM_FIELD_TWO .EQS. "two-b"
  $ THEN
       WRITE SYS$OUTPUT "b:" + WWW_FORM_FIELD_THREE
       EXIT
  $ ENDIF
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=

<H2>This is an example using DCL symbols.</H2>

<P> This is the <A HREF="/ht_root/docs/deform/ExampleDeformSymbols.com">
DCL procedure script</A>.

<P> This provides an <A HREF="/ExampleDeformSymbols">online demonstration</A>.  
When this link is first selected a <TT>GET</TT> method request is generated 
and the script redirects to an HTML file providing a form.  When the form is 
submitted a <TT>POST</TT> method request is generated.  This parses the form 
fields and returns an HTML document show the field values.

) 

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<HEAD2>(Constraints\head_symbol_constraints)

<P> Symbol names are limited to 255 characters.  This should be more than 
adequate.  Symbol values are also limited to 255 characters.  This may be of 
greater concern in some circumstances.  Due to this VMS Run-Time Library 
constraint the only alternative is parse the body into a temporary file (see 
<REFERENCE>(head_post_file)).

<HEAD1>(File\head_post_file)

<P> Due to the limitations on DCL symbol size (see 
<REFERENCE>(head_symbol_constraints)) it may sometimes be necessary to parse 
the contents of the request body into a temporary file, and process that.  The 
file is formatted as a series of form field names on a single line followed by 
the form value on one or more subsequent lines.  Multiple field names and
their values are separated by blank lines.

<P> Any field with an empty value contains only the name line with a blank line
following immediately.

<P> All non-empty field value lines begin with a single <EMPHASIS>(equal)
symbol.  Hence when processing, all values begin from the second character in
the line.

<P> Where the value contains multiple lines (as with a
<EMPHASIS>(<LITERAL>(<)INPUT TYPE=textarea ...<LITERAL>(>)\SMALLCAPS) HTML
construct) these lines are reproduced following the field name.  If the value
contained a blank line, this is differentiated from the field-separating blank
lines by the leading <EMPHASIS>(equal) symbol.

<P> This functionality is activated by using the 
<EMPHASIS>(/FILE\SMALLCAPS) qualifier.

<P> An example form (the same as in the earlier example) would be:

<CODE_EXAMPLE><LITERAL>  <FORM METHOD=POST ACTION="/example/only">
  <INPUT TYPE=text NAME=field_one VALUE="default text">
  <INPUT TYPE=radio NAME=field_two VALUE="two-a" CHECKED> two-a
  <INPUT TYPE=radio NAME=field_two VALUE="two-b"> two-b
  <INPUT TYPE=radio NAME=field_two VALUE="two-c"> two-c
  <INPUT TYPE=textarea NAME=field_three ROWS=4 COLS=32 VALUE="Line 1;
  Line 2;
  "
  <INPUT TYPE=submit>
  </FORM>
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> This would generate a file comprising:

<CODE_EXAMPLE>
  field_one
  =default text

  field_two
  =two-a

  field_three
  =Line 1;
  =Line 2;
  =
<ENDCODE_EXAMPLE>

<HEAD2>(Example DCL\head_post_file_example)

<P> To ensure a unique file name it is generated from time components.  After 
successful creation the file name is available to the script via the 
<EMPHASIS>(DEFORM_FILE\SMALLCAPS) symbol.  Please ensure the file is deleted 
when processing is concluded.  The file could be opened, processed, closed and 
deleted in DCL using the following syntax: 

<CODE_EXAMPLE>
  $ DEFORM /FILE
  $ IF .NOT. $STATUS THEN EXIT
  $ ON ERROR THEN GOTO ERROR_TRAP
  $ OPEN /READ DFILE 'DEFORM_FILE'
    .
    .
    .
  $ ERROR_TRAP:
  $    IF F$TRNLNM("DFILE") .NES. "" THEN CLOSE DFILE
  $    DELETE 'DEFORM_FILE';*
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=

<H2>This is an example using a temporary file.</H2>

<P> This is the <A HREF="/ht_root/docs/deform/ExampleDeformFile.com">
DCL procedure script</A>.

<P> This provides an <A HREF="/ExampleDeformFile">online demonstration</A>.  
When this link is first selected a <TT>GET</TT> method request is generated 
and the script redirects to an HTML file providing a form.  When the form is 
submitted a <TT>POST</TT> method request is generated.  This parses the form 
fields into a plain text file.  The file is opened and read to generate an 
HTML document showing the field values.  The file then is closed and deleted. 

) 

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<HEAD2>(Other\head_post_other)

<P> The DEFORM utility can also be used to conveniently perform other 
functions in the <EMPHASIS>(POST\SMALLCAPS) environment.  These include:

<LIST>(UNNUMBERED)

<LE> Ensuring script activation is by an authenticated user, done using the 
<EMPHASIS>(/AUTHENTICATE\SMALLCAPS) qualifier.

<LE> Providing a document/link via redirection, using the 
<EMPHASIS>(/LOCATION\SMALLCAPS) qualifier.  This will cause the HTTPd server 
or browser to transparently request the specified URL.

<LE> Providing HTTP header components using the
<EMPHASIS>(/HTML\SMALLCAPS)
<EMPHASIS>(/STATUS\SMALLCAPS)
<EMPHASIS>(/TEXT\SMALLCAPS)
<EMPHASIS>(/TYPE\SMALLCAPS)
qualifiers.

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(DEFORM Parameters and Qualifiers\chap_parameters_qualifiers)

<P>
<EMPHASIS>(DEFORM [qualifiers]\BOLD)

<LINE>(SMALLSKIP)
<P> A symbol for a foreign command should be first assigned, then the image 
activated.

<CODE_EXAMPLE>
  $ DEFORM = "$HT_EXE:DEFORM"
  $ DEFORM <EMPHASIS>([qualifiers])
<ENDCODE_EXAMPLE>

<HEAD1>(Parameters\head_parameters)

<P> None.

<HEAD1>(Qualifiers\head_qualifiers)

<EMPHASIS>(/AUTHENTICATE=\BOLD) <EMPHASIS>(realm)
<LINE>
The utility checks for the presence of an authenticated remote user name 
(DCL symbol <EMPHASIS>(WWW_REMOTE_USER\SMALLCAPS).  If not detected the 
utility send an authentication failure header to the browser, causing it to 
provide authentication dialog, then exits with an error status.  If an 
authenticated user name exists any other functionality is performed.  The 
value supplied specifies the authentication <EMPHASIS>(realm).  Currently only 
HFRD is defined. 

<LINE>(SMALLSKIP)
<EMPHASIS>(/FILE\BOLD)
<LINE>
For the HTTP <EMPHASIS>(POST\SMALLCAPS) method the request body is parsed into 
plain text contained within a temporary file specified by the DCL symbol
<EMPHASIS>(DEFORM_FILE\SMALLCAPS).

<LINE>(SMALLSKIP)
<EMPHASIS>(/GET\BOLD)
<LINE>
If the HTTP method is not <EMPHASIS>(GET\SMALLCAPS) then just exit with a 
success status.  That is, only perform any specified functionality if the 
method is the same as the qualifier. 

<LINE>(SMALLSKIP)
<EMPHASIS>(/HTML\BOLD)
<LINE>
The utility outputs an HTTP response header specifying to the browser that the 
following document will be HyperText Markup Language.  The document supplied 
should not include embedded HTTP carriage-control (i.e. no
carriage-return/line-feed sequences).

<LINE>(SMALLSKIP)
<EMPHASIS>(/LOCATION=\BOLD) <EMPHASIS>(URL)
<LINE>
The utility will output a redirection response resulting in the document of 
the specified URL begin returned to the browser.  The URL must be either a 
full URL (<EMPHASIS>(scheme//host/path), e.g. 
<QUOTE>(http://host.domain/dir1/dir2/doc.type)), or the full path of a 
document accessable by the same server (e.g. <QUOTE>(/dir1/dir2/doc.type)).
Relative paths cannot be processed.

<LINE>(SMALLSKIP)
<EMPHASIS>(/TYPE=\BOLD) <EMPHASIS>(MIME-Content-Type)
<LINE>
The utility outputs an HTTP response header specifying to the browser that the 
following document will be of the specified type.  The document supplied 
should not include embedded HTTP carriage-control (i.e. no
carriage-return/line-feed sequences).

<LINE>(SMALLSKIP)
<EMPHASIS>(/POST\BOLD)
<LINE>
If the HTTP method is not <EMPHASIS>(POST\SMALLCAPS) then just exit with a 
success status.  That is, only perform any specified functionality if the 
method is the same as the qualifier. 

<LINE>(SMALLSKIP)
<EMPHASIS>(/SCRATCH\BOLD)
<LINE>
Assigns two DCL symbols indicating the location of a directory for scratch
files (<EMPHASIS>(DEFORM_SCRATCH\SMALLCAPS)) and a time string that can be
used to create unique file names, etc. (<EMPHASIS>(DEFORM_UNIQUE\SMALLCAPS)).

<LINE>(SMALLSKIP)
<EMPHASIS>(/STATUS=\BOLD) <EMPHASIS>(HTTP-Status-String)
<LINE>
The utility outputs an HTTP header to the browser including the supplied 
string as the reponse status.  It must be a legitimate three digit code, with 
or without a trailing explanation string.  When specifying a header any 
subsequent output to the browser should include full embedded HTTP
carriage-control (i.e. carriage-return/line-feed sequences). 

<LINE>(SMALLSKIP)
<EMPHASIS>(/TEXT\BOLD)
<LINE>
The utility outputs an HTTP response header specifying to the browser that the 
following document will be plain text.  The document supplied should not 
include embedded HTTP carriage-control (i.e. no carriage-return/line-feed 
sequences). 

<LINE>(SMALLSKIP)
<EMPHASIS>(/SYMBOLS\BOLD)
<LINE>
For the HTTP <EMPHASIS>(POST\SMALLCAPS) method the request body is parsed into 
a series of global symbols.

<COMMENT>(--------------------------------------------------------------------)


