WASD Hypertext Services - Scripting Environment

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 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. 

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

The mechanism is quite simple. 

1. The script suspends normal output by writing a record containing a unique escape sequence. 

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

3. The script concludes the callout by writing a record containing a unique end-of-text sequence. 

4. 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). 

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

5.1 - Requests and Responses

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. 

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 "!" or "#".

• AUTH-FILE: file specification

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

• GATEWAY-BEGIN: integer

  When using the raw TCP/IP socket for output (see 10 - Raw TCP/IP 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.)

• GATEWAY-END: integer

  When using the raw TCP/IP socket for output (see 10 - Raw TCP/IP Socket) this callout is used to notify the server of the quantity of data transfered directly to the client by the script. 

• LIFETIME: integer

  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 "none" (or -1) gives it an infinite lifetime, zero resets to default. 

• MAP-FILE: file specification

  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. 

• MAP-PATH: URL-style path

  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. 

• NOOP:

  No operation.  Just return a success response. 

• TIMEOUT-OUTPUT: integer

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

• TIMEOUT-NOPROGRESS: integer

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

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. 

  /* 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")

Also see working examples in HT_ROOT:[SRC.CGIPLUS].