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

<CHAPTER>(CGI Callouts\chapter_scripting_callouts)

<P> During CGI or CGIplus processing (though not DECnet-based CGI) it is
possible to suspend  normal script  output to the client and for the script to
interact directly with the server, then resume output to the client.  This may
done more than once during processing.  During the <EMPHASIS>(callout) the
script makes a request of the server and receives a response.  These requests
are to perform some server function, such as the mapping of a path to a file
specification, on behalf of the script.  Naturally, this makes the script no
longer portable, but may be extrememly useful in some circumstances.

<P> It is this general callout mechanism that allows specific authentication
agents (see <QUOTE>(Technical Overview, Authorization)) to be implemented as
standard CGIplus scripts.

<P> The mechanism is quite simple.

<LIST>(NUMBERED)

<LE> The script suspends normal output by writing a record containing a
unique <EMPHASIS>(escape) sequence.

<COMMENT>(HTML=<P>)

<LE> It then writes a record containing a formatted request.  The server
interprets the request, performs the action and returns a success or error
response.

<COMMENT>(HTML=<P>)

<LE> The script concludes the callout by writing a record containing a
unique <EMPHASIS>(end-of-text) sequence.

<COMMENT>(HTML=<P>)

<LE> The script reads the server's response and continues processing.  In
reality the response read could occur immediately after the request write (i.e.
before the concluding end-of-text sequence).

<ENDLIST>

<P> This is a basic callout.  Between the callout escape and end-of-text
sequences multiple request/responses transactions may be undertaken.

<HEAD1>(Requests and Responses\head_scripting_callout_requests)

<P> The request record is plain text, comprising a request key-word
(case-insensitive), full-colon, and following optional white-space and
parameter(s).  It is designed not to be implementation language specific.

<P> The response record is also plain-text.  It begins with a three-digit
response code, with similar meanings and used for the same purpose as HTTP
response codes.  That is 200 is a success status, 500 a server error, 400 a
request error, etc.  Following the response code is white-space and the plain
text result or error message.  A response to any given callout request may be
suppressed by providing a request record with a leading <QUOTE>(!) or
<QUOTE>(#).

<LIST>(UNNUMBERED)

<LE><EMPHASIS>(AUTH-FILE:\BOLD) <EMPHASIS>(file specification)

<P> If the specialized /PROFILE capability is enabled (see
<QUOTE>(Technical Overview, Security Profile)) this can determine whether the
specified file name is allowed access by the request's username.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(GATEWAY-BEGIN:\BOLD) <EMPHASIS>(integer)

<P> When using the raw TCP/IP socket for output (see
<REFERENCE>(chapter_raw_socket)) this callout is used to notify the server that
the script will be using the gateway device and the HTTP status code (e.g. 200,
302, 404, etc.)

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(GATEWAY-END:\BOLD) <EMPHASIS>(integer)

<P> When using the raw TCP/IP socket for output (see
<REFERENCE>(chapter_raw_socket)) this callout is used to notify the server of
the quantity of data transfered directly to the client by the script.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(LIFETIME:\BOLD) <EMPHASIS>(integer)

<P> Sets/resets a script subprocess' lifetime (in minutes).  For instance, use
to give frequently used  CGIplus scripts an extended lifetime before being
rundown by the server (override the [DclCgiPlusLifeTime] configuration
parameter).  Specifying <QUOTE>(none) (or -1) gives it an <EMPHASIS>(infinite)
lifetime, zero resets to default.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(MAP-FILE:\BOLD) <EMPHASIS>(file specification)

<P> Map the supplied file specification to it's URL-style path equivalent, and
against the server's mapping rule.  This does not check the file name is legal
RMS syntax.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(MAP-PATH:\BOLD) <EMPHASIS>(URL-style path)

<P> Map the supplied URL-style path against the server's rule database into a
VMS file specification.  Note that this does not verify the file name legaility
or that the file actually exists.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(NOOP:\BOLD)

<P> No operation.  Just return a success response.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(TIMEOUT-OUTPUT:\BOLD) <EMPHASIS>(integer)

<P> Sets/resets a script request lifetime (in minutes, overrides the
[TimeoutOutput] configuration parameter).  Specifying <QUOTE>(none) (or -1)
gives it an <EMPHASIS>(infinite) lifetime, zero resets to default.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(TIMEOUT-NOPROGRESS:\BOLD) <EMPHASIS>(integer)

<P> Sets/resets a script request no-progress (in minutes, overrides the
[TimeoutNoProgress] configuration parameter).  The <EMPHASIS>(no-progress)
period is the maximum number of seconds that there may be no output from the
script before it is aborted.  Specifying <QUOTE>(none) (or -1) gives it an
<EMPHASIS>(infinite) lifetime, zero resets to default.

<ENDLIST>

<HEAD1>(Code Examples\head_callout_code_examples)

<P> The record-oriented callout sequences and request/response makes
implementation quite straight-forward.  The following C language and DCL
procedure code fragments illustrate the basics.

<CODE_EXAMPLE>
  /* C language */
  CgiPlusIn = fopen ("CGIPLUSIN:", "r");
  printf ("%s\nMAP-FILE: %s\n%s\n",
          getenv("CGIPLUSESC"), FileNamePtr, getenv("CGIPLUSEOT"));
  fgets (CalloutResponse, sizeof(CalloutResponse), CgiPlusIn);

  $! DCL procedure
  $ open /read CgiPlusIn CGIPLUSIN
  $ write sys$output f$trnlnm("CGIPLUSESC")
  $ write sys$output "MAP-PATH: " + PathPtr
  $ read CgiPlusIn Response
  $!(no need to read a response for this next request, it's suppressed)
  $ write sys$output "#TIMEOUT-OUTPUT:10"
  $ write sys$output f$trnlnm("CGIPLUSEOT")
<ENDCODE_EXAMPLE>

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

<COMMENT>(HTML=
<P> Also see working examples in
<A HREF="/ht_root/src/CGIplus/*callout*.*">HT_ROOT:[SRC.CGIPLUS]</A>.
)

<COMMENT>(HTML/OFF)
<P> Also see working examples in HT_ROOT:[SRC.CGIPLUS]
<P> <BOX>(on-line hypertext link)
<COMMENT>(HTML/ON)

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

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