WASD Web Services - Scripting

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 ( "Features and Facilities, 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.

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 ( "Features and Facilities, Security Profile") this can determine whether the specified file name is allowed access by the request's username.

• BUFFER-BEGIN: <integer>[k|M]

  Create a temporary global section to act as a memory buffer shared between a script process and the server. The default is Megabytes. See 2.2.3 - Bulk Content Output for a description of the purpose and use of all the BUFFER-.. callouts.

• BUFFER-END:

  Dispose of the shared memory buffer created by callout BUFFER-BEGIN.

• BUFFER-WRITE: <integer>

  Instruct the server to write <integer> bytes from the shared memory buffer to the client.

• CGIPLUS: string

  This callout is used to indicate to the server that a CGIplus script can process the CGI variables in "struct" mode. By default each CGI variable is transfered to a CGIplus script one "record" at a time. In "struct" mode all variables are transfered in a single, binary I/O which must the be parsed by the the script. It is of course a much more efficient method for CGIplus (Struct-Mode CGIplus).

• GATEWAY-BEGIN: integer

  When using the raw TCP/IP socket for output (11 - 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-CCL: integer

  When using the raw TCP/IP socket for output (11 - Raw TCP/IP Socket) this can be used to change the BG: device carriage-control. A value of 1 enables a <CR><LF> with each record (the default), while 0 disables it. This is analagous to the APACHE$SET_CCL utility.

• GATEWAY-END: integer

  When using the raw TCP/IP socket for output (11 - 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 scripting process' lifetime which may be expressed as an integer number of minutes or in the format hh:mm:ss. 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 its 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.

• NOTICED: string

  Place the supplied string into the server process log. Used to report incidental processing or other errors.

• OPCOM: string

  Send the supplied string to OPCOM.

• REDACT:

  See 10 - Request Redaction.

• REDACT-SIZE:

  See 10 - Request Redaction.

• SCRIPT-CONTROL:

  Equivalent to the script issuing a "Script-Control:" response header field (although of course some script control directives will not apply after header generation).

• TIMEOUT-BIT-BUCKET: integer

  Specifies the period for which a script continues to execute if the client disconnects. Overrides the WASD_CONFIG_GLOBAL [DclBitBucketTimeout] confiuration directive.

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