Callout processing may redact (completely rewrite and restart) a request.
re-dact -verb (used with object) 1. to put into suitable literary form; revise; edit. 2. to draw up or frame (a statement, proclamation, etc.). [Origin: 13501400; ME < L redactus (ptp. of redigere to lead back), equiv. to red- red- + ctus, ptp. of agere to lead; see act]
To do this a script must use the REDACT:<opaque> callout to send back to the server a completely new request header and body (if applicable) which the server then treats as if received from the client over the network. This allows a request to be partially or completely rewritten (as required) and restarted. The data supplied to this callout is treated as completely opaque and care must be taken to include all and no extra carriage-control, etc.
Request redaction may only be initiated (using the REDACT: callout) if the CGI response header has not been sent. Once request redaction has been initiated no CGI output subsequently can be generated. The server will generate an error if such a protocol error occurs.
The REDACT-SIZE:<integer> callout may be used prior to any REDACT: callout. By default the server allocates memory on demand to accomodate the redacted request. If the redacted request is large (more than [BufferSizeDclOutput]) and the total size of the redacted request known in advance there is some efficiency in requesting the server to preallocate this amount of space using the REDACT-SIZE: callout.
An elementary (and somewhat contrived) example:
stdout = freopen ("SYS$OUTPUT:", "w", stdout, "ctx=bin", "ctx=xplct"); fputs (getenv("CGIPLUSESC"),stdout); fflush (stdout); fputs ("REDACT:HTTP/1.1 POST /an_example.php\r\n\ Host: example.com\r\n\ Content-Length: 26\r\n\ Content-Type: application/x-www-form-urlencoded\r\n\ \r\n", stdout); fflush (stdout); fwrite ("REDACT:one=two&three=four\n", 26, 1, stdout); fflush (stdout); fputs (getenv("CGIPLUSEOT"),stdout); fflush (stdout);
Once the request has been redacted the script just finishes processing without other output and the server transparently restarts processing.
An actual usage example may be found in the WASD PAPI authentication agent (not a component of the standard WASD package).
This facility was originally incorporated to allow a PAPI
authentication agent to store a request on-disk and then some time and several processing steps later restart the original request processing.