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

<CHAPTER>(Run-Time Environments\chapter_scripting_rte)

<P> A Run-Time Environment (RTE) is a persistant scripting environment with
similar objectives to CGIplus <HELLIPSIS> reducing script response time,
increasing server throughput and reducing system impact.  In fact the RTE
environment is implemented using CGIplus!  There is very little difference in
the behaviour of CGIplus scripts and RTEs.  Both are activated by the server,
process multiple requests (reading the request CGI environment from a data
stream supplied by the server), persist between requests in a quiescent state,
and may be removed by the server if idle for a specified period or when it
wishes to use the process for some other purpose. <EMPHASIS>(Like CGIplus an
RTE must be purpose-written for the environment!\BOLD)  What is the difference
then?

<P> With CGIplus the script itself persists between uses, retaining all of it's
state.  With an RTE the script does not persist or retain state, only the RTE
itself.

<P> A RTE is intended as an environment in which a script source is interpreted
or otherwise processed, that is for scripting engines, although it is not
limited to that.  The essential  difference between an RTE and a CGIplus script
is this script source.  In CGIplus the SCRIPT_NAME and SCRIPT_FILENAME CGI
variables reflect the script itself, and remain constant for each activation of
the script, with PATH_INFO and PATH_TRANSLATED providing the additional
<QUOTE>(location) information for the script processing.  With an RTE the
SCRIPT_NAME and SCRIPT_FILENAME can vary with each activation.  This allows the
RTE to process multiple, successive different (or the same) scripts, each with
it's own PATH_INFO and PATH_TRANSLATED.  Hence, it is not unreasonable to
consider the two environments to be the same, with a slight difference in the
mapping of resources passed to them.

<P> This might be best illustrated with examples.

<HEAD>(CGIplus Example\head_cgiplus_example)

<P> Consider the mapping rule

