WASD Scripting Environment

6.CGI Callouts

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 (Authentication and Authorization in WASD Features) 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.1Requests 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 ! (exclamation point) or # (hash symbol).

• AGENT-BEGIN: <string>

  WASD v12.0 and later agents require the agent to declare its role and typically provide some information about itself. An example callout is shown below.

  CgiLibCgiPlusCallout ("!AGENT-BEGIN: %s (%s) usage:%d", SoftwareId, CgiLibEnvironmentVersion(), CgiPlusUsageCount);
• AGENT-END: <string>

  WASD v12.0 and later agents are required to declare process concluded, and optionally to return any results to the calling code.

  CgiLibCgiPlusCallout ("!AGENT-END:");
  CgiLibCgiPlusCallout ("!AGENT-END: 418 %s", cptr);
• AUTH-FILE: <file specification>

  If the specialized /PROFILE capability is enabled (SYSUAF Security Profile in WASD Features) 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.

• CGI: string

  Specialised callout allowing an access agent, lookup agent or meta agent to insert, modify or delete a CGI variable for a request. These agents are currently only proof-of-concept. See sources in

  WASD_ROOT:[SRC.AGENT]

• 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’ in 3.1 CGIplus Programming).

• CSP: <string>
  CSPRO: <string>

  Provide Content Security Policy (CSP) configuration(s) from a script.

  1.9 Content Security Policy (CSP)
  Content Security Policy (CSP) in WASD Configuration

• DICT: string

  Specialised callout allowing an access agent, lookup agent or meta agent to insert, modify or delete a dictionary entry. These agents are currently only proof-of-concept. See sources in

  WASD_ROOT:[SRC.AGENT]

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

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

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