WASD Web Services - Scripting

6 - CGI Callouts

6.1 - Requests and Responses 6.2 - Code Examples
next previous contents full-page

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

6.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 "#".

6.2 - Code Examples

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 WASD_ROOT:[SRC.CGIPLUS].

next previous contents full-page