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.
This is a basic callout. Between the callout escape and end-of-text
sequences multiple request/responses transactions may be undertaken.
4.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.
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.
Sets/resets a CGIplus process' lifetime (in seconds). Use to give frequently used scripts an extended lifetime before being rundown by the server (override the [DclCgiPlusLifeTime] configuration parameter). Specifying -1 gives it an infinite lifetime.
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 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.
No operation. Just return a success response.
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 $ write sys$output f$trnlnm("CGIPLUSEOT")
Also see working examples in HT_ROOT:[SRC.CGIPLUS].