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

<CHAPTER>(ISAPI\chapter_scripting_isapi)

<P> ISAPI (procounced <EMPHASIS>(eye-sap-ee)) was developed by Process Software
Corporation (the developer of Purveyor Encrypt Web Server available under VMS),
Microsoft Corporation and a small number of other vendors.  It has an
software infrastructure similar to CGI but a different architecture.  It is
designed to eliminate the expensive process creation overheads of CGI (under
Unix, let alone VMS), reduce latency for expensive-to-activate resources, and
generally improve server throughput, particularly on busy sites.

<P> Unlike standard CGI, which creates a child process to service each request,
ISAPI is designed to load additional sharable code (DLLs, or Dynamic Link
Libraries in MSWindows, shareable images under VMS) into the Web server's
process space. These are known as server <EMPHASIS>(extensions). This radically
reduces the overheads of subsequent request processing and makes possible
server functionality that can maintain resources between requests (for instance
keep open a large database), again contributing to reduced latency and
increased throughput.

<P> Of course there is a down-side!  Loading foreign executable code into the
server compromises it's integrity.  Poorly written extensions can seriously
impact server performance and in the worst-case even crash a server process.
The other significant concern is the multi-threaded environment of most
servers.  Extensions must be carefully constructed so as not to impact the
granularity of processing in a server and to be <EMPHASIS>(thread-safe), not
creating circumstances where processing corruption or deadlock occurs.

<HEAD1>(CGIsapi\head_isapi_cgisapi)

<P> WASD provides an environment for executing ISAPI based extensions.  Unlike
classic ISAPI the DLLs are not loaded into server space but into autonomous
processes, in much the same way as CGIplus scripts are handled
(<REFERENCE>(chapter_scripting_cgiplus)).  This still offers significantly
improved performance through the persistance of the ISAPI extension between
requests.  Measurements show a potential five-fold, to in excess of ten-fold
increase in throughput  compared to an equivalent CGI script!  This is
comparable to reported performance differences between the two environments in
the Microsoft IIS environment.

<P> While the script process context does add more overhead than if the DLL was  
loaded directly into the server process space, it does have two significant
advantages.

<LIST>(NUMBERED)

<LE> Buggy DLL code will generally not directly affect the integrity of the
server process.  At worst the script process may terminate.

<LE> Each process services only the one request at a time.  This eliminates
the threading issues.

<ENDLIST>

<P> WASD implements the ISAPI environment as an instance of it's CGIplus
environment.  CGIplus shares two significant characteristics with ISAPI,
persistance and a CGI-like environment.  This allows a simple CGIplus
<EMPHASIS>(wrapper) script to be used to load and interface with the ISAPI DLL.
After being loaded the ISAPI-compliant code cannot tell the difference between
the WASD environment and any other vanilla ISAPI one!

<P> This wrapper is known as <EMPHASIS>(CGIsapi\BOLD) (pronounced
<EMPHASIS>(-gee-eye-sap-ee)).

<P> Wrapping another layer does introduce overhead not present in
the native CGIplus itself, however measurements indicate in <EMPHASIS>(the real
world) (tm) performance of the two is quite comparable. See
<QUOTE>(Technical Overview, Performance) for further information.  The
advantage of  ISAPI over CGIplus is not performance but the fact it's a well
documented interface.  Writing a script to that specification may be an easier
option, particularly for sites with a mixture or history of different Web
servers, than learning the CGIplus interface (simple as CGIplus is).

<HEAD1>(Writing ISAPI Scripts\head_isapi_writing)

<P> This section is by-no-means a tutorial on how to write for ISAPI.

<P> First, get a book on ISAPI.  Second, ignore most of it!  Generally these
tomes concentrate on the Microsoft environment.  Still, information on the
basic behaviour of ISAPI extensions and the Internet Server API is valuable. 
Other resources are available at no cost from the Microsoft and Process
Software Corporation sites.

<P> Have a look at the WASD example DLL and it's build procedure in

<COMMENT>(HTML=
<A HREF="/ht_root/src/cgiplus/*isapi*.*?httpd=index&readme=no">HT_ROOT:[SRC.CGIPLUS]</A>.
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.CGIPLUS].
<COMMENT>(HTML/ON)

<P> The CGIsapi wrapper,

<COMMENT>(HTML=
<A HREF="/ht_root/src/cgiplus/cgisapi.c">HT_ROOT:[SRC.CGIPLUS]CGISAPI.C</A>,
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.CGIPLUS]CGISAPI.C,
<COMMENT>(HTML/ON)

is relatively straight-forward, relying on CGIplus for IPC with the parent
server process.  A brief description of the detail of the implementation is
provided in the source code.

<P> CGIsapi has a simple facility to assist with debugging DLLs. When enabled,
information on passed parameters is output whenever a call is made to an ISAPI
function.  This debugging can be toggled on and off whenever desired.  Once
enabled DLL debugging remains active through multiple uses of a CGISAPI
instance, or until disabled, or until the particular CGISAPI process'
lifetime expires.  Check detail in the CGIsapi source code description.

<HEAD>(CGIsapi Considerations\head_isapi_considerations)

<P> The wrapper is designed to be ISAPI 1.0 compliant.  It should also be
vanilla ISAPI 2.0 compliant (not the Microsoft WIN32 variety, so don't think
you'll necessarily be able to grab all those IIS extensions and just recompile
and use ;^)

<P> With CGIsapi multiple instances of any one extension may be active on the
one  server (each in an autonomous process, unlike a server-process-space
loaded extension where only one would ever be active at any one time).  Be
aware this could present different concurrency issues than one multiple or
single threaded instance.

<P> When CGIplus processes are idle they can be run-down at any time
by the server at expiry of lifetime or to free up required server resources. 
For this reason ISAPI extensions (scripts) should finalize the processing of
transactions when finished, not leave anything in a state where it's unexpected
demise might corrupt resources or otherwise cause problems (which is fairly
good general advice anyway ;^)  That is, when finished tidy up as much as is
necessary.

<P> CGIsapi loaded extensions can exit at any time they wish.  The process
context allows this.  Of course, normally a server-process-space loaded
instance would not be able to do so!

<P> For other technical detail refer to the description with the source code.

<NOTE>(Hint!)
Whenever developing ISAPI extensions don't forget that after compiling,
the old version must be purged from the server before trying out the new!!!

<P> Scripting processes may be purged or deleted using (
<QUOTE>(Techncial Overview, Server Command Line Control)):

<CODE_EXAMPLE>
  $ HTTPD /DO=DCL=DELETE
  $ HTTPD /DO=DCL=PURGE
<ENDCODE_EXAMPLE>
<ENDNOTE>

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

<HEAD1>(Server Configuration\head_isapi_config)

<P> Ensure the following are in the appropriate sections of HTTPD$CONFIG.

<CODE_EXAMPLE>
  [DclScriptRunTime]
  .DLL  $CGI-BIN:[000000]CGISAPI.EXE

  [AddType]
  .DLL  application/octet-stream  -  ISAPI extension DLL
<ENDCODE_EXAMPLE>

<P> Ensure this rule exists in the scripting section of HTTPD$MAP.

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

<P> With this rule DLLs may be accessed using something like

<CODE_EXAMPLE>
  http://host.name.domain/isapi/isapiexample.dll
<ENDCODE_EXAMPLE>

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