RTEset for WASD httpd.

RTEset is designed to enable effective scripting in the WASD RunTime Environment using a number of programming languages. For more information on WASD RTE environment see WASD scripting documentation.

Many programming languages enables very efficient scripting, but it takes a lot to start the language environment itself. To avoid multiple language startups in web scripting Mark G. Daniel suggested an efficient mechanism of language environment reuse - the script RunTime Environment (RTE). The main idea is as follows: On the first request the language environment starts and the first script is executed in this environment. After script execution the language environment doesn't exit - it restores to initial state and waits for the next request. When the next request is accepted the environment is reused without new language environment starup.

The RTE/httpd interaction doesn't matter for the script as it interacts mostly with language RTE environment which best-try emulates standard CGI environment in language internal resources.

The main script/RTE interaction uses the same standard output channel for the language mapped to SYS$OUTPUT:, the same PUT/POST input channel mapped to HTTP$INPUT: and the internal language variables (instead of environment variables) named just the same as DCL CGI variables.

Some language specifics are present, but the scheme is the same - at script startup it has CGI variables and the output channel predefined according to the request. The script uses CGI variables, outputs the CGI header and the response body to the output channel. After the execution the script returns the control to RTE instead of exiting thus enabling the environment reuse.

For example the script, reporting the client's address in various environments will look like:

TPU

TCL

PS

- very simple... Compare to the same DCL CGI script:

DCL

doesn't look the same?

Environment reuse.

Not only language environment can be reused. By default RTEs reset the environment to the initial state after script execution. The only exception is the precompiled script in TPUrte. It is kept until next request and reused if the same script is requested.

Sometimes the script startup or data file preprocessing takes a long too. In such a case the RTE can be instructed to reuse the script environment best-try. That is all the script environment is kept until the next request and reset only if the next request is to other script. The use of this feature requires the httpd to use the special RTE reuse strategy. Note that resetting the environment in such a configuration is the script's job and the environment is not nesessary kept - the script should check it and restore if needed.

In addition such a reuse mechanism allows httpd to use RTE as scripting coprocessor supporting <SERVER> HTML tags.

Language specifics.

At the time RTEset supports the following language RTEs: TCL, TPU, PS and DCL (example).

There is a number of language specifics due to language conventions and limitations.

CGI variables.

There are no language specifics for CGI variables - they are named just as in DCL CGI. Only in TCL CGI variables are the same named members of env() array for compatibility. For PS all CGI variables are stored in WWWdict dictionary available to script.

Note that the names are in upper case - it does matter to TCL and PS where the names are case-sensitive.

Output channel.

All RTEs can work with SYS$OUTPUT: directly, but have the RTE_output predefined variable pointing there - it's use is recommended.

For TCL output is available directly via "puts" language command.

For PS output is available via "print" and "showpage" language commands, so the text and graphics comes the same way - don't mix. If "showpage" outputs graphics - the text output should be used only for CGI header.

For TPU direct and buffered output is available. The "MESSAGE" language command outputs directly to SYS$OUTPUT:. Any buffer can be written directly to SYS$OUTPUT: using "WRITE_FILE(<buffer>,RTE_output)" language command. E.g. the temporary buffer RTE_scratch predefined by RTE can be used. The special predefined buffer named RTE_flush can be used for buffered output - if the script writes to this buffer, RTE will automatically write it's contence to SYS$OUTPUT: after the scipt is executed.

For RTEs where stdout is available it can be used for direct output.

Input channel.

All RTEs work with HTTP$INPUT: directly, but have the RTE_input predefined variable pointing there - it's use is recommended.

In TPU environment HTTP$INPUT: can be pre-read into special predefined buffer named RTE_fetch. This is done by defining special CGI variable WWW_RTE_FETCH.

For RTEs where stdin is available it can be used for direct PUT/POST body input.

RTE variables.

All RTE variables have the RTE_ prefix. Some of them can be used by user script. The user scripts shouldn't use or affect such variables if their use is not stated in the documentation.

RTE callbacks.

RTEs have predefined callouts for scripting support.

Specific features.

Script precompilation is available only for TPU. See the TPU compilation specifics.

At the moment the environment modification is available only for TPU. See the TPU environment specifics.

Installation.

To install RTEset or any of it's components SET DEFAULT to the root distribution directory and type @INSTALL. The instructions will follow.

Mapping rules and server configuration.

Mapping rules look very much alike for all RTEs:

Don't forget about script throttling and timeouts, especially for PSrte.

RTEs can be set against script file types in server configuration.

Special mapping parameters.

WASD mapping rules allow user-defined CGI variables to be passed to script using

set script=params=()

The following special parameters can be used for RTE control:

Sample scripts.

For all environments the sample CGI_SYMBOLS script is available with the corresponding type (.TPU .TCL .PS). For PS environment an additional script CGI_SYMBOLS_IMAGE.PS is available - the same as CGI_SYMBOLS, but in graphics.

A stub DCL RTE is included as an example of RTE scripting in DCL.

Accessing scripts.

Try accessing:

You can change "cgi_symbols" to any other installed script.

Availability.

RTEset is free available from S&B web site.