<CODE_EXAMPLE>
  exec+ /cgiplus-bin/* /cgi-bin/*
<ENDCODE_EXAMPLE>

<CP> applied to the following CGIplus request

<CODE_EXAMPLE>
  /cgiplus-bin/xyz/the/path/information?and=a&query=string
<ENDCODE_EXAMPLE>

<P> If the script was an executable it would be activated as

<CODE_EXAMPLE>
  CGI-BIN:[000000]XYZ.EXE
<ENDCODE_EXAMPLE>

<CP> with script CGI information

<CODE_EXAMPLE>
  /cgiplus-bin/xyz
  CGI-BIN:[000000]XYZ.EXE
<ENDCODE_EXAMPLE>

<CP> and the request path information and query string supplied as

<CODE_EXAMPLE>
  /the/path/information
  THE:[PATH]INFORMATION
  and=a&query=string
<ENDCODE_EXAMPLE>

<HEAD>(RTE Example\head_rte_example)

<P> By contrast with a request to activate an RTE the following mapping rule

<CODE_EXAMPLE>
  exec+ /xyz-bin/* (CGI-BIN:[000000]XYZ.EXE)/ht_root/src/xyz/*
<ENDCODE_EXAMPLE>

<CP> (note the RTE executable specified inside parentheses) and request

<CODE_EXAMPLE>
  /xyz-bin/an_example/the/path/information?and=a&query=string
<ENDCODE_EXAMPLE>

<CP> would activate the scripting environment (perhaps interpreter)

<CODE_EXAMPLE>
  CGI-BIN:[000000]XYZ.EXE
<ENDCODE_EXAMPLE>

<CP> supplying it with per-request script name and file information 

<CODE_EXAMPLE>
  /xyz-bin/an_example.xyz
  HT_ROOT:[SRC.XYZ]AN_EXAMPLE.XYZ
<ENDCODE_EXAMPLE>

<CP> and path and query string information

<CODE_EXAMPLE>
  /the/path/information
  THE:[PATH]INFORMATION
  and=a&query=string
<ENDCODE_EXAMPLE>

<HEAD>(Summary\head_RTE_summary)

<P> As can be seen the script information is constant for each request to a
CGIplus script, while with RTE the script information could vary with each
request (although of course it would be the same if the same script is
requested).  In the case of CGIplus the <EMPHASIS>(process what?) request
information is provided only by path information, however with RTE both script
and path information are used.

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

<HEAD1>(RTE Programming\head_rte_programming)

<P> <EMPHASIS>(The RTE interface is still CGI\BOLD), with all the usual
environment variables and input/output streams available, just in a CGIplus
environment!  Hence when coding a Run-Time Environment the same considerations
involved in CGIplus programming apply (<REFERENCE>(chapter_scripting_cgiplus)).

<P> In particular it is important a RTE should explicitly close files, free
allocated memory, etc., after processing a request (of course it cannot rely on
image  run-down to clean-up after itself). It is particularly important that
all traces of each script's processing are removed after it concludes.  This
does not mean for example that databases need to be completely closed, etc.,
which might defeat the purpose of using a persistant environment, just that
great care must be exercised by the programmer to prevent one script
interfering with another!

<P> An example RTE,

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

<COMMENT>(HTML=
<A HREF="/ht_root/src/CGIplus/RTE_example.c"> HT_ROOT:[SRC.CGIPLUS]RTE_EXAMPLE.C</A>
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.CGIPLUS]RTE_EXAMPLE.C.
<P> <BOX>(online hypertext link)
<COMMENT>(HTML/ON)

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

provides the basics of the environment.

<P> A source code collection of C language functions useful for processing the
more vexing aspects of CGI/CGIplus/RTE programming (<REFERENCE>(head_cgilib)). 
The example RTE implementation uses this library.

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

<HEAD1>(Server Configuration\head_rte_config)

<P> The following configuration information uses the supplied Perl RTE as the
example.  Note that RTE scripting engines must always be mapped using the EXEC+
rules.  The SCRIPT+ rule does not apply.

<P> The following rule in HTTPD$MAP maps the /pl-bin/ location to where the
site wishes to locate it's CGI Perl scripts (not necessarily the same as in the
example).

<CODE_EXAMPLE>
  exec+ /pl-bin/* (CGI-BIN:[000000]PERLRTE.EXE)/ht_root/src/perl/*
<ENDCODE_EXAMPLE>

<P> With this rule Perl scripts may be accessed using 

<CODE_EXAMPLE>
  http://host.name.domain/pl-bin/an_example
<ENDCODE_EXAMPLE>

<P> A DCL procedure can be specified in place of an executable.  Merely prefix
the specification with a <QUOTE>(@).

<P> This HTTPD$CONFIG rule ensures Perl scripts could be activated via
the Perl RTE even if the HTTPD$MAP rule did not exist
(<REFERENCE>(head_script_runtime)).

<CODE_EXAMPLE>
  [DclScriptRunTime]
  .PL  (CGI-BIN:[000000]PERLRTE.EXE)
<ENDCODE_EXAMPLE>

<NOTE>
The server makes no check of the RTE executable (or procedure) before
attempting to activate  it using DCL for processing the script.  If it does not
exist or is not accessable due to incorrent file protections the DCL of the
scripting process will report the problem.
<ENDNOTE>

<P> It does by default however, check that the file used as the script source
exists as with other scripting environments.  If it does not this is reported
as a <QUOTE>(script not found).  For RTEs that wish to report on this
themselves, or that possibly construct their own script specification via some
internal processing, this server behaviour may be suppressed for the script
activation path using the HTTPD$MAP path SETting <QUOTE>(script=nofind) as in
the following example.

<CODE_EXAMPLE>
  set /xyz-bin/* script=nofind
  exec+ /xyz-bin/* (CGI-BIN:[000000]XYZ.EXE)/ht_root/src/xyz/*
<ENDCODE_EXAMPLE>

